Move here from ../../lispref

72 files changed, 83477 insertions, 0 deletions

diff --git a/doc/lispref/.arch-inventory b/doc/lispref/.arch-inventory
new file mode 100644
index 00000000000..2f5e6b9eea0
--- /dev/null
+++ b/doc/lispref/.arch-inventory
@@ -0,0 +1,4 @@
+# Generated files
+precious ^(config\.status|config\.cache)$
+
+# arch-tag: dde817a2-94ff-4c6e-838c-bb5b33e7f0df
diff --git a/doc/lispref/.gitignore b/doc/lispref/.gitignore
new file mode 100644
index 00000000000..a149258f6dd
--- /dev/null
+++ b/doc/lispref/.gitignore
@@ -0,0 +1,17 @@
+texput.log
+elisp.??
+elisp.???
+configure
+config.log
+config.cache
+config.status
+Makefile
+makefile
+index.texi
+elisp
+elisp-?
+elisp-??
+vol1.*
+vol2.*
+elisp1* 
+elisp2*
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
new file mode 100644
index 00000000000..490ef3623a5
--- /dev/null
+++ b/doc/lispref/ChangeLog
@@ -0,0 +1,6291 @@
+2007-09-06  Glenn Morris  <rgm@gnu.org>
+
+	* Move from lispref/ to doc/lispref/.  Change all setfilename
+	commands to use ../../info.
+	* Makefile.in (infodir): Go up one more level.
+        (usermanualdir): Change from ../man to ../emacs.
+	(miscmanualdir): New.
+	(dist): Use new variable miscmanualdir.
+	* makefile.w32-in (infodir, texinputdir): Go up one more level.
+	(usermanualdir): Change from ../man to ../emacs.
+
+2007-08-29  Glenn Morris  <rgm@gnu.org>
+
+	* elisp.texi (EMACSVER): Increase to 23.0.50.
+
+2007-08-29  Dan Nicolaescu  <dann@ics.uci.edu>
+
+	* frames.texi (Basic Parameters): Add display-environment-variable
+	and term-environment-variable.
+
+2007-08-28  Juri Linkov  <juri@jurta.org>
+
+	* display.texi (Image Formats, Other Image Types): Add SVG.
+
+2007-08-28  Juri Linkov  <juri@jurta.org>
+
+	* display.texi (Images): Move formats-related text to new node
+	"Image Formats".
+	(Image Formats): New node.
+
+2007-08-25  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Images): Delete redundant @findex.
+
+2007-08-16  Richard Stallman  <rms@gnu.org>
+
+	* processes.texi (Asynchronous Processes): Clarify
+	doc of start-file-process.
+
+2007-08-08  Martin Rudalics  <rudalics@gmx.at>
+
+	* modes.texi (Example Major Modes): Fix typo.
+
+2007-08-08  Glenn Morris  <rgm@gnu.org>
+
+	* intro.texi (nil and t): Do not use `iff' in documentation.
+
+	* tips.texi (Documentation Tips): Recommend against `iff'.
+
+2007-08-07  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Image Cache): Document image-refresh.
+
+2007-08-06  Martin Rudalics  <rudalics@gmx.at>
+
+	* windows.texi (Size of Window): Document window-full-width-p.
+
+2007-07-25  Glenn Morris  <rgm@gnu.org>
+
+	* gpl.texi (GPL): Replace license with GPLv3.
+
+	* Relicense all FSF files to GPLv3 or later.
+
+2007-07-24  Michael Albinus  <michael.albinus@gmx.de>
+
+	* processes.texi (Synchronous Processes): Add
+	`process-file-shell-command',
+	(Asynchronous Processes): Mention restricted use of
+	`process-filter' and `process-sentinel' in
+	`start-file-process'.  Add `start-file-process-shell-command'.
+
+2007-07-17  Michael Albinus  <michael.albinus@gmx.de>
+
+	* files.texi (Magic File Names): Introduce optional parameter
+	IDENTIFICATION for `file-remote-p'.
+
+2007-07-16  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Defining Faces): Fix previous change.
+
+2007-07-14  Richard Stallman  <rms@gnu.org>
+
+	* control.texi (Handling Errors): Document `debug' in handler list.
+
+2007-07-10  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Defining Faces): Explain C-M-x feature for defface.
+
+2007-07-09  Richard Stallman  <rms@gnu.org>
+
+	* files.texi (Magic File Names): Rewrite previous change.
+
+2007-07-08  Michael Albinus  <michael.albinus@gmx.de>
+
+	* files.texi (Magic File Names): Introduce optional parameter
+	CONNECTED for `file-remote-p'.
+
+2007-07-07  Michael Albinus  <michael.albinus@gmx.de>
+
+	* processes.texi (Asynchronous Processes):
+	* files.texi (Magic File Names): Add `start-file-process'.
+
+2007-06-27  Richard Stallman  <rms@gnu.org>
+
+	* files.texi (Format Conversion Piecemeal): Clarify
+	`after-insert-file-functions' calling convention.
+
+2007-06-27  Michael Albinus  <michael.albinus@gmx.de>
+
+	* files.texi (Magic File Names): Remove `dired-call-process'.  Add
+	`process-file'.
+
+2007-06-27  Kenichi Handa  <handa@m17n.org>
+
+	* text.texi (Special Properties): Fix description about
+	`compostion' property.
+
+2007-06-26  Kenichi Handa  <handa@m17n.org>
+
+	* nonascii.texi (Default Coding Systems): Document about the
+	return value `undecided'.
+
+2007-06-25  David Kastrup  <dak@gnu.org>
+
+	* keymaps.texi (Active Keymaps): Document new POSITION argument of
+	`current-active-maps'.
+
+2007-06-24  Karl Berry  <karl@gnu.org>
+
+	* elisp.texi, vol1.texi, vol2.texi: new Back-Cover Text.
+
+2007-06-15  Juanma Barranquero  <lekktu@gmail.com>
+
+	* display.texi (Overlay Arrow): Doc fix.
+
+2007-06-14  Karl Berry  <karl@tug.org>
+
+	* anti.texi (Antinews): Typo.
+
+2007-06-14  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Image Cache): Document image-refresh.
+
+2007-06-12  Karl Berry  <karl@gnu.org>
+
+	* vol1.texi, vol2.texi, two-volume-cross-refs.txt: Update.
+	* two-volume.make: New file.
+	* .cvsignore: Ignore two-volume files.
+
+2007-06-12  Tom Tromey  <tromey@redhat.com>
+
+	* os.texi (Init File): Document user-emacs-directory.
+
+2007-06-03  Nick Roberts  <nickrob@snap.net.nz>
+
+	* commands.texi (Click Events): Describe width and height when
+	object is nil.
+
+2007-05-30  Nick Roberts  <nickrob@snap.net.nz>
+
+	* commands.texi (Click Events): Layout more logically.  Describe
+	width and height.
+	(Drag Events, Motion Events): Update to new format for position.
+
+2007-06-02  Richard Stallman  <rms@gnu.org>
+
+	* frames.texi (Color Parameters): Add xref to (emacs)Standard Faces.
+
+2007-06-02  Chong Yidong  <cyd@stupidchicken.com>
+
+	* Version 22.1 released.
+
+2007-06-01  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* text.texi (Special Properties): Correct meaning of fontified face.
+
+2007-05-30  Richard Stallman  <rms@gnu.org>
+
+	* text.texi (Special Properties): Add link to Adjusting Point.
+
+2007-05-12  Richard Stallman  <rms@gnu.org>
+
+	* text.texi (Margins): indent-to-left-margin is not the default.
+	(Mode-Specific Indent): For indent-line-function, the default
+	is indent-relative.
+
+	* modes.texi (Example Major Modes): Explain last line of text-mode
+	is redundant.
+
+2007-05-10  Richard Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Scanning Keymaps): Update where-is-internal example.
+
+	* help.texi (Keys in Documentation): Add reference to
+	Documentation Tips.
+
+	* files.texi (Format Conversion): TO-FN gets three arguments.
+
+	* modes.texi (Auto Major Mode): Document file-start-mode-alist.
+
+2007-05-10  Thien-Thi Nguyen  <ttn@gnuvola.org>
+
+	* elisp.texi (Top): Remove "Saving Properties" from detailed menu.
+	* files.texi (Format Conversion): Expand intro; add menu.
+	(Format Conversion Overview, Format Conversion Round-Trip)
+	(Format Conversion Piecemeal): New nodes/subsections.
+	* hooks.texi: Xref "Format Conversion" , not "Saving Properties".
+	* text.texi (Text Properties): Remove "Saving Properties" from menu.
+	(Saving Properties): Delete node/subsection.
+
+2007-05-07  Karl Berry  <karl@gnu.org>
+
+	* elisp.texi (EMACSVER): Back to 22.
+
+2007-05-06  Richard Stallman  <rms@gnu.org>
+
+	* processes.texi (Accepting Output): Revert most of previous change.
+
+2007-05-05  Richard Stallman  <rms@gnu.org>
+
+	* processes.texi (Accepting Output): accept-process-output
+	uses microseconds, not milliseconds.  But that arg is obsolete.
+
+2007-05-04  Karl Berry  <karl@tug.org>
+
+	* elisp.texi (EMACSVER) [smallbook]: 22.1, not 22.
+
+2007-05-04  Eli Zaretskii  <eliz@gnu.org>
+
+	* tips.texi (Documentation Tips): Rearrange items to place the
+	more important ones first.  Add an index entry for hyperlinks.
+
+2007-05-03  Karl Berry  <karl@gnu.org>
+
+	* elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing.
+	(EMACSVER) [smallbook]: 22 for printed version.
+
+	* control.texi (Signaling Errors) <signal>: texinfo.tex is fixed,
+	so restore anchor to normal position after defun.  Found by Kevin Ryde.
+
+2007-04-26  Glenn Morris  <rgm@gnu.org>
+
+	* elisp.texi (EMACSVER): Increase to 22.1.50.
+
+2007-04-28  Karl Berry  <karl@gnu.org>
+
+	* elisp.texi: Improve line breaks on copyright page,
+	similar layout to emacs manual, 8.5x11 by default.
+
+2007-04-24  Richard Stallman  <rms@gnu.org>
+
+	* text.texi (Special Properties): Add xref to Overlay Properties.
+
+	* display.texi (Overlay Properties): Add xref to Special Properties.
+
+2007-04-22  Richard Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Extended Menu Items): Move the info about
+	format with cached keyboard binding.
+
+2007-04-21  Richard Stallman  <rms@gnu.org>
+
+	* text.texi (Special Properties): Clarify previous change.
+
+	* files.texi (File Name Expansion): Clarify previous change.
+
+	* display.texi (Attribute Functions): Fix example for
+	face-attribute-relative-p.
+
+2007-04-19  Kenichi Handa  <handa@m17n.org>
+
+	* text.texi (Special Properties): Document composition property.
+
+2007-04-19  Glenn Morris  <rgm@gnu.org>
+
+	* files.texi (File Name Expansion): Mention "superroot".
+
+2007-04-15  Chong Yidong  <cyd@stupidchicken.com>
+
+	* frames.texi (Multiple Displays): Add note about "multi-monitor"
+	setups.
+	(Display Feature Testing): Note that display refers to all
+	physical monitors for multi-monitor setups.
+
+2007-04-14  Richard Stallman  <rms@gnu.org>
+
+	* lists.texi (Sets And Lists): Clarify `delete' examples.
+	Remove spurious xref to same node.
+	Clarify xref for add-to-list.
+
+2007-04-12  Nick Roberts  <nickrob@snap.net.nz>
+
+	* keymaps.texi (Format of Keymaps): Remove spurious ")" from
+	value of lisp-mode-map.
+
+2007-04-11  Karl Berry  <karl@gnu.org>
+
+	* anti.texi (Antinews):
+	* display.texi (Overlay Properties, Defining Images):
+	* processes.texi (Synchronous Processes, Sentinels):
+	* syntax.texi (Syntax Table Internals):
+	* searching.texi (Regexp Special):
+	* nonascii.texi (Default Coding Systems):
+	* text.texi (Special Properties):
+	* minibuf.texi (Basic Completion): Wording to improve breaks in
+	8.5x11 format.
+	* elisp.texi (smallbook): New @set to more easily switch between
+	smallbook and 8.5x11.
+
+2007-04-11  Richard Stallman  <rms@gnu.org>
+
+	* text.texi (Lazy Properties): Minor fix.
+
+2007-04-08  Karl Berry  <karl@gnu.org>
+
+	* symbols.texi (Plists and Alists): Period after "vs" in index entries.
+	* macros.texi (Backquote): Downcase Backquote in index entries for
+	consistency.
+
+2007-04-08  Richard Stallman  <rms@gnu.org>
+
+	* text.texi (Adaptive Fill): Just describe default,
+	don't show it (since it contains non-ASCII chars).
+
+2007-04-07  Karl Berry  <karl@gnu.org>
+
+	* text.texi (Adaptive Fill) [@iftex]: Omit binary characters in
+	adaptive-fill-regexp's value, since they are not in the standard
+	TeX fonts.
+
+2007-04-07  Guanpeng Xu  <herberteuler@hotmail.com>
+
+	* display.texi (Defining Faces): Fix example.
+
+2007-04-07  Karl Berry  <karl@gnu.org>
+
+	* display.texi (Button Buffer Commands): Improve page break.
+
+2007-04-07  Richard Stallman  <rms@gnu.org>
+
+	* advice.texi (Activation of Advice): Remove redundant index entry.
+
+	* backups.texi: Improve index entries.  Remove redundant ones.
+
+	* compile.texi (Byte Compilation): Improve index entry.
+
+	* hash.texi (Creating Hash): Improve index entry.
+
+	* symbols.texi (Definitions): Improve index entry.
+
+	* edebug.texi: Improve index entries.  Remove redundant/useless ones.
+
+	* maps.texi (Standard Keymaps): Remove useless index entry.
+
+	* help.texi (Documentation Basics): Remove redundant index entries.
+
+	* customize.texi: Improve index entries.
+	Remove redundant/useless ones.
+
+	* locals.texi (Standard Buffer-Local Variables): Clarify intro text.
+
+	* streams.texi (Output Variables): Improve index entry.
+
+	* abbrevs.texi (Abbrevs): Remove useless index entry.
+
+	* macros.texi (Expansion): Remove useless index entry.
+
+	* text.texi: Improve index entries.  Remove redundant/useless ones.
+	(Text Properties, Examining Properties)
+	(Special Properties): Use "property category" instead of "category"
+	to refer to the `category' property.
+
+	* positions.texi: Improve index entries.  Remove useless one.
+
+	* lists.texi: Improve index entries.  Remove redundant/useless ones.
+
+	* os.texi: Improve index entries.
+	(Timers): Fix previous change.
+
+	* buffers.texi: Improve index entries.
+	(Modification Time): Get rid of term "obsolete buffer".
+
+	* debugging.texi: Improve index entries.
+	(Test Coverage): Add xref to other test coverage ftr.
+
+	* eval.texi: Improve index entry.  Remove redundant ones.
+
+	* numbers.texi: Improve index entries.  Remove redundant/useless ones.
+
+	* files.texi: Improve index entries.  Remove redundant/useless ones.
+
+	* objects.texi: Improve index entries.
+
+	* processes.texi: Improve index entries.
+
+	* modes.texi: Improve index entry.  Remove redundant one.
+
+	* nonascii.texi: Improve index entries.
+
+	* internals.texi: Improve index entries.
+
+	* syntax.texi: Improve index entries.
+
+	* keymaps.texi (Active Keymaps): Improve index entries.
+
+	* commands.texi: Improve index entries.  Remove redundant/useless ones.
+
+	* frames.texi: Improve index entries.  Remove redundant/useless ones.
+
+	* markers.texi: Improve index entries.  Remove redundant ones.
+
+	* tips.texi: Improve index entries.
+
+	* loading.texi (Unloading): Improve index entry.
+
+	* variables.texi: Improve index entries.  Remove redundant one.
+
+	* sequences.texi: Improve index entry.
+
+	* display.texi: Improve index entries.  Remove redundant ones.
+
+	* windows.texi: Improve index entries.
+
+	* searching.texi: Improve index entries.  Remove redundant one.
+
+	* strings.texi (Case Tables): Improve last change.
+
+2007-04-04  Chong Yidong  <cyd@stupidchicken.com>
+
+	* strings.texi (Case Tables): Document with-case-table and
+	ascii-case-table.
+
+2007-04-03  Karl Berry  <karl@gnu.org>
+
+	* processes.texi (Network): Reword to improve page break.
+
+2007-04-03  Eli Zaretskii  <eliz@gnu.org>
+
+	* functions.texi (Inline Functions): Describe more disadvantages
+	of defsubst, and make advice against it stronger.
+
+2007-04-02  Karl Berry  <karl@gnu.org>
+
+	* backups.texi (Backup Names): Avoid widow words.
+	* modes.texi (Example Major Modes): Align last comment.
+
+2007-04-01  Chong Yidong  <cyd@stupidchicken.com>
+
+	* keymaps.texi (Remapping Commands): Document new arg to
+	command-remapping.
+
+2007-04-01  Karl Berry  <karl@gnu.org>
+
+	* processes.texi (Low-Level Network): Typo.
+	* loading.texi (Hooks for Loading): Avoid double "the".
+	* keymaps.texi (Key Sequences): No double "and".
+	(Changing Key Bindings): Shorten to improve line break.
+
+2007-03-31  Glenn Morris  <rgm@gnu.org>
+
+	* os.texi (Timers): Fix description of run-at-time TIME formats.
+
+2007-03-31  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Invisible Text): Correct buffer-invisibility-spec
+	regarding ellipsis.
+
+2007-03-31  Eli Zaretskii  <eliz@gnu.org>
+
+	* intro.texi (nil and t):
+	* symbols.texi (Plists and Alists):
+	* variables.texi (Variable Aliases, Constant Variables):
+	* functions.texi (Defining Functions):
+	* advice.texi (Advising Primitives):
+	* debugging.texi (Syntax Errors, Compilation Errors):
+	* minibuf.texi (Minibuffer Windows):
+	* commands.texi (Adjusting Point):
+	* modes.texi (Syntactic Font Lock, Faces for Font Lock)
+	(Auto Major Mode, Major Mode Conventions):
+	* help.texi (Describing Characters):
+	* files.texi (Create/Delete Dirs, Information about Files)
+	(File Locks, Writing to Files, Reading from Files)
+	(Saving Buffers):
+	* windows.texi (Resizing Windows, Cyclic Window Ordering):
+	* frames.texi (Finding All Frames):
+	* positions.texi (Buffer End, Motion):
+	* markers.texi (The Region):
+	* text.texi (Deletion, Near Point):
+	* display.texi (Displaying Messages, Truncation):
+	* os.texi (Processor Run Time):
+	* tips.texi (Key Binding Conventions, Programming Tips)
+	(Warning Tips, Documentation Tips, Comment Tips):
+	* internals.texi (Memory Usage): Improve indexing.
+
+	* variables.texi (Frame-Local Variables):
+	* functions.texi (Argument List):
+	* loading.texi (Library Search):
+	* streams.texi (Output Variables):
+	* keymaps.texi (Translation Keymaps, Searching Keymaps):
+	* searching.texi (Replacing Match, Search and Replace):
+	* processes.texi (Byte Packing, Decoding Output)
+	(Accepting Output, Network Servers, Shell Arguments):
+	* display.texi (Abstract Display, Image Cache, Scroll Bars):
+	* windows.texi (Window Point, Window Start):
+	* frames.texi (Management Parameters, Frame Parameters, Frame Titles):
+	* commands.texi (Reading Input, Keyboard Events):
+	* minibuf.texi (Reading File Names, Minibuffer Completion)
+	(Recursive Mini):
+	* positions.texi (List Motion):
+	* hash.texi (Hash Tables, Creating Hash, Defining Hash):
+	* numbers.texi (Arithmetic Operations, Math Functions)
+	(Predicates on Numbers, Comparison of Numbers):
+	(Numeric Conversions):
+	* locals.texi (Standard Buffer-Local Variables):
+	* maps.texi (Standard Keymaps):
+	* os.texi (User Identification, System Environment, Recording Input)
+	(X11 Keysyms):
+	* nonascii.texi (Non-ASCII Characters, Splitting Characters):
+	* backups.texi (Backups and Auto-Saving):
+	* customize.texi (Customization, Group Definitions)
+	(Variable Definitions):
+	* compile.texi (Byte Compilation): Improve index entries.
+
+2007-03-31  Karl Berry  <karl@gnu.org>
+
+	* macros.texi (Defining Macros): Avoid widow syllable.
+
+2007-03-31  Eli Zaretskii  <eliz@gnu.org>
+
+	* elisp.texi (Top): Postscript -> PostScript.
+
+	* display.texi (Images, Postscript Images): Postscript -> PostScript.
+
+2007-03-31  Markus Triska  <markus.triska@gmx.at>
+
+	* internals.texi (Writing Emacs Primitives): Untabify `For'.
+
+2007-03-30  Karl Berry  <karl@gnu.org>
+
+	* lists.texi (List-related Predicates): Remove spurious @need.
+	(Setcdr): Use @smallexample to improve page break.
+	(Association Lists) <assoc>: Reword to improve page break.
+
+	* strings.texi (String Conversion): Insert blank line to improve
+	page break.
+
+	* numbers.texi (Random Numbers): Use @minus{}.
+	(Math Functions): Use @minus{}.
+
+	* intro.texi (Acknowledgements): Avoid line breaks before middle
+	initials.
+
+2007-03-24  Eli Zaretskii  <eliz@gnu.org>
+
+	* errors.texi (Standard Errors): Add an index entry.
+
+2007-03-19  Richard Stallman  <rms@gnu.org>
+
+	* os.texi (Recording Input): recent-keys now gives 300 keys.
+
+2007-03-12  Glenn Morris  <rgm@gnu.org>
+
+	* os.texi: Replace "daylight savings" with "daylight saving"
+	throughout.
+
+2007-03-05  Richard Stallman  <rms@gnu.org>
+
+	* variables.texi (File Local Variables): Update
+	enable-local-variables values.
+
+2007-03-04  Richard Stallman  <rms@gnu.org>
+
+	* syntax.texi (Control Parsing): Minor clarification.
+
+	* strings.texi (Formatting Strings): Clarify width, precision, flags.
+
+	* sequences.texi (Sequence Functions): Move string-bytes away,
+	add xref.
+
+	* nonascii.texi (Text Representations): Move string-bytes here.
+
+	* modes.texi (Major Mode Conventions): Fundamental mode is exception.
+
+	* minibuf.texi (Basic Completion): Minor clarification.
+
+	* markers.texi (The Mark): Clarify existence vs activation of mark.
+	Other cleanup.
+
+	* display.texi (Finding Overlays): Write better example.
+
+	* compile.texi (Eval During Compile): Clarify putting macros
+	in eval-when-compile.
+
+2007-02-25  Vinicius Jose Latorre  <viniciusjl@ig.com.br>
+
+	* loading.texi (How Programs Do Loading): Fix anchor position at
+	load-read-function definition doc. (tiny change)
+
+2007-02-21  Kim F. Storm  <storm@cua.dk>
+
+	* strings.texi (Text Comparison): Mention that assoc-string
+	converts symbols to strings before testing.
+
+2007-02-17  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Bindat Spec): Vector types can have optional
+	element type.
+	(Bindat Examples): Fix example.  Add vector with element type.
+
+2007-02-16  Andreas Schwab  <schwab@suse.de>
+
+	* strings.texi (Formatting Strings): Document '+' flag.
+
+2007-02-15  Juanma Barranquero  <lekktu@gmail.com>
+
+	* strings.texi (Modifying Strings): Clarify that `clear-string'
+	always converts the string to unibyte.
+
+2007-02-14  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Glyphs): Add make-glyph-code, glyph-char, glyph-face.
+	Rewrite glyph code description to refer to these functions.
+	Remove details of encoding face number and char into integer code.
+
+2007-02-03  Alan Mackenzie  <acm@muc.de>
+
+	* loading.texi (Hooks for Loading): Make the description of
+	`eval-after-load' more detailed, and amend the description of
+	after-load-alist, in accordance with changes from 2006-05.
+
+2007-02-03  Chong Yidong  <cyd@stupidchicken.com>
+
+	* modes.texi (Defining Minor Modes): Document that a :require
+	keyword or similar may be required to make saved customization
+	variables work.
+
+2007-02-03  Eli Zaretskii  <eliz@gnu.org>
+
+	* elisp.texi (Top): 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-02-02  Eli Zaretskii  <eliz@gnu.org>
+
+	* elisp.texi (Top): Update the top-level menus.
+
+	* syntax.texi (Categories): Add index entries.
+
+2007-02-01  Juanma Barranquero  <lekktu@gmail.com>
+
+	* display.texi (Attribute Functions): Fix name and description of
+	the UNDERLINE arg of `set-face-underline-p'.
+
+2007-01-29  Eli Zaretskii  <eliz@gnu.org>
+
+	* elisp.texi (Top): Add "Standard Errors", "Standard Buffer-Local
+	Variables", and "Standard Keymaps" to the detailed menu.
+
+	* variables.texi (Future Local Variables): Add index entry.
+
+2007-01-28  Richard Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Clarify the tip about macros
+	that define a function or a variable.
+
+	* files.texi (File Attributes): UID and GID can be floats.
+	(Magic File Names): Explain why deferring all operations to
+	the standard handler does not work.
+
+2007-01-23  Martin Rudalics  <rudalics@gmx.at>
+
+	* backups.texi (Reverting): Use "buffer" instead of "file"
+	when talking about major and minor modes.
+
+2007-01-21  Richard Stallman  <rms@gnu.org>
+
+	* help.texi (Documentation): Add xref to Documentation Tips.
+
+2007-01-14  Juanma Barranquero  <lekktu@gmail.com>
+
+	* tips.texi (Coding Conventions): Fix typos.
+
+2007-01-05  Richard Stallman  <rms@gnu.org>
+
+	* modes.texi (Defining Minor Modes): Fix previous change.
+
+2007-01-03  Richard Stallman  <rms@gnu.org>
+
+	* customize.texi (Variable Definitions, Customization Types):
+	Don't use * in doc string for defcustom.
+
+2007-01-02  Richard Stallman  <rms@gnu.org>
+
+	* variables.texi (Variable Aliases): Clarify that aliases vars
+	always have the same value.
+
+	* processes.texi (Bindat Spec): Fix Texinfo usage.
+
+	* modes.texi (Defining Minor Modes): Explain effect of command
+	defined with define-global-minor-mode on new buffers.
+
+2006-12-30  Kim F. Storm  <storm@cua.dk>
+
+	* keymaps.texi (Tool Bar): Describe `grow-only' value of
+	`auto-resize-tool-bars'.
+
+2006-12-30  Richard Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Active Keymaps): Fix previous change.
+
+2006-12-30  Nick Roberts  <nickrob@snap.net.nz>
+
+	* keymaps.texi (Active Keymaps): Make xref to lookup-key.
+
+2006-12-30  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Bindat Spec): Clarify using field names in
+	length specifications.
+
+2006-12-29  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Bindat Spec): Explain eval forms and lengths better.
+	Add count and index variables for eval forms in repeat blocks.
+
+2006-12-24  Richard Stallman  <rms@gnu.org>
+
+	* customize.texi (Variable Definitions): Document
+	new name custom-add-frequent-value.
+
+2006-12-19  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Misc Events): User signals now result in sigusr1
+	and sigusr2 events which are handled through special-event-map.
+	(Special Events): User signals and drag-n-drop are special.
+
+2006-12-17  Richard Stallman  <rms@gnu.org>
+
+	* loading.texi (Named Features): Explain subfeatures better.
+
+	* customize.texi: Use "option" only for user options.
+	For the keyword values inside defcustom etc, say "keywords".
+	For :options value's elements, say "elements".
+	:group should not be omitted.
+
+	* syntax.texi (Parsing Expressions): Split up node.
+	(Motion via Parsing, Position Parse, Parser State)
+	(Low-Level Parsing, Control Parsing): New subnodes.
+	(Parser State): Document syntax-ppss-toplevel-pos.
+
+	* positions.texi (List Motion): Punctuation fix.
+
+	* files.texi (File Name Completion): Document PREDICATE arg
+	to file-name-completion.
+
+2006-12-16  Eli Zaretskii  <eliz@gnu.org>
+
+	* internals.texi (Building Emacs, Writing Emacs Primitives):
+	Add index entries.
+
+2006-12-11  Richard Stallman  <rms@gnu.org>
+
+	* modes.texi (Font Lock Basics): Explain how nil for font-lock-defaults
+	affects face menu.  Explain how to make it non-nil without enabling
+	any fontification.
+
+2006-12-10  Chong Yidong  <cyd@stupidchicken.com>
+
+	* modes.texi (Font Lock Basics): Document nil value of
+	font-lock-defaults.
+
+2006-12-10  Glenn Morris  <rgm@gnu.org>
+
+	* abbrevs.texi (Defining Abbrevs): Mention `define-abbrev' 'force
+	value for system-flag argument.  Abbrev tables may not be empty
+	when major modes are loaded.
+
+2006-12-08  Juanma Barranquero  <lekktu@gmail.com>
+
+	* makefile.w32-in (maintainer-clean): Partially revert last
+	change; delete "elisp-?" and "elisp-??" instead of "elisp-*"
+	to protect elisp-covers.texi.
+
+2006-12-07  Juanma Barranquero  <lekktu@gmail.com>
+
+	* makefile.w32-in (maintainer-clean): Depend on `distclean'.
+	Don't remove elisp* info files; they are already deleted by the
+	`clean' and `distclean' targets, and they are in the $(infodir)
+	directory, not the current one.
+
+2006-12-04  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Misc Events): Update signal events.
+	(Event Examples): Add signal example.
+
+2006-11-29  Richard Stallman  <rms@gnu.org>
+
+	* frames.texi (Visibility of Frames): Explain visible windows
+	can be covered by others.  Add xref for raise-frame.
+
+2006-11-28  Richard Stallman  <rms@gnu.org>
+
+	* searching.texi (Regexp Special): Update when ^ is special.
+
+2006-11-27  Eli Zaretskii  <eliz@gnu.org>
+
+	* customize.texi (Customization, Common Keywords)
+	(Group Definitions, Variable Definitions, Composite Types)
+	(Type Keywords, Customization Types): Add index entries for
+	various customization keywords.
+
+2006-11-23  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* modes.texi (Multiline Font Lock): Rephrase some parts for clarity.
+
+2006-11-10  Jan Dj,Ad(Brv  <jan.h.d@swipnet.se>
+
+	* frames.texi (Window System Selections): Remove clipboard from
+	description of selection-coding-system.
+
+2006-11-06  Richard Stallman  <rms@gnu.org>
+
+	* lists.texi (List Variables): Document COMPARE-FN.
+
+	* keymaps.texi: Avoid use of "binding" to mean a relation;
+	use it only to refer to the meaning associated with a key.
+	(Keymaps): Change menu node description.
+
+	* elisp.texi (Top): Change menu node description.
+
+	* display.texi (Managing Overlays): Document overlay-recenter.
+
+2006-10-29  Chong Yidong  <cyd@stupidchicken.com>
+
+	* Makefile.in: Use relative paths to avoid advertising filesystem
+	contents during compilation.
+
+2006-10-23  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Event Input Misc): Update unread-command-events.
+
+2006-10-23  Nick Roberts  <nickrob@snap.net.nz>
+
+	* lists.texi (Sets And Lists): Fix typos.
+
+2006-10-18  Juanma Barranquero  <lekktu@gmail.com>
+
+	* control.texi (Processing of Errors): Use @var for an argument,
+	not @code.
+
+2006-10-16  Richard Stallman  <rms@gnu.org>
+
+	* edebug.texi (Edebug Recursive Edit): Minor cleanup.
+
+	* keymaps.texi (Format of Keymaps): Show all the keymap element
+	patterns that result from menu items.
+	(Key Lookup): Minor cleanups.
+
+	* modes.texi (Precalculated Fontification): Don't say that
+	not setting font-lock-defaults avoids loading font-lock.
+
+	* help.texi (Documentation): Move xref to Emacs Manual here.
+	(Documentation Basics): From here.
+	Also doc emacs-lisp-docstring-fill-column.
+
+	* elisp.texi: Update version and ISBN.
+
+	* commands.texi (Interactive Call): Clarify KEYS arg to
+	call-interactively is a vector.
+	(Command Loop Info): Delete anchor in this-command-keys.
+	Add anchor in this-command-keys-vector.
+	(Recursive Editing): Document how recursive-edit
+	handles the current buffer.
+
+2006-10-13  Chong Yidong  <cyd@stupidchicken.com>
+
+	* frames.texi (Frame Titles): %c and %l are ignored in
+	frame-title-format.
+
+2006-10-11  Richard Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Key Sequences): Clarify use of kbd.
+
+2006-10-10  Kim F. Storm  <storm@cua.dk>
+
+	* lists.texi (Sets And Lists): Add memql.
+
+2006-10-03  Richard Stallman  <rms@gnu.org>
+
+	* searching.texi (Char Classes): Document :multibyte: and :unibyte:.
+	Clarify :ascii: and :nonascii:.
+
+2006-09-29  Juri Linkov  <juri@jurta.org>
+
+	* modes.texi (%-Constructs): Reorder coding systems in the
+	documentation of %z to the real order displayed in the modeline.
+
+2006-09-25  Richard Stallman  <rms@gnu.org>
+
+	* os.texi (Timers): Describe timer-max-repeats.
+
+2006-09-25  Chong Yidong  <cyd@stupidchicken.com>
+
+	* os.texi (Timers): Mention with-local-quit.
+
+2006-09-24  Richard Stallman  <rms@gnu.org>
+
+	* searching.texi (Searching and Matching): Mention property search.
+
+	* commands.texi (Command Loop Info): Explain how read-event affects
+	this-command-keys.
+
+2006-09-20  Richard Stallman  <rms@gnu.org>
+
+	* os.texi (Timers): Clarify about REPEAT when timer is delayed.
+
+	* windows.texi (Window Start): Minor cleanups.
+
+2006-09-20  Kim F. Storm  <storm@cua.dk>
+
+	* windows.texi (Window Start): pos-visible-in-window-p allows
+	specifying t for position to mean "end of window".
+	Add window-line-height.
+
+	* anti.texi (Antinews): Mention window-line-height.
+
+2006-09-19  David Kastrup  <dak@gnu.org>
+
+	* keymaps.texi (Searching Keymaps): Small clarification.
+
+2006-09-18  Richard Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Creating Keymaps): Explain that keymap prompt strings
+	cause keyboard menus.
+	(Menu Keymaps): Likewise.
+	(Defining Menus, Keyboard Menus): Clarify.
+
+	* text.texi (Fields): Clarify explanation of constrain-to-field.
+
+2006-09-16  Eli Zaretskii  <eliz@gnu.org>
+
+	* variables.texi (Tips for Defining): Fix a typo.
+
+2006-09-15  Richard Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Remapping Commands, Searching Keymaps)
+	(Active Keymaps): Clean up previous change.
+
+2006-09-15  Jay Belanger  <belanger@truman.edu>
+
+	* gpl.texi: Replace "Library Public License" by "Lesser Public
+	License" throughout.
+
+2006-09-15  David Kastrup  <dak@gnu.org>
+
+	* keymaps.texi (Active Keymaps): Adapt description to use
+	`get-char-property' instead `get-text-property'.  Explain how
+	mouse events change this.  Explain the new optional argument of
+	`key-binding' and its mouse-dependent lookup.
+	(Searching Keymaps): Adapt description similarly.
+	(Remapping Commands): Explain the new optional argument of
+	`command-remapping'.
+
+2006-09-14  Richard Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Searching Keymaps): Clarification.
+	(Active Keymaps): Refer to Searching Keymaps instead of duplication.
+
+2006-09-13  Richard Stallman  <rms@gnu.org>
+
+	* objects.texi (Character Type): Node split.
+	Add xref to Describing Characters.
+	(Basic Char Syntax, General Escape Syntax)
+	(Ctl-Char Syntax, Meta-Char Syntax): New subnodes.
+
+2006-09-11  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Display Table Format): Wording clarification.
+	(Glyphs): Clarifications.
+
+2006-09-10  Chong Yidong  <cyd@stupidchicken.com>
+
+	* keymaps.texi (Active Keymaps): Mention that key-binding checks
+	local maps.
+
+2006-09-10  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Forcing Redisplay): Document return value of
+	function redisplay.
+
+2006-09-09  Richard Stallman  <rms@gnu.org>
+
+	* windows.texi (Window Hooks): Explain limits of
+	window-scroll-functions.
+
+	* display.texi (Fringe Indicators): Update for last change in
+	indicate-buffer-boundaries.
+
+2006-09-08  Richard Stallman  <rms@gnu.org>
+
+	* processes.texi (Bindat Spec): Suggest names ending in -bindat-spec.
+
+2006-09-06  Kim F. Storm  <storm@cua.dk>
+
+	* frames.texi (Display Feature Testing): display-mm-dimensions-alist.
+
+	* windows.texi (Window Start): Update pos-visible-in-window-p.
+
+2006-09-04  Richard Stallman  <rms@gnu.org>
+
+	* processes.texi (Accepting Output): Explain SECONDS=0 for
+	accept-process-output.
+
+	* os.texi (Idle Timers): Explain why timer functions should not
+	loop until (input-pending-p).
+
+2006-09-02  Eli Zaretskii  <eliz@gnu.org>
+
+	* makefile.w32-in (usermanualdir): New variable.
+	(elisp.dvi): Use it.
+
+2006-09-01  Eli Zaretskii  <eliz@gnu.org>
+
+	* buffers.texi (Buffer Modification): Fix last change.
+
+2006-09-01  Chong Yidong  <cyd@stupidchicken.com>
+
+	* buffers.texi (Buffer Modification): Document
+	buffer-chars-modified-tick.
+
+2006-08-31  Richard Stallman  <rms@gnu.org>
+
+	* modes.texi (Syntactic Font Lock): Mention specific faces once again.
+
+2006-08-31  Richard Bielawski  <RBielawski@moneygram.com>  (tiny change)
+
+	* modes.texi (Syntactic Font Lock):
+	Mention font-lock-syntactic-face-function
+	instead of specific faces.
+
+2006-08-29  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Images): Add xrref to display-images-p.
+
+2006-08-28  Kenichi Handa  <handa@m17n.org>
+
+	* nonascii.texi (Lisp and Coding Systems): Fix description of
+	detect-coding-region.
+
+2006-08-27  Michael Olson  <mwolson@gnu.org>
+
+	* processes.texi (Transaction Queues): Remove stray quote
+	character.
+
+2006-08-25  Richard Stallman  <rms@gnu.org>
+
+	* os.texi (Idle Timers): run-with-idle-timer allows Lisp time value.
+	Add xref.
+
+2006-08-24  Chong Yidong  <cyd@stupidchicken.com>
+
+	* os.texi (Timers): Avoid waiting inside timers.
+
+2006-08-21  Lute Kamstra  <lute@gnu.org>
+
+	* Makefile.in: Use ../man/texinfo.tex to build elisp.dvi.
+
+2006-08-20  Richard Stallman  <rms@gnu.org>
+
+	* os.texi (Idle Timers): New node, split out from Timers.
+	Document current-idle-time.
+	* commands.texi (Reading One Event): Update xref.
+	* elisp.texi (Top): Update subnode menu.
+
+2006-08-16  Richard Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Extended Menu Items): Show format of cached
+	bindings in extended menu items.
+
+	* customize.texi (Variable Definitions): Explain when the
+	standard value expression is evaluated.
+
+2006-08-15  Chong Yidong  <cyd@stupidchicken.com>
+
+	* commands.texi (Reading One Event): Explain idleness in
+	`read-event'.
+
+2006-08-12  Chong Yidong  <cyd@stupidchicken.com>
+
+	* text.texi (Near Point): Say "cursor" not "terminal cursor".
+	(Commands for Insertion): Removed split-line since it's not
+	relevant for Lisp programming.
+	(Yank Commands): Rewrite introduction.
+	(Undo): Clarify.
+	(Maintaining Undo): Clarify.  Document undo-ask-before-discard.
+	(Filling): Remove redundant comment.  Clarify return value of
+	current-justification.
+	(Margins): Minor clarifications.
+	(Adaptive Fill): Update default value of adaptive-fill-regexp.
+	(Sorting): Update definition of sort-lines.
+	(Columns): Clarify behavior of sort-columns.
+	(Indent Tabs): Link to Tab Stops in Emacs manual.
+	(Special Properties): Clarify.
+	(Clickable Text): Mention Buttons package.
+
+2006-08-12  Kevin Ryde  <user42@zip.com.au>
+
+	* os.texi (Time Parsing): Add %z to description of
+	format-time-string, as per docstring.  Add cross reference to
+	glibc manual for strftime.
+
+2006-08-08  Richard Stallman  <rms@gnu.org>
+
+	* modes.texi: Clean up wording in previous change.
+
+2006-08-07  Chong Yidong  <cyd@stupidchicken.com>
+
+	* modes.texi (Hooks): Clarify.
+	(Major Mode Basics): Mention define-derived-mode explicitly.
+	(Major Mode Conventions): Rebinding RET is OK for some modes.
+	Mention change-major-mode-hook and after-change-major-mode-hook.
+	(Example Major Modes): Moved to end of Modes section.
+	(Mode Line Basics): Clarify.
+	(Mode Line Data): Mention help-echo and local-map in strings.
+	Explain reason for treatment of non-risky variables.
+	(Properties in Mode): Clarify.
+	(Faces for Font Lock): Add font-lock-negation-char-face.
+
+2006-08-04  Eli Zaretskii  <eliz@gnu.org>
+
+	* strings.texi (Formatting Strings): Warn against arbitrary
+	strings as first arg to `format'.
+
+2006-07-31  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* text.texi (Clickable Text): Mention `help-echo' text property.
+	Update intro, examples and associated explanations.
+
+2006-07-31  Richard Stallman  <rms@gnu.org>
+
+	* commands.texi: Update xrefs.
+	(Event Mod): New node, cut out from old Translating Input.
+
+	* maps.texi: Update xrefs.
+
+	* keymaps.texi (Translation Keymaps): New node.
+	Update xrefs from Translating Input to Translation Keymaps.
+
+	* elisp.texi (Top): Update subnode menu.
+
+	* display.texi (Face Functions): Fix explanations of FRAME=t or nil.
+
+	* os.texi (System Interface): Fix menu descriptions of some nodes.
+	(Translating Input): Node deleted.
+
+2006-07-31  Nick Roberts  <nickrob@snap.net.nz>
+
+	* modes.texi (Minor Mode Conventions): Update xref for add-to-list.
+
+	* lists.texi (Sets And Lists): Likewise.
+
+2006-07-30  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* text.texi (Fields): Mention POS
+	requirement when narrowing is in effect.
+
+2006-07-28  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Face Attributes): Simplify wording.
+	(Attribute Functions): Clarify meaning of new-frame default
+	attribute settings.
+
+	* customize.texi (Common Keywords): Document how to use
+	:package-version in a package not in Emacs.
+
+2006-07-28  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Reading One Event): Fix last change.
+
+2006-07-26  Chong Yidong  <cyd@stupidchicken.com>
+
+	* commands.texi (Reading One Event): Document SECONDS argument for
+	read-event, read-char, and read-char-exclusive.
+
+2006-07-25  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline
+	to ensure correct identification.
+
+2006-07-24  Richard Stallman  <rms@gnu.org>
+
+	* text.texi (Clickable Text): Clarify.
+
+	* sequences.texi (Vector Functions): Delete duplicate xref.
+
+	* objects.texi (Function Type): Clarify.
+
+	* modes.texi (Keymaps and Minor Modes): List punct chars for minor
+	modes.
+
+	* lists.texi (List Variables): New node.
+	Material moved from other nodes.
+
+	* variables.texi (Setting Variables): add-to-list and
+	add-to-ordered-list moved to List Variables node.
+
+2006-07-23  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* text.texi (Links and Mouse-1):
+	For mouse-on-link-p, expand on arg POS.
+
+2006-07-21  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Forcing Redisplay): Don't mention systems which
+	don't support sub-second timers for redisplay-preemption-period.
+
+	* os.texi (Terminal Output): Clarify text vs graphical terminal.
+
+2006-07-21  Eli Zaretskii  <eliz@gnu.org>
+
+	* frames.texi (Input Focus): Document that focus-follows-mouse has
+	no effect on MS-Windows.
+
+2006-07-18  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Forcing Redisplay): Cleanups in previous change.
+
+	* processes.texi (Low-Level Network): Make menu more convenient.
+
+2006-07-18  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Forcing Redisplay): redisplay-preemption-period
+	only used on window systems.  Add xref to Terminal Output.
+
+	* os.texi (Terminal Output): baud-rate only controls preemption on
+	non-window systems.  Add xref to Forcing Redisplay.
+
+	* processes.texi (Low-Level Network): Rename node "Make Network"
+	to "Network Processes".
+
+2006-07-18  Karl Berry  <karl@gnu.org>
+
+	* variables.texi, functions.texi, customize.texi, loading.texi:
+	* edebug.texi, minibuf.texi: Fix page breaks through chapter 20.
+
+2006-07-17  Chong Yidong  <cyd@stupidchicken.com>
+
+	* commands.texi (Waiting): Document batch-mode sit-for behavior.
+
+2006-07-17  Richard Stallman  <rms@gnu.org>
+
+	* eval.texi, elisp.texi, text.texi: Use real doublequote inside menus.
+	Put period and comma inside quotes.
+
+	* loading.texi, markers.texi: Use real doublequote inside menus.
+
+	* windows.texi: Put point and comma inside quotes.
+	(Textual Scrolling): Use @samp for error message.
+
+	* variables.texi, tips.texi, syntax.texi, symbols.texi:
+	* strings.texi, streams.texi, processes.texi, os.texi:
+	* objects.texi, numbers.texi, modes.texi, minibuf.texi:
+	* lists.texi, keymaps.texi, intro.texi, hash.texi, internals.texi:
+	* gpl.texi, functions.texi, files.texi, frames.texi, doclicense.texi:
+	* display.texi, control.texi, commands.texi, buffers.texi, anti.texi:
+	Put point and comma inside quotes.
+
+	* control.texi (Processing of Errors): Add command-error-function.
+
+	* variables.texi (File Local Variables): Clarify that
+	file local variables make buffer-local bindings.
+
+	* modes.texi (Syntactic Font Lock): Give default for
+	font-lock-syntax-table.
+
+2006-07-17  Nick Roberts  <nickrob@snap.net.nz>
+
+	* text.texi (Special Properties): Clean up previous change.
+
+2006-07-16  Karl Berry  <karl@gnu.org>
+
+	* objects.texi, numbers.texi, strings.texi, lists.texi, hash.texi:
+	* control.texi: Fix bad page breaks through chapter 10 (control).
+
+	* anti.texi (Antinews): Reorder face-attribute fns to avoid
+	underfull hbox.
+
+2006-07-15  Nick Roberts  <nickrob@snap.net.nz>
+
+	* text.texi (Special Properties): Describe fontified text property
+	in relation to a character (not text).
+
+2006-07-15  Kim F. Storm  <storm@cua.dk>
+
+	* maps.texi (Standard Keymaps): Add xref for minibuffer maps.
+	Add apropos-mode-map, custom-mode-map, esc-map, global-map,
+	grep-mode-map, help-map, help-mode-map, kmacro-map, and tool-bar-map.
+
+	* anti.texi (Antinews): Mention redisplay function.
+	The kbd macro existed, but was not documented, before 22.x.
+	Function pos-visible-in-window-p is not new in 22.x, just enhanced.
+
+2006-07-14  Nick Roberts  <nickrob@snap.net.nz>
+
+	* display.texi (Displaying Messages): Add anchor.
+
+	* frames.texi (Dialog Boxes): Use it.
+
+2006-07-12  Richard Stallman  <rms@gnu.org>
+
+	* objects.texi (Frame Type): Explain nature of frames better.
+
+	* frames.texi (Frames): Explain nature of frames better.
+
+2006-07-12  Ken Manheimer  <ken.manheimer@gmail.com>
+
+	* tips.texi (Coding Conventions): Explain why use cl at compile time.
+
+2006-07-12  YAMAMOTO Mitsuharu  <mituharu@math.s.chiba-u.ac.jp>
+
+	* frames.texi (Window System Selections): Mention scrap support for Mac.
+	Default value of x-select-enable-clipboard is t on Mac.
+
+	* os.texi (Getting Out): Suspending is not allowed on Mac, either.
+
+2006-07-11  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Forcing Redisplay): Add `redisplay' function.
+	Don't mention (sit-for -1) -- use (redisplay t) instead.
+
+	* commands.texi (Waiting): (sit-for -1) is no longer special.
+	(sit-for 0) is equivalent to (redisplay).
+	Iconifying/deiconifying no longer makes sit-for return.
+
+2006-07-10  Nick Roberts  <nickrob@snap.net.nz>
+
+	* display.texi (Buttons): Fix typo.
+
+	* index.texi, elisp.texi (New Symbols): Comment node out.
+
+2006-07-09  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Truncation): Clean up previous change.
+
+2006-07-08  Richard Stallman  <rms@gnu.org>
+
+	* commands.texi (Interactive Call): Use 3 as prefix in example
+	for execute-extended-command.
+
+	* display.texi (Attribute Functions): Move paragraph about
+	compatibility with Emacs < 21.
+
+2006-07-09  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Refresh Screen): Clarify force-window-update.
+	(Truncation): "Normally" indicated by fringe arrows.
+
+2006-07-08  Eli Zaretskii  <eliz@gnu.org>
+
+	* windows.texi (Textual Scrolling, Resizing Windows):
+	* variables.texi (Constant Variables):
+	* text.texi (Buffer Contents, Deletion, Changing Properties)
+	(Property Search, Special Properties, Sticky Properties)
+	(Links and Mouse-1, Fields, Change Hooks):
+	* syntax.texi (Syntax Table Functions, Parsing Expressions)
+	(Categories):
+	* symbols.texi (Other Plists):
+	* streams.texi (Output Variables):
+	* processes.texi (Input to Processes, Query Before Exit):
+	* positions.texi (Word Motion, Text Lines, List Motion):
+	* os.texi (Init File, System Environment, Sound Output)
+	(Session Management):
+	* nonascii.texi (Text Representations, Character Sets)
+	(Chars and Bytes, Locales):
+	* modes.texi (Defining Minor Modes, Header Lines):
+	* minibuf.texi (Minibuffer Contents):
+	* markers.texi (Information from Markers):
+	* lists.texi (List Elements, Building Lists, Association Lists):
+	* keymaps.texi (Tool Bar):
+	* hash.texi (Creating Hash, Hash Access, Defining Hash, Other Hash):
+	* functions.texi (What Is a Function, Mapping Functions):
+	* frames.texi (Creating Frames, Parameter Access, Pointer Shape)
+	(Color Names, Text Terminal Colors, Display Feature Testing):
+	* files.texi (Visiting Functions, File Name Components)
+	(Unique File Names, Contents of Directories):
+	* display.texi (Forcing Redisplay, Displaying Messages)
+	(Temporary Displays, Font Selection, Auto Faces)
+	(Font Lookup, Fringe Indicators, Display Margins)
+	(Image Descriptors, Showing Images, Image Cache, Button Types)
+	(Making Buttons, Manipulating Buttons, Button Buffer Commands)
+	(Display Table Format, Glyphs):
+	* control.texi (Iteration):
+	* commands.texi (Command Loop Info, Adjusting Point):
+	* backups.texi (Making Backups, Auto-Saving):
+	Remove @tindex entries.
+
+2006-07-07  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Fringe Cursors): Fix typo.
+	(Customizing Bitmaps): Fix define-fringe-bitmap entry.
+	(Overlay Arrow): Default is overlay-arrow fringe indicator.
+
+2006-07-05  Richard Stallman  <rms@gnu.org>
+
+	* text.texi (Buffer Contents): Add example of text props
+	in result of buffer-substring.
+	(Text Properties): Explain better about use of specific property names.
+	(Property Search): Some cleanups; reorder some functions.
+
+	* keymaps.texi (Changing Key Bindings): Cleanup.
+	Add xref to Key Binding Conventions.
+
+	* display.texi (Attribute Functions): Add examples for
+	face-attribute-relative-p.
+
+	* tips.texi (Coding Conventions): Cleanup last change.
+
+2006-07-05  Karl Berry  <karl@gnu.org>
+
+	* elisp.texi: Use @fonttextsize 10pt, a la emacs.texi.
+	Remove @setchapternewpage odd.
+	Result is 1013 pages, down from 1100.
+
+	* anti.texi, customize.texi, display.texi, internals.texi:
+	* minibuf.texi, modes.texi, tips.texi:
+	Fix overfull/underfull boxes.
+
+2006-07-05  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* edebug.texi (Instrumenting):
+	Add Edebug-specific findex for eval-buffer.
+	* loading.texi (Loading):
+	Replace eval-current-buffer with eval-buffer.
+
+2006-06-30  Nick Roberts  <nickrob@snap.net.nz>
+
+	* locals.texi (Standard Buffer-Local Variables): Update the list
+	of variables.
+
+2006-06-26  Nick Roberts  <nickrob@snap.net.nz>
+
+	* files.texi (File Name Completion): Point user to the node
+	"Reading File Names".
+
+2006-06-24  Eli Zaretskii  <eliz@gnu.org>
+
+	* files.texi (Contents of Directories): Document case-insensitive
+	behavior on respective filesystems.
+
+	* objects.texi (Character Type): Document that Emacs signals an
+	error for unsupported Unicode characters specified as \uNNNN.
+
+2006-06-19  Richard Stallman  <rms@gnu.org>
+
+	* processes.texi (Bindat Spec): Clarify previous change.
+
+2006-06-16  Richard Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Better explain conventions
+	for definition constructs.
+
+	* text.texi (Special Properties): String value of `read-only'
+	serves as the error message.
+
+	* objects.texi (Character Type): Clarify prev. change.
+	(Non-ASCII in Strings): Mention \u and \U.
+
+	* commands.texi (Using Interactive): Explain problem of
+	markers, etc., in command-history.
+
+2006-06-14  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Waiting): Negative arg to sit-for forces
+	redisplay even if input is pending.
+
+	* display.texi (Forcing Redisplay): Use (sit-for -1) to force a
+	redisplay.  Remove incorrect example of binding redisplay-dont-pause
+	around (sit-for 0).
+
+2006-06-13  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Forcing Redisplay): Clarify previous change.
+
+2006-06-13  Romain Francoise  <romain@orebokech.com>
+
+	* display.texi (Forcing Redisplay): Fix typo.
+
+2006-06-13  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Forcing Redisplay): Add redisplay-preemption-period.
+
+2006-06-10  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* tips.texi (Coding Conventions): Add `@end itemize'.
+
+2006-06-10  Richard Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Explain use of coding systems
+	to ensure one decoding for strings.
+
+2006-06-09  Aidan Kehoe  <kehoea@parhasard.net>
+
+	* objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF
+	syntax.
+
+2006-06-07  Eli Zaretskii  <eliz@gnu.org>
+
+	* display.texi (Font Selection): Remove description of
+	clear-face-cache.
+
+	* compile.texi (Eval During Compile): Fix a typo.  Add index
+	entries for possible uses of eval-when-compile.
+
+2006-06-04  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* display.texi (Abstract Display): Fix typo.
+
+2006-06-03  Eli Zaretskii  <eliz@gnu.org>
+
+	* minibuf.texi (Minibuffer History) <history-add-new-input>:
+	Reword variable's description.
+
+2006-06-01  Richard Stallman  <rms@gnu.org>
+
+	* windows.texi (Splitting Windows): Clarify splitting nonselected
+	window.
+
+2006-05-31  Juri Linkov  <juri@jurta.org>
+
+	* minibuf.texi (Minibuffer History): Add history-add-new-input.
+
+2006-05-30  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Line Height): Fix errors in description of
+	default line height and line-height properyty.
+
+	* nonascii.texi (Default Coding Systems): Further clarification.
+
+2006-05-29  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* internals.texi (Pure Storage): Mention that an overflow in pure
+	space causes a memory leak.
+	(Garbage Collection): If there was an overflow in pure space,
+	`garbage-collect' returns nil.
+
+2006-05-30  Eli Zaretskii  <eliz@gnu.org>
+
+	* nonascii.texi (Default Coding Systems): Fix it some more.
+
+2006-05-29  Eli Zaretskii  <eliz@gnu.org>
+
+	* nonascii.texi (Default Coding Systems): Fix last change.
+
+2006-05-29  Kenichi Handa  <handa@m17n.org>
+
+	* nonascii.texi (find-operation-coding-system): Describe the new
+	argument format (FILENAME . BUFFER).
+
+2006-05-28  Richard Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Better explain reasons not to
+	advise other packages or use `eval-after-load'.
+
+2006-05-29  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Bindat Functions): Rename `pos' and `raw-data' to
+	`bindat-idx' and `bindat-raw' for clarity.
+
+2006-05-27  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* processes.texi (Bindat Spec): Expand on `repeat' handler.
+
+	* display.texi (Display): Add "Abstract Display" to menu.
+	(Abstract Display, Abstract Display Functions)
+	(Abstract Display Example): New nodes.
+	* elisp.texi (Top): Add "Abstract Display" to menu.
+
+2006-05-27  Chong Yidong  <cyd@stupidchicken.com>
+
+	* keymaps.texi (Key Sequences): Link to input events definition.
+	(Format of Keymaps): Delete material duplicated in Keymap Basics.
+
+	* files.texi (Changing Files): Document updated argument list for
+	copy-file.
+
+2006-05-27  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* processes.texi (Bindat Functions): Explain term "total length".
+	Use it in bindat-length and bindat-pack descriptions.
+
+2006-05-26  Eli Zaretskii  <eliz@gnu.org>
+
+	* tips.texi (Coding Conventions): Advise against using
+	eval-after-load in packages.  Add an index entry.
+
+2006-05-25  Juri Linkov  <juri@jurta.org>
+
+	* minibuf.texi (Text from Minibuffer): Undocument keep-all.
+
+	* modes.texi (%-Constructs): Add %e, %z, %Z.
+
+2006-05-25  Richard Stallman  <rms@gnu.org>
+
+	* elisp.texi (Top): Update subnode menu.
+
+	* keymaps.texi (Keymap Basics): New node, split out of Key Sequences.
+	(Keymaps): Update menu.
+
+2006-05-25  Chong Yidong  <cyd@stupidchicken.com>
+
+	* keymaps.texi (Key Sequences): Some clarifications.
+
+2006-05-25  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* processes.texi (Bindat Functions): Say "unibyte string"
+	explicitly for bindat-unpack and bindat-pack descriptions.
+	(Bindat Examples): Don't call `string-make-unibyte' in example.
+
+2006-05-25  Chong Yidong  <cyd@stupidchicken.com>
+
+	* keymaps.texi (Key Sequences): Renamed from Keymap Terminology.
+	Explain string and vector representations of key sequences
+
+	* keymaps.texi (Changing Key Bindings):
+	* commands.texi (Interactive Codes, Interactive Codes):
+	* help.texi (Describing Characters): Refer to it.
+
+2006-05-23  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* frames.texi (Pointer Shape): @end table -> @end defvar.
+
+2006-05-22  Richard Stallman  <rms@gnu.org>
+
+	* elisp.texi (Top): Update subnode menus.
+
+	* frames.texi (Pointer Shape): Node renamed from Pointer Shapes.
+	Contents rewritten; material from old Pointer Shape node moved here.
+
+	* display.texi (Pointer Shape): Node deleted.
+	(Image Descriptors): Minor cleanup.
+
+2006-05-21  Richard Stallman  <rms@gnu.org>
+
+	* syntax.texi (Parsing Expressions): Update info on which STATE
+	elements are ignored.
+
+2006-05-19  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* hooks.texi (Standard Hooks): Correct typo.
+
+	* gpl.texi (GPL): ifinfo -> ifnottex.
+
+2006-05-19  Michael Ernst  <mernst@alum.mit.edu>  (tiny change)
+
+	* searching.texi (Simple Match Data): Warn about match data being
+	set anew by every search.
+
+2006-05-17  Richard Stallman  <rms@gnu.org>
+
+	* minibuf.texi (Minibuffer History): Clarify.
+
+	* searching.texi (Regexp Special): Clarify nested regexp warning.
+
+2006-05-16  Kim F. Storm  <storm@cua.dk>
+
+	* minibuf.texi (Minibuffer History): Update add-to-history.
+
+2006-05-15  Oliver Scholz  <epameinondas@gmx.de>  (tiny change)
+
+	* nonascii.texi (Explicit Encoding): Fix
+	typo (encoding<->decoding).
+
+2006-05-14  Richard Stallman  <rms@gnu.org>
+
+	* buffers.texi (Creating Buffers): Cleanup.
+
+	* files.texi (Visiting Functions): Rewrite in find-file-noselect.
+
+2006-05-13  Eli Zaretskii  <eliz@gnu.org>
+
+	* buffers.texi (Current Buffer): Document that with-temp-buffer
+	disables undo.
+
+	* os.texi (Terminal-Specific): More accurate description of how
+	Emacs searches for the terminal-specific libraries.
+
+2006-05-12  Eli Zaretskii  <eliz@gnu.org>
+
+	* hooks.texi (Standard Hooks) [iftex]: Convert @xref's to
+	emacs-xtra to @inforef's.
+
+	* text.texi (Undo): Document that undo is turned off in buffers
+	whose names begin with a space.
+
+	* buffers.texi (Buffer Names): Add index entries for buffers whose
+	names begin with a space.
+	(Creating Buffers): Document that undo is turned off in buffers
+	whose names begin with a space.
+
+	* files.texi (Visiting Functions, Reading from Files)
+	(Saving Buffers): Mention code and EOL conversions by file I/O
+	primitives and subroutines.
+
+	* nonascii.texi (Lisp and Coding Systems): Document
+	coding-system-eol-type.  Add index entries for eol conversion.
+
+	* display.texi (Defining Faces): Mention `mac', and add an xref to
+	where window-system is described.
+
+2006-05-10  Richard Stallman  <rms@gnu.org>
+
+	* internals.texi (Writing Emacs Primitives): Clarify GCPRO rules.
+
+2006-05-10  Reiner Steib  <Reiner.Steib@gmx.de>
+
+	* variables.texi (File Local Variables): Recommend to quote lambda
+	expressions in safe-local-variable property.
+
+2006-05-09  Richard Stallman  <rms@gnu.org>
+
+	* variables.texi (File Local Variables): Document
+	safe-local-eval-forms and safe-local-eval-function.
+
+2006-05-07  Kim F. Storm  <storm@cua.dk>
+
+	* minibuf.texi (Minibuffer History): Remove keep-dups arg
+	from add-to-history.
+
+2006-05-07  Romain Francoise  <romain@orebokech.com>
+
+	* commands.texi (Event Input Misc):
+	* compile.texi (Eval During Compile):
+	* internals.texi (Buffer Internals):
+	* minibuf.texi (Initial Input):
+	* nonascii.texi (Scanning Charsets):
+	* numbers.texi (Comparison of Numbers):
+	* windows.texi (Textual Scrolling, Vertical Scrolling):
+	Fix various typos.
+
+2006-05-06  Eli Zaretskii  <eliz@gnu.org>
+
+	* hooks.texi (Standard Hooks): Replace inforef to emacs-xtra by
+	conditional xref's to either emacs or emacs-xtra, depending on
+	@iftex/@ifnottex.
+
+	* minibuf.texi (Minibuffer History): Document add-to-history.
+
+2006-05-05  Eli Zaretskii  <eliz@gnu.org>
+
+	* internals.texi (Pure Storage): Mention the pure overflow message
+	at startup.
+
+2006-05-05  Johan Bockg,Ae(Brd  <bojohan@dd.chalmers.se>
+
+	* keymaps.texi (Active Keymaps): Fix pseudo-Lisp syntax.
+	(Searching Keymaps): Fix pseudo-Lisp description of keymap
+	search.
+
+2006-05-01  Richard Stallman  <rms@gnu.org>
+
+	* intro.texi (nil and t): Clarify.
+
+	* variables.texi (File Local Variables): Suggest using booleanp.
+
+2006-05-01  Juanma Barranquero  <lekktu@gmail.com>
+
+	* objects.texi (Type Predicates): Fix typos.
+
+2006-05-01  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* intro.texi (nil and t): Add booleanp.
+
+	* objects.texi (Type Predicates): Add links for booleanp and
+	string-or-null-p.
+
+2006-04-29  Richard Stallman  <rms@gnu.org>
+
+	* modes.texi (Multiline Font Lock): Rename from
+	Multi line Font Lock Elements.  Much clarification.
+	(Font Lock Multiline, Region to Fontify): Much clarification.
+
+2006-04-29  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* variables.texi (File Local Variables): Remove the special case t for
+	safe-local-variable.
+
+2006-04-26  Richard Stallman  <rms@gnu.org>
+
+	* syntax.texi (Parsing Expressions): Minor cleanup.
+
+2006-04-18  Richard Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Explain when the package's
+	prefix should appear later on (not at the start of the name).
+
+	* searching.texi (String Search): Clarify effect of NOERROR.
+
+	* modes.texi (Imenu): Clarify what special items do.
+
+	* hooks.texi (Standard Hooks): Delete text about old hook names.
+
+2006-04-17  Romain Francoise  <romain@orebokech.com>
+
+	* variables.texi (Local Variables): Update the default value of
+	`max-specpdl-size'.
+
+2006-04-15  Michael Olson  <mwolson@gnu.org>
+
+	* processes.texi (Transaction Queues): Mention the new optional
+	`delay-question' argument for `tq-enqueue'.
+
+2006-04-13  Bill Wohler  <wohler@newt.com>
+
+	* customize.texi (Common Keywords): Use dotted notation for
+	:package-version value.  Specify its values.  Improve documentation
+	for customize-package-emacs-version-alist.
+
+2006-04-12  Bill Wohler  <wohler@newt.com>
+
+	* customize.texi (Common Keywords): Move description of
+	customize-package-emacs-version-alist to @defvar.
+
+2006-04-10  Bill Wohler  <wohler@newt.com>
+
+	* customize.texi (Common Keywords): Add :package-version.
+
+2006-04-10  Kim F. Storm  <storm@cua.dk>
+
+	* text.texi (Buffer Contents): Add NOPROPS arg to
+	filter-buffer-substring.
+
+2006-04-08  Kevin Ryde  <user42@zip.com.au>
+
+	* os.texi (Command-Line Arguments): Update xref to emacs manual
+	"Command Arguments" -> "Emacs Invocation", per change there.
+
+2006-04-08  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* display.texi (Other Display Specs): Arrange a @code{DOTTED-LIST} to
+	be on one line to help makeinfo not render two spaces after the dot.
+
+2006-04-07  Reiner Steib  <Reiner.Steib@gmx.de>
+
+	* strings.texi (Predicates for Strings): Add string-or-null-p.
+
+2006-03-28  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Accepting Output): Remove obsolete (and incorrect)
+	remarks about systems that don't support fractional seconds.
+
+2006-03-25  Karl Berry  <karl@gnu.org>
+
+	* elisp.texi: Use @copyright{} instead of (C), and do not indent
+	the year list.
+
+2006-03-21  Nick Roberts  <nickrob@snap.net.nz>
+
+	* display.texi (Fringe Indicators): Fix typos.
+
+2006-03-19  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* tips.texi (Documentation Tips): One can now also write `program'
+	in front of a quoted symbol in a docstring to prevent making a
+	hyperlink.
+
+2006-03-19  Alan Mackenzie  <acm@muc.de>
+
+	* text.texi (Special Properties): Clarify `fontified' property.
+
+2006-03-16  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Defining Images): Minor cleanup.
+
+2006-03-16  Bill Wohler  <wohler@newt.com>
+
+	* display.texi (Defining Images): In image-load-path-for-library,
+	prefer user's images.
+
+2006-03-15  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* modes.texi (Region to Fontify): Remove font-lock-lines-before.
+
+2006-03-15  Bill Wohler  <wohler@newt.com>
+
+	* display.texi (Defining Images): Fix example in
+	image-load-path-for-library by not recommending that one binds
+	image-load-path.  Just defvar it to placate compiler and only use
+	it if previously defined.
+
+2006-03-14  Bill Wohler  <wohler@newt.com>
+
+	* display.texi (Defining Images): In image-load-path-for-library,
+	always return list of directories.  Update example.
+
+2006-03-14  Alan Mackenzie  <acm@muc.de>
+
+	* modes.texi: New node, "Region to Fontify" (for Font Lock).
+	This describes font-lock-extend-region-function.
+	("Other Font Lock Variables"): Move "font-lock-lines-before" to
+	the new node "Region to Fontify".
+
+2006-03-13  Richard Stallman  <rms@gnu.org>
+
+	* display.texi (Invisible Text): The impossible position is
+	now before the invisible text, not after.
+	(Defining Images): Clean up last change.
+
+2006-03-11  Bill Wohler  <wohler@newt.com>
+
+	* display.texi (Defining Images): Add image-load-path-for-library.
+
+2006-03-11  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* text.texi (Adaptive Fill): Fix Texinfo usage.
+
+	* strings.texi (Creating Strings): Fix Texinfo usage.
+
+	* searching.texi (Regexp Special): Use @samp for regular
+	expressions that are not in Lisp syntax.
+
+2006-03-08  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* searching.texi (Regexp Special): Put remark between parentheses
+	to avoid misreading.
+
+2006-03-07  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* searching.texi (Syntax of Regexps): More accurately describe
+	which characters are special in which situations.
+	(Regexp Special): Recommend _not_ to quote `]' or `-' when they
+	are not special.  Describe in detail when `[' and `]' are special.
+	(Regexp Backslash): Plenty of regexps with unbalanced square
+	brackets are valid, so reword that statement.
+
+2006-03-02  Kim F. Storm  <storm@cua.dk>
+
+	* keymaps.texi (Tool Bar): Add tool-bar-border.
+
+2006-02-28  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* loading.texi (Load Suffixes): Rephrase last paragraph.  Fix typos.
+
+2006-02-27  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* elisp.texi (Top): Include "Load Suffixes" in the detailed menu.
+
+	* files.texi (Locating Files): Suggest additional values for the
+	SUFFIXES arg of `locate-file'.  Update pxref.
+
+	* loading.texi (Loading): Include new node "Load Suffixes" in menu.
+	(How Programs Do Loading): Discuss the effects of Auto Compression
+	mode on `load'.
+	(Load Suffixes): New node.
+	(Library Search): Delete description of `load-suffixes'; it was
+	moved to "Load Suffixes".
+	(Autoload, Named Features): Mention `load-suffixes'.
+
+2006-02-21  Giorgos Keramidas  <keramida@ceid.upatras.gr>  (tiny change)
+
+	* display.texi (Fringe Indicators, Fringe Cursors): Fix typos.
+
+	* windows.texi (Window Tree): Fix typo.
+
+2006-02-20  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Fringe Indicators): New section.
+	Move indicate-empty-lines, indicate-buffer-boundaries, and
+	default-indicate-buffer-boundaries here.
+	Add fringe-indicator-alist and default-fringes-indicator-alist.
+	Add list of logical fringe indicator symbols.
+	Update list of standard bitmap names.
+	(Fringe Cursors): New section.
+	Move overflow-newline-into-fringe here.
+	Add fringe-cursor-alist and default-fringes-cursor-alist.
+	Add list of fringe cursor symbols.
+
+2006-02-20  Juanma Barranquero  <lekktu@gmail.com>
+
+	* commands.texi (Using Interactive): Fix reference to node
+	"Minibuffers".
+
+2006-02-19  Richard M. Stallman  <rms@gnu.org>
+
+	* minibuf.texi (High-Level Completion):
+	Add xref to read-input-method-name.
+
+	* files.texi (Relative File Names): Move file-relative-name here.
+	(File Name Expansion): From here.  Minor clarifications.
+
+	* commands.texi (Using Interactive): Add xrefs about reading input.
+	Clarify remarks about that moving point and mark.
+	Put string case before list case.
+
+2006-02-16  Johan Bockg,Ae(Brd  <bojohan@dd.chalmers.se>
+
+	* display.texi (Other Display Specs, Image Descriptors):
+	Revert erroneous changes.  The previous description of
+	image-descriptors as `(image . PROPS)' was correct.
+
+2006-02-14  Richard M. Stallman  <rms@gnu.org>
+
+	* variables.texi (File Local Variables): Clarifications.
+
+2006-02-14  Juanma Barranquero  <lekktu@gmail.com>
+
+	* variables.texi (File Local Variables): Use @code for a cons
+	cell, not @var.
+
+2006-02-13  Chong Yidong  <cyd@stupidchicken.com>
+
+	* variables.texi (File Local Variables): Document new file local
+	variable behavior.
+
+2006-02-10  Kim F. Storm  <storm@cua.dk>
+
+	* eval.texi (Function Indirection): Add NOERROR to indirect-function.
+
+2006-02-08  Juanma Barranquero  <lekktu@gmail.com>
+
+	* modes.texi (%-Constructs): Remove obsolete info about
+	`global-mode-string'.
+
+2006-02-07  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Prefix Command Arguments): Minor cleanup.
+
+	* display.texi: "Graphical display", not window system.
+
+	* functions.texi (What Is a Function): Fix xref.
+
+	* keymaps.texi (Key Lookup): Clarify wrt commands vs other functions.
+	(Changing Key Bindings): Clarify when remapping is better than
+	substitute-key-definition.
+
+2006-02-02  Richard M. Stallman  <rms@gnu.org>
+
+	* minibuf.texi (Basic Completion): Completion alists are risky.
+
+	* keymaps.texi (Active Keymaps): Clarifications.
+	(Searching Keymaps): New node.
+	(Keymaps): Update menu.
+
+	* frames.texi (Layout Parameters): Minor clarification.
+	(Drag and Drop): New node.
+	(Frames): Update menu.
+
+2006-01-29  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Other Display Specs, Image Descriptors):
+	Image description is a list, not a cons cell.
+
+2006-01-28  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* lists.texi (Cons Cells): Minor correction (the cdr of a dotted
+	list is not necessarily a list).
+
+2006-01-27  Eli Zaretskii  <eliz@gnu.org>
+
+	* frames.texi (Layout Parameters): border-width and
+	internal-border-width belong to the frame, not the window.
+
+2006-01-19  Richard M. Stallman  <rms@gnu.org>
+
+	* nonascii.texi (Translation of Characters): Search cmds use
+	translation-table-for-input.  Automatically made local.
+
+	* markers.texi (Overview of Markers): Count insertion type
+	as one of a marker's attributes.
+
+	* keymaps.texi (Controlling Active Maps): New node, split out of
+	Active Keymaps.
+	(Keymaps): Menu updated.
+	(Active Keymaps): Give pseudocode to explain how the active
+	maps are searched.  current-active-maps and key-binding moved here.
+	(Functions for Key Lookup): current-active-maps and key-binding moved.
+	Clarifications.
+	(Searching the Keymaps): New subnode.
+
+	* elisp.texi (Top): Menu clarification.
+
+	* display.texi (Other Display Specs): Delete duplicate entry for
+	just a string as display spec.  Move text about recursive display
+	specs on such a string.
+
+	* commands.texi (Key Sequence Input): Clarify.
+	Move num-nonmacro-input-events out.
+	(Reading One Event): num-nonmacro-input-events moved here.
+
+2006-01-14  Nick Roberts  <nickrob@snap.net.nz>
+
+	* advice.texi (Simple Advice): Update example to fit argument
+	change in previous-line.
+
+2006-01-05  Richard M. Stallman  <rms@gnu.org>
+
+	* markers.texi (The Mark): Fix in `mark'.
+
+2006-01-04  Richard M. Stallman  <rms@gnu.org>
+
+	* processes.texi (Misc Network, Make Network): Minor cleanups.
+
+2006-01-04  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Make Network): Add IPv6 addresses and handling.
+	(Network Feature Testing): Mention (:family ipv6).
+	(Misc Network): Add IPv6 formats to format-network-address.
+
+2005-12-30  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Changing Properties):
+	Don't use return value of set-text-properties.
+
+2005-12-29  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* modes.texi (Mode Line Format): Correct typo in menu.
+
+2005-12-29  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Mode Line Top): New node.
+	(Mode Line Data): Some text moved to new node.
+	Explain the data structure more concretely.
+	(Mode Line Basics): Clarifications.
+	(Mode Line Variables): Clarify intro paragraph.
+	(%-Constructs): Clarify intro paragraph.
+	(Mode Line Format): Update menu.
+
+2005-12-28  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* minibuf.texi (Basic Completion): Update lazy-completion-table
+	examples for removal of ARGS argument.
+
+2005-12-23  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Undo): Restore some explanation from the version
+	that was deleted.
+
+2005-12-23  Eli Zaretskii  <eliz@gnu.org>
+
+	* text.texi (Undo): Remove duplicate descriptions of `apply
+	funname' and `apply delta' elements of the undo list.
+
+2005-12-20  Richard M. Stallman  <rms@gnu.org>
+
+	* help.texi (Help Functions): Update documentation of `apropos'.
+
+2005-12-20  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* customize.texi (Type Keywords): Delete xref to "Text help-echo",
+	because it is confusing.  If the :help-echo keyword is a function,
+	it is not directly used as the :help-echo overlay property, as the
+	xref seems to suggest (it does not take the appropriate args).
+
+2005-12-19  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* customize.texi (Common Keywords): Fix Texinfo usage.
+	(Group Definitions, Variable Definitions): Update for new
+	conventions for using `*' in docstrings.
+
+	* tips.texi (Documentation Tips): Update for new conventions for
+	using `*' in docstrings.
+
+2005-12-16  Richard M. Stallman  <rms@gnu.org>
+
+	* minibuf.texi (Minibuffer Contents): Minor cleanup.
+
+2005-12-16  Juri Linkov  <juri@jurta.org>
+
+	* minibuf.texi (Minibuffer Contents): Add minibuffer-completion-contents.
+
+2005-12-14  Romain Francoise  <romain@orebokech.com>
+
+	* modes.texi (Customizing Keywords): Rename `append' to `how'.
+	Fix typo.
+
+2005-12-11  Juri Linkov  <juri@jurta.org>
+
+	* minibuf.texi (Completion Commands): Add mention of read-file-name
+	for filename completion keymaps.
+	(Reading File Names): Add mention of filename completion keymaps
+	for read-file-name and xref to `Completion Commands'.
+
+2005-12-10  Richard M. Stallman  <rms@gnu.org>
+
+	* customize.texi (Common Keywords): State caveats for use of :tag.
+
+2005-12-08  Richard M. Stallman  <rms@gnu.org>
+
+	* minibuf.texi (Intro to Minibuffers): Replace list of local maps
+	with xrefs and better explanation.
+	(Completion Commands): Add the filename completion maps.
+
+	* objects.texi (Character Type): Clarify that \s is not space
+	if a dash follows.
+
+2005-12-05  Richard M. Stallman  <rms@gnu.org>
+
+	* windows.texi (Resizing Windows): Delete preserve-before args.
+
+2005-12-05  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* keymaps.texi (Format of Keymaps): Remove mention of a quirk
+	in full keymaps, since the quirk has been fixed.
+
+2005-12-03  Eli Zaretskii  <eliz@gnu.org>
+
+	* hooks.texi (Standard Hooks): Add index entries.  Mention
+	`compilation-finish-functions'.
+
+2005-11-27  Richard M. Stallman  <rms@gnu.org>
+
+	* windows.texi (Resizing Windows): Add adjust-window-trailing-edge.
+
+2005-11-21  Juri Linkov  <juri@jurta.org>
+
+	* customize.texi (Common Keywords): Update links types
+	custom-manual and url-link.  Add link types emacs-library-link,
+	file-link, function-link, variable-link, custom-group-link.
+
+2005-11-20  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi: Revert 2005-11-20 change.
+
+2005-11-20  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* processes.texi (Bindat Functions):
+	Say "third" to refer to zero-based index "2".
+
+2005-11-18  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* loading.texi (Library Search): Update the default value of
+	`load-suffixes'.
+
+2005-11-17  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Attribute Functions): Mention :ignore-defface.
+
+2005-11-16  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* modes.texi (Minor Mode Conventions): Use custom-set-minor-mode.
+	(Minor Mode Conventions): Mention the use of a hook.
+
+2005-11-06  Richard M. Stallman  <rms@gnu.org>
+
+	* files.texi (Magic File Names): find-file-name-handler checks the
+	`operations' property of the handler.
+
+2005-11-03  Richard M. Stallman  <rms@gnu.org>
+
+	* variables.texi (Frame-Local Variables): Small clarification.
+
+2005-10-29  Chong Yidong  <cyd@stupidchicken.com>
+
+	* os.texi (Init File): Document ~/.emacs.d/init.el.
+
+2005-10-29  Richard M. Stallman  <rms@gnu.org>
+
+	* internals.texi (Garbage Collection): Document memory-full.
+
+2005-10-28  Bill Wohler  <wohler@newt.com>
+
+	* tips.texi (Documentation Tips): Help mode now creates hyperlinks
+	for URLs.
+
+2005-10-28  Richard M. Stallman  <rms@gnu.org>
+
+	* minibuf.texi (Completion Commands): Clean up prev change.
+
+2005-10-26  Kevin Ryde  <user42@zip.com.au>
+
+	* compile.texi (Eval During Compile): Explain recommended uses
+	of eval-when-compile and eval-and-compile.
+
+2005-10-27  Masatake YAMATO  <jet@gyve.org>
+
+	* minibuf.texi (Completion Commands):
+	Write about new optional argument for `display-completion-list'.
+
+2005-10-23  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Overlay Arrow): Clarify about local bindings of
+	overlay-arrow-position.
+
+2005-10-22  Eli Zaretskii  <eliz@gnu.org>
+
+	* internals.texi (Building Emacs): Fix last change.
+
+2005-10-22  Richard M. Stallman  <rms@gnu.org>
+
+	* internals.texi (Building Emacs): Document eval-at-startup.
+
+2005-10-21  Richard M. Stallman  <rms@gnu.org>
+
+	* loading.texi (Where Defined): load-history contains abs file names.
+	symbol-file returns abs file names.
+
+2005-10-19  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Showing Images): Add max-image-size integer value.
+
+2005-10-18  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Showing Images): Document max-image-size.
+
+2005-10-17  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Quitting): Minor clarification.
+
+	* processes.texi (Sentinels): Clarify about output and quitting.
+	(Filter Functions): Mention with-local-quit.
+
+2005-10-17  Juri Linkov  <juri@jurta.org>
+
+	* buffers.texi (Current Buffer):
+	* commands.texi (Event Input Misc):
+	* compile.texi (Eval During Compile, Compiler Errors):
+	* customize.texi (Group Definitions):
+	* display.texi (Progress, Defining Faces):
+	* files.texi (Writing to Files):
+	* modes.texi (Mode Hooks, Defining Minor Modes):
+	* streams.texi (Output Functions):
+	* syntax.texi (Syntax Table Functions):
+	* text.texi (Change Hooks):
+	Replace `...' with `@dots{}' in `@defmac' and `@defspec'.
+
+	* commands.texi (Quitting): Replace arg `forms' with `body' in
+	`with-local-quit'.
+
+	* positions.texi (Excursions): Replace arg `forms' with `body' in
+	`save-excursion'.
+
+2005-10-08  Kim F. Storm  <storm@cua.dk>
+
+	* windows.texi (Window Tree): Rename window-split-tree to window-tree.
+	Rename manual section accordingly.
+
+2005-10-04  Kim F. Storm  <storm@cua.dk>
+
+	* windows.texi (Window Split Tree): New section describing
+	new function window-split-tree function.
+
+2005-10-03  Nick Roberts  <nickrob@snap.net.nz>
+
+	* display.texi (Fringe Size/Pos): Simplify and add detail.
+
+2005-09-30  Romain Francoise  <romain@orebokech.com>
+
+	* minibuf.texi (High-Level Completion): Explain that the prompt
+	given to `read-buffer' should end with a colon and a space.
+	Update usage examples.
+
+2005-09-29  Juri Linkov  <juri@jurta.org>
+
+	* display.texi (Displaying Messages): Rename argument name
+	`string' to `format-string' in functions `message', `message-box',
+	`message-or-box'.
+
+2005-09-26  Chong Yidong  <cyd@stupidchicken.com>
+
+	* errors.texi (Standard Errors): Correct xrefs.
+
+2005-09-18  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Defining Images): Update documentation for
+	`image-load-path'.
+
+2005-09-17  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Defining Images): Clean up previous change.
+
+2005-09-16  Romain Francoise  <romain@orebokech.com>
+
+	* elisp.texi: Specify GFDL version 1.2.
+
+	* doclicense.texi (GNU Free Documentation License): Update to
+	version 1.2.
+
+2005-09-15  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Defining Images): Document `image-load-path'.
+
+2005-09-15  Richard M. Stallman  <rms@gnu.org>
+
+	* objects.texi (Printed Representation): Minor cleanup.
+	(Box Diagrams): Minor fix.
+	(Cons Cell Type): Move (...) index item here.
+	(Box Diagrams): From here.
+	(Array Type): Minor fix.
+	(Type Predicates): Delete index "predicates".
+	(Hash Table Type): Clarify xref.
+	(Dotted Pair Notation): Minor fix.
+
+2005-09-10  Chong Yidong  <cyd@stupidchicken.com>
+
+	* files.texi (Saving Buffers): Fix typo.
+
+2005-09-08  Richard M. Stallman  <rms@gnu.org>
+
+	* tips.texi (Programming Tips): Correct the "default" prompt spec.
+
+2005-09-08  Chong Yidong  <cyd@stupidchicken.com>
+
+	* locals.texi (Standard Buffer-Local Variables): Don't include
+	mode variables for minor modes.
+	Fix xrefs for buffer-display-count, buffer-display-table,
+	buffer-offer-save, buffer-saved-size, cache-long-line-scans,
+	enable-multibyte-characters, fill-column, header-line-format,
+	left-fringe-width, left-margin, and right-fringe-width.
+
+	* hooks.texi (Standard Hooks): All hooks should conform to the
+	standard naming convention now.
+	Fix xref for `echo-area-clear-hook'.
+
+	* display.texi (Usual Display): Note that indicate-empty-lines and
+	tab-width are buffer-local.
+
+	* files.texi (Saving Buffers): Add xref to `Killing Buffers'.
+
+	* modes.texi (Mode Help): Note that major-mode is buffer-local.
+
+	* nonascii.texi (Encoding and I/O): Note that
+	buffer-file-coding-system is buffer-local.
+
+	* positions.texi (List Motion): Note that defun-prompt-regexp is
+	buffer-local.
+
+	* text.texi (Auto Filling): Note that auto-fill-function is
+	buffer-local.
+	(Undo): Note that buffer-undo-list is buffer-local.
+
+	* windows.texi (Buffers and Windows): Document
+	buffer-display-count.
+
+2005-09-06  Richard M. Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Sometimes it is ok to put the
+	package prefix elsewhere than at the start of the name.
+
+2005-09-03  Richard M. Stallman  <rms@gnu.org>
+
+	* tips.texi (Programming Tips): Add conventions for minibuffer
+	questions and prompts.
+
+2005-09-03  Joshua Varner  <jlvarner@gmail.com>  (tiny change)
+
+	* intro.texi (nil and t): Minor cleanup.
+	Delete spurious mention of keyword symbols.
+	(Evaluation Notation): Add index entry.
+	(A Sample Function Description): Minor cleanup.
+	(A Sample Variable Description): Not all vars can be set.
+
+2005-09-03  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* text.texi (Buffer Contents): Use "\n" in examples' result strings.
+
+	(Insertion): Document precise type of `insert-char' arg COUNT.
+
+2005-09-02  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* modes.texi (Other Font Lock Variables): Sync the default of
+	font-lock-lines-before.
+
+2005-08-31  Michael Albinus  <michael.albinus@gmx.de>
+
+	* files.texi (Magic File Names): Add `make-auto-save-file-name'.
+
+2005-08-29  Richard M. Stallman  <rms@gnu.org>
+
+	* elisp.texi (Top): Update subnode menu.
+
+	* searching.texi (Searching and Matching): Move node.
+	Rearrange contents and add overall explanation.
+	(Searching and Case): Move node.
+	(Searching and Matching): Update menu.
+
+2005-08-27  Eli Zaretskii  <eliz@gnu.org>
+
+	* os.texi (Startup Summary): Fix the description of the initial
+	startup message display.
+
+2005-08-25  Richard M. Stallman  <rms@gnu.org>
+
+	* searching.texi (Search and Replace): Add replace-regexp-in-string.
+
+2005-08-25  Emilio C. Lopes  <eclig@gmx.net>
+
+	* display.texi (Finding Overlays): Fix `find-overlay-prop' in
+	`next-overlay-change' example.
+
+2005-08-22  Juri Linkov  <juri@jurta.org>
+
+	* display.texi (Attribute Functions): Add set-face-inverse-video-p.
+	Fix invert-face.  Fix args of face-background.
+
+	* display.texi (Standard Faces): Delete node.
+	(Faces): Add xref to `(emacs)Standard Faces'.
+	(Displaying Faces): Fix xref to `Standard Faces'.
+
+	* modes.texi (Mode Line Data): Fix xref to Standard Faces.
+
+2005-08-20  Alan Mackenzie  <acm@muc.de>
+
+	* buffers.texi (The Buffer List): Clarify the manipulation of the
+	buffer list.
+
+2005-08-14  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Auto Major Mode): interpreter-mode-alist key is not
+	a regexp.
+
+2005-08-11  Richard M. Stallman  <rms@gnu.org>
+
+	* elisp.texi (Top): Update subnode lists.
+
+	* display.texi (Inverse Video): Node deleted.
+
+	* tips.texi (Key Binding Conventions, Programming Tips, Warning Tips):
+	New nodes split out of Coding Conventions.
+
+	* searching.texi (Regular Expressions): Document re-builder.
+
+	* os.texi (Time Parsing): New node split out of Time Conversion.
+
+	* processes.texi (Misc Network, Network Feature Testing)
+	(Network Options, Make Network): New nodes split out of
+	Low-Level Network.
+
+2005-08-09  Richard M. Stallman  <rms@gnu.org>
+
+	* frames.texi (Geometry): New node, split from Size and Position.
+	(Frame Parameters): Refer to Geometry.
+
+	* buffers.texi (The Buffer List): Fix xrefs.
+
+	* windows.texi (Splitting Windows): Fix xref.
+
+	* frames.texi (Layout Parameters): Add xref.
+
+	* display.texi (Line Height, Scroll Bars): Fix xrefs.
+
+	* keymaps.texi (Menu Bar): Fix xref.
+
+	* locals.texi (Standard Buffer-Local Variables): Fix xref.
+
+	* modes.texi (%-Constructs): Fix xref.
+
+	* frames.texi (Window Frame Parameters): Node split up.
+	(Basic Parameters, Position Parameters, Size Parameters)
+	(Layout Parameters, Buffer Parameters, Management Parameters)
+	(Cursor Parameters, Color Parameters): New subnodes.
+
+2005-08-09  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* positions.texi (Screen Lines): Update xref for previous change
+	in minibuf.texi.
+
+	* minibuf.texi (Intro to Minibuffers): Update pxref for previous
+	change in minibuf.texi.
+
+2005-08-09  Richard M. Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Minor cleanup.
+
+	* modes.texi (Defining Minor Modes): Explain when init-value
+	can be non-nil.
+
+	* elisp.texi (Top): Update submenu for Minibuffer.
+
+	* minibuf.texi (Minibuffer Misc): Node split up.
+	(Minibuffer Commands, Minibuffer Windows, Minibuffer Contents)
+	(Recursive Mini): New nodes split out from Minibuffer Misc.
+	(Minibuffer Misc): Document max-mini-window-height.
+
+	* hash.texi (Defining Hash): Delete stray paren in example.
+
+	* display.texi (Echo Area Customization): Don't define
+	max-mini-window-height here; xref instead.
+
+	* commands.texi (Event Input Misc): Update while-no-input.
+
+	* advice.texi (Advising Functions): Explain when to use advice
+	and when to use a hook.
+
+2005-07-30  Eli Zaretskii  <eliz@gnu.org>
+
+	* makefile.w32-in (info): Don't run install-info.
+	($(infodir)/dir): New target, produced by running install-info.
+
+2005-07-27  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* modes.texi (Defining Minor Modes): The keyword for the initial
+	value is :init-value, not :initial-value.
+
+2005-07-23  Eli Zaretskii  <eliz@gnu.org>
+
+	* loading.texi (Autoload): Make the `doctor' example be consistent
+	with what's in current loaddefs.el.  Describe the "fn" magic in
+	the usage portion of the doc string.
+
+2005-07-22  Richard M. Stallman  <rms@gnu.org>
+
+	* internals.texi (Garbage Collection): Clarify previous change.
+
+2005-07-21  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* internals.texi (Garbage Collection): Add gc-cons-percentage.
+
+2005-07-18  Juri Linkov  <juri@jurta.org>
+
+	* commands.texi (Accessing Events):
+	* frames.texi (Text Terminal Colors, Resources):
+	* markers.texi (The Mark):
+	* modes.texi (Defining Minor Modes):
+	Delete duplicate duplicate words.
+
+2005-07-16  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Managing Overlays): Clarify make-overlay
+	args for insertion types.
+
+2005-07-13  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* customize.texi (Variable Definitions):
+	Add `custom-initialize-safe-set' and `custom-initialize-safe-default'.
+	`standard-value' is a list too.
+	(Defining New Types): Use @key{RET} instead of @key{ret}.
+
+2005-07-13  Francis Litterio  <franl@world.std.com>  (tiny change)
+
+	* os.texi (Translating Input): Fix typo.
+
+2005-07-08  Richard M. Stallman  <rms@gnu.org>
+
+	* README: Update edition number and size estimate.
+
+	* elisp.texi (VERSION): Set to 2.9.
+
+2005-07-07  Richard M. Stallman  <rms@gnu.org>
+
+	* book-spine.texinfo: Update Emacs version.
+
+	* display.texi (Inverse Video): Delete mode-line-inverse-video.
+
+2005-07-06  Richard M. Stallman  <rms@gnu.org>
+
+	* searching.texi (Regexp Search): Clarify what re-search-forward
+	does when the search fails.
+
+2005-07-05  Lute Kamstra  <lute@gnu.org>
+
+	* Update FSF's address in GPL notices.
+
+	* doclicense.texi (GNU Free Documentation License):
+	* gpl.texi (GPL):
+	* tips.texi (Coding Conventions, Library Headers):
+	* vol1.texi:
+	* vol2.texi: Update FSF's address.
+
+2005-07-04  Richard M. Stallman  <rms@gnu.org>
+
+	* hooks.texi (Standard Hooks): Add occur-hook.
+
+2005-07-03  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* display.texi (The Echo Area): Correct menu.
+
+2005-07-03  Richard M. Stallman  <rms@gnu.org>
+
+	* elisp.texi (Top): Update subnode menu for Display.
+
+	* display.texi (Displaying Messages): New node, with most
+	of what was in The Echo Area.
+	(Progress): Moved under The Echo Area.
+	(Logging Messages): New node with new text.
+	(Echo Area Customization): New node, the rest of what was
+	in The Echo Area.  Document message-truncate-lines with @defvar.
+	(Display): Update menu.
+
+	* windows.texi (Textual Scrolling): Doc 3 values for
+	scroll-preserve-screen-position.
+
+	* text.texi (Special Properties): Change hook functions
+	should bind inhibit-modification-hooks around altering buffer text.
+
+	* keymaps.texi (Key Binding Commands): Call binding BINDING
+	rather than DEFINITION.
+
+2005-06-29  Juanma Barranquero  <lekktu@gmail.com>
+
+	* variables.texi (Defining Variables): `user-variable-p' returns t
+	for aliases of user options, nil for alias loops.
+
+2005-06-28  Richard M. Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Creating Keymaps): Put make-sparse-keymap before
+	make-keymap.
+
+2005-06-27  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* variables.texi (Setting Variables): Correct and clarify
+	description of `add-to-ordered-list'.
+
+2005-06-26  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Faces): Minor cleanup.
+
+2005-06-25  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* display.texi (Faces): `facep' returns t for strings that are
+	face names.
+
+2005-06-25  Richard M. Stallman  <rms@gnu.org>
+
+	* objects.texi (Equality Predicates): Clarify meaning of equal.
+
+	* windows.texi (Selecting Windows): save-selected-window
+	and with-selected-window save and restore the current buffer.
+
+2005-06-24  Richard M. Stallman  <rms@gnu.org>
+
+	* numbers.texi (Float Basics): Explain how to test for NaN,
+	and printing the sign of NaNs.
+
+2005-06-24  Eli Zaretskii  <eliz@gnu.org>
+
+	* makefile.w32-in (MAKEINFO): Use --force.
+
+2005-06-23  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Face Functions): Correct Texinfo usage.
+
+2005-06-23  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* lists.texi (Rings): `ring-elements' now returns the elements of
+	RING in order.
+
+2005-06-23  Juanma Barranquero  <lekktu@gmail.com>
+
+	* markers.texi (The Mark): Texinfo usage fix.
+
+2005-06-23  Kim F. Storm  <storm@cua.dk>
+
+	* searching.texi (Entire Match Data): Remove evaporate option for
+	match-data.  Do not mention evaporate option for set-match-data.
+
+2005-06-22  Glenn Morris  <gmorris@ast.cam.ac.uk>
+
+	* display.texi (Face Functions): Mention face aliases.
+
+2005-06-21  Richard M. Stallman  <rms@gnu.org>
+
+	* anti.texi (Antinews): Texinfo usage fix.
+
+2005-06-21  Karl Berry  <karl@gnu.org>
+
+	* elisp.texi: Use @copying.
+
+	* elisp.texi: Put @summarycontents and @contents before the Top
+	node, instead of the end of the file, so that the contents appear
+	in the right place in the dvi/pdf output.
+
+2005-06-21  Juri Linkov  <juri@jurta.org>
+
+	* display.texi (Defining Faces): Add `customized-face'.
+
+2005-06-20  Kim F. Storm  <storm@cua.dk>
+
+	* variables.texi (Setting Variables): Any type of element can be
+	given order in add-to-ordered-list.  Compare elements with eq.
+
+	* lists.texi (Rearrangement): Sort predicate may just return non-nil.
+
+2005-06-20  Karl Berry  <karl@gnu.org>
+
+	* syntax.texi (Syntax Flags): Make last column very slightly wider
+	to avoid "generic comment" breaking on two lines and causing an
+	underfull box.
+
+2005-06-19  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* lists.texi (Rings): Various minor clarifications and corrections.
+
+2005-06-18  Richard M. Stallman  <rms@gnu.org>
+
+	* functions.texi (Obsolete Functions): Simplify.
+
+	* variables.texi (Variable Aliases): Simplify.
+
+	* anti.texi, backups.texi, compile.texi, customization.texi:
+	* debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi:
+	* functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi:
+	* os.texi, processes.texi, searching.texi, strings.texi, text.texi:
+	* variables.texi: Fix formatting ugliness.
+
+	* elisp.texi: Add links to Rings and Byte Packing.
+	Update version and copyright years.
+
+	* minibuf.texi: Fix formatting ugliness.
+	(Completion Commands): Move keymap vars to the end
+	and vars completing-read binds to the top.
+
+2005-06-17  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* processes.texi: Fix typos.
+	(Bindat Spec): Correct Texinfo error.
+	(Byte Packing): Fix ungrammatical sentence.
+
+2005-06-17  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* lists.texi (Rings): New node.
+	(Lists): Add it to menu.
+
+	* processes.texi (Byte Packing): New node.
+	(Processes): Add it to menu.
+
+2005-06-17  Richard M. Stallman  <rms@gnu.org>
+
+	* syntax.texi (Parsing Expressions): Fix texinfo usage.
+
+	* help.texi (Documentation Basics): Explain the xref to
+	Documentation Tips.
+
+	* debugging.texi (Debugger Commands): Minor fix.
+
+2005-06-16  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* edebug.texi (Instrumenting): Eliminate duplicate link.
+	(Specification List): Replace references to "below", referring to
+	a later node, with one @ref to that node.
+
+	* os.texi (Timers): Timers should save and restore the match data
+	if they change it.
+
+	* debugging.texi (Debugger Commands): Mention that the Lisp
+	debugger can not step through primitive functions.
+
+2005-06-16  Juanma Barranquero  <lekktu@gmail.com>
+
+	* functions.texi (Obsolete Functions): Update argument names of
+	`make-obsolete' and `define-obsolete-function-alias'.
+
+	* variables.texi (Variable Aliases): Update argument names of
+	`defvaralias', `make-obsolete-variable' and
+	`define-obsolete-variable-alias'.
+
+2005-06-15  Kim F. Storm  <storm@cua.dk>
+
+	* searching.texi (Entire Match Data): Rephrase warnings about
+	evaporate arg to match-data and set-match-data.
+
+2005-06-14  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* elisp.texi (Top): Update detailed menu.
+
+	* edebug.texi (Edebug): Update menu.
+	(Instrumenting): Update xrefs.
+	(Edebug Execution Modes): Correct xref.
+	(Jumping): Clarify description of `h' command.
+	Eliminate redundant @ref.
+	(Breaks): New node.
+	(Breakpoints): Is now a subsubsection.
+	(Global Break Condition): Mention `C-x X X'.
+	(Edebug Views): Clarify `v' and `p'.  Mention `C-x X w'.
+	(Trace Buffer): Clarify STRING arg of `edebug-tracing'.
+	(Edebug Display Update): Correct pxref.
+	(Edebug and Macros): New node.
+	(Instrumenting Macro Calls): Is now a subsubsection.
+	Neither arg of `def-edebug-spec' is evaluated.
+	(Instrumenting Macro Calls): Mention `edebug-eval-macro-args'.
+	(Specification Examples): Fix typo.
+
+2005-06-14  Lute Kamstra  <lute@gnu.org>
+
+	* debugging.texi (Function Debugging): Primitives can break on
+	entry too.
+
+2005-06-14  Kim F. Storm  <storm@cua.dk>
+
+	* variables.texi (Setting Variables): Add add-to-ordered-list.
+
+2005-06-13  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* syntax.texi (Parsing Expressions): Document aux functions and vars of
+	syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function.
+
+2005-06-13  Lute Kamstra  <lute@gnu.org>
+
+	* text.texi (Special Properties): Fix cross reference.
+
+2005-06-11  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* debugging.texi (Function Debugging): Delete mention of empty
+	string argument to `cancel-debug-on-entry'.  Delete inaccurate
+	description of the return value of that command.
+
+2005-06-11  Alan Mackenzie  <acm@muc.de>
+
+	* text.texi (Adaptive Fill): Amplify the description of
+	fill-context-prefix.
+
+2005-06-10  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* syntax.texi (Parsing Expressions): Fix Texinfo error.
+
+2005-06-10  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* syntax.texi (Parsing Expressions): Document syntax-ppss.
+
+2005-06-10  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* debugging.texi (Error Debugging): Minor rewording.
+	(Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry'
+	is optional.
+
+2005-06-10  Lute Kamstra  <lute@gnu.org>
+
+	* elisp.texi: Use EMACSVER to refer to the current version of Emacs.
+	(Top): Give it a title.  Correct version number.  Give the
+	detailed node listing a more prominent header.
+	* intro.texi: Don't set VERSION here a second time.
+	Mention Emacs's version too.
+	* anti.texi (Antinews): Use EMACSVER to refer to the current
+	version of Emacs.
+
+2005-06-09  Kim F. Storm  <storm@cua.dk>
+
+	* searching.texi (Entire Match Data): Explain new `reseat' argument to
+	match-data and set-match-data.
+
+2005-06-08  Richard M. Stallman  <rms@gnu.org>
+
+	* searching.texi (Entire Match Data): Clarify when match-data
+	returns markers and when integers.
+
+	* display.texi (Defining Faces): Explain that face name should not
+	end in `-face'.
+
+	* modes.texi (Mode Line Data): Minor cleanup.
+	(Customizing Keywords): Node split out of Search-based Fontification.
+	Add example of using font-lock-add-keywords from a hook.
+	Clarify when MODE should be non-nil, and when nil.
+
+2005-06-06  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Mode Line Data): Explain what happens when the car
+	of a list is a void symbol.
+	(Search-based Fontification): Explain MODE arg to
+	font-lock-add-keywords and warn about calls from major modes.
+
+2005-06-08  Juri Linkov  <juri@jurta.org>
+
+	* display.texi (Standard Faces): Add `shadow' face.
+
+2005-05-29  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* modes.texi (Major Mode Conventions): A derived mode only needs
+	to put the call to the parent mode inside `delay-mode-hooks'.
+
+2005-05-29  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Mode Hooks): Explain that after-change-major-mode-hook is
+	new, and what that implies.  Clarify.
+
+	* files.texi (Locating Files): Clean up the text.
+
+	* frames.texi (Window Frame Parameters): Document user-size.
+	Shorten entry for top by referring to left.
+
+2005-05-26  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Mode Hooks): Explain that after-change-major-mode-hook
+	is new, and what the implications are.  Other clarifications.
+
+2005-05-24  Richard M. Stallman  <rms@gnu.org>
+
+	* frames.texi (Dialog Boxes): Minor fixes.
+
+2005-05-25  Masatake YAMATO  <jet@gyve.org>
+
+	* display.texi (Standard Faces): Write about `mode-line-highlight'.
+
+2005-05-24  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* frames.texi (Dialog Boxes): HEADER argument to `x-popup-dialog'
+	is optional.
+
+2005-05-24  Nick Roberts  <nickrob@snap.net.nz>
+
+	* frames.texi (Dialog Boxes): Descibe new optional argument.
+
+2005-05-23  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Font Lock Basics, Syntactic Font Lock): Recommend
+	syntax-begin-function over font-lock-beginning-of-syntax-function.
+
+2005-05-21  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* minibuf.texi (Reading File Names): Update description of
+	`read-directory-name'.
+
+	* modes.texi (Derived Modes): Clarify :group keyword.
+
+2005-05-21  Eli Zaretskii  <eliz@gnu.org>
+
+	* files.texi (Locating Files): New subsection.
+	Describe locate-file and executable-find.
+
+2005-05-21  Kevin Ryde  <user42@zip.com.au>
+
+	* frames.texi (Initial Parameters): Update cross reference to
+	"Emacs Invocation".
+
+2005-05-19  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* keymaps.texi (Active Keymaps): Add anchor.
+
+	* modes.texi (Hooks): Delete confusing and unnecessary sentence.
+	(Major Mode Conventions): Refer to `Auto Major Mode' in more
+	appropriate place.
+	(Derived Modes): Small clarifications.
+	(Minor Mode Conventions, Keymaps and Minor Modes):
+	Replace references to nodes with references to anchors.
+	(Mode Line Data): Warn that `(:eval FORM)' should not load any files.
+	Clarify description of lists whose first element is an integer.
+	(Mode Line Variables): Add anchor.
+	(%-Constructs): Clarify description of integer after %.
+	(Emulating Mode Line): Describe nil value for FACE.
+
+2005-05-18  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* modes.texi (Derived Modes): Correct references to non-existing
+	variable standard-syntax-table.
+
+2005-05-17  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Defining Minor Modes): Mention the mode hook.
+
+2005-05-15  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Network): Remove open-network-stream-nowait.
+	(Network Servers): Remove open-network-stream-server.
+
+2005-05-15  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* elisp.texi (Top): Update detailed menu.
+
+	* variables.texi: Reorder nodes.
+	(Variables): Update menu.
+	(File Local Variables): Do not refer to the `-*-' line as
+	a "local variables list".  Add pxref.
+
+2005-05-14  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* elisp.texi (Top): Update detailed menu for node changes.
+
+	* modes.texi (Modes): Update Menu.
+	(Hooks): Move to beginning of chapter.
+	Most minor modes run mode hooks too.
+	`add-hook' can handle void hooks or hooks whose value is a single
+	function.
+	(Major Modes): Update Menu.
+	(Major Mode Basics): New node, split off from `Major Modes'.
+	(Major Mode Conventions): Correct xref.  Explain how to handle
+	auto-mode-alist if the major mode command has an autoload cookie.
+	(Auto Major Mode): Major update.  Add magic-mode-alist.
+	(Derived Modes): Major update.
+	(Mode Line Format): Update Menu.
+	(Mode Line Basics): New node, split off from `Mode Line Format'.
+
+	* loading.texi (Autoload): Mention `autoload cookie' as synonym
+	for `magic autoload comment'.  Add index entries and anchor.
+
+2005-05-14  Richard M. Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Explain how important it is
+	that just loading certain files not change Emacs behavior.
+
+	* modes.texi (Defining Minor Modes): Define define-global-minor-mode.
+
+2005-05-12  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Generic Modes): Update.
+	(Major Modes): Refer to node "Generic Modes".
+
+	* elisp.texi (Top): Update to the current structure of the manual.
+	* processes.texi (Processes): Add menu description.
+	* customize.texi (Customization): Add menu descriptions.
+
+2005-05-11  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* processes.texi (Signals to Processes)
+	(Low-Level Network): Fix typos.
+
+2005-05-11  Lute Kamstra  <lute@gnu.org>
+
+	* elisp.texi (Top): Add some nodes from the chapter "Major and
+	Minor Modes" to the detailed node listing.
+
+2005-05-10  Richard M. Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Extended Menu Items): Menu item filter functions
+	can be called at any time.
+
+2005-05-08  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* variables.texi (File Local Variables): `(hack-local-variables t)'
+	now also checks whether a mode is specified in the local variables
+	list.
+
+2005-05-05  Kevin Ryde  <user42@zip.com.au>
+
+	* display.texi (The Echo Area): Correct format function cross
+	reference.
+
+2005-05-05  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* variables.texi (Variable Aliases): Change description of
+	`define-obsolete-variable-alias'.
+
+	* functions.texi (Functions): Add "Obsolete Functions" to menu.
+	(Defining Functions): Add xref.
+	(Obsolete Functions): New node.
+	(Function Safety): Standardize capitalization of section title.
+
+	* frames.texi (Pop-Up Menus): Complete description of `x-popup-menu'.
+	(Dialog Boxes): Complete description of `x-popup-dialog'.
+
+2005-05-04  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Interactive Codes): Fix Texinfo usage.
+	Document U more clearly.
+
+2005-05-01  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* variables.texi (Variable Aliases): `make-obsolete-variable' is a
+	function and not a macro.
+
+	* frames.texi (Pop-Up Menus): Correct and clarify description of
+	`x-popup-menu'.
+	(Dialog Boxes): Clarify description of `x-popup-dialog'.
+
+2005-05-01  Richard M. Stallman  <rms@gnu.org>
+
+	* edebug.texi (Checking Whether to Stop): Fix previous change.
+
+2005-05-01  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* display.texi: Fix typos and Texinfo usage.
+
+	* edebug.texi (Checking Whether to Stop): executing-macro ->
+	executing-kbd-macro.
+
+2005-05-01  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Invisible Text): Correct add-to-invisibility-spec.
+
+2005-04-30  Richard M. Stallman  <rms@gnu.org>
+
+	* files.texi (Magic File Names): Document `operations' property.
+
+2005-04-29  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Generic Modes): New node.
+	(Major Modes): Add it to the menu.
+	(Derived Modes): Add "derived mode" to concept index.
+
+2005-04-28  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Defining Minor Modes): Fix previous change.
+	(Font Lock Mode): Simplify.
+	(Font Lock Basics): Say that font-lock-defaults is buffer-local
+	when set and that some parts are optional.  Add cross references.
+	(Search-based Fontification): Say how to specify font-lock-keywords.
+	Add cross references.  Add font-lock-multiline to index.
+	Move font-lock-keywords-case-fold-search here from node "Other Font
+	Lock Variables".  Document font-lock-add-keywords and
+	font-lock-remove-keywords.
+	(Other Font Lock Variables): Move font-lock-keywords-only,
+	font-lock-syntax-table, font-lock-beginning-of-syntax-function,
+	and font-lock-syntactic-face-function to node "Syntactic Font
+	Lock".  Move font-lock-keywords-case-fold-search to node
+	"Search-based Fontification".  Document font-lock-inhibit-thing-lock
+	and font-lock-{,un}fontify-{buffer,region}-function.
+	(Precalculated Fontification): Remove reference to deleted variable
+	font-lock-core-only.
+	(Faces for Font Lock): Add font-lock-comment-delimiter-face.
+	(Syntactic Font Lock): Add intro.  Move font-lock-keywords-only,
+	font-lock-syntax-table, font-lock-beginning-of-syntax-function,
+	and font-lock-syntactic-face-function here from node "Other Font
+	Lock Variables".  Move font-lock-syntactic-keywords to "Setting
+	Syntax Properties".  Add cross references.
+	(Setting Syntax Properties): New node.
+	Move font-lock-syntactic-keywords here from "Syntactic Font Lock".
+	* syntax.texi (Syntax Properties): Add cross reference.
+	* hooks.texi (Standard Hooks): Add Font-Lock hooks.
+
+2005-04-26  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Defining Faces):
+	Document `default' elements of defface spec.
+
+	* modes.texi (Major Mode Conventions): Explain customizing ElDoc mode.
+
+	* variables.texi (Variable Aliases): Clarify text.
+
+2005-04-25  Chong Yidong  <cyd@stupidchicken.com>
+
+	* windows.texi (Window Hooks): Remove reference to obsolete Lazy Lock.
+
+2005-04-25  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* hooks.texi (Standard Hooks): Most minor modes have mode hooks too.
+
+2005-04-24  Eli Zaretskii  <eliz@gnu.org>
+
+	* syntax.texi (Syntax Table Internals): Elaborate documentation of
+	syntax-after and syntax-class.
+
+	* files.texi (Changing Files): Fix last change's cross-reference.
+	(Unique File Names): Don't mention "numbers" in the documentation
+	of make-temp-file and make-temp-name.
+
+2005-04-23  Richard M. Stallman  <rms@gnu.org>
+
+	* files.texi (Changing Files): Document MUSTBENEW arg in copy-file.
+
+2005-04-22  Nick Roberts  <nickrob@snap.net.nz>
+
+	* windows.texi (Cyclic Window Ordering): Clarify window-list.
+
+2005-04-22  Nick Roberts  <nickrob@snap.net.nz>
+
+	* variables.texi (Variable Aliases): Describe make-obsolete-variable
+	and define-obsolete-variable-alias.
+
+2005-04-22  Kim F. Storm  <storm@cua.dk>
+
+	* symbols.texi (Symbol Plists): Remove safe-get, as get is now safe.
+	(Other Plists): Remove safe-plist-get, as plist-get is now safe.
+
+2005-04-21  Lute Kamstra  <lute@gnu.org>
+
+	* lists.texi (Association Lists): Document rassq-delete-all.
+
+2005-04-19  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Search-based Fontification): Explain that
+	facespec is an expression to be evaluated.
+
+2005-04-19  Kevin Ryde  <user42@zip.com.au>
+
+	* streams.texi (Output Functions): Fix xref.
+	* strings.texi (String Conversion): Fix xref.
+
+2005-04-19  Kim F. Storm  <storm@cua.dk>
+
+	* symbols.texi (Symbol Plists): Add safe-get.
+	Mention that `get' may signal an error.
+
+2005-04-18  Nick Roberts  <nickrob@snap.net.nz>
+
+	* customize.texi (Variable Definitions): Replace tooltip-mode
+	example with save-place.
+
+2005-04-17  Richard M. Stallman  <rms@gnu.org>
+
+	* buffers.texi (Indirect Buffers): Clarify.
+
+	* positions.texi (Positions): Clarify converting marker to integer.
+
+	* strings.texi (String Basics): Mention string-match; clarify.
+
+2005-04-08  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Search-based Fontification): Fix cross references.
+	Use consistent terminology.  Document anchored highlighting.
+
+2005-04-05  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Defining Minor Modes): Document :group keyword
+	argument and its default value.
+
+2005-04-03  Lute Kamstra  <lute@gnu.org>
+
+	* hooks.texi (Standard Hooks): Add some hooks.  Add cross
+	references and/or descriptions.  Delete major mode hooks; mention
+	them as a category instead.  Rename or delete obsolete hooks.
+
+2005-04-02  Richard M. Stallman  <rms@gnu.org>
+
+	* nonascii.texi (Coding System Basics): Another wording cleanup.
+
+2005-04-01  Richard M. Stallman  <rms@gnu.org>
+
+	* nonascii.texi (Coding System Basics): Clarify previous change.
+
+2005-04-01  Kenichi Handa  <handa@m17n.org>
+
+	* nonascii.texi (Coding System Basics): Describe about rondtrip
+	identity of coding systems.
+
+2005-03-29  Chong Yidong  <cyd@stupidchicken.com>
+
+	* text.texi (Buffer Contents): Add filter-buffer-substring and
+	buffer-substring-filters.
+
+2005-03-26  Chong Yidong  <cyd@stupidchicken.com>
+
+	* anti.texi (Antinews): Mention `G' interactive code.
+
+	* tips.texi (Compilation Tips): Mention benchmark.el.
+
+2005-03-27  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* modes.texi (Other Font Lock Variables): `font-lock-fontify-block'
+	is now bound to M-o M-o.
+
+	* keymaps.texi (Prefix Keys): `facemenu-keymap' is now on M-o.
+
+2005-03-26  Glenn Morris  <gmorris@ast.cam.ac.uk>
+
+	* calendar.texi: Delete file (and move contents to emacs-xtra.texi
+	in the Emacs Manual).
+	* Makefile.in (srcs): Remove calendar.texi.
+	* makefile.w32-in (srcs): Remove calendar.texi.
+	* display.texi (Display): Change name of next node.
+	* os.texi (System In): Change name of previous node.
+	* elisp.texi (Top): Remove Calendar references.
+	* vol1.texi (Top): Remove Calendar references.
+	* vol2.texi (Top): Remove Calendar references.
+
+2005-03-25  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Standard Faces, Fringe Bitmaps, Customizing Bitmaps):
+	Cleanup previous change.
+
+2005-03-25  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Face Attributes): Faces earlier in an :inherit
+	list take precedence.
+	(Scroll Bars): Fix description of vertical-scroll-bars.
+	Document frame-current-scroll-bars and window-current-scroll-bars.
+
+	* markers.texi (The Mark): Document temporary Transient Mark mode.
+
+	* minibuf.texi (Reading File Names):
+	Document read-file-name-completion-ignore-case.
+
+	* positions.texi (Screen Lines): Document nil for width argument
+	to compute-motion.
+
+2005-03-23  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Standard Faces): Other faces used in the fringe
+	implicitly inherits from the fringe face.
+	(Fringe Bitmaps): FACE in right-fringe and left-fringe display
+	properties implicitly inherits from fringe face.
+	(Customizing Bitmaps): Likewise for set-fringe-bitmap-face.
+
+2005-03-20  Chong Yidong  <cyd@stupidchicken.com>
+
+	* display.texi (Invisible Text): State default value of
+	line-move-ignore-invisible.
+	(Managing Overlays): Document remove-overlays.
+	(Standard Faces): Document escape-glyph face.
+
+	* minibuf.texi (Reading File Names): Document read-file-name-function.
+
+	* modes.texi (Other Font Lock Variables):
+	Document font-lock-lines-before.
+
+	* positions.texi (Skipping Characters): skip-chars-forward allows
+	character classes.
+
+2005-03-18  Lute Kamstra  <lute@gnu.org>
+
+	* edebug.texi (Instrumenting Macro Calls): Fix another typo.
+
+2005-03-17  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Undo): Document extensible undo entries.
+
+	* searching.texi (String Search, Regexp Search, Regexp Search):
+	Cleanups.
+
+	* nonascii.texi (Character Codes): Minor fix.
+
+	* display.texi (Display Property): Explain the significance
+	of having text properties that are eq.
+	(Other Display Specs): Explain string as display spec.
+
+	* commands.texi (Interactive Codes): Document G option.
+
+2005-03-17  Chong Yidong  <cyd@stupidchicken.com>
+
+	* text.texi (Filling): Add sentence-end-without-period and
+	sentence-end-without-space.
+	(Changing Properties): Minor fix.
+
+	* anti.texi: Total rewrite.
+
+2005-03-15  Lute Kamstra  <lute@gnu.org>
+
+	* edebug.texi (Instrumenting Macro Calls): Fix typos.
+
+2005-03-08  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Specified Space): Property :width is support on
+	non-graphic terminals, :height is not.
+
+2005-03-07  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Overlay Arrow, Fringe Bitmaps, Customizing Bitmaps):
+	Now subnodes of Fringes.
+	(Overlay Arrow): Document overlay-arrow-variable-list.
+	(Fringe Size/Pos): New node, broken out of Fringes.
+	(Display): Explain clearing vs redisplay better.
+	(Truncation): Clarify use of bitmaps.
+	(The Echo Area): Clarify the uses of the echo area.
+	Add max-mini-window-height.
+	(Progress): Clarify.
+	(Invisible Text): Explain that main loop moves point out.
+	(Selective Display): Say "hidden", not "invisible".
+	(Managing Overlays): Move up.  Describe relation to Undo here.
+	(Overlay Properties): Clarify intro.
+	(Finding Overlays): Explain return values when nothing found.
+	(Width): truncate-string-to-width has added arg.
+	(Displaying Faces): Clarify and update mode line face handling.
+	(Face Functions): Minor cleanup.
+	(Conditional Display): Merge into Other Display Specs.
+	(Pixel Specification, Other Display Specs): Minor cleanups.
+	(Images, Image Descriptors): Minor cleanups.
+	(GIF Images): Patents have expired.
+	(Showing Images): Explain default text for insert-image.
+	(Manipulating Button Types): Merge into Manipulating Buttons.
+	(Making Buttons): Explain return values.
+	(Button Buffer Commands): Add xref.
+	(Inverse Video): Update mode-line-inverse-video.
+	(Display Table Format): Clarify.
+	(Active Display Table): Give defaults for window-display-table.
+
+	* calendar.texi (Calendar Customizing): calendar-holiday-marker
+	and calendar-today-marker are strings, not chars.
+	(Holiday Customizing): Minor fix.
+
+	* internals.texi (Writing Emacs Primitives): Update `or' example.
+	Update limit on # args of subr.
+
+	* edebug.texi (Using Edebug): Arrow is in fringe.
+	(Instrumenting): Arg to eval-defun works without loading edebug.
+	(Edebug Execution Modes): Add xref.
+
+	* customize.texi (Common Keywords): Clarify :require.
+	Mention :version here.
+	(Variable Definitions, Group Definitions): Not here.
+	(Variable Definitions): Clarify symbol arg to :initialize and :set fns.
+
+2005-03-07  Chong Yidong  <cyd@stupidchicken.com>
+	* nonascii.texi (Text Representations): Clarify position-bytes.
+	(Character Sets): Add list-charset-chars.
+	(Scanning Charsets): Add charset-after.
+	(Encoding and I/O): Minor fix.
+
+2005-03-06  Richard M. Stallman  <rms@gnu.org>
+
+	* windows.texi (Vertical Scrolling): Get rid of "Emacs 21".
+	(Resizing Windows): Likewise.
+
+	* text.texi (Change Hooks): Get rid of "Emacs 21".
+
+	* strings.texi (Formatting Strings): Get rid of "Emacs 21".
+
+	* streams.texi (Output Variables): Get rid of "Emacs 21".
+
+	* searching.texi (Regexp Special, Char Classes): Get rid of "Emacs 21".
+
+	* os.texi (Translating Input): Replace flow-control example
+	with a less obsolete example that uses `keyboard-translate'.
+
+	* objects.texi (Hash Table Type, Circular Objects):
+	Get rid of "Emacs 21".
+
+	* modes.texi (Mode Line Format): Get rid of "Emacs 21".
+	(Mode Line Data, Properties in Mode, Header Lines): Likewise.
+
+	* minibuf.texi (Minibuffer Misc): Get rid of "Emacs 21".
+
+	* lists.texi (List Elements, Building Lists): Get rid of "Emacs 21".
+
+	* keymaps.texi (Menu Separators, Tool Bar): Get rid of "Emacs 21".
+	(Menu Bar): Fix when menu-bar-update-hook is called.
+
+	* hash.texi (Hash Tables): Get rid of "Emacs 21".
+
+	* frames.texi (Text Terminal Colors): Get rid of "Emacs 21",
+	and make it read better.
+
+	* files.texi (Writing to Files): Get rid of "Emacs 21".
+	(Unique File Names): Likewise.
+
+	* elisp.texi: Update Emacs version to 22.
+
+	* display.texi (Forcing Redisplay): Get rid of "Emacs 21".
+	(Overlay Properties, Face Attributes): Likewise.
+	(Managing Overlays): Fix punctuation.
+	(Attribute Functions): Clarify set-face-font; get rid of
+	info about old Emacs versions.
+	(Auto Faces, Font Lookup, Display Property, Images):
+	Get rid of "Emacs 21".
+
+	* calendar.texi (Calendar Customizing): Get rid of "Emacs 21".
+
+2005-03-05  Richard M. Stallman  <rms@gnu.org>
+
+	* debugging.texi (Error Debugging): Remove stack-trace-on-error.
+
+2005-03-04  Lute Kamstra  <lute@gnu.org>
+
+	* debugging.texi (Error Debugging): Document stack-trace-on-error.
+
+2005-03-03  Lute Kamstra  <lute@gnu.org>
+
+	* edebug.texi (Instrumenting Macro Calls): Fix typo.
+
+2005-03-01  Lute Kamstra  <lute@gnu.org>
+
+	* debugging.texi (Debugger Commands): Update `j'.
+
+2005-02-28  Lute Kamstra  <lute@gnu.org>
+
+	* debugging.texi (Debugging): Fix typo.
+	(Error Debugging): Document eval-expression-debug-on-error.
+	(Function Debugging): Update example.
+	(Using Debugger): Mention starred stack frames.
+	(Debugger Commands): Document `j' and `l'.
+	(Invoking the Debugger): `d' and `j' exit recursive edit too.
+	Update the messages that the debugger displays.
+	(Internals of Debugger): Add cross reference.  Update example.
+	(Excess Open): Minor improvement.
+	(Excess Close): Minor improvement.
+
+2005-02-26  Richard M. Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Clarify.
+	Put all the major mode key reservations together.
+	Mention the Mouse-1 => Mouse-2 conventions.
+
+	* syntax.texi (Syntax Class Table): Clarify.
+	(Syntax Table Functions): syntax-after moved from here.
+	(Syntax Table Internals): syntax-after moved to here.
+	(Parsing Expressions): Update info on number of values
+	and what's meaningful in the STATE argument.
+	(Categories): Fix typo.
+
+	* sequences.texi (Arrays): Cleanup.
+	(Char-Tables): Clarify.
+
+	* processes.texi (Deleting Processes): Cleanups, add xref.
+	(Subprocess Creation): Explain nil in exec-path.  Cleanup.
+	(Process Information): set-process-coding-system, some args optional.
+	(Input to Processes): Explain various types for PROCESS args.
+	Rename them from PROCESS-NAME to PROCESS.
+	(Signals to Processes): Likewise.
+	(Decoding Output): Cleanup.
+	(Query Before Exit): Clarify.
+
+	* os.texi (Startup Summary): Correct the options; add missing ones.
+	(Terminal Output, Batch Mode): Clarify.
+	(Flow Control): Node deleted.
+
+	* markers.texi (The Mark): Clarify.
+
+	* macros.texi (Expansion): Cleanup.
+	(Indenting Macros): indent-spec allows ints, not floats.
+
+	* keymaps.texi (Keymaps): Clarify.
+	(Format of Keymaps): Update lisp-mode-map example.
+	(Active Keymaps, Key Lookup): Clarify.
+	(Changing Key Bindings): Add xref to `kbd'.
+	(Key Binding Commands, Simple Menu Items): Clarify.
+	(Mouse Menus, Menu Bar): Clarify.
+	(Menu Example): Replace print example with menu-bar-replace-menu.
+
+	* help.texi (Documentation Basics): Add function-documentation prop.
+
+	* elisp.texi (Top): Don't refer to Flow Control node.
+
+	* commands.texi (Command Overview): Improve xrefs.
+	(Adjusting Point): Adjusting point applies to intangible and invis.
+	(Key Sequence Input): Doc extra read-key-sequence args.
+	Likewise for read-key-sequence-vector.
+
+	* backups.texi (Rename or Copy): Minor fix.
+	(Numbered Backups): For version-control, say the default.
+	(Auto-Saving): make-auto-save-file-name example is simplified.
+
+	* advice.texi (Advising Functions): Don't imply one part of Emacs
+	should advise another part.  Markup changes.
+	(Defining Advice): Move transitional para.
+	(Activation of Advice): Cleanup.
+	Explain if COMPILE is nil or negative.
+
+	* abbrevs.texi (Abbrev Expansion): Clarify, fix typo.
+
+2005-02-24  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Defining Minor Modes): Explain that INIT-VALUE,
+	LIGHTER, and KEYMAP can be omitted when KEYWORD-ARGS are used.
+
+2005-02-23  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Defining Minor Modes): define-minor-mode can be used
+	to define global minor modes as well.
+
+	* display.texi (Managing Overlays): overlay-buffer returns nil for
+	deleted overlays.
+
+2005-02-22  Kim F. Storm  <storm@cua.dk>
+
+	* minibuf.texi (Basic Completion): Allow symbols in addition to
+	strings in try-completion and all-completions.
+
+2005-02-14  Lute Kamstra  <lute@gnu.org>
+
+	* elisp.texi (Top): Remove reference to deleted node.
+
+	* lists.texi (Lists): Remove reference to deleted node.
+	(Cons Cells): Fix typo.
+
+	* loading.texi (Where Defined): Fix typo.
+
+2005-02-14  Richard M. Stallman  <rms@gnu.org>
+
+	* variables.texi (Creating Buffer-Local): change-major-mode-hook
+	is useful for discarding some minor modes.
+
+	* symbols.texi (Symbol Components): Reorder examples.
+
+	* streams.texi (Input Functions): State standard-input default.
+	(Output Variables): State standard-output default.
+
+	* objects.texi (Printed Representation): Clarify read syntax vs print.
+	(Floating Point Type): Explain meaning better.
+	(Symbol Type): Explain uniqueness better.
+	(Cons Cell Type): Explain empty list sooner.  CAR and CDR later.
+	List examples sooner.
+	(Box Diagrams): New subnode broken out.
+	Some examples moved from old Lists as Boxes node.
+	(Dotted Pair Notation): Clarify intro.
+	(Array Type): Clarify.
+	(Type Predicates): Add hash-table-p.
+
+	* numbers.texi (Integer Basics): Clarify radix explanation.
+	(Predicates on Numbers): Minor clarification.
+	(Comparison of Numbers): Minor clarification.  Clarify eql.
+	Typos in min, max.
+	(Math Functions): Clarify overflow in expt.
+
+	* minibuf.texi (Text from Minibuffer): Minor clarification.
+	Mention arrow keys.
+
+	* loading.texi (Autoload): defun's doc string overrides autoload's
+	doc string.
+	(Repeated Loading): Modernize "add to list" examples.
+	(Where Defined): Finish updating table of load-history elts.
+
+	* lists.texi (List-related Predicates): Minor wording improvement.
+	(Lists as Boxes): Node deleted.
+	(Building Lists): Explain trivial cases of number-sequence.
+
+	* hash.texi (Hash Tables): Add desc to menu items.
+	(Creating Hash): Expain "full" means "make larger",
+	(Hash Access): Any object can be a key.
+	State value of maphash.
+
+	* functions.texi (What Is a Function): Wording cleanup.
+	(Function Documentation): Minor cleanup.
+	Explain purpose of calling convention at end of doc string.
+	(Function Names): Wording cleanup.
+	(Calling Functions): Wording cleanup.
+	Explain better how funcall calls the function.
+	(Function Cells): Delete example of saving and redefining function.
+
+	* control.texi (Combining Conditions): Wording cleanup.
+	(Iteration): dolist and dotimes bind VAR locally.
+	(Cleanups): Xref to Atomic Changes.
+
+	* compile.texi (Byte Compilation): Delete 19.29 info.
+	(Compilation Functions): Macros' difficulties don't affect defsubst.
+	(Docs and Compilation): Delete 19.29 info.
+
+2005-02-10  Richard M. Stallman  <rms@gnu.org>
+
+	* objects.texi (Symbol Type): Minor correction.
+
+2005-02-06  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Example Major Modes): Fix typos.
+
+2005-02-06  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Margins): fill-nobreak-predicate can be one function.
+
+	* strings.texi (Modifying Strings): clear-string can make unibyte.
+	(Formatting Strings): format gives error if values missing.
+
+	* positions.texi (Character Motion): Mention default arg
+	for forward-char.  backward-char refers to forward-char.
+	(Word Motion): Mention default arg for forward-word.
+	(Buffer End Motion): Mention default arg for beginning-of-buffer.
+	Simplify end-of-buffer.
+	(Text Lines): Mention default arg for forward-line.
+	(List Motion): Mention default arg for beginning/end-of-defun.
+	(Skipping Characters): Minor fixes in explaining character-set.
+
+	* modes.texi (Major Mode Conventions): Mention "system abbrevs".
+	Mode inheritance applies only when default-major-mode is nil.
+	Clarifications.
+	(Example Major Modes): Update Text mode and Lisp mode examples.
+	(Minor Mode Conventions): Mention define-minor-mode at top.
+	(Defining Minor Modes): In Hungry example, don't define C-M-DEL.
+	(Mode Line Format): Update mode line face display info.
+	(Properties in Mode): Mention effect of risky vars.
+	(Imenu): Define imenu-add-to-menubar.
+	(Font Lock Mode): Add descriptions to menu lines.
+	(Faces for Font Lock): Add font-lock-doc-face.
+
+2005-02-05  Lute Kamstra  <lute@gnu.org>
+
+	* text.texi (Maintaining Undo): Remove obsolete function.
+
+2005-02-05  Eli Zaretskii  <eliz@gnu.org>
+
+	* frames.texi (Color Names): Add pointer to the X docs about RGB
+	color specifications.  Improve indexing
+	(Text Terminal Colors): Replace the description of RGB values by
+	an xref to "Color Names".
+
+2005-02-03  Richard M. Stallman  <rms@gnu.org>
+
+	* windows.texi (Basic Windows): Add cursor-in-non-selected-windows.
+	Clarify.
+	(Selecting Windows): Clarify save-selected-window.
+	(Cyclic Window Ordering): Clarify walk-windows.
+	(Window Point): Clarify.
+	(Window Start): Add comment to example.
+	(Resizing Windows): Add `interactive' specs in examples.
+	Document fit-window-to-buffer.
+
+	* text.texi (User-Level Deletion): just-one-space takes numeric arg.
+	(Undo, Maintaining Undo): Clarify last change.
+	(Sorting): In sort-numeric-fields, explain about octal and hex.
+	Mention sort-numeric-base.
+	(Format Properties): Add xref for hard newlines.
+
+	* frames.texi (Window Frame Parameters): Explain pixel=char on tty.
+	(Pop-Up Menus): Fix typo.
+	(Color Names): Explain all types of color names.
+	Explain color-values on B&W terminal.
+	(Text Terminal Colors): Explain "rgb values" are lists.  Fix arg names.
+
+	* files.texi (File Locks): Not supported on MS systems.
+	(Testing Accessibility): Clarify.
+
+	* edebug.texi (Printing in Edebug): Fix edebug-print-circle.
+	(Coverage Testing): Fix typo.
+
+	* commands.texi (Misc Events): Remove stray space.
+
+	* buffers.texi (Buffer Names): Clarify generate-new-buffer-name.
+	(Modification Time): Clarify when visited-file-modtime returns 0.
+	(The Buffer List): Clarify bury-buffer.
+	(Killing Buffers): Clarify.
+	(Indirect Buffers): Add clone-indirect-buffer.
+
+2005-02-02  Matt Hodges  <MPHodges@member.fsf.org>
+
+	* edebug.texi (Printing in Edebug): Fix default value of
+	edebug-print-circle.
+	(Coverage Testing): Fix displayed frequency count data.
+
+2005-02-02  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* text.texi (Maintaining Undo): Add `undo-outer-limit'.
+
+2005-02-02  Kim F. Storm  <storm@cua.dk>
+
+	* text.texi (Undo) <buffer-undo-list>: Describe `apply' elements.
+
+2005-01-29  Eli Zaretskii  <eliz@gnu.org>
+
+	* commands.texi (Misc Events): Describe the help-echo event.
+
+	* text.texi (Special Properties) <help-echo>: Use `pos'
+	consistently in description of the help-echo property.
+	Use @code{nil} instead of @var{nil}.
+
+	* display.texi (Overlay Properties): Fix the index entry for
+	help-echo overlay property.
+
+	* customize.texi (Type Keywords): Uncomment the xref to the
+	help-echo property documentation.
+
+2005-01-23  Kim F. Storm  <storm@cua.dk>
+
+	* windows.texi (Window Start): Fix `pos-visible-in-window-p'
+	return value.  Third element FULLY replaced by PARTIAL which
+	specifies number of invisible pixels if row is only partially visible.
+	(Textual Scrolling): Mention auto-window-vscroll.
+	(Vertical Scrolling): New defvar auto-window-vscroll.
+
+2005-01-16  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* keymaps.texi (Changing Key Bindings): `suppress-keymap' now uses
+	command remapping.
+
+2005-01-15  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Defining Images): Mention DATA-P arg of create-image.
+
+2005-01-14  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Accessing Events): Add WHOLE arg to posn-at-x-y.
+
+	* text.texi (Links and Mouse-1): Fix string and vector item.
+
+2005-01-13  Richard M. Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Active Keymaps): Rewrite the text, and update the
+	descriptions of overriding-local-map and overriding-terminal-local-map.
+
+	* text.texi (Links and Mouse-1): Clarify text.
+
+2005-01-13  Kim F. Storm  <storm@cua.dk>
+
+	* modes.texi (Emulating Mode Line): Update format-mode-line entry.
+
+2005-01-13  Francis Litterio  <franl@world.std.com>  (tiny change)
+
+	* keymaps.texi (Active Keymaps): Fix overriding-local-map description.
+
+2005-01-12  Kim F. Storm  <storm@cua.dk>
+
+	* text.texi (Links and Mouse-1): Rename section from Enabling
+	Mouse-1 to Following Links.  Change xrefs.
+	Add examples for define-button-type and define-widget.
+
+	* display.texi (Button Properties, Button Buffer Commands):
+	Clarify mouse-1 and follow-link functionality.
+
+2005-01-12  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Enabling Mouse-1 to Follow Links): Redo prev. change.
+
+	* display.texi (Beeping): Fix Texinfo usage.
+
+	* modes.texi (Emulating Mode Line): Doc FACE arg in format-header-line.
+
+2005-01-11  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Button Properties, Button Buffer Commands):
+	Mention mouse-1 binding.  Add follow-link keyword.
+
+	* text.texi (Text Properties): Add "Enable Mouse-1" to submenu.
+	(Enabling Mouse-1 to Follow Links): New subsection.
+
+2005-01-06  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Special Properties): Minor change.
+
+	* os.texi (Timers): Clarify previous change.
+
+	* modes.texi (Emulating Mode Line): format-mode-line requires 1 arg.
+
+2005-01-01  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* display.texi (Face Attributes): Correct xref to renamed node.
+
+2005-01-01  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Face Attributes): Describe hex color specs.
+
+2004-12-31  Richard M. Stallman  <rms@gnu.org>
+
+	* os.texi (Timers): Update previous change.
+
+2004-12-30  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Line Height): Total line-height is now specified
+	in line-height property of form (HEIGHT TOTAL).  Swap (FACE . RATIO)
+	in cons cells.  (nil . RATIO) is relative to actual line height.
+	Use line-height `t' instead of `0' to get minimum height.
+
+2004-12-29  Richard M. Stallman  <rms@gnu.org>
+
+	* os.texi (Timers): Discuss timers vs editing the buffer and undo.
+
+2004-12-28  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Quitting): Clarify value of with-local-quit.
+
+	* elisp.texi (Top): Fix previous change.
+
+	* loading.texi (Loading): Fix previous change.
+
+2004-12-27  Richard M. Stallman  <rms@gnu.org>
+
+	* Makefile.in (MAKEINFO): Specify --force.
+
+	* buffers.texi (Killing Buffers): Add buffer-save-without-query.
+
+	* modes.texi (Emulating Mode Line): Document format's BUFFER arg.
+
+	* display.texi (Line Height): Further clarify.
+
+	* elisp.texi (Top): Update Loading submenu.
+
+	* loading.texi (Where Defined): New node.
+	(Unloading): load-history moved to Where Defined.
+
+2004-12-21  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Event Input Misc): Add while-no-input.
+
+2004-12-11  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Line Height): Rewrite text for clarity.
+
+2004-12-11  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Display): Add node "Line Height" to menu.
+	(Line Height): New node.  Move full description of line-spacing
+	and line-height text properties here from text.texi.
+	(Scroll Bars): Add vertical-scroll-bar variable.
+
+	* frames.texi (Window Frame Parameters): Remove line-height defvar.
+
+	* locals.texi (Standard Buffer-Local Variables): Fix xref for
+	line-spacing and vertical-scroll-bar.
+
+	* text.texi (Special Properties): Just mention line-spacing and
+	line-height here, add xref to new "Line Height" node.
+
+2004-12-09  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* frames.texi (Window Frame Parameters): New @defvar for `line-spacing'.
+
+	* locals.texi (Standard Buffer-Local Variables):
+	Add @xref for `line-spacing'.
+
+2004-12-05  Richard M. Stallman  <rms@gnu.org>
+
+	* Makefile.in (maintainer-clean): Remove the info files
+	in $(infodir) where they are created.
+
+2004-12-03  Richard M. Stallman  <rms@gnu.org>
+
+	* windows.texi (Selecting Windows): get-lru-window and
+	get-largest-window don't consider dedicated windows.
+
+	* text.texi (Undo): Document undo-in-progress.
+
+2004-11-26  Richard M. Stallman  <rms@gnu.org>
+
+	* locals.texi (Standard Buffer-Local Variables): Undo prev change.
+	Remove a few vars that are not always buffer-local.
+
+2004-11-24  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* locals.texi (Standard Buffer-Local Variables): Comment out
+	xref's to non-existent node `Yet to be written'.
+
+2004-11-24  Richard M. Stallman  <rms@gnu.org>
+
+	* processes.texi (Synchronous Processes): Grammar fix.
+
+	* numbers.texi (Comparison of Numbers): Add eql.
+
+	* locals.texi (Standard Buffer-Local Variables): Add many vars.
+
+	* intro.texi (Printing Notation): Fix previous change.
+
+	* display.texi (Customizing Bitmaps): Move indicate-buffer-boundaries
+	and default-indicate-buffer-boundaries from here.
+	(Usual Display): To here.
+	(Scroll Bars): Add scroll-bar-mode and scroll-bar-width.
+	(Usual Display): Move tab-width up.
+
+	* customize.texi (Variable Definitions): Replace
+	show-paren-mode example with tooltip-mode.
+	(Simple Types, Composite Types, Defining New Types):
+	Minor cleanups.
+
+2004-11-21  Jesper Harder  <harder@ifa.au.dk>
+
+	* processes.texi (Synchronous Processes, Output from Processes):
+	Markup fix.
+
+2004-11-20  Richard M. Stallman  <rms@gnu.org>
+
+	* positions.texi (Skipping Characters): skip-chars-forward
+	now handles char classes.
+
+	* intro.texi (Printing Notation): Avoid confusion of `print'
+	when explaining @print.
+
+	* macros.texi (Argument Evaluation): Fix 1st `for' expansion example.
+
+	* display.texi (Display Table Format): Minor fix.
+
+	* streams.texi (Output Functions): Fix print example.
+
+	* Makefile.in (elisp): New target.
+	(dist): Depend on $(infodir)/elisp, not elisp.
+	Copy the info files from $(infodir).
+
+	* minibuf.texi (Text from Minibuffer): Document KEEP-ALL arg in
+	read-from-minibuffer.
+
+	* searching.texi (Regexp Search): Rename that to search-spaces-regexp.
+
+2004-11-19  Richard M. Stallman  <rms@gnu.org>
+
+	* searching.texi (Regexp Search): Add search-whitespace-regexp.
+
+2004-11-19  CHENG Gao  <chenggao@gmail.com>  (tiny change)
+
+	* tips.texi (Coding Conventions): Fix typo.
+
+2004-11-16  Richard M. Stallman  <rms@gnu.org>
+
+	* tips.texi (Coding Conventions): Separate defvar and require
+	methods to avoid warnings.  Use require only when there are many
+	functions and variables from that package.
+
+	* minibuf.texi (Minibuffer Completion): When ignoring case,
+	predicate must not be case-sensitive.
+
+	* debugging.texi (Function Debugging, Explicit Debug): Clarified.
+	(Test Coverage): Don't talk about "splotches".  Clarified.
+
+2004-11-16  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* frames.texi (Window Frame Parameters): Fix typo.
+
+2004-11-15  Kim F. Storm  <storm@cua.dk>
+
+	* symbols.texi (Other Plists): Note that plist-get may signal error.
+	Add safe-plist-get.
+
+2004-11-15  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* modes.texi (Font Lock Basics): Fix typo.
+
+2004-11-08  Richard M. Stallman  <rms@gnu.org>
+
+	* syntax.texi (Syntax Table Functions): Add syntax-after.
+
+2004-11-06  Lars Brinkhoff  <lars@nocrew.org>
+
+	* os.texi (Processor Run Time): New section documenting
+	get-internal-run-time.
+
+2004-11-06  Eli Zaretskii  <eliz@gnu.org>
+
+	* Makefile.in (install, maintainer-clean): Don't use "elisp-*" as
+	it nukes elisp-cover.texi.
+	(dist): Change elisp-[0-9] to elisp-[1-9], as there could be no
+	elisp-0 etc.
+
+2004-11-05  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* commands.texi (Keyboard Macros): Document `append' return value
+	of `defining-kbd-macro'.
+
+2004-11-01  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Interactive Call): Add called-interactively-p.
+
+2004-10-29  Simon Josefsson  <jas@extundo.com>
+
+	* minibuf.texi (Reading a Password): Revert.
+
+2004-10-28  Richard M. Stallman  <rms@gnu.org>
+
+	* frames.texi (Display Feature Testing): Explain about "vendor".
+
+2004-10-27  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Interactive Codes): `N' uses numeric prefix,
+	not raw.  Clarify `n'.
+	(Interactive Call): Rewrite interactive-p, focusing on when
+	and how to use it.
+	(Misc Events): Clarify previous change.
+
+	* advice.texi (Simple Advice): Clarify what job the example does.
+	(Around-Advice): Clarify ad-do-it.
+	(Activation of Advice): An option of ad-default-compilation-action
+	is `never', not `nil'.
+
+2004-10-26  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Interactive Codes): Add U code letter.
+
+2004-10-25  Simon Josefsson  <jas@extundo.com>
+
+	* minibuf.texi (Reading a Password): Add.
+
+2004-10-24  Jason Rumney  <jasonr@gnu.org>
+
+	* commands.texi (Misc Events): Remove mouse-wheel.  Add wheel-up
+	and wheel-down.
+
+2004-10-24  Kai Grossjohann  <kai.grossjohann@gmx.net>
+
+	* processes.texi (Synchronous Processes): Document process-file.
+
+2004-10-22  Kenichi Handa  <handa@m17n.org>
+
+	* text.texi (translate-region): Document that it accepts also a
+	char-table.
+
+2004-10-22  David Ponce  <david@dponce.com>
+
+	* windows.texi (Resizing Windows): Document the `preserve-before'
+	argument of the functions `enlarge-window' and `shrink-window'.
+
+2004-10-19  Jason Rumney  <jasonr@gnu.org>
+
+	* makefile.w32-in (elisp): Change order of arguments to makeinfo.
+
+2004-10-09  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* text.texi (Filling): Add anchor for definition of
+	`sentence-end-double-space'.
+
+	* searching.texi (Regexp Example): Update description of how
+	Emacs currently recognizes the end of a sentence.
+	(Standard Regexps): Update definition of the variable
+	`sentence-end'.  Add definition of the function `sentence-end'.
+
+2004-10-08  Paul Pogonyshev  <pogonyshev@gmx.net>
+
+	* display.texi (Progress): New node.
+
+2004-10-05  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos.
+
+2004-09-29  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Fringe Bitmaps): Use symbols rather than numbers
+	to identify bitmaps.  Remove -fringe-bitmap suffix for standard
+	fringe bitmap symbols, as they now have their own namespace.
+	(Customizing Bitmaps) <define-fringe-bitmap>: Clarify bit ordering
+	vs. pixels.  Signal error if no free bitmap slots.
+	(Pixel Specification): Change IMAGE to @var{image}.
+
+2004-09-28  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Special Properties): Clarify line-spacing and line-height.
+
+	* searching.texi (Regexp Search): Add looking-back.
+
+2004-09-25  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* display.texi: Correct typos.
+	(Image Descriptors): Correct xref's.
+
+2004-09-25  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Special Properties): Cleanups in `cursor'.
+	Rewrites in `line-height' and `line-spacing'; exchange them.
+
+	* display.texi (Fringes): Rewrite previous change.
+	(Fringe Bitmaps): Merge text from Display Fringe Bitmaps.  Rewrite.
+	(Display Fringe Bitmaps): Node deleted, text moved.
+	(Customizing Bitmaps): Split off from Fringe Bitmaps.  Rewrite.
+	(Scroll Bars): Clarify set-window-scroll-bars.
+	(Pointer Shape): Rewrite.
+	(Specified Space): Clarify :align-to, etc.
+	(Pixel Specification): Use @var.  Clarify new text.
+	(Other Display Specs): Clarify `slice'.
+	(Image Descriptors): Cleanups.
+	(Showing Images): Cleanups.
+
+2004-09-24  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* hooks.texi (Standard Hooks): Add `after-change-major-mode-hook'.
+
+	* modes.texi: Various minor changes in addition to:
+	(Major Mode Conventions): Final call to `run-mode-hooks' should
+	not be inside the `delay-mode-hooks' form.
+	(Mode Hooks): New node.
+	(Hooks): Delete obsolete example.
+	Move definitions of `run-mode-hooks' and `delay-mode-hooks' to new
+	node "Mode Hooks".
+
+2004-09-22  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* display.texi: Correct various typos.
+	(Display): Rename node "Pointer Shapes" to "Pointer
+	Shape".  (There is already a node called "Pointer Shapes" in
+	frames.texi.)
+	(Images): Remove non-existent node "Image Slices" from menu.
+
+2004-09-23  Kim F. Storm  <storm@cua.dk>
+
+	* text.texi (Special Properties): Add `cursor', `pointer',
+	`line-height', and `line-spacing' properties.
+
+	* display.texi (Display): Add 'Fringe Bitmaps' and 'Pointer
+	Shapes' to menu.
+	(Standard Faces): Doc fix for fringe face.
+	(Fringes): Add `overflow-newline-into-fringe' and
+	'indicate-buffer-boundaries'.
+	(Fringe Bitmaps, Pointer Shapes): New nodes.
+	(Display Property): Add 'Pixel Specification' and 'Display Fringe
+	Bitmaps' to menu.
+	(Specified Space): Describe pixel width and height.
+	(Pixel Specification): New node.
+	(Other Display Specs): Add `slice' property.
+	(Display Fringe Bitmaps): New node.
+	(Images): Add 'Image Slices' to menu.
+	(Image Descriptors): Add `:pointer' and `:map' properties.
+	(Showing Images): Add slice arg to `insert-image'.  Add
+	'insert-sliced-image'.
+
+2004-09-20  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Key Sequence Input):
+	Clarify downcasing in read-key-sequence.
+
+2004-09-08  Juri Linkov  <juri@jurta.org>
+
+	* minibuf.texi (Minibuffer History): Add `history-delete-duplicates'.
+
+2004-09-07  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* locals.texi (Standard Buffer-Local Variables): Add
+	`buffer-auto-save-file-format'.
+	* internals.texi (Buffer Internals): Describe new
+	auto_save_file_format field of the buffer structure.
+	* files.texi (Format Conversion): `auto-save-file-format' has been
+	renamed `buffer-auto-save-file-format'.
+
+2004-08-27  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* abbrevs.texi (Abbrev Expansion): `abbrev-start-location' can be
+	an integer or a marker.
+	(Abbrev Expansion): Replace example for `pre-abbrev-expand-hook'.
+
+2004-08-22  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Major Mode Conventions): Discuss rebinding of
+	standard key bindings.
+
+2004-08-18  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Accepting Output): Add `just-this-one' arg to
+	`accept-process-output'.
+	(Output from Processes): New var `process-adaptive-read-buffering'.
+
+2004-08-10  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* keymaps.texi: Various changes in addition to:
+	(Keymap Terminology): `kbd' uses same syntax as Edit Macro mode.
+	Give more varied examples for `kbd'.
+	(Creating Keymaps): Char tables have slots for all characters
+	without modifiers.
+	(Active Keymaps): `overriding-local-map' and
+	`overriding-terminal-local-map' also override text property and
+	overlay keymaps.
+	(Functions for Key Lookup): Mention OLP arg to `current-active-maps'.
+	(Scanning Keymaps): `accessible-keymaps' uses `[]' instead of `""'
+	to denote a prefix of no events.
+	`map-keymap' includes parent's bindings _recursively_.
+	Clarify and correct description of `where-is-internal'.
+	Mention BUFFER-OR-NAME arg to `describe-bindings'.
+	(Menu Example): For menus intended for use with the keyboard, the
+	menu items should be bound to characters or real function keys.
+
+2004-08-08  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* objects.texi (Character Type): Reposition `@anchor' to prevent
+	double space inside sentence in Info.
+
+	* hooks.texi (Standard Hooks): `disabled-command-hook' has been
+	renamed to `disabled-command-function'.
+	* commands.texi (Key Sequence Input): Remove unnecessary anchor.
+	(Command Loop Info): Replace reference to it.
+	(Disabling Commands): `disabled-command-hook' has been renamed to
+	`disabled-command-function'.
+
+2004-08-07  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* os.texi (Translating Input): Only non-prefix bindings in
+	`key-translation-map' override actual key bindings.  Warn about
+	possible indirect effect of actual key bindings on non-prefix
+	bindings in `key-translation-map'.
+
+2004-08-06  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* minibuf.texi (High-Level Completion): Add anchor for definition
+	of `read-variable'.
+
+	* commands.texi: Various changes in addition to:
+	(Using Interactive): Clarify description of `interactive-form'.
+	(Interactive Call): Mention default for KEYS argument to
+	`call-interactively'.
+	(Command Loop Info): Clarify description of `this-command-keys'.
+	Mention KEEP-RECORD argument to `clear-this-command-keys'.
+	Value of `last-event-frame' can be `macro'.
+	(Repeat Events): `double-click-fuzz' is also used to distinguish
+	clicks and drags.
+	(Classifying Events): Clarify descriptions of `event-modifiers'
+	`event-basic-type' and `event-convert-list'.
+	(Accessing Events): `posn-timestamp' takes POSITION argument.
+	(Quoted Character Input): Clarify description of
+	`read-quoted-char' and fix example.
+	(Quitting): Add `with-local-quit'.
+	(Disabling Commands): Correct and clarify descriptions of
+	`enable-command' and `disable-command'.
+	Mention what happens if `disabled-command-hook' is nil.
+	(Keyboard Macros): Mention LOOPFUNC arg to `execute-kbd-macro'.
+	Describe `executing-kbd-macro' instead of obsolete `executing-macro'.
+
+2004-07-24  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* frames.texi: Various changes in addition to:
+	(Creating Frames): Expand and clarify description of `make-frame'.
+	(Window Frame Parameters): Either none or both of the `icon-left'
+	and `icon-top' parameters must be specified.  Put descriptions of
+	`menu-bar-lines' and `toolbar-lines' closer together and change
+	them accordingly.
+	(Frame Titles): `multiple-frames' is not guaranteed to be accurate
+	except while processing `frame-title-format' or `icon-title-format'.
+	(Deleting Frames): Correct description of `delete-frame'.
+	Non-nil return values of `frame-live-p' are like those of `framep'.
+	(Frames and Windows): Mention return value of
+	`set-frame-selected-window'.
+	(Visibility of Frames): Mention `force' argument to
+	`make-frame-invisible'.  `frame-visible-p' returns t for all
+	frames on text-only terminals.
+	(Frame Configurations): Restoring a frame configuration does not
+	restore deleted frames.
+	(Window System Selections): `x-set-selection' returns DATA.
+	(Resources): Add example.
+	(Display Feature Testing): Clarify descriptions of
+	`display-pixel-height', `display-pixel-width', `x-server-version'
+	and `x-server-vendor'.
+
+	* windows.texi (Choosing Window): Add anchor.
+	* minibuf.texi (Minibuffer Misc): Add anchor.
+
+2004-07-23  John Paul Wallington  <jpw@gnu.org>
+
+	* macros.texi (Defining Macros): Declaration keyword for setting
+	Edebug spec is `debug' not `edebug'.
+
+2004-07-19  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* windows.texi: Various small changes in addition to:
+	(Window Point): Mention return value of `set-window-point'.
+	(Window Start): `pos-visible-in-window-p' disregards horizontal
+	scrolling.  Explain return value if PARTIALLY is non-nil.
+	(Vertical Scrolling): Mention PIXELS-P argument to `window-vscroll'
+	and `set-window-vscroll'.
+	(Size of Window): The argument WINDOW to `window-inside-edges',
+	`window-pixel-edges' and `window-inside-pixel-edges' is optional.
+	(Resizing Windows): Explain return value of
+	`shrink-window-if-larger-than-buffer'.
+	`window-size-fixed' automatically becomes buffer local when set.
+	(Window Configurations): Explain return value of
+	`set-window-configuration'.
+
+	* minibuf.texi (Minibuffer Misc): Add anchor for
+	`minibuffer-scroll-window'.
+
+	* positions.texi (Text Lines): Add anchor for `count-lines'.
+
+2004-07-17  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Overlay Properties): Adding `evaporate' prop
+	deletes empty overlay immediately.
+
+	* abbrevs.texi (Abbrev Expansion): Clarify pre-abbrev-expand-hook,
+	fix example.
+
+2004-07-16  Jim Blandy  <jimb@redhat.com>
+
+	* searching.texi (Regexp Backslash): Document new \_< and \_>
+	operators.
+
+2004-07-16  Juanma Barranquero  <lektu@terra.es>
+
+	* display.texi (Images): Fix Texinfo usage.
+
+2004-07-14  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* buffers.texi (Modification Time): `visited-file-modtime' now
+	returns a list of two integers, instead of a cons.
+
+2004-07-13  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* windows.texi: Various changes in addition to:
+	(Splitting Windows): Add `split-window-keep-point'.
+
+2004-07-09  Richard M. Stallman  <rms@gnu.org>
+
+	* frames.texi (Input Focus): Minor fix.
+
+2004-07-07  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* frames.texi (Input Focus): Clarify descriptions of
+	`select-frame-set-input-focus' and `select-frame'.
+
+2004-07-06  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* os.texi: Various small changes in addition to:
+	(Killing Emacs): Expand and clarify description of
+	`kill-emacs-query-functions' and `kill-emacs-hook'.
+	(System Environment): Expand and clarify description of `getenv'
+	and `setenv'.
+	(Timers): Clarify description of `run-at-time'.
+	(Translating Input): Correct description of
+	`extra-keyboard-modifiers'.
+	(Flow Control): Correct description of `enable-flow-control'.
+
+2004-07-06  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* os.texi: Update copyright.
+	(Session Management): Grammar fix.
+	Clarify which Emacs does the restarting.
+	Use @samp for *scratch* buffer.
+
+2004-07-04  Alan Mackenzie  <acm@muc.de>
+
+	* frames.texi (Input Focus): Add documentation for
+	`select-frame-set-input-focus'.  Replace refs to non-existent
+	`switch-frame' with `select-frame'.  Minor corrections and tidying
+	up of text-only terminal stuff.
+
+2004-07-02  Richard M. Stallman  <rms@gnu.org>
+
+	* files.texi (Saving Buffers): Cleanup write-contents-function.
+	(Magic File Names): Cleanup file-remote-p.
+
+2004-07-02  Kai Grossjohann  <kai@emptydomain.de>
+
+	* files.texi (Magic File Names): `file-remote-p' returns an
+	identifier of the remote system, not just t.
+
+2004-07-02  David Kastrup  <dak@gnu.org>
+
+	* searching.texi (Entire Match Data): Add explanation about new
+	match-data behavior when @var{integers} is non-nil.
+
+2004-06-24  Richard M. Stallman  <rms@gnu.org>
+
+	* commands.texi (Misc Events): Describe usr1-signal, usr2-signal event.
+
+	* customize.texi (Variable Definitions): Note about doc strings
+	and :set.
+
+	* keymaps.texi (Keymap Terminology): Document `kbd'.
+	(Changing Key Bindings, Key Binding Commands): Use kbd in examples.
+
+	* display.texi (Invisible Text): Setting buffer-invisibility-spec
+	makes it buffer-local.
+
+	* files.texi (Saving Buffers): Correct previous change.
+
+	* commands.texi (Accessing Events):
+	Clarify posn-col-row and posn-actual-col-row.
+
+2004-06-24  David Ponce  <david.ponce@wanadoo.fr>
+
+	* commands.texi (Accessing Events): New functions
+	posn-at-point and posn-at-x-y.  Add example to posn-x-y.
+
+2004-06-23  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* lists.texi, files.texi, processes.texi, macros.texi, hash.texi:
+	* frames.texi, buffers.texi, backups.texi, variables.texi:
+	* loading.texi, eval.texi, functions.texi, control.texi:
+	* symbols.texi, minibuf.texi: Reposition @anchor's.
+
+	* help.texi: Various small changes in addition to the following.
+	(Describing Characters): Describe PREFIX argument to
+	`key-description'.  Correct and clarify definition of
+	`text-char-description'.  Describe NEED-VECTOR argument to
+	`read-kbd-macro'.
+	(Help Functions): Clarify definition of `apropos'.
+
+2004-06-23  Lars Hansen  <larsh@math.ku.dk>
+
+	* files.texi (Saving Buffers): Correct description of
+	`write-contents-functions'.
+
+2004-06-21  Juanma Barranquero  <lektu@terra.es>
+
+	* display.texi (Images): Remove redundant @vindex directives.
+	Rewrite `image-library-alist' doc in active voice.
+
+2004-06-14  Juanma Barranquero  <lektu@terra.es>
+
+	* display.texi (Images): Document new delayed library loading,
+	variable `image-library-alist' and (existing but undocumented)
+	function `image-type-available-p'.
+
+2004-06-05  Richard M. Stallman  <rms@gnu.org>
+
+	* minibuf.texi (Minibuffer Completion): For INITIAL arg,
+	refer the user to the Initial Input node.
+	(Text from Minibuffer): Likewise.
+	(Initial Input): New node.  Document this feature
+	and say it is mostly deprecated.
+
+2004-05-30  Richard M. Stallman  <rms@gnu.org>
+
+	* loading.texi (Named Features): Clarify return value
+	and meaning of NOERROR.
+
+	* variables.texi (File Local Variables): Minor cleanup.
+
+2004-05-30  Michael Albinus  <michael.albinus@gmx.de>
+
+	* files.texi (Magic File Names): Add `file-remote-p' as operation
+	of file name handlers.
+
+2004-05-29  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Minor Mode Conventions): (-) has no special meaning
+	as arg to a minor mode command.
+
+2004-05-22  Richard M. Stallman  <rms@gnu.org>
+
+	* syntax.texi (Syntax Class Table): Word syntax not just for English.
+
+	* streams.texi (Output Variables): Doc float-output-format.
+
+	* searching.texi (Regexp Special): Nested repetition can be infloop.
+
+	* eval.texi (Eval): Increasing max-lisp-eval-depth can cause
+	real stack overflow.
+
+	* compile.texi: Minor cleanups.
+
+2004-05-22  Luc Teirlinck  <teirllm@dms.auburn.edu>
+
+	* lists.texi (Cons Cells): Explain dotted lists, true lists,
+	circular lists.
+	(List Elements): Explain handling of circular and dotted lists.
+
+2004-05-19  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* modes.texi (Search-based Fontification): Fix typo.
+
+2004-05-10  Juanma Barranquero  <lektu@terra.es>
+
+	* modes.texi (Mode Line Variables): Fix description of
+	global-mode-string, which is now after which-func-mode, not the
+	buffer name.
+
+2004-05-07  Lars Hansen  <larsh@math.ku.dk>
+
+	* modes.texi (Desktop Save Mode): Add.
+	(Modes): Add menu entry Desktop Save Mode.
+
+	* hooks.texi: Add desktop-after-read-hook,
+	desktop-no-desktop-file-hook and desktop-save-hook.
+
+	* locals.texi: Add desktop-save-buffer.
+
+2004-04-30  Jesper Harder  <harder@ifa.au.dk>
+
+	* display.texi: emacs -> Emacs.
+
+2004-04-27  Matthew Mundell  <matt@mundell.ukfsn.org>
+
+	* files.texi (Changing Files): Document set-file-times.
+
+2004-04-23  Juanma Barranquero  <lektu@terra.es>
+
+	* makefile.w32-in: Add "-*- makefile -*-" mode tag.
+
+2004-04-18  Jesper Harder  <harder@ifa.au.dk>
+
+	* tips.texi (Coding Conventions): defopt -> defcustom.
+
+2004-04-16  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* sequences.texi: Various clarifications.
+
+2004-04-14  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* buffers.texi (Read Only Buffers): Mention optional ARG to
+	`toggle-read-only'.
+
+2004-04-14  Nick Roberts  <nick@nick.uklinux.net>
+
+	* windows.texi (Selecting Windows): Note that get-lru-window
+	returns a full-width window if possible.
+
+2004-04-13  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* buffers.texi: Various changes in addition to:
+	(Buffer File Name): Add `find-buffer-visiting'.
+	(Buffer Modification): Mention optional ARG to `not-modified'.
+	(Indirect Buffers): Mention optional CLONE argument to
+	`make-indirect-buffer'.
+
+	* files.texi: Various changes in addition to:
+	(Visiting Functions): `find-file-hook' is now a normal hook.
+	(File Name Expansion): Explain difference between the way that
+	`expand-file-name' and `file-truename' treat `..'.
+	(Contents of Directories): Mention optional ID-FORMAT argument to
+	`directory-files-and-attributes'.
+	(Format Conversion): Mention new optional CONFIRM argument to
+	`format-write-file'.
+
+2004-04-12  Miles Bader  <miles@gnu.org>
+
+	* macros.texi (Expansion): Add description of `macroexpand-all'.
+
+2004-04-05  Jesper Harder  <harder@ifa.au.dk>
+
+	* variables.texi (Variable Aliases): Mention
+	cyclic-variable-indirection.
+
+	* errors.texi (Standard Errors): Ditto.
+
+2004-04-04  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* backups.texi: Various small changes in addition to:
+	(Making Backups): Mention return value of `backup-buffer'.
+	(Auto-Saving): Mention optional FORCE argument to
+	`delete-auto-save-file-if-necessary'.
+	(Reverting): Mention optional PRESERVE-MODES argument to
+	`revert-buffer'.  Correct description of `revert-buffer-function'.
+
+2004-03-22  Juri Linkov  <juri@jurta.org>
+
+	* sequences.texi (Sequence Functions): Replace xref to `Vectors'
+	with `Vector Functions'.
+
+	* text.texi (Sorting): Add missing quote.
+
+2004-03-14  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* intro.texi (Lisp History): Replace xref to `cl' manual with
+	inforef.
+
+2004-03-12  Richard M. Stallman  <rms@gnu.org>
+
+	* intro.texi (Version Info): Add arg to emacs-version.
+	(Lisp History): Change xref to CL manual.
+
+2004-03-09  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* minibuf.texi (Completion Commands): Add xref to Emacs manual
+	for Partial Completion mode.
+
+2004-03-07  Thien-Thi Nguyen  <ttn@gnu.org>
+
+	* customize.texi: Fix typo.  Remove eol whitespace.
+
+2004-03-04  Richard M. Stallman  <rms@gnu.org>
+
+	* processes.texi: Fix typos.
+
+	* lists.texi (Building Lists): Minor clarification.
+
+	* hash.texi (Creating Hash): Correct the meaning of t for WEAK
+	in make-hash-table.
+
+2004-02-29  Juanma Barranquero  <lektu@terra.es>
+
+	* makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of
+	rm, and ignore exit code.
+
+2004-02-27  Dan Nicolaescu  <dann@ics.uci.edu>
+
+	* display.texi (Defining Faces): Add description for min-colors.
+	Update example.
+
+2004-02-23  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* abbrevs.texi: Various corrections and clarifications in addition
+	to the following:
+	(Abbrev Tables): Delete add-abbrev (as suggested by RMS).
+
+2004-02-22  Matthew Mundell  <matt@mundell.ukfsn.org>  (tiny change)
+
+	* calendar.texi (Holiday Customizing): Quote arg of holiday-sexp.
+
+2004-02-21  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* text.texi: Various small changes in addition to the following:
+	(User-Level Deletion): Mention optional BACKWARD-ONLY argument
+	to delete-horizontal-space.
+	(Kill Functions, Yanking, Low-Level Kill Ring): Clarify and correct
+	description of yank-handler text property at various places.
+
+	* frames.texi (Window System Selections): Add anchor.
+
+	* syntax.texi (Syntax Table Functions): Clarify and correct
+	descriptions of make-syntax-table and copy-syntax-table.
+	(Motion and Syntax): Clarify SYNTAXES argument to
+	skip-syntax-forward.
+	(Parsing Expressions): Mention that the return value of
+	parse-partial-sexp is currently a list of ten rather than nine
+	elements.
+	(Categories): Various corrections and clarifications.
+
+2004-02-17  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* markers.texi (Marker Insertion Types): Minor change.
+
+	* locals.texi (Standard Buffer-Local Variables):
+	* commands.texi (Interactive Codes, Using Interactive):
+	* functions.texi (Related Topics): Fix xrefs.
+
+2004-02-16  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* lists.texi (Sets And Lists): Update description of delete-dups.
+
+2004-02-16  Jesper Harder  <harder@ifa.au.dk>  (tiny change)
+
+	* keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button.
+
+2004-02-16  Jan Dj,Ad(Brv  <jan.h.d@swipnet.se>
+
+	* frames.texi (Parameter Access): frame-parameters arg is optional.
+	modify-frame-parameters handles nil for FRAME.
+	(Window Frame Parameters): menu-bar-lines and tool-bar-lines
+	are all-or-nothing for certain toolkits.
+	Mention parameter wait-for-wm.
+	(Frames and Windows): In frame-first-window and frame-selected-window
+	the arg is optional.
+	(Input Focus): In redirect-frame-focus the second arg is optional.
+	(Window System Selections): Mention selection type CLIPBOARD.
+	Mention data-type UTF8_STRING.
+	Mention numbering of cut buffers.
+	(Resources): Describe x-resource-name.
+
+2004-02-16  Richard M. Stallman  <rms@gnu.org>
+
+	* windows.texi (Buffers and Windows): Delete false table
+	about all-frames.
+
+	* syntax.texi (Parsing Expressions): Delete old caveat
+	about parse-sexp-ignore-comments.
+
+	* streams.texi (Output Variables): Add print-quoted.
+
+	* lists.texi (Building Lists): Minor cleanup.
+
+	* hash.texi (Creating Hash): Correct and clarify doc of WEAK values.
+
+	* display.texi (Overlays): Explain overlays use markers.
+	(Managing Overlays): Explain front-advance and rear-advance
+	in more detail.
+
+	* loading.texi (Unloading): Document unload-feature-special-hooks.
+	Get rid of fns-NNN.el file.
+
+2004-02-16  Matthew Mundell  <matt@mundell.ukfsn.org>  (tiny change)
+
+	* help.texi (Describing Characters): Fix text-char-description
+	example output.
+
+	* edebug.texi (Using Edebug): Fix example.
+
+	* debugging.texi (Internals of Debugger): Fix return value.
+
+	* files.texi (Changing Files): Fix argname.
+
+	* calendar.texi: Fix parens, and default values.
+
+	* display.texi, frames.texi, internals.texi, modes.texi: Minor fixes.
+	* nonascii.texi, objects.texi, os.texi: Minor fixes.
+	* searching.texi, text.texi, tips.texi, windows.text: Minor fixes.
+
+	* positions.texi (Text Lines): Don't add -1 in current-line.
+
+2004-02-16  Richard M. Stallman  <rms@gnu.org>
+
+	* compile.texi (Compiler Errors): if-boundp feature applies to cond.
+
+2004-02-16  Jesper Harder  <harder@ifa.au.dk>  (tiny change)
+
+	* processes.texi (Low-Level Network): Fix a typo.
+
+2004-02-12  Kim F. Storm  <storm@cua.dk>
+
+	* display.texi (Fringes): Use consistent wording.
+	Note that window-fringe's window arg is optional.
+	(Scroll Bars): Use consistent wording.
+
+2004-02-11  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* tips.texi (Comment Tips): Document the new conventions for
+	commenting out code.
+
+2004-02-07  Jan Dj,Ad(Brv  <jan.h.d@swipnet.se>
+
+	* positions.texi (Text Lines): Added missing end defun.
+
+2004-02-07  Kim F. Storm  <storm@cua.dk>
+
+	* positions.texi (Text Lines): Add line-number-at-pos.
+
+2004-02-06  John Paul Wallington  <jpw@gnu.org>
+
+	* display.texi (Button Properties, Button Buffer Commands):
+	mouse-2 invokes button, not down-mouse-1.
+
+2004-02-04  Jason Rumney  <jasonr@gnu.org>
+
+	* makefile.w32-in: Sync with Makefile.in changes.
+
+2004-02-03  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* minibuf.texi (Text from Minibuffer): Various corrections and
+	clarifications.
+	(Object from Minibuffer): Correct Lisp description of
+	read-minibuffer.
+	(Minibuffer History): Clarify description of cons values for
+	HISTORY arguments.
+	(Basic Completion): Various corrections and clarifications.  Add
+	completion-regexp-list.
+	(Minibuffer Completion): Correct and clarify description of
+	completing-read.
+	(Completion Commands): Mention Partial Completion mode.  Various
+	other minor changes.
+	(High-Level Completion): Various corrections and clarifications.
+	(Reading File Names): Ditto.
+	(Minibuffer Misc): Ditto.
+
+2004-01-26  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* strings.texi (Text Comparison): assoc-string also matches
+	elements of alists that are strings instead of conses.
+	(Formatting Strings): Standardize Texinfo usage.  Update index
+	entries.
+
+2004-01-20  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* lists.texi (Sets And Lists): Add delete-dups.
+
+2004-01-15  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* edebug.texi (Instrumenting Macro Calls): `declare' is not a
+	special form.
+	* macros.texi (Defining Macros): Update description of `declare',
+	which now is a macro.
+	(Wrong Time): Fix typos.
+
+2004-01-14  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* compile.texi (Compilation Functions): Expand descriptions of
+	`compile-defun', `byte-compile-file', `byte-recompile-directory'
+	and `batch-byte-compile'.  In particular, mention and describe
+	all optional arguments.
+	(Disassembly): Correct and clarify the description of `disassemble'.
+
+2004-01-11  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* searching.texi: Various small changes in addition to the
+	following.
+	(Regexp Example): Adapt to new value of `sentence-end'.
+	(Regexp Functions): The PAREN argument to `regexp-opt' can be
+	`words'.
+	(Search and Replace): Add usage note for `perform-replace'.
+	(Entire Match Data): Mention INTEGERS and REUSE arguments to
+	`match-data'.
+	(Standard Regexps): Update for new values of `paragraph-start'
+	and `sentence-end'.
+
+2004-01-07  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* files.texi (Saving Buffers): Clarify descriptions of
+	`write-contents-functions' and `before-save-hook'.
+	Make the defvar's for `before-save-hook' and `after-save-hook'
+	into defopt's.
+
+2004-01-07  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Click Events): Describe new image and
+	width/height elements of click events.
+	(Accessing Events): Add posn-string, posn-image, and
+	posn-object-width-height.  Change posn-object to return either
+	image or string object.
+
+2004-01-01  Simon Josefsson  <jas@extundo.com>
+
+	* hooks.texi (Standard Hooks): Add before-save-hook.
+	* files.texi (Saving Buffers): Likewise.
+
+2004-01-03  Richard M. Stallman  <rms@gnu.org>
+
+	* frames.texi (Frames and Windows): Delete frame-root-window.
+
+2004-01-03  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* eval.texi, hash.texi, help.texi, symbols.texi: Add anchors.
+
+	* functions.texi: Various small changes in addition to the
+	following.
+	(What Is a Function): `functionp' returns nil for macros.  Clarify
+	behavior of this and following functions for symbol arguments.
+	(Function Documentation): Add `\' in front of (fn @var{arglist})
+	and explain why.
+	(Defining Functions): Mention DOCSTRING argument to `defalias'.
+	Add anchor.
+	(Mapping Functions): Add anchor.  Unquote nil in mapcar* example.
+
+2004-01-01  Miles Bader  <miles@gnu.org>
+
+	* display.texi (Buttons): New section.
+
+2003-12-31  Andreas Schwab  <schwab@suse.de>
+
+	* numbers.texi (Math Functions): sqrt reports a domain-error
+	error.
+	(Float Basics): Use `(/ 0.0 0.0)' instead of `(sqrt -1.0)'.
+
+2003-12-30  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* tips.texi (Documentation Tips): Update item on hyperlinks in
+	documentation strings.
+
+	* errors.texi (Standard Errors): Various small corrections and
+	additions.
+
+	* control.texi: Various small changes in addition to the
+	following.
+	(Signaling Errors): Provide some more details on how `signal'
+	constructs the error message.  Add anchor to the definition of
+	`signal'.
+	(Error Symbols): Describe special treatment of `quit'.
+	(Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM
+	to emphasize that it has to be a single form.
+
+	* buffers.texi: Add anchor.
+
+2003-12-29  Richard M. Stallman  <rms@gnu.org>
+
+	* windows.texi (Choosing Window): Add same-window-p, special-display-p.
+	(Window Configurations): Add window-configuration-frame.
+
+	* variables.texi (Creating Buffer-Local): Add local-variable-if-set-p.
+
+	* text.texi (Examining Properties): Add get-char-property-and-overlay.
+	Change arg name in get-char-property.
+	(Special Properties): Update handling of keymap property.
+
+	* strings.texi (Modifying Strings): Add clear-string.
+	(Text Comparison): Add assoc-string and remove
+	assoc-ignore-case, assoc-ignore-representation.
+
+	* os.texi (Time of Day): Add set-time-zone-rule.
+
+	* numbers.texi (Math Functions): asin, acos, log, log10
+	report domain-error errors.
+
+	* nonascii.texi (Converting Representations):
+	Add multibyte-char-to-unibyte and unibyte-char-to-multibyte.
+	(Encoding and I/O): Add file-name-coding-system.
+
+	* modes.texi (Search-based Fontification): Explain that
+	face specs are symbols with face names as values.
+
+	* minibuf.texi (Minibuffer Misc): Add set-minibuffer-window.
+
+	* lists.texi (Building Lists): remq moved elsewhere.
+	(Sets And Lists): remq moved here.
+	(Association Lists): Refer to assoc-string.
+
+	* internals.texi (Garbage Collection): Add memory-use-counts.
+
+	* frames.texi (Frames and Windows): Add set-frame-selected-window
+	and frame-root-window.
+
+	* files.texi (Contents of Directories):
+	Add directory-files-and-attributes.
+
+	* display.texi (Refresh Screen): Add force-window-update.
+	(Invisible Text): Explain about moving point out of invis text.
+	(Overlay Properties): Add overlay-properties.
+	(Managing Overlays): Add overlayp.
+	(GIF Images): Invalid image number displays a hollow box.
+
+	* buffers.texi (Buffer Modification): Add restore-buffer-modified-p.
+	(Killing Buffers): Add buffer-live-p.
+
+2003-12-25  Markus Rost  <rost@mathematik.uni-bielefeld.de>
+
+	* display.texi (Fringes): Fix typo "set-buffer-window".
+
+2003-12-24  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* display.texi, eval.texi, help.texi, internals.texi, loading.texi:
+	* nonascii.texi, processes.texi, tips.texi, variables.texi:
+	Add or change various xrefs and anchors.
+
+	* commands.texi: Replace all occurrences of @acronym{CAR} with
+	@sc{car}, for consistency with the rest of the Elisp manual.
+	`car' and `cdr' are historically acronyms, but are no longer
+	widely thought of as such.
+
+	* internals.texi (Pure Storage): Mention that `purecopy' does not
+	copy text properties.
+	(Object Internals): Now 29 bits are used (in most implementations)
+	to address Lisp objects.
+
+	* variables.texi (Variables with Restricted Values): New node.
+
+	* objects.texi (Lisp Data Types): Mention that certain variables
+	can only take on a restricted set of values and add an xref to
+	the new node "Variables with Restricted Values".
+
+	* eval.texi (Function Indirection): Describe the errors that
+	`indirect-function' can signal.
+	(Eval): Clarify the descriptions of `eval-region' and `values'.
+	Describe `eval-buffer' instead of `eval-current-buffer' and
+	mention `eval-current-buffer' as an alias for `current-buffer'.
+	Correct the description and mention all optional arguments.
+
+	* nonascii.texi: Various small changes in addition to the
+	following.
+	(Converting Representations): Clarify behavior of
+	`string-make-multibyte' and `string-to-multibyte' for unibyte all
+	ASCII arguments.
+	(Character Sets): Document the variable `charset-list' and adapt
+	the definition of the function `charset-list' accordingly.
+	(Translation of Characters): Clarify use of generic characters in
+	`make-translation-table'.  Clarify and correct the description of
+	the use of translation tables in encoding and decoding.
+	(User-Chosen Coding Systems): Correct and clarify the description
+	of `select-safe-coding-system'.
+	(Default Coding Systems): Clarify description of
+	`file-coding-system-alist'.
+
+2003-11-30  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* strings.texi (Text Comparison): Correctly describe when two
+	strings are `equal'.  Combine and clarify descriptions of
+	`assoc-ignore-case' and `assoc-ignore-representation'.
+
+	* objects.texi (Non-ASCII in Strings): Clarify description of
+	when a string is unibyte or multibyte.
+	(Bool-Vector Type): Update examples.
+	(Equality Predicates): Correctly describe when two strings are
+	`equal'.
+
+2003-11-29  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* lists.texi (Building Lists): `append' no longer accepts integer
+	arguments.  Update the description of `number-sequence' to reflect
+	recent changes.
+	(Sets And Lists): Describe `member-ignore-case' after `member'.
+
+2003-11-27  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Click Events): Click object may be an images.
+	Describe (dx . dy) element of click positions.
+	(Accessing Events): Remove duplicate posn-timestamp.
+	New functions posn-object and posn-object-x-y.
+
+2003-11-23  Kim F. Storm  <storm@cua.dk>
+
+	* commands.texi (Click Events): Describe enhancements to event
+	position lists, including new text-pos and (col . row) items.
+	Mention left-fringe and right-fringe area events.
+	(Accessing Events): New functions posn-area and
+	posn-actual-col-row.  Mention posn-timestamp.  Mention that
+	posn-point in non-text area still returns buffer position.
+	Clarify posn-col-row.
+
+2003-11-21  Lars Hansen  <larsh@math.ku.dk>
+
+	* files.texi (File Attributes): Describe new parameter ID-FORMAT.
+	* anti.texi (File Attributes): Describe removed parameter
+	ID-FORMAT.
+
+2003-11-20  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* positions.texi (Positions): Mention that, if a marker is used as
+	a position, its buffer is ignored.
+
+	* markers.texi (Overview of Markers): Mention it here too.
+
+2003-11-12  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* numbers.texi (Numeric Conversions): Not just `floor', but also
+	`truncate', `ceiling' and `round' accept optional argument DIVISOR.
+
+2003-11-10  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* markers.texi (Creating Markers): Specify insertion type of
+	created markers.  Add xref to `Marker Insertion Types'.
+	Second argument to `copy-marker' is optional.
+	(Marker Insertion Types): Mention that most markers are created
+	with insertion type nil.
+	(The Mark): Correctly describe when `mark' signals an error.
+	(The Region): Correctly describe when `region-beginning' and
+	`region-end' signal an error.
+
+2003-11-08  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* hash.texi (Creating Hash): Clarify description of `eql'.
+	`makehash' is obsolete.
+	(Hash Access): Add Common Lisp notes for `remhash' and `clrhash'.
+
+	* positions.texi (Point): Change description of `buffer-end', so
+	that it is also correct for floating point arguments.
+	(List Motion): Correct argument lists of `beginning-of-defun' and
+	`end-of-defun'.
+	(Excursions): Add xref to `Marker Insertion Types'.
+	(Narrowing): Argument to `narrow-to-page' is optional.
+
+2003-11-06  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* streams.texi (Output Streams): Clarify behavior of point for
+	marker output streams.
+
+2003-11-04  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* variables.texi (Defining Variables): Second argument to
+	`defconst' is not optional.
+	(Setting Variables): Mention optional argument APPEND to
+	`add-to-list'.
+	(Creating Buffer-Local): Expand description of
+	`make-variable-buffer-local'.
+	(Frame-Local Variables): Expand description of
+	`make-variable-frame-local'.
+	(Variable Aliases): Correct description of optional argument
+	DOCSTRING to `defvaralias'.  Mention return value of
+	`defvaralias'.
+	(File Local Variables): Add xref to `File variables' in Emacs
+	Manual.  Correct description of `hack-local-variables'.  Mention
+	`safe-local-variable' property.  Mention optional second argument
+	to `risky-local-variable-p'.
+
+2003-11-03  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* symbols.texi (Symbol Plists): Mention return value of `setplist'.
+
+2003-11-02  Jesper Harder  <harder@ifa.au.dk>  (tiny change)
+
+	* lispref/anti.texi, lispref/backups.texi, lispref/commands.texi
+	lispref/customize.texi, lispref/display.texi, lispref/files.texi,
+	lispref/internals.texi, lispref/keymaps.texi, lispref/loading.texi,
+	lispref/modes.texi, lispref/nonascii.texi, lispref/numbers.texi,
+	lispref/objects.texi, lispref/os.texi, lispref/positions.texi,
+	lispref/processes.texi, lispref/searching.texi,
+	lispref/sequences.texi, lispref/streams.texi, lispref/strings.texi,
+	lispref/syntax.texi, lispref/text.texi: Replace @sc{foo} with
+	@acronym{FOO}.
+
+2003-10-27  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* strings.texi (Creating Strings): Argument START to `substring'
+	can not be `nil'.  Expand description of
+	`substring-no-properties'.  Correct description of `split-string',
+	especially with respect to empty matches.  Prevent very bad line
+	break in definition of `split-string-default-separators'.
+	(Text Comparison): `string=' and `string<' also accept symbols as
+	arguments.
+	(String Conversion): More completely describe argument BASE in
+	`string-to-number'.
+	(Formatting Strings): `%s' and `%S' in `format' do require
+	corresponding object.  Clarify behavior of numeric prefix after
+	`%' in `format'.
+	(Case Conversion): The argument to `upcase-initials' can be a
+	character.
+
+2003-10-27  Kenichi Handa  <handa@m17n.org>
+
+	* display.texi (Fontsets): Fix texinfo usage.
+
+2003-10-25  Kenichi Handa  <handa@m17n.org>
+
+	* display.texi (Fontsets): Add description of the function
+	set-fontset-font.
+
+2003-10-23  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* display.texi (Temporary Displays): Add xref to `Documentation
+	Tips'.
+
+	* functions.texi (Function Safety): Use inforef instead of pxref
+	for SES.
+
+2003-10-23  Andreas Schwab  <schwab@suse.de>
+
+	* Makefile.in (TEX, texinputdir): Don't define.
+	(TEXI2DVI): Define.
+	(srcs): Remove $(srcdir)/index.perm and $(srcdir)/index.unperm,
+	add $(srcdir)/index.texi.
+	($(infodir)/elisp): Remove index.texi dependency.
+	(elisp.dvi): Likewise.  Use $(TEXI2DVI).
+	(index.texi): Remove target.
+	(dist): Don't link $(srcdir)/permute-index.
+	(clean): Don't remove index.texi.
+
+	* permute-index, index.perm: Remove.
+	* index.texi: Rename from index.unperm.
+
+2003-10-22  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* tips.texi (Documentation Tips): Document new behavior for face
+	and variable hyperlinks in Help mode.
+
+2003-10-21  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* objects.texi (Integer Type): Update for extra bit of integer range.
+	(Character Type): Ditto.
+
+2003-10-16  Eli Zaretskii  <eliz@gnu.org>
+
+	* numbers.texi (Integer Basics): Add index entries for reading
+	numbers in hex, octal, and binary.
+
+2003-10-16  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Mode Line Format): Mention force-mode-line-update's
+	argument.
+
+2003-10-13  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* windows.texi (Choosing Window): Fix typo.
+	* edebug.texi (Edebug Execution Modes): Fix typo.
+
+2003-10-13  Richard M. Stallman  <rms@gnu.org>
+
+	* windows.texi (Basic Windows): A window has fringe settings,
+	display margins and scroll-bar settings.
+	(Splitting Windows): Doc split-window return value.
+	Clean up one-window-p.
+	(Selecting Windows): Fix typo.
+	(Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window.
+	(Buffers and Windows): In set-window-buffer, explain effect
+	on fringe settings and scroll bar settings.
+	(Displaying Buffers): In pop-to-buffer, explain nil as buffer arg.
+	(Choosing Window): Use defopt for pop-up-frame-function.
+	For special-display-buffer-names, explain same-window and same-frame.
+	Clarify window-dedicated-p return value.
+	(Textual Scrolling): scroll-up and scroll-down can get an error.
+	(Horizontal Scrolling): Clarify auto-hscroll-mode.
+	Clarify set-window-hscroll.
+	(Size of Window): Don't mention tool bar in window-height.
+	(Coordinates and Windows): Explain what coordinates-in-window-p
+	returns for fringes and display margins.
+	(Window Configurations): Explain saving fringes, etc.
+
+	* tips.texi (Library Headers): Clean up Documentation.
+
+	* syntax.texi (Parsing Expressions): Clean up forward-comment
+	and parse-sexp-lookup-properties.
+
+	* sequences.texi (Sequence Functions): sequencep accepts bool-vectors.
+
+	* os.texi (System Environment): Clean up text for load-average errors.
+
+	* modes.texi (Hooks): Don't explain local hook details at front.
+	Clarify run-hooks and run-hook-with-args a little.
+	Clean up add-hook and remove-hook.
+
+	* edebug.texi (Edebug Execution Modes): Clarify t.
+	Document edebug-sit-for-seconds.
+	(Coverage Testing): Document C-x X = and =.
+	(Instrumenting Macro Calls): Fix typo.
+	(Specification List): Don't index the specification keywords.
+
+2003-10-10  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Network): Introduce make-network-process.
+
+2003-10-09  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* tips.texi (Library Headers): Fix typo.
+
+2003-10-07  Juri Linkov  <juri@jurta.org>
+
+	* modes.texi (Imenu): Mention imenu-create-index-function's
+	default value.  Explain submenus better.
+
+2003-10-07  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Faces for Font Lock): Fix typo.
+	(Hooks): Explain how buffer-local hook variables can refer to
+	global hook variables.
+	Various minor clarifications.
+
+2003-10-06  Lute Kamstra  <lute@gnu.org>
+
+	* tips.texi (Coding Conventions): Mention naming conventions for
+	hooks.
+
+2003-10-05  Luc Teirlinck  <teirllm@auburn.edu>
+
+	* loading.texi (Library Search): Correct default value of
+	load-suffixes.
+	(Named Features): Fix typo.
+
+2003-10-05  Richard M. Stallman  <rms@gnu.org>
+
+	* loading.texi (Named Features): In `provide',
+	say how to test for subfeatures.
+	(Unloading): In unload-feature, use new var name
+	unload-feature-special-hooks.
+
+2003-10-03  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Major Mode Conventions): Mention third way to set up
+	Imenu.
+	(Imenu): A number of small fixes.
+	Delete documentation of internal variable imenu--index-alist.
+	Document the return value format of imenu-create-index-function
+	functions.
+
+2003-09-30  Richard M. Stallman  <rms@gnu.org>
+
+	* processes.texi (Network): Say what stopped datagram connections do.
+
+	* lists.texi (Association Lists): Clarify `assq-delete-all'.
+
+	* display.texi (Overlay Properties): Clarify `evaporate' property.
+
+2003-09-29  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Mode Line Data): Explain when symbols in mode-line
+	constructs should be marked as risky.
+	Change cons cell into proper list.
+	(Mode Line Variables): Change cons cell into proper list.
+
+2003-09-26  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (Mode Line Data): Document the :propertize construct.
+	(Mode Line Variables): Reorder the descriptions of the variables
+	to match their order in the default mode-line-format.
+	Describe the new variables mode-line-position and mode-line-modes.
+	Update the default values of mode-line-frame-identification,
+	minor-mode-alist, and default-mode-line-format.
+	(Properties in Mode): Mention the :propertize construct.
+
+2003-09-26  Richard M. Stallman  <rms@gnu.org>
+
+	* buffers.texi, commands.texi, debugging.texi, eval.texi:
+	* loading.texi, minibuf.texi, text.texi, variables.texi:
+	Avoid @strong{Note:}.
+
+2003-09-26  Richard M. Stallman  <rms@gnu.org>
+
+	* keymaps.texi (Remapping Commands): Fix typo.
+
+2003-09-23  Luc Teirlinck  <teirllm@mail.auburn.edu>
+
+	* processes.texi (Low-Level Network): Fix typo.
+
+2003-09-23  Kim F. Storm  <storm@cua.dk>
+
+	* processes.texi (Network, Network Servers): Fix typos.
+	(Low-Level Network): Add timeout value for :server keyword.
+	Add new option keywords to make-network-process.
+	Add set-network-process-options.
+	Explain how to test availability of network options.
+
+2003-09-19  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Motion by Indent): Arg to
+	backward-to-indentation and forward-to-indentation is optional.
+
+	* strings.texi (Creating Strings): Add substring-no-properties.
+
+	* processes.texi
+	(Process Information): Add list-processes arg QUERY-ONLY.
+	Delete process-contact from here.
+	Add new status values for process-status.
+	Add process-get, process-put, process-plist, set-process-plist.
+	(Synchronous Processes): Add call-process-shell-command.
+	(Signals to Processes): signal-process allows process objects.
+	(Network): Complete rewrite.
+	(Network Servers, Datagrams, Low-Level Network): New nodes.
+
+	* positions.texi (Word Motion): forward-word, backward-word
+	arg is optional.  Reword.
+
+	* abbrevs.texi (Defining Abbrevs): Index no-self-insert.
+
+	* variables.texi (Creating Buffer-Local):
+	Delete duplicate definition of buffer-local-value.
+	(File Local Variables): Explain about discarding text props.
+
+2003-09-11  Richard M. Stallman  <rms@gnu.org>
+
+	* minibuf.texi (Intro to Minibuffers): Explain that the minibuffer
+	changes variables that record input events.
+	(Minibuffer Misc): Add minibuffer-selected-window.
+
+	* lists.texi (Building Lists): Add copy-tree.
+
+	* display.texi (Fontsets): Add char-displayable-p.
+	(Scroll Bars): New node.
+
+2003-09-08  Lute Kamstra  <lute@gnu.org>
+
+	* modes.texi (%-Constructs): Document new `%i' and `%I'
+	constructs.
+
+2003-09-03  Peter Runestig  <peter@runestig.com>
+
+	* makefile.w32-in: New file.
+
+2003-08-29  Richard M. Stallman  <rms@gnu.org>
+
+	* display.texi (Overlay Properties): Clarify how priorities
+	affect use of the properties.
+
+2003-08-19  Luc Teirlinck  <teirllm@mail.auburn.edu>
+
+	* customize.texi (Type Keywords): Correct the description of
+	`:help-echo' in the case where `motion-doc' is a function.
+
+2003-08-14  John Paul Wallington  <jpw@gnu.org>
+
+	* modes.texi (Emulating Mode Line): Subsection, not section.
+
+2003-08-13  Richard M. Stallman  <rms@gnu.org>
+
+	* elisp.texi (Top): Update subnode lists in menu.
+
+	* text.texi (Insertion): Add insert-buffer-substring-no-properties.
+	(Kill Functions): kill-region has new arg yank-handler.
+	(Yanking): New node.
+	(Yank Commands): Add yank-undo-function.
+	(Low-Level Kill Ring):
+	kill-new and kill-append have new arg yank-handler.
+	(Changing Properties): Add remove-list-of-text-properties.
+	(Atomic Changes): New node.
+
+	* symbols.texi (Other Plists): Add lax-plist-get, lax-plist-put.
+
+	* streams.texi (Output Variables): Add eval-expression-print-length
+	and eval-expression-print-level.
+
+	* os.texi (Time Conversion): For encode-time, explain limits on year.
+
+	* objects.texi (Character Type): Define anchor "modifier bits".
+
+	* modes.texi (Emulating Mode Line): New node.
+	(Search-based Fontification): Font Lock uses font-lock-face property.
+	(Other Font Lock Variables): Likewise.
+
+	* keymaps.texi (Format of Keymaps): Keymaps contain char tables,
+	not vectors.
+	(Active Keymaps): Add emulation-mode-map-alists.
+	(Functions for Key Lookup): key-binding has new arg no-remap.
+	(Remapping Commands): New node.
+	(Scanning Keymaps): where-is-internal has new arg no-remap.
+	(Tool Bar): Add tool-bar-local-item-from-menu.
+	Clarify when to use tool-bar-add-item-from-menu.
+
+	* commands.texi (Interactive Call): commandp has new arg.
+	(Command Loop Info): Add this-original-command.
+
+2003-08-06  John Paul Wallington  <jpw@gnu.org>
+
+	* compile.texi (Compiler Errors): Say `@end defmac' after `@defmac'.
+
+	* display.texi (Warning Basics): Fix typo.
+	(Fringes): Add closing curly bracket and fix typo.
+
+	* elisp.texi (Top): Fix typo.
+
+2003-08-05  Richard M. Stallman  <rms@gnu.org>
+
+	* elisp.texi: Update lists of subnodes.
+
+	* windows.texi (Buffers and Windows): set-window-buffer has new arg.
+
+	* variables.texi (Local Variables): Use lc for example variable names.
+
+	* tips.texi (Library Headers): Explain where to put -*-.
+
+	* strings.texi (Creating Strings): Fix xref for vconcat.
+
+	* sequences.texi (Vector Functions):
+	vconcat no longer allows integer args.
+
+	* minibuf.texi (Reading File Names): read-file-name has new
+	arg PREDICATE.  New function read-directory-name.
+
+	* macros.texi (Defining Macros): Give definition of `declare'
+	(Indenting Macros): New node.
+
+	* frames.texi (Parameter Access): Add modify-all-frames-parameters.
+	(Window Frame Parameters): Make separate table of parameters
+	that are coupled with specific face attributes.
+	(Deleting Frames): delete-frame-hooks renamed to
+	delete-frame-functions.
+
+	* files.texi (Magic File Names): Add file-remote-p.
+	Clarify file-local-copy.
+
+	* edebug.texi (Instrumenting Macro Calls): Don't define `declare'
+	here; instead xref Defining Macros.
+
+	* display.texi (Warnings): New node, and subnodes.
+	(Fringes): New node.
+
+	* debugging.texi (Test Coverage): New node.
+
+	* compile.texi (Compiler Errors): Explain with-no-warnings
+	and other ways to suppress warnings.
+
+	* commands.texi (Interactive Call): Minor clarification.
+
+	* buffers.texi (Buffer File Name): set-visited-file-name
+	renames the buffer too.
+
+	* abbrevs.texi (Abbrev Tables): Add copy-abbrev-table.
+
+2003-07-24  Markus Rost  <rost@math.ohio-state.edu>
+
+	* abbrevs.texi (Abbrev Expansion): Use \s syntax in example.
+
+2003-07-22  Markus Rost  <rost@math.ohio-state.edu>
+
+	* internals.texi (Garbage Collection): Fix previous change.
+
+2003-07-22  Richard M. Stallman  <rms@gnu.org>
+
+	* files.texi (Truenames): Add LIMIT arg to file-chase-links.
+
+	* display.texi (Width): Use \s syntax in example.
+	(Font Selection): Add face-font-rescale-alist.
+
+	* modes.texi (Imenu): Add xref to Emacs Manual node on Imenu.
+	Remove spurious indent in example.
+
+	* lists.texi (Building Lists): Add number-sequence.
+
+	* internals.texi (Garbage Collection): Add gcs-done, gc-elapsed.
+
+	* functions.texi (Function Documentation): Explain how to
+	show calling convention explicitly in the doc string.
+
+	* windows.texi (Selecting Windows): save-selected-window saves
+	selected window of each frame.
+	(Window Configurations): Minor change.
+
+	* syntax.texi (Syntax Table Functions): Use \s syntax in examples.
+
+	* streams.texi (Output Variables): Add print-continuous-numbering
+	and print-number-table.
+
+	* processes.texi (Decoding Output): New node.
+
+	* os.texi (Time Conversion): decode-time arg is optional.
+
+	* objects.texi (Character Type): Don't use space as example for \.
+	Make list of char names and \-sequences correspond.
+	Explain that \s is not used in strings.  `\ ' needs space after.
+
+	* nonascii.texi (Converting Representations): Add string-to-multibyte.
+	(Translation of Characters): Add translation-table-for-input.
+	(Default Coding Systems): Add auto-coding-functions.
+	(Explicit Encoding): Add decode-coding-inserted-region.
+	(Locales): Add locale-info.
+
+	* minibuf.texi (Basic Completion): Describe test-completion.
+	Collections can be lists of strings.
+	Clean up lazy-completion-table.
+	(Programmed Completion): Mention test-completion.
+	Clarify why lambda expressions are not accepted.
+	(Minibuffer Misc): Describe minibufferp.
+
+2003-07-14  Richard M. Stallman  <rms@gnu.org>
+
+	* buffers.texi (Killing Buffers): kill-buffer-hook is perm local.
+
+	* windows.texi (Selecting Windows): New arg to select-window.
+	(Selecting Windows): Add with-selected-window.
+	(Size of Window): Add window-inside-edges, etc.
+
+	* internals.texi (Garbage Collection): Add post-gc-hook.
+
+	* processes.texi (Subprocess Creation): Add exec-suffixes.
+
+	* keymaps.texi (Functions for Key Lookup): Add current-active-maps.
+	(Scanning Keymaps): Add map-keymaps.
+	(Defining Menus): Add keymap-prompt.
+
+	* numbers.texi (Integer Basics): Add most-positive-fixnum,
+	most-negative-fixnum.
+
+	* compile.texi (Byte Compilation): Explain no-byte-compile
+	(Compiler Errors): New node.
+
+	* os.texi (User Identification): user-uid, user-real-uid
+	can return float.
+
+	* modes.texi (Major Mode Conventions): Explain about run-mode-hooks
+	and about derived modes.
+	(Minor Modes): Add minor-mode-list.
+	(Defining Minor Modes): Keyword args for define-minor-mode.
+	(Search-based Fontification): Explain managing other properties.
+	(Other Font Lock Variables): Add font-lock-extra-managed-props.
+	(Faces for Font Lock): Add font-locl-preprocessor-face.
+	(Hooks): Add run-mode-hooks and delay-mode-hooks.
+
+	* variables.texi (Creating Buffer-Local): Add buffer-local-value.
+	(Variable Aliases): Clarify defvaralias.
+
+	* loading.texi (Library Search): Add load-suffixes.
+
+	* minibuf.texi (Basic Completion): Add lazy-completion-table.
+	(Programmed Completion): Add dynamic-completion-table.
+
+	* files.texi (Changing Files): copy-file allows dir as NEWNAME.
+	(Magic File Names): Specify precedence order of handlers.
+
+	* commands.texi (Command Overview): Emacs server runs pre-command-hook
+	and post-command-hook.
+	(Waiting): New calling convention for sit-for.
+
+	* text.texi (Special Properties): local-map and keymap properties
+	apply based on their stickiness.
+
+2003-07-07  Richard M. Stallman  <rms@gnu.org>
+
+	* modes.texi (Minor Mode Conventions): Specify only some kinds
+	of list values as args to minor modes.
+
+	* files.texi (File Name Expansion): Warn about iterative use
+	of substitute-in-file-name.
+
+	* advice.texi (Activation of Advice): Clean up previous change.
+
+2003-07-06  Markus Rost  <rost@math.ohio-state.edu>
+
+	* advice.texi (Activation of Advice): Note that ad-start-advice is
+	turned on by default.
+
+2003-06-30  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Buffer Contents): Document current-word.
+	(Change Hooks): Not called for *Messages*.
+
+	* functions.texi (Defining Functions): Explain about redefining
+	primitives.
+	(Function Safety): Renamed.  Minor changes.
+	Comment out the detailed criteria for what is safe.
+
+2003-06-22  Andreas Schwab  <schwab@suse.de>
+
+	* objects.texi (Symbol Type): Fix description of examples.
+
+2003-06-16  Andreas Schwab  <schwab@suse.de>
+
+	* hash.texi (Creating Hash): Fix description of :weakness.
+
+2003-06-13  Kai Gro,A_(Bjohann  <kai.grossjohann@gmx.net>
+
+	* files.texi (Changing Files): copy-file copies file modes, too.
+
+2003-05-28  Richard M. Stallman  <rms@gnu.org>
+
+	* strings.texi (Creating Strings): Clarify split-string.
+
+2003-05-22  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* strings.texi (Creating Strings): Update split-string specification
+	and examples.
+
+2003-05-19  Richard M. Stallman  <rms@gnu.org>
+
+	* elisp.texi: Correct invariant section names.
+
+2003-04-20  Richard M. Stallman  <rms@gnu.org>
+
+	* os.texi (Timers): Explain about timers and quitting.
+
+2003-04-19  Richard M. Stallman  <rms@gnu.org>
+
+	* internals.texi (Writing Emacs Primitives): Strings are
+	no longer special for GCPROs.  Mention GCPRO5, GCPRO6.
+	Explain GCPRO convention for varargs function args.
+
+2003-04-16  Richard M. Stallman  <rms@gnu.org>
+
+	* minibuf.texi (Minibuffer Misc): Document fn minibuffer-message.
+
+2003-04-08  Richard M. Stallman  <rms@gnu.org>
+
+	* files.texi (Kinds of Files): Correct return value of file-symlink-p.
+
+2003-02-13  Kim F. Storm  <storm@cua.dk>
+
+	* objects.texi (Character Type): New \s escape for space.
+
+2003-01-31  Joe Buehler  <jhpb@draco.hekimian.com>
+
+	* os.texi (System Environment): Added cygwin system-type.
+
+2003-01-25  Richard M. Stallman  <rms@gnu.org>
+
+	* keymaps.texi: Document that a symbol can act as a keymap.
+
+2003-01-13  Richard M. Stallman  <rms@gnu.org>
+
+	* text.texi (Changing Properties): Say string indices are origin-0.
+
+	* positions.texi (Screen Lines) <compute-motion>:
+	Correct order of elts in return value.
+
+	* keymaps.texi (Changing Key Bindings) <define-key>: Mention
+	how to define a default binding.
+
+2002-12-07  Markus Rost  <rost@math.ohio-state.edu>
+
+	* loading.texi (Unloading): Fix recent change for load-history.
+
+	* customize.texi (Simple Types): Clarify description of custom
+	type 'number.  Describe new custom type 'float.
+
+2002-12-04  Markus Rost  <rost@math.ohio-state.edu>
+
+	* variables.texi (File Local Variables): Fix typo.
+
+2002-10-23  Kai Gro,A_(Bjohann  <kai.grossjohann@uni-duisburg.de>
+
+	From Michael Albinus <Michael.Albinus@alcatel.de>.
+
+	* README: Target for Info file is `make info'.
+
+	* files.texi (File Name Components): Fixed typos in
+	`file-name-sans-extension'.
+	(Magic File Names): Complete list of operations for magic file
+	name handlers.
+
+2002-09-16  Jonathan Yavner  <jyavner@engineer.com>
+
+	* variables.texi (File Local Variables): New function
+	risky-local-variable-p.
+
+2002-09-15  Jonathan Yavner  <jyavner@engineer.com>
+
+	* functions.texi (Function safety): New node about unsafep.
+
+2002-08-05  Per Abrahamsen  <abraham@dina.kvl.dk>
+
+	* customize.texi (Splicing into Lists): Fixed example.
+	Reported by Fabrice Bauzac <fabrice.bauzac@wanadoo.fr>
+
+2002-06-17  Juanma Barranquero  <lektu@terra.es>
+
+	* frames.texi (Display Feature Testing): Fix typo.
+
+2002-06-12  Andreas Schwab  <schwab@suse.de>
+
+	* frames.texi (Initial Parameters, Resources): Fix references to
+	the Emacs manual.
+
+2002-05-13  Kim F. Storm  <storm@cua.dk>
+
+	* variables.texi (Intro to Buffer-Local): Updated warning and
+	example relating to changing buffer inside let.
+
+2002-03-10  Jan Dj,Ad(Brv  <jan.h.d@swipnet.se>
+
+	* os.texi (Session Management): New node about X Session management.
+
+2002-01-18  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* elisp.texi (VERSION): Set to 2.9.  Update the version of Emacs
+	to which the manual corresponds, and the copyright years.
+
+	* Makefile.in (VERSION): Set to 2.9.
+
+2001-11-29  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* elisp.texi: Change the category in @dircategory to "Emacs", to
+	make it consistent with info/dir.
+
+2001-11-25  Miles Bader  <miles@gnu.org>
+
+	* text.texi (Fields): Describe new `limit' arg in
+	field-beginning/field-end.
+
+2001-11-17  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* permute-index: Don't depend on csh-specific features.  Replace
+	the interpreter name with /bin/sh.
+
+	* two-volume-cross-refs.txt: New file.
+	* two.el: New file.
+	* spellfile: New file.
+
+2001-11-16  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* permute-index: New file.
+
+	* vol1.texi, vol2.texi: Renamed from elisp-vol1.texi and
+	elisp-vol2.texi, respectively, to avoid file-name clashes in DOS
+	8+3 restricted namespace.
+
+	* Makefile.in (infodir): Define relative to $(srcdir).
+	($(infodir)/elisp): Don't chdir into $(srcdir), but add it to the
+	include directories list via -I switch to makeinfo.
+	(index.texi): Use cp if both hard and symbolic links fail.
+
+2001-11-10  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* Makefile.in (distclean): Add.
+
+	The following changes make ELisp manual part of the Emacs
+	distribution:
+
+	* Makefile.in: Add Copyright notice.
+	(prefix): Remove.
+	(infodir): Change value to "../info".
+	(VPATH): New variable.
+	(MAKE): Don't define.
+	(texmacrodir): Don't define.
+	(texinputdir): Append the existing value of TEXINPUTS.
+	($(infodir)/elisp): Instead of just "elisp".  Reformat the
+	command to be compatible with man/Makefile.in, and to put the
+	output into ../info.
+	(info): Add target.
+	(installall): Target removed.
+
+2001-10-31  Pavel Jan,Am(Bk  <Pavel@Janik.cz>
+
+	* tips.texi (Coding Conventions): Fix typo.
+
+2001-10-23  Gerd Moellmann  <gerd@gnu.org>
+
+	* Makefile.in (srcs): Add gpl.texi and doclicense.texi.
+
+2001-10-22  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* files.texi (File Name Components): Update the description of
+	file-name-sans-extension and file-name-extension, as they now
+	ignore leading dots.
+
+2001-10-20  Gerd Moellmann  <gerd@gnu.org>
+
+	* (Version 21.1 released.)
+
+2001-10-19  Miles Bader  <miles@gnu.org>
+
+	* positions.texi (Text Lines): Describe behavior of
+	`beginning-of-line'/`end-of-line' in the presence of field properties.
+
+2001-10-17  Gerd Moellmann  <gerd@gnu.org>
+
+	* Makefile.in (VERSION): Set to 2.8.
+	(manual): Use `manual-21'.
+
+	* elisp.texi (VERSION): Add and use it where the version
+	number was used.  Set it to 2.8.
+
+	* intro.texi: Likewise.
+
+2001-10-13  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* files.texi (File Name Completion): Document the significance of
+	a trailing slash in elements of completion-ignored-extensions.
+
+2001-10-06  Miles Bader  <miles@gnu.org>
+
+	* variables.texi (Variable Aliases): It's `@defmac', not `@defmacro'.
+
+2001-10-04  Gerd Moellmann  <gerd@gnu.org>
+
+	* variables.texi (Variable Aliases): New node.
+
+2001-10-04  Gerd Moellmann  <gerd@gnu.org>
+
+	* Branch for 21.1.
+
+2001-10-02  Miles Bader  <miles@gnu.org>
+
+	* minibuf.texi (Minibuffer Misc): Add entries for
+	`minibuffer-contents', `minibuffer-contents-no-properties', and
+	`delete-minibuffer-contents'.
+	Correct description for `minibuffer-prompt-end'.
+
+	* text.texi (Property Search): Correct descriptions of
+	`next-char-property-change' and `previous-char-property-change'.
+	Add entries for `next-single-char-property-change' and
+	`previous-single-char-property-change'.
+	Make operand names a bit more consistent.
+
+2001-09-30  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* frames.texi (Finding All Frames): Document that next-frame and
+	previous-frame are local to current terminal.
+
+2001-09-26  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* keymaps.texi (Creating Keymaps): Fix the description of the
+	result of make-keymap.
+
+2001-09-23  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* display.texi (Font Lookup, Attribute Functions)
+	(Image Descriptors): Add cross-references to the definition of
+	selected frame.
+
+	* buffers.texi (The Buffer List): Add cross-references to the
+	definition of selected frame.
+
+	* frames.texi (Input Focus): Clarify which frame is _the_ selected
+	frame at any given time.
+	(Multiple Displays, Size and Position): Add a cross-reference to
+	the definition of the selected frame.
+
+2001-09-08  Eli Zaretskii  <eliz@is.elta.co.il>
+
+	* strings.texi (String Conversion) <string-to-number>: Document
+	that a float is returned for integers that are too large.
+
+	* frames.texi (Mouse Position): Document mouse-position-function.
+	(Display Feature Testing): Document display-images-p.
+	(Window Frame Parameters): Document the cursor-type variable.
+
+	* numbers.texi (Integer Basics): Document CL style read syntax for
+	integers in bases other than 10.
+
+	* positions.texi (List Motion): Document
+	open-paren-in-column-0-is-defun-start.
+
+	* lists.texi (Sets And Lists): Document member-ignore-case.
+
+	* internals.texi (Garbage Collection): Document the used and free
+	strings report.
+	(Memory Usage): Document strings-consed.
+
+	* os.texi (Time of Day): Document float-time.
+	(Recording Input): Document that clear-this-command-keys clears
+	the vector to be returned by recent-keys.
+
+	* keymaps.texi (Scanning Keymaps) <where-is-internal>: The
+	argument keymap can be a list.
+
+	* nonascii.texi (User-Chosen Coding Systems)
+	<select-safe-coding-system>: Document the new argument
+	accept-default-p and the variable
+	select-safe-coding-system-accept-default-p.  Tell what happens if
+	buffer-file-coding-system is undecided.
+	(Default Coding Systems): Document auto-coding-regexp-alist.
+
+	* display.texi (The Echo Area) <message>: Document
+	message-truncate-lines.
+	(Glyphs): Document that the glyph table is unused on windowed
+	displays.
+
+	* help.texi (Describing Characters) <single-key-description>:
+	Document the new argument no-angles.
+	(Accessing Documentation) <documentation-property>: Document that
+	a non-string property is evaluated.
+	<documentation>: Document that the function-documentation property
+	is looked for.
+
+	* windows.texi (Selecting Windows): Document some-window.
+
+	* text.texi (MD5 Checksum): New node, documents the md5 primitive.
+
+	* hooks.texi (Standard Hooks): Add kbd-macro-termination-hook and
+	apropos-mode-hook.
+
+	* commands.texi (Using Interactive): Document interactive-form.
+	(Keyboard Macros): Document kbd-macro-termination-hook.
+	(Command Loop Info): Document that clear-this-command-keys clears
+	the vector to be returned by recent-keys.
+
+2001-09-04  Werner LEMBERG  <wl@gnu.org>
+
+	* Makefile.in (srcdir, texinputdir): New variables.
+	(srcs, index.texi, install): Use $(srcdir).
+	(.PHONY): Remove elisp.dvi.
+	(elisp): Use -I switch for makeinfo.
+	(elisp.dvi): Use $(srcdir) and $(texinputdir).
+	(installall, dist): Use $(srcdir).
+	Fix path to texinfo.tex.
+	(maintainer-clean): Add elisp.dvi and elisp.oaux.
+
+2001-08-30  Gerd Moellmann  <gerd@gnu.org>
+
+	* display.texi (Conditional Display): Adjust to API change.
+
+	* configure: New file.
+
+2001-07-30  Gerd Moellmann  <gerd@gnu.org>
+
+	* commands.texi (Repeat Events): Add description of
+	double-click-fuzz.
+
+2001-05-08  Stefan Monnier  <monnier@cs.yale.edu>
+
+	* syntax.texi (Syntax Class Table): Add the missing designator for
+	comment and string fences.
+	(Syntax Properties): Add a xref to syntax table internals.
+	(Syntax Table Internals): Document string-to-syntax.
+
+2001-05-07  Gerd Moellmann  <gerd@gnu.org>
+
+	* Makefile.in (install): Use install-info command line options
+	like in Emacs' Makefile.in.
+
+2000-12-09  Miles Bader  <miles@gnu.org>
+
+	* windows.texi (Window Start): Update documentation for
+	`pos-visible-in-window-p'.
+
+2000-11-12  Stefan Monnier  <monnier@cs.yale.edu>
+
+	* lists.texi (Building Lists): Add footnote to explain how to add
+	to the end of a list.
+
+2000-10-25  Gerd Moellmann  <gerd@gnu.org>
+
+	* files.texi (Visiting Functions): Typos.
+
+2000-10-25  Kenichi Handa  <handa@etl.go.jp>
+
+	* files.texi (Visiting Functions): Return value of
+	find-file-noselect may be a list of buffers if wildcards are used.
+
+2000-10-24  Miles Bader  <miles@lsi.nec.co.jp>
+
+	* display.texi (Defining Faces): Document `graphic' display type
+	in face specs.
+
+2000-10-18  Kai Grossjohann  <Kai.Grossjohann@CS.Uni-Dortmund.DE>
+
+	* hooks.texi (Standard Hooks): Replace obsolete
+	`after-make-frame-hook' with `after-make-frame-functions'.
+
+	* frames.texi (Creating Frames): Ditto.
+
+	* variables.texi (Future Local Variables): Ditto.
+
+2000-10-16  Gerd Moellmann  <gerd@gnu.org>
+
+	* display.texi (Other Image Types): Add description of :foreground
+	and :background properties of mono PBM images.
+
+2000-08-17  Werner LEMBERG  <wl@gnu.org>
+
+	* .cvsignore: New file.
+
+2000-01-05  Gerd Moellmann  <gerd@gnu.org>
+
+	* tindex.pl: New script.
+
+1999-12-03  Dave Love  <fx@gnu.org>
+
+	* Makefile.in (MAKEINFO): New parameter.
+
+1999-09-17  Richard Stallman  <rms@gnu.org>
+
+	* Makefile.in (srcs): Add hash.texi.
+	(VERSION): Update to 20.6.
+
+1999-09-13  Richard Stallman  <rms@gnu.org>
+
+	* Makefile.in (index.texi): If cannot make a symlink, make a hard link.
+
+1998-08-29  Karl Heuer  <kwzh@gnu.org>
+
+	* configure.in: New file.
+	* Makefile.in: Renamed from Makefile.
+	(prefix, infodir): Use value obtained from configure.
+	(emacslibdir): Obsolete variable deleted.
+	(dist): Distribute configure.in, configure, Makefile.in.
+
+1998-06-12  Richard Stallman  <rms@psilocin.ai.mit.edu>
+
+	* Makefile (INSTALL_INFO): New variable.
+	(install): Run install-info.
+
+1998-05-09  Richard Stallman  <rms@psilocin.ai.mit.edu>
+
+	* Makefile (elisp.dvi): Add missing backslash.
+
+1998-05-02  Richard Stallman  <rms@psilocin.gnu.org>
+
+	* Makefile (elisp.dvi): Don't depend on texindex or on elisp.tps.
+	Run texindex without `./'.  Always run texindex on elisp.tp.
+	(elisp.tps): Target deleted.
+
+1998-04-05  Richard Stallman  <rms@psilocin.gnu.org>
+
+	* Makefile (srcs): Add nonascii.texi and customize.texi.
+	(dist): Start by deleting `temp'.
+
+1998-02-17  Richard Stallman  <rms@psilocin.gnu.org>
+
+	* Makefile (makeinfo, texindex): Targets deleted.
+	(makeinfo.o, texindex.o): Targets deleted.
+	(clean, dist): Don't do anything with them or with getopt*.
+
+1998-01-30  Richard Stallman  <rms@psilocin.gnu.org>
+
+	* Makefile (SHELL): Defined.
+
+1998-01-27  Richard Stallman  <rms@psilocin.gnu.org>
+
+	* Makefile (elisp.tps): New target.
+	(elisp.dvi): Depend on elisp.tps.
+
+Wed Apr  3 15:24:25 1996  Karl Heuer  <kwzh@gnu.ai.mit.edu>
+
+	* README: Update phone number.
+
+	* Makefile (elisp): Make this be the default target.
+	Depend on makeinfo.c instead of makeinfo.
+	(install): Don't depend on elisp.dvi, since we don't install that.
+	Use mkinstalldirs.
+	(dist): Add mkinstalldirs.
+
+Mon Jun 19 14:35:26 1995  Richard Stallman  <rms@mole.gnu.ai.mit.edu>
+
+	* Makefile (VERSION): Update version number.
+	(maintainer-clean): Renamed from realclean.
+
+Wed Jun  7 17:04:59 1995  Karl Heuer  <kwzh@nutrimat.gnu.ai.mit.edu>
+
+	* Makefile (realclean): New target.
+	(elisp): Remove any old elisp-* files first.
+
+Tue Nov 23 19:59:40 1993  Noah Friedman  (friedman@nutrimat.gnu.ai.mit.edu)
+
+	* Makefile (VERSION): New variable.
+	(dist): Make packaged directory name `elisp-manual-19-$(VERSION)'.
+	Compressed file suffix should be `.gz', not `.z'.
+
+Mon Nov 22 15:06:19 1993  Richard Stallman  (rms@mole.gnu.ai.mit.edu)
+
+	* Makefile (elisp): Depend on makeinfo.
+
+Fri Nov 19 02:29:33 1993  Noah Friedman  (friedman@gnu.ai.mit.edu)
+
+	* Makefile (srcs): Add anti.texi.
+
+Fri May 28 18:04:53 1993  Richard Stallman  (rms@mole.gnu.ai.mit.edu)
+
+	* Makefile (infodir, prefix): New vars.
+	(install): Use infodir.
+	(emacsinfodir): Deleted.
+
+Thu May 27 02:11:25 1993  Richard Stallman  (rms@mole.gnu.ai.mit.edu)
+
+	* Makefile (srcs): Add calendar.texi.
+
+	* Makefile (dist): Copy texindex.c and makeinfo.c.
+	Limit elisp-* files to those with one or two digits.
+
+Sun May 16 17:58:21 1993  Jim Blandy  (jimb@wookumz.gnu.ai.mit.edu)
+
+	* Makefile (dist): Changed to use Gzip instead of compress.
+
+Fri Apr 23 01:05:23 1993  Eric S. Raymond  (eric@mole.gnu.ai.mit.edu)
+
+	* loading.texi (Unloading): define-function changed back to
+	defalias.  It may not stay this way, but at least it's
+	consistent with the known-good version of the code patch.
+
+Fri Mar 26 21:14:54 1993  Eric S. Raymond  (eric@geech.gnu.ai.mit.edu)
+
+	* modes.texi (Hooks): Document new optional arg of add-hook.
+
+Wed Mar 17 08:48:24 1993  Eric S. Raymond  (eric@mole.gnu.ai.mit.edu)
+
+	* variables.texi: Document nil initial value of buffer-local variables.
+
+	* tips.texi: Add new section on standard library headers.
+
+Sat Feb 27 18:00:25 1993  Jim Blandy  (jimb@wookumz.gnu.ai.mit.edu)
+
+	* Makefile (srcs): Add frame.texi to the list of sources.
+
+Tue Feb 23 10:50:25 1993  Jim Blandy  (jimb@wookumz.gnu.ai.mit.edu)
+
+	* Makefile (dist): Don't bother excluding autosave files; they'll
+	never make it into the temp directory anyway, and the hash marks
+	in the name are problematic for make and the Bourne shell.
+	(srcs):
+
+Fri Feb 12 16:54:38 1993  Jim Blandy  (jimb@wookumz.gnu.ai.mit.edu)
+
+	* Makefile (dist): Don't include backup files or autosave files in
+	the distribution tar file.
+
+Tue Nov 26 21:10:34 1991  Richard Stallman  (rms@mole.gnu.ai.mit.edu)
+
+	* Makefile (srcs): Added index.perm.
+	(elisp.dvi): Remove erroneous shell comment.
+	Expect output of permute-index in permuted.fns.
+	Save old elisp.aux in elisp.oaux.
+	(clean): Added index.texi to be deleted.
+
+Sat Aug 11 17:39:10 1990  Richard Stallman  (rms@sugar-bombs.ai.mit.edu)
+
+	* Makefile (elisp.dvi, index.texi): Use shell if instead of ifdef.
+
+Tue Jun 26 09:57:26 1990  David Lawrence  (tale@geech)
+
+	* files.texi: Noted that completion-ignored-extensions is ignored
+	when making *Completions*.
+
+Fri Jun  8 16:44:44 EDT 1990 Jay Fenlason (hack@ai.mit.edu)
+
+	* Makefile  make dist now depends on elisp.dvi, since it tries
+	to include it in the dist file.
+
+Wed Mar 28 22:57:35 1990  Jim Kingdon  (kingdon@mole.ai.mit.edu)
+
+	* functions.texinfo (Mapping Functions): Add missing quote
+
+Mon Jun 19 18:09:24 1989  Richard Stallman  (rms@sugar-bombs.ai.mit.edu)
+
+	* texinfo.tex (frenchspacing): Use decimal codes for char to be set.
+	(defunargs): Turn off \hyphenchar of \sl font temporarily.
+
+Wed May 10 18:01:17 1989  Robert J. Chassell  (bob@rice-chex.ai.mit.edu)
+
+	* @result{}, @expansion{}, @print{}, @quiv{}, @point{},
+	and @error{} are the terms now being used.  The files in the
+	directory have been changed to reflect this.
+
+	* All instances of @indentedresultt{} have been changed to
+	`     @result{}', using 5 spaces at the begining of the line.
+
+Mon Apr 24 21:02:55 1989  Robert J. Chassell  (bob@rice-chex.ai.mit.edu)
+
+	* @result{}, @expandsto{}, @prints{}, @quiv{}, @error{}, and the
+	experimental @indentedresult{}, @indentedexpandsto{} are part of
+	the texinfo.tex in this directory.  These TeX macros are not
+	stable yet.
+
+Mon Apr 17 18:56:50 1989  Robert J. Chassell  (bob@rice-chex.ai.mit.edu)
+
+	* texinfo.tex: Temporarily added
+		\let\result=\dblarrow
+		\def\error{{\it ERROR} \longdblarrow}
+	We need to do this better soon.
+
+Tue Apr 11 12:23:28 1989  Robert J. Chassell  (bob@rice-chex.ai.mit.edu)
+
+	* Applied Karl Berry's patches to *.texinfo files, but not to
+	texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'.  (Karl's
+	new title page format is also not applied, since it requires
+	texinfo.tex changes.)
+
+	* Cleaned up `Makefile' and defined the `emacslibdir' directory
+	for the Project GNU development environment.
+
+;; Local Variables:
+;; coding: iso-2022-7bit
+;; add-log-time-zone-rule: t
+;; End:
+
+    Copyright (C) 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.
+
+;;; arch-tag: 985ae0ce-df29-475b-b3f8-4bbcbf6f7fda
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
new file mode 100644
index 00000000000..1a34d60a0d8
--- /dev/null
+++ b/doc/lispref/Makefile.in
@@ -0,0 +1,144 @@
+# Makefile for the GNU Emacs Lisp Reference Manual.
+
+# Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 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.
+
+# Standard configure variables.
+srcdir = @srcdir@
+
+# Tell make where to find source files; this is needed for the makefiles.
+VPATH=@srcdir@
+
+infodir = ../info
+usermanualdir = $(srcdir)/../man
+
+TEXI2DVI = texi2dvi
+SHELL = /bin/sh
+INSTALL_INFO = install-info
+MAKEINFO = makeinfo --force
+
+# The name of the manual:
+VERSION=2.9
+manual = elisp-manual-21-$(VERSION)
+
+# List of all the texinfo files in the manual:
+
+srcs = \
+  $(srcdir)/abbrevs.texi \
+  $(srcdir)/advice.texi \
+  $(srcdir)/anti.texi \
+  $(srcdir)/back.texi \
+  $(srcdir)/backups.texi \
+  $(srcdir)/buffers.texi \
+  $(srcdir)/commands.texi \
+  $(srcdir)/compile.texi \
+  $(srcdir)/control.texi \
+  $(srcdir)/customize.texi \
+  $(srcdir)/debugging.texi \
+  $(srcdir)/display.texi \
+  $(srcdir)/edebug.texi \
+  $(srcdir)/elisp.texi \
+  $(srcdir)/errors.texi \
+  $(srcdir)/eval.texi \
+  $(srcdir)/files.texi \
+  $(srcdir)/frames.texi \
+  $(srcdir)/functions.texi \
+  $(srcdir)/hash.texi \
+  $(srcdir)/help.texi \
+  $(srcdir)/hooks.texi \
+  $(srcdir)/internals.texi \
+  $(srcdir)/intro.texi \
+  $(srcdir)/keymaps.texi \
+  $(srcdir)/lists.texi \
+  $(srcdir)/loading.texi \
+  $(srcdir)/locals.texi \
+  $(srcdir)/macros.texi \
+  $(srcdir)/maps.texi \
+  $(srcdir)/markers.texi \
+  $(srcdir)/minibuf.texi \
+  $(srcdir)/modes.texi \
+  $(srcdir)/nonascii.texi \
+  $(srcdir)/numbers.texi \
+  $(srcdir)/objects.texi \
+  $(srcdir)/os.texi \
+  $(srcdir)/positions.texi \
+  $(srcdir)/processes.texi \
+  $(srcdir)/searching.texi \
+  $(srcdir)/sequences.texi \
+  $(srcdir)/streams.texi \
+  $(srcdir)/strings.texi \
+  $(srcdir)/symbols.texi \
+  $(srcdir)/syntax.texi \
+  $(srcdir)/text.texi \
+  $(srcdir)/tips.texi \
+  $(srcdir)/variables.texi \
+  $(srcdir)/windows.texi \
+  $(srcdir)/index.texi \
+  $(srcdir)/gpl.texi \
+  $(srcdir)/doclicense.texi
+
+
+.PHONY: clean
+
+# The info file is named `elisp'.
+info: $(infodir)/elisp
+
+$(infodir)/elisp: $(srcs)
+	cd $(srcdir); $(MAKEINFO) -I. -I$(infodir) elisp.texi -o $(infodir)/elisp
+
+elisp.dvi: $(srcs)
+	$(TEXI2DVI) -I $(srcdir) -I $(usermanualdir) $(srcdir)/elisp.texi
+
+# This is for use in a separate distro of the Emacs Lisp manual.
+install: elisp
+	$(srcdir)/mkinstalldirs $(infodir)
+	cp elisp elisp-[1-9] elisp-[1-9][0-9] $(infodir)
+	${INSTALL_INFO} --info-dir=${infodir} ${infodir}/elisp
+
+# This is for use in a separate distro of the Emacs Lisp manual.
+elisp: $(srcs)
+	$(MAKEINFO) -I. -I$(srcdir) $(srcdir)/elisp.texi
+
+clean:
+	rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
+              *.vr *.vrs *.pg *.pgs *.ky *.kys
+	rm -f make.out core
+
+distclean: clean
+
+maintainer-clean: clean
+	rm -f elisp.dvi elisp.oaux
+	cd $(infodir); rm -f elisp elisp-[1-9] elisp-[1-9][0-9]
+
+dist: $(infodir)/elisp elisp.dvi
+	-rm -rf temp
+	-mkdir temp
+	-mkdir temp/$(manual)
+	-ln $(srcdir)/README $(srcdir)/configure.in $(srcdir)/configure \
+ $(srcdir)/Makefile.in $(srcs) \
+ $(srcdir)/../man/texinfo.tex \
+ elisp.dvi elisp.aux elisp.??s \
+ $(infodir)/elisp $(infodir)/elisp-[1-9] $(infodir)/elisp-[1-9][0-9] \
+ temp/$(manual)
+	-(cd temp/$(manual); rm -f mkinstalldirs)
+	cp $(srcdir)/mkinstalldirs temp/$(manual)
+	(cd temp/$(manual); rm -f *~)
+	(cd temp; tar chf - $(manual)) | gzip > $(manual).tar.gz
+	-rm -rf temp
diff --git a/doc/lispref/README b/doc/lispref/README
new file mode 100644
index 00000000000..c5d4c8acc77
--- /dev/null
+++ b/doc/lispref/README
@@ -0,0 +1,72 @@
+Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
+  Free Software Foundation, Inc.
+See the end of the file for license conditions.
+
+
+README for Edition 2.9 of the Emacs Lisp Reference Manual.
+
+* This directory contains the texinfo source files for the Reference
+Manual, make-permuted-index, and the latest version of texinfo.tex,
+which handles forms that cannot be handled by the older versions of
+texinfo.tex.
+
+* Report Lisp Manual bugs to bug-lisp-manual@gnu.org.  We don't read
+these bug reports until it's time for a new edition.  To report other
+Emacs bugs, use bug-gnu-emacs@gnu.org.  To ask questions, use the
+newsgroup gnu.emacs.help.
+
+* The Emacs Lisp Reference Manual is quite large.  It totals around
+1100 pages in smallbook format; the info files total over
+2.5 megabytes.
+
+* You can format this manual either for Info or for printing hardcopy
+using TeX.
+
+* You can buy nicely printed copies from the Free Software Foundation.
+For info, send mail to gnu@gnu.org or phone 617-542-5942.  Buying a
+manual from the Free Software Foundation helps support our GNU
+development work.
+
+** This distribution contains a Makefile that you can use with GNU Make.
+Otherwise, here are detailed instructions:
+
+** HARDCOPY: A copy of the version of `texinfo.tex' that formats this
+manual is included in this distribution.
+
+The master file for formatting this manual for Tex is called
+`elisp.texi'.  It contains @include commands to include all the
+chapters that make up the manual.  In addition, `elisp.texi' has
+the title page in a new format designed by Karl Berry, using the
+@titlespec command.
+
+To create a DVI file with a sorted index, execute the following
+commands in the shell:
+
+% ./configure
+% make index.texi
+% make elisp.dvi
+
+*** To create a DVI file with a permuted index, you may experiment
+with `make-permuted-index'.
+
+** To make an Info file, you need to install Texinfo, then run
+`./configure' and `make info'.  To install the Info files, run
+`make install'.
+
+
+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.
diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi
new file mode 100644
index 00000000000..46e7c3739c4
--- /dev/null
+++ b/doc/lispref/abbrevs.texi
@@ -0,0 +1,411 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2001, 2002, 2003,
+@c   2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/abbrevs
+@node Abbrevs, Processes, Syntax Tables, Top
+@chapter Abbrevs and Abbrev Expansion
+@cindex abbrev
+@c  @cindex abbrev table  Redundant with "abbrev".
+
+  An abbreviation or @dfn{abbrev} is a string of characters that may be
+expanded to a longer string.  The user can insert the abbrev string and
+find it replaced automatically with the expansion of the abbrev.  This
+saves typing.
+
+  The set of abbrevs currently in effect is recorded in an @dfn{abbrev
+table}.  Each buffer has a local abbrev table, but normally all buffers
+in the same major mode share one abbrev table.  There is also a global
+abbrev table.  Normally both are used.
+
+  An abbrev table is represented as an obarray containing a symbol for
+each abbreviation.  The symbol's name is the abbreviation; its value
+is the expansion; its function definition is the hook function to do
+the expansion (@pxref{Defining Abbrevs}); its property list cell
+typically contains the use count, the number of times the abbreviation
+has been expanded.  Alternatively, the use count is on the
+@code{count} property and the system-abbrev flag is on the
+@code{system-type} property.  Abbrevs with a non-@code{nil}
+@code{system-type} property are called ``system'' abbrevs.  They are
+usually defined by modes or packages, instead of by the user, and are
+treated specially in certain respects.
+
+Because the symbols used for abbrevs are not interned in the usual
+obarray, they will never appear as the result of reading a Lisp
+expression; in fact, normally they are never used except by the code
+that handles abbrevs.  Therefore, it is safe to use them in an
+extremely nonstandard way.  @xref{Creating Symbols}.
+
+  For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
+Mode, emacs, The GNU Emacs Manual}.
+
+@menu
+* Abbrev Mode::                 Setting up Emacs for abbreviation.
+* Tables: Abbrev Tables.        Creating and working with abbrev tables.
+* Defining Abbrevs::            Specifying abbreviations and their expansions.
+* Files: Abbrev Files.          Saving abbrevs in files.
+* Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables::      Abbrev tables used by various major modes.
+@end menu
+
+@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
+@comment  node-name,  next,  previous,  up
+@section Setting Up Abbrev Mode
+
+  Abbrev mode is a minor mode controlled by the value of the variable
+@code{abbrev-mode}.
+
+@defvar abbrev-mode
+A non-@code{nil} value of this variable turns on the automatic expansion
+of abbrevs when their abbreviations are inserted into a buffer.
+If the value is @code{nil}, abbrevs may be defined, but they are not
+expanded automatically.
+
+This variable automatically becomes buffer-local when set in any fashion.
+@end defvar
+
+@defvar default-abbrev-mode
+This is the value of @code{abbrev-mode} for buffers that do not override it.
+This is the same as @code{(default-value 'abbrev-mode)}.
+@end defvar
+
+@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
+@section Abbrev Tables
+
+  This section describes how to create and manipulate abbrev tables.
+
+@defun make-abbrev-table
+This function creates and returns a new, empty abbrev table---an obarray
+containing no symbols.  It is a vector filled with zeros.
+@end defun
+
+@defun clear-abbrev-table table
+This function undefines all the abbrevs in abbrev table @var{table},
+leaving it empty.  It always returns @code{nil}.
+@end defun
+
+@defun copy-abbrev-table table
+This function returns a copy of abbrev table @var{table}---a new
+abbrev table that contains the same abbrev definitions.  The only
+difference between @var{table} and the returned copy is that this
+function sets the property lists of all copied abbrevs to 0.
+@end defun
+
+@defun define-abbrev-table tabname definitions
+This function defines @var{tabname} (a symbol) as an abbrev table
+name, i.e., as a variable whose value is an abbrev table.  It defines
+abbrevs in the table according to @var{definitions}, a list of
+elements of the form @code{(@var{abbrevname} @var{expansion}
+@var{hook} @var{usecount} @var{system-flag})}.  If an element of
+@var{definitions} has length less than five, omitted elements default
+to @code{nil}.  A value of @code{nil} for @var{usecount} is equivalent
+to zero.  The return value is always @code{nil}.
+
+If this function is called more than once for the same @var{tabname},
+subsequent calls add the definitions in @var{definitions} to
+@var{tabname}, rather than overriding the entire original contents.
+(A subsequent call only overrides abbrevs explicitly redefined or
+undefined in @var{definitions}.)
+@end defun
+
+@defvar abbrev-table-name-list
+This is a list of symbols whose values are abbrev tables.
+@code{define-abbrev-table} adds the new abbrev table name to this list.
+@end defvar
+
+@defun insert-abbrev-table-description name &optional human
+This function inserts before point a description of the abbrev table
+named @var{name}.  The argument @var{name} is a symbol whose value is an
+abbrev table.  The return value is always @code{nil}.
+
+If @var{human} is non-@code{nil}, the description is human-oriented.
+System abbrevs are listed and identified as such.  Otherwise the
+description is a Lisp expression---a call to @code{define-abbrev-table}
+that would define @var{name} as it is currently defined, but without
+the system abbrevs.  (The mode or package using @var{name} is supposed
+to add these to @var{name} separately.)
+@end defun
+
+@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
+@comment  node-name,  next,  previous,  up
+@section Defining Abbrevs
+  @code{define-abbrev} is the low-level basic function for defining an
+abbrev in a specified abbrev table.  When major modes predefine standard
+abbrevs, they should call @code{define-abbrev} and specify @code{t} for
+@var{system-flag}.  Be aware that any saved non-``system'' abbrevs are
+restored at startup, i.e. before some major modes are loaded.  Major modes
+should therefore not assume that when they are first loaded their abbrev
+tables are empty.
+
+@defun define-abbrev table name expansion &optional hook count system-flag
+This function defines an abbrev named @var{name}, in @var{table}, to
+expand to @var{expansion} and call @var{hook}.  The return value is
+@var{name}.
+
+The value of @var{count}, if specified, initializes the abbrev's
+usage-count.  If @var{count} is not specified or @code{nil}, the use
+count is initialized to zero.
+
+The argument @var{name} should be a string.  The argument
+@var{expansion} is normally the desired expansion (a string), or
+@code{nil} to undefine the abbrev.  If it is anything but a string or
+@code{nil}, then the abbreviation ``expands'' solely by running
+@var{hook}.
+
+The argument @var{hook} is a function or @code{nil}.  If @var{hook} is
+non-@code{nil}, then it is called with no arguments after the abbrev is
+replaced with @var{expansion}; point is located at the end of
+@var{expansion} when @var{hook} is called.
+
+@cindex @code{no-self-insert} property
+If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert}
+property is non-@code{nil}, @var{hook} can explicitly control whether
+to insert the self-inserting input character that triggered the
+expansion.  If @var{hook} returns non-@code{nil} in this case, that
+inhibits insertion of the character.  By contrast, if @var{hook}
+returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as
+if expansion had not really occurred.
+
+If @var{system-flag} is non-@code{nil}, that marks the abbrev as a
+``system'' abbrev with the @code{system-type} property.  Unless
+@var{system-flag} has the value @code{force}, a ``system'' abbrev will
+not overwrite an existing definition for a non-``system'' abbrev of the
+same name.
+
+Normally the function @code{define-abbrev} sets the variable
+@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev.
+(This is so that some commands will offer to save the abbrevs.)  It
+does not do this for a ``system'' abbrev, since those won't be saved
+anyway.
+@end defun
+
+@defopt only-global-abbrevs
+If this variable is non-@code{nil}, it means that the user plans to use
+global abbrevs only.  This tells the commands that define mode-specific
+abbrevs to define global ones instead.  This variable does not alter the
+behavior of the functions in this section; it is examined by their
+callers.
+@end defopt
+
+@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
+@section Saving Abbrevs in Files
+
+  A file of saved abbrev definitions is actually a file of Lisp code.
+The abbrevs are saved in the form of a Lisp program to define the same
+abbrev tables with the same contents.  Therefore, you can load the file
+with @code{load} (@pxref{How Programs Do Loading}).  However, the
+function @code{quietly-read-abbrev-file} is provided as a more
+convenient interface.
+
+  User-level facilities such as @code{save-some-buffers} can save
+abbrevs in a file automatically, under the control of variables
+described here.
+
+@defopt abbrev-file-name
+This is the default file name for reading and saving abbrevs.
+@end defopt
+
+@defun quietly-read-abbrev-file &optional filename
+This function reads abbrev definitions from a file named @var{filename},
+previously written with @code{write-abbrev-file}.  If @var{filename} is
+omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
+used.  @code{save-abbrevs} is set to @code{t} so that changes will be
+saved.
+
+This function does not display any messages.  It returns @code{nil}.
+@end defun
+
+@defopt save-abbrevs
+A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
+offer the user to save abbrevs when files are saved.  If the value is
+@code{silently}, Emacs saves the abbrevs without asking the user.
+@code{abbrev-file-name} specifies the file to save the abbrevs in.
+@end defopt
+
+@defvar abbrevs-changed
+This variable is set non-@code{nil} by defining or altering any
+abbrevs (except ``system'' abbrevs).  This serves as a flag for
+various Emacs commands to offer to save your abbrevs.
+@end defvar
+
+@deffn Command write-abbrev-file &optional filename
+Save all abbrev definitions (except ``system'' abbrevs), for all abbrev
+tables listed in @code{abbrev-table-name-list}, in the file
+@var{filename}, in the form of a Lisp program that when loaded will
+define the same abbrevs.  If @var{filename} is @code{nil} or omitted,
+@code{abbrev-file-name} is used.  This function returns @code{nil}.
+@end deffn
+
+@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
+@comment  node-name,  next,  previous,  up
+@section Looking Up and Expanding Abbreviations
+
+  Abbrevs are usually expanded by certain interactive commands,
+including @code{self-insert-command}.  This section describes the
+subroutines used in writing such commands, as well as the variables they
+use for communication.
+
+@defun abbrev-symbol abbrev &optional table
+This function returns the symbol representing the abbrev named
+@var{abbrev}.  The value returned is @code{nil} if that abbrev is not
+defined.  The optional second argument @var{table} is the abbrev table
+to look it up in.  If @var{table} is @code{nil}, this function tries
+first the current buffer's local abbrev table, and second the global
+abbrev table.
+@end defun
+
+@defun abbrev-expansion abbrev &optional table
+This function returns the string that @var{abbrev} would expand into (as
+defined by the abbrev tables used for the current buffer).  If
+@var{abbrev} is not a valid abbrev, the function returns @code{nil}.
+The optional argument @var{table} specifies the abbrev table to use,
+as in @code{abbrev-symbol}.
+@end defun
+
+@deffn Command expand-abbrev
+This command expands the abbrev before point, if any.  If point does not
+follow an abbrev, this command does nothing.  The command returns the
+abbrev symbol if it did expansion, @code{nil} otherwise.
+
+If the abbrev symbol has a hook function which is a symbol whose
+@code{no-self-insert} property is non-@code{nil}, and if the hook
+function returns @code{nil} as its value, then @code{expand-abbrev}
+returns @code{nil} even though expansion did occur.
+@end deffn
+
+@deffn Command abbrev-prefix-mark &optional arg
+This command marks the current location of point as the beginning of
+an abbrev.  The next call to @code{expand-abbrev} will use the text
+from here to point (where it is then) as the abbrev to expand, rather
+than using the previous word as usual.
+
+First, this command expands any abbrev before point, unless @var{arg}
+is non-@code{nil}.  (Interactively, @var{arg} is the prefix argument.)
+Then it inserts a hyphen before point, to indicate the start of the
+next abbrev to be expanded.  The actual expansion removes the hyphen.
+@end deffn
+
+@defopt abbrev-all-caps
+When this is set non-@code{nil}, an abbrev entered entirely in upper
+case is expanded using all upper case.  Otherwise, an abbrev entered
+entirely in upper case is expanded by capitalizing each word of the
+expansion.
+@end defopt
+
+@defvar abbrev-start-location
+The value of this variable is a buffer position (an integer or a marker)
+for @code{expand-abbrev} to use as the start of the next abbrev to be
+expanded.  The value can also be @code{nil}, which means to use the
+word before point instead.  @code{abbrev-start-location} is set to
+@code{nil} each time @code{expand-abbrev} is called.  This variable is
+also set by @code{abbrev-prefix-mark}.
+@end defvar
+
+@defvar abbrev-start-location-buffer
+The value of this variable is the buffer for which
+@code{abbrev-start-location} has been set.  Trying to expand an abbrev
+in any other buffer clears @code{abbrev-start-location}.  This variable
+is set by @code{abbrev-prefix-mark}.
+@end defvar
+
+@defvar last-abbrev
+This is the @code{abbrev-symbol} of the most recent abbrev expanded.  This
+information is left by @code{expand-abbrev} for the sake of the
+@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding
+Abbrevs, emacs, The GNU Emacs Manual}).
+@end defvar
+
+@defvar last-abbrev-location
+This is the location of the most recent abbrev expanded.  This contains
+information left by @code{expand-abbrev} for the sake of the
+@code{unexpand-abbrev} command.
+@end defvar
+
+@defvar last-abbrev-text
+This is the exact expansion text of the most recent abbrev expanded,
+after case conversion (if any).  Its value is @code{nil} if the abbrev
+has already been unexpanded.  This contains information left by
+@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
+@end defvar
+
+@c Emacs 19 feature
+@defvar pre-abbrev-expand-hook
+This is a normal hook whose functions are executed, in sequence, just
+before any expansion of an abbrev.  @xref{Hooks}.  Since it is a normal
+hook, the hook functions receive no arguments.  However, they can find
+the abbrev to be expanded by looking in the buffer before point.
+Running the hook is the first thing that @code{expand-abbrev} does, and
+so a hook function can be used to change the current abbrev table before
+abbrev lookup happens.  (Although you have to do this carefully.  See
+the example below.)
+@end defvar
+
+  The following sample code shows a simple use of
+@code{pre-abbrev-expand-hook}.  It assumes that @code{foo-mode} is a
+mode for editing certain files in which lines that start with @samp{#}
+are comments.  You want to use Text mode abbrevs for those lines.  The
+regular local abbrev table, @code{foo-mode-abbrev-table} is
+appropriate for all other lines.  Then you can put the following code
+in your @file{.emacs} file.  @xref{Standard Abbrev Tables}, for the
+definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
+
+@smallexample
+(defun foo-mode-pre-abbrev-expand ()
+  (when (save-excursion (forward-line 0) (eq (char-after) ?#))
+    (let ((local-abbrev-table text-mode-abbrev-table)
+	  ;; Avoid infinite loop.
+	  (pre-abbrev-expand-hook nil))
+      (expand-abbrev))
+    ;; We have already called `expand-abbrev' in this hook.
+    ;; Hence we want the "actual" call following this hook to be a no-op.
+    (setq abbrev-start-location (point-max)
+	  abbrev-start-location-buffer (current-buffer))))
+
+(add-hook 'foo-mode-hook
+	  #'(lambda ()
+	      (add-hook 'pre-abbrev-expand-hook
+			'foo-mode-pre-abbrev-expand
+			nil t)))
+@end smallexample
+
+Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil}
+without doing anything for lines not starting with @samp{#}.  Hence
+abbrevs expand normally using @code{foo-mode-abbrev-table} as local
+abbrev table for such lines.
+
+@node Standard Abbrev Tables,  , Abbrev Expansion, Abbrevs
+@comment  node-name,  next,  previous,  up
+@section Standard Abbrev Tables
+
+  Here we list the variables that hold the abbrev tables for the
+preloaded major modes of Emacs.
+
+@defvar global-abbrev-table
+This is the abbrev table for mode-independent abbrevs.  The abbrevs
+defined in it apply to all buffers.  Each buffer may also have a local
+abbrev table, whose abbrev definitions take precedence over those in the
+global table.
+@end defvar
+
+@defvar local-abbrev-table
+The value of this buffer-local variable is the (mode-specific)
+abbreviation table of the current buffer.
+@end defvar
+
+@defvar fundamental-mode-abbrev-table
+This is the local abbrev table used in Fundamental mode; in other words,
+it is the local abbrev table in all buffers in Fundamental mode.
+@end defvar
+
+@defvar text-mode-abbrev-table
+This is the local abbrev table used in Text mode.
+@end defvar
+
+@defvar lisp-mode-abbrev-table
+This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
+@end defvar
+
+@ignore
+   arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
+@end ignore
diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi
new file mode 100644
index 00000000000..4d580f9846d
--- /dev/null
+++ b/doc/lispref/advice.texi
@@ -0,0 +1,773 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/advising
+@node Advising Functions, Debugging, Byte Compilation, Top
+@chapter Advising Emacs Lisp Functions
+@cindex advising functions
+
+  The @dfn{advice} feature lets you add to the existing definition of
+a function, by @dfn{advising the function}.  This is a cleaner method
+for a library to customize functions defined within Emacs---cleaner
+than redefining the whole function.
+
+@cindex piece of advice
+  Each function can have multiple @dfn{pieces of advice}, separately
+defined.  Each defined piece of advice can be @dfn{enabled} or
+@dfn{disabled} explicitly.  All the enabled pieces of advice for any given
+function actually take effect when you @dfn{activate} advice for that
+function, or when you define or redefine the function.  Note that
+enabling a piece of advice and activating advice for a function
+are not the same thing.
+
+  @strong{Usage Note:} Advice is useful for altering the behavior of
+existing calls to an existing function.  If you want the new behavior
+for new calls, or for key bindings, you should define a new function
+(or a new command) which uses the existing function.
+
+  @strong{Usage note:} Advising a function can cause confusion in
+debugging, since people who debug calls to the original function may
+not notice that it has been modified with advice.  Therefore, if you
+have the possibility to change the code of that function (or ask
+someone to do so) to run a hook, please solve the problem that way.
+Advice should be reserved for the cases where you cannot get the
+function changed.
+
+  In particular, this means that a file in Emacs should not put advice
+on a function in Emacs.  There are currently a few exceptions to this
+convention, but we aim to correct them.
+
+@menu
+* Simple Advice::           A simple example to explain the basics of advice.
+* Defining Advice::         Detailed description of @code{defadvice}.
+* Around-Advice::           Wrapping advice around a function's definition.
+* Computed Advice::         ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice::    Advice doesn't do anything until you activate it.
+* Enabling Advice::         You can enable or disable each piece of advice.
+* Preactivation::           Preactivation is a way of speeding up the
+                              loading of compiled advice.
+* Argument Access in Advice:: How advice can access the function's arguments.
+* Advising Primitives::     Accessing arguments when advising a primitive.
+* Combined Definition::     How advice is implemented.
+@end menu
+
+@node Simple Advice
+@section A Simple Advice Example
+
+  The command @code{next-line} moves point down vertically one or more
+lines; it is the standard binding of @kbd{C-n}.  When used on the last
+line of the buffer, this command inserts a newline to create a line to
+move to if @code{next-line-add-newlines} is non-@code{nil} (its default
+is @code{nil}.)
+
+  Suppose you wanted to add a similar feature to @code{previous-line},
+which would insert a new line at the beginning of the buffer for the
+command to move to (when @code{next-line-add-newlines} is
+non-@code{nil}).  How could you do this?
+
+  You could do it by redefining the whole function, but that is not
+modular.  The advice feature provides a cleaner alternative: you can
+effectively add your code to the existing function definition, without
+actually changing or even seeing that definition.  Here is how to do
+this:
+
+@example
+(defadvice previous-line (before next-line-at-end
+                                 (&optional arg try-vscroll))
+  "Insert an empty line when moving up from the top line."
+  (if (and next-line-add-newlines (= arg 1)
+           (save-excursion (beginning-of-line) (bobp)))
+      (progn
+        (beginning-of-line)
+        (newline))))
+@end example
+
+  This expression defines a @dfn{piece of advice} for the function
+@code{previous-line}.  This piece of advice is named
+@code{next-line-at-end}, and the symbol @code{before} says that it is
+@dfn{before-advice} which should run before the regular definition of
+@code{previous-line}.  @code{(&optional arg try-vscroll)} specifies
+how the advice code can refer to the function's arguments.
+
+  When this piece of advice runs, it creates an additional line, in the
+situation where that is appropriate, but does not move point to that
+line.  This is the correct way to write the advice, because the normal
+definition will run afterward and will move back to the newly inserted
+line.
+
+  Defining the advice doesn't immediately change the function
+@code{previous-line}.  That happens when you @dfn{activate} the advice,
+like this:
+
+@example
+(ad-activate 'previous-line)
+@end example
+
+@noindent
+This is what actually begins to use the advice that has been defined so
+far for the function @code{previous-line}.  Henceforth, whenever that
+function is run, whether invoked by the user with @kbd{C-p} or
+@kbd{M-x}, or called from Lisp, it runs the advice first, and its
+regular definition second.
+
+  This example illustrates before-advice, which is one @dfn{class} of
+advice: it runs before the function's base definition.  There are two
+other advice classes: @dfn{after-advice}, which runs after the base
+definition, and @dfn{around-advice}, which lets you specify an
+expression to wrap around the invocation of the base definition.
+
+@node Defining Advice
+@section Defining Advice
+@cindex defining advice
+@cindex advice, defining
+
+  To define a piece of advice, use the macro @code{defadvice}.  A call
+to @code{defadvice} has the following syntax, which is based on the
+syntax of @code{defun} and @code{defmacro}, but adds more:
+
+@findex defadvice
+@example
+(defadvice @var{function} (@var{class} @var{name}
+                         @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]}
+                         @var{flags}...)
+  @r{[}@var{documentation-string}@r{]}
+  @r{[}@var{interactive-form}@r{]}
+  @var{body-forms}...)
+@end example
+
+@noindent
+Here, @var{function} is the name of the function (or macro or special
+form) to be advised.  From now on, we will write just ``function'' when
+describing the entity being advised, but this always includes macros and
+special forms.
+
+  In place of the argument list in an ordinary definition, an advice
+definition calls for several different pieces of information.
+
+@cindex class of advice
+@cindex before-advice
+@cindex after-advice
+@cindex around-advice
+@var{class} specifies the @dfn{class} of the advice---one of @code{before},
+@code{after}, or @code{around}.  Before-advice runs before the function
+itself; after-advice runs after the function itself; around-advice is
+wrapped around the execution of the function itself.  After-advice and
+around-advice can override the return value by setting
+@code{ad-return-value}.
+
+@defvar ad-return-value
+While advice is executing, after the function's original definition has
+been executed, this variable holds its return value, which will
+ultimately be returned to the caller after finishing all the advice.
+After-advice and around-advice can arrange to return some other value
+by storing it in this variable.
+@end defvar
+
+The argument @var{name} is the name of the advice, a non-@code{nil}
+symbol.  The advice name uniquely identifies one piece of advice, within all
+the pieces of advice in a particular class for a particular
+@var{function}.  The name allows you to refer to the piece of
+advice---to redefine it, or to enable or disable it.
+
+The optional @var{position} specifies where, in the current list of
+advice of the specified @var{class}, this new advice should be placed.
+It should be either @code{first}, @code{last} or a number that specifies
+a zero-based position (@code{first} is equivalent to 0).  If no position
+is specified, the default is @code{first}.  Position values outside the
+range of existing positions in this class are mapped to the beginning or
+the end of the range, whichever is closer.  The @var{position} value is
+ignored when redefining an existing piece of advice.
+
+The optional @var{arglist} can be used to define the argument list for
+the sake of advice.  This becomes the argument list of the combined
+definition that is generated in order to run the advice (@pxref{Combined
+Definition}).  Therefore, the advice expressions can use the argument
+variables in this list to access argument values.
+
+The argument list used in advice need not be the same as the argument
+list used in the original function, but must be compatible with it, so
+that it can handle the ways the function is actually called.  If two
+pieces of advice for a function both specify an argument list, they must
+specify the same argument list.
+
+@xref{Argument Access in Advice}, for more information about argument
+lists and advice, and a more flexible way for advice to access the
+arguments.
+
+The remaining elements, @var{flags}, are symbols that specify further
+information about how to use this piece of advice.  Here are the valid
+symbols and their meanings:
+
+@table @code
+@item activate
+Activate the advice for @var{function} now.  Changes in a function's
+advice always take effect the next time you activate advice for the
+function; this flag says to do so, for @var{function}, immediately after
+defining this piece of advice.
+
+@cindex forward advice
+This flag has no immediate effect if @var{function} itself is not defined yet (a
+situation known as @dfn{forward advice}), because it is impossible to
+activate an undefined function's advice.  However, defining
+@var{function} will automatically activate its advice.
+
+@item protect
+Protect this piece of advice against non-local exits and errors in
+preceding code and advice.  Protecting advice places it as a cleanup in
+an @code{unwind-protect} form, so that it will execute even if the
+previous code gets an error or uses @code{throw}.  @xref{Cleanups}.
+
+@item compile
+Compile the combined definition that is used to run the advice.  This
+flag is ignored unless @code{activate} is also specified.
+@xref{Combined Definition}.
+
+@item disable
+Initially disable this piece of advice, so that it will not be used
+unless subsequently explicitly enabled.  @xref{Enabling Advice}.
+
+@item preactivate
+Activate advice for @var{function} when this @code{defadvice} is
+compiled or macroexpanded.  This generates a compiled advised definition
+according to the current advice state, which will be used during
+activation if appropriate.  @xref{Preactivation}.
+
+This is useful only if this @code{defadvice} is byte-compiled.
+@end table
+
+The optional @var{documentation-string} serves to document this piece of
+advice.  When advice is active for @var{function}, the documentation for
+@var{function} (as returned by @code{documentation}) combines the
+documentation strings of all the advice for @var{function} with the
+documentation string of its original function definition.
+
+The optional @var{interactive-form} form can be supplied to change the
+interactive behavior of the original function.  If more than one piece
+of advice has an @var{interactive-form}, then the first one (the one
+with the smallest position) found among all the advice takes precedence.
+
+The possibly empty list of @var{body-forms} specifies the body of the
+advice.  The body of an advice can access or change the arguments, the
+return value, the binding environment, and perform any other kind of
+side effect.
+
+@strong{Warning:} When you advise a macro, keep in mind that macros are
+expanded when a program is compiled, not when a compiled program is run.
+All subroutines used by the advice need to be available when the byte
+compiler expands the macro.
+
+@deffn Command ad-unadvise function
+This command deletes the advice from @var{function}.
+@end deffn
+
+@deffn Command ad-unadvise-all
+This command deletes all pieces of advice from all functions.
+@end deffn
+
+@node Around-Advice
+@section Around-Advice
+
+  Around-advice lets you ``wrap'' a Lisp expression ``around'' the
+original function definition.  You specify where the original function
+definition should go by means of the special symbol @code{ad-do-it}.
+Where this symbol occurs inside the around-advice body, it is replaced
+with a @code{progn} containing the forms of the surrounded code.  Here
+is an example:
+
+@example
+(defadvice foo (around foo-around)
+  "Ignore case in `foo'."
+  (let ((case-fold-search t))
+    ad-do-it))
+@end example
+
+@noindent
+Its effect is to make sure that case is ignored in
+searches when the original definition of @code{foo} is run.
+
+@defvar ad-do-it
+This is not really a variable, rather a place-holder that looks like a
+variable.  You use it in around-advice to specify the place to run the
+function's original definition and other ``earlier'' around-advice.
+@end defvar
+
+If the around-advice does not use @code{ad-do-it}, then it does not run
+the original function definition.  This provides a way to override the
+original definition completely.  (It also overrides lower-positioned
+pieces of around-advice).
+
+If the around-advice uses @code{ad-do-it} more than once, the original
+definition is run at each place.  In this way, around-advice can execute
+the original definition (and lower-positioned pieces of around-advice)
+several times.  Another way to do that is by using @code{ad-do-it}
+inside of a loop.
+
+@node Computed Advice
+@section Computed Advice
+
+The macro @code{defadvice} resembles @code{defun} in that the code for
+the advice, and all other information about it, are explicitly stated in
+the source code.  You can also create advice whose details are computed,
+using the function @code{ad-add-advice}.
+
+@defun ad-add-advice function advice class position
+Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to
+@var{function} in class @var{class}.  The argument @var{advice}  has
+this form:
+
+@example
+(@var{name} @var{protected} @var{enabled} @var{definition})
+@end example
+
+Here @var{protected} and @var{enabled} are flags, and @var{definition}
+is the expression that says what the advice should do.  If @var{enabled}
+is @code{nil}, this piece of advice is initially disabled
+(@pxref{Enabling Advice}).
+
+If @var{function} already has one or more pieces of advice in the
+specified @var{class}, then @var{position} specifies where in the list
+to put the new piece of advice.  The value of @var{position} can either
+be @code{first}, @code{last}, or a number (counting from 0 at the
+beginning of the list).  Numbers outside the range are mapped to the
+beginning or the end of the range, whichever is closer.  The
+@var{position} value is ignored when redefining an existing piece of
+advice.
+
+If @var{function} already has a piece of @var{advice} with the same
+name, then the position argument is ignored and the old advice is
+replaced with the new one.
+@end defun
+
+@node Activation of Advice
+@section Activation of Advice
+@cindex activating advice
+@cindex advice, activating
+
+By default, advice does not take effect when you define it---only when
+you @dfn{activate} advice for the function that was advised.  However,
+the advice will be activated automatically if you define or redefine
+the function later.  You can request the activation of advice for a
+function when you define the advice, by specifying the @code{activate}
+flag in the @code{defadvice}.  But normally you activate the advice
+for a function by calling the function @code{ad-activate} or one of
+the other activation commands listed below.
+
+Separating the activation of advice from the act of defining it permits
+you to add several pieces of advice to one function efficiently, without
+redefining the function over and over as each advice is added.  More
+importantly, it permits defining advice for a function before that
+function is actually defined.
+
+When a function's advice is first activated, the function's original
+definition is saved, and all enabled pieces of advice for that function
+are combined with the original definition to make a new definition.
+(Pieces of advice that are currently disabled are not used; see
+@ref{Enabling Advice}.)  This definition is installed, and optionally
+byte-compiled as well, depending on conditions described below.
+
+In all of the commands to activate advice, if @var{compile} is
+@code{t} (or anything but @code{nil} or a negative number), the
+command also compiles the combined definition which implements the
+advice.  If it is @code{nil} or a negative number, what happens
+depends on @code{ad-default-compilation-action} as described below.
+
+@deffn Command ad-activate function &optional compile
+This command activates all the advice defined for @var{function}.
+@end deffn
+
+  Activating advice does nothing if @var{function}'s advice is already
+active.  But if there is new advice, added since the previous time you
+activated advice for @var{function}, it activates the new advice.
+
+@deffn Command ad-deactivate function
+This command deactivates the advice for @var{function}.
+@cindex deactivating advice
+@c @cindex advice, deactivating   "advice, activating" is just above
+@end deffn
+
+@deffn Command ad-update function &optional compile
+This command activates the advice for @var{function}
+if its advice is already activated.  This is useful
+if you change the advice.
+@end deffn
+
+@deffn Command ad-activate-all &optional compile
+This command activates the advice for all functions.
+@end deffn
+
+@deffn Command ad-deactivate-all
+This command deactivates the advice for all functions.
+@end deffn
+
+@deffn Command ad-update-all &optional compile
+This command activates the advice for all functions
+whose advice is already activated.  This is useful
+if you change the advice of some functions.
+@end deffn
+
+@deffn Command ad-activate-regexp regexp &optional compile
+This command activates all pieces of advice whose names match
+@var{regexp}.  More precisely, it activates all advice for any function
+which has at least one piece of advice that matches @var{regexp}.
+@end deffn
+
+@deffn Command ad-deactivate-regexp regexp
+This command deactivates all pieces of advice whose names match
+@var{regexp}.  More precisely, it deactivates all advice for any
+function which has at least one piece of advice that matches
+@var{regexp}.
+@end deffn
+
+@deffn Command ad-update-regexp regexp &optional compile
+This command activates pieces of advice whose names match @var{regexp},
+but only those for functions whose advice is already activated.
+@cindex reactivating advice
+
+Reactivating a function's advice is useful for putting into effect all
+the changes that have been made in its advice (including enabling and
+disabling specific pieces of advice; @pxref{Enabling Advice}) since the
+last time it was activated.
+@end deffn
+
+@deffn Command ad-start-advice
+Turn on automatic advice activation when a function is defined or
+redefined.  This is the default mode.
+@end deffn
+
+@deffn Command ad-stop-advice
+Turn off automatic advice activation when a function is defined or
+redefined.
+@end deffn
+
+@defopt ad-default-compilation-action
+This variable controls whether to compile the combined definition
+that results from activating advice for a function.
+
+A value of @code{always} specifies to compile unconditionally.
+A value of @code{never} specifies never compile the advice.
+
+A value of @code{maybe} specifies to compile if the byte-compiler is
+already loaded.  A value of @code{like-original} specifies to compile
+the advice if the original definition of the advised function is
+compiled or a built-in function.
+
+This variable takes effect only if the @var{compile} argument of
+@code{ad-activate} (or any of the above functions) did not force
+compilation.
+@end defopt
+
+  If the advised definition was constructed during ``preactivation''
+(@pxref{Preactivation}), then that definition must already be compiled,
+because it was constructed during byte-compilation of the file that
+contained the @code{defadvice} with the @code{preactivate} flag.
+
+@node Enabling Advice
+@section Enabling and Disabling Advice
+@cindex enabling advice
+@cindex advice, enabling and disabling
+@cindex disabling advice
+
+  Each piece of advice has a flag that says whether it is enabled or
+not.  By enabling or disabling a piece of advice, you can turn it on
+and off without having to undefine and redefine it.  For example, here is
+how to disable a particular piece of advice named @code{my-advice} for
+the function @code{foo}:
+
+@example
+(ad-disable-advice 'foo 'before 'my-advice)
+@end example
+
+  This function by itself only changes the enable flag for a piece of
+advice.  To make the change take effect in the advised definition, you
+must activate the advice for @code{foo} again:
+
+@example
+(ad-activate 'foo)
+@end example
+
+@deffn Command ad-disable-advice function class name
+This command disables the piece of advice named @var{name} in class
+@var{class} on @var{function}.
+@end deffn
+
+@deffn Command ad-enable-advice function class name
+This command enables the piece of advice named @var{name} in class
+@var{class} on @var{function}.
+@end deffn
+
+  You can also disable many pieces of advice at once, for various
+functions, using a regular expression.  As always, the changes take real
+effect only when you next reactivate advice for the functions in
+question.
+
+@deffn Command ad-disable-regexp regexp
+This command disables all pieces of advice whose names match
+@var{regexp}, in all classes, on all functions.
+@end deffn
+
+@deffn Command ad-enable-regexp regexp
+This command enables all pieces of advice whose names match
+@var{regexp}, in all classes, on all functions.
+@end deffn
+
+@node Preactivation
+@section Preactivation
+@cindex preactivating advice
+@cindex advice, preactivating
+
+  Constructing a combined definition to execute advice is moderately
+expensive.  When a library advises many functions, this can make loading
+the library slow.  In that case, you can use @dfn{preactivation} to
+construct suitable combined definitions in advance.
+
+  To use preactivation, specify the @code{preactivate} flag when you
+define the advice with @code{defadvice}.  This @code{defadvice} call
+creates a combined definition which embodies this piece of advice
+(whether enabled or not) plus any other currently enabled advice for the
+same function, and the function's own definition.  If the
+@code{defadvice} is compiled, that compiles the combined definition
+also.
+
+  When the function's advice is subsequently activated, if the enabled
+advice for the function matches what was used to make this combined
+definition, then the existing combined definition is used, thus avoiding
+the need to construct one.  Thus, preactivation never causes wrong
+results---but it may fail to do any good, if the enabled advice at the
+time of activation doesn't match what was used for preactivation.
+
+  Here are some symptoms that can indicate that a preactivation did not
+work properly, because of a mismatch.
+
+@itemize @bullet
+@item
+Activation of the advised
+function takes longer than usual.
+@item
+The byte-compiler gets
+loaded while an advised function gets activated.
+@item
+@code{byte-compile} is included in the value of @code{features} even
+though you did not ever explicitly use the byte-compiler.
+@end itemize
+
+Compiled preactivated advice works properly even if the function itself
+is not defined until later; however, the function needs to be defined
+when you @emph{compile} the preactivated advice.
+
+There is no elegant way to find out why preactivated advice is not being
+used.  What you can do is to trace the function
+@code{ad-cache-id-verification-code} (with the function
+@code{trace-function-background}) before the advised function's advice
+is activated.  After activation, check the value returned by
+@code{ad-cache-id-verification-code} for that function: @code{verified}
+means that the preactivated advice was used, while other values give
+some information about why they were considered inappropriate.
+
+  @strong{Warning:} There is one known case that can make preactivation
+fail, in that a preconstructed combined definition is used even though
+it fails to match the current state of advice.  This can happen when two
+packages define different pieces of advice with the same name, in the
+same class, for the same function.  But you should avoid that anyway.
+
+@node Argument Access in Advice
+@section Argument Access in Advice
+
+  The simplest way to access the arguments of an advised function in the
+body of a piece of advice is to use the same names that the function
+definition uses.  To do this, you need to know the names of the argument
+variables of the original function.
+
+  While this simple method is sufficient in many cases, it has a
+disadvantage: it is not robust, because it hard-codes the argument names
+into the advice.  If the definition of the original function changes,
+the advice might break.
+
+  Another method is to specify an argument list in the advice itself.
+This avoids the need to know the original function definition's argument
+names, but it has a limitation: all the advice on any particular
+function must use the same argument list, because the argument list
+actually used for all the advice comes from the first piece of advice
+for that function.
+
+  A more robust method is to use macros that are translated into the
+proper access forms at activation time, i.e., when constructing the
+advised definition.  Access macros access actual arguments by position
+regardless of how these actual arguments get distributed onto the
+argument variables of a function.  This is robust because in Emacs Lisp
+the meaning of an argument is strictly determined by its position in the
+argument list.
+
+@defmac ad-get-arg position
+This returns the actual argument that was supplied at @var{position}.
+@end defmac
+
+@defmac ad-get-args position
+This returns the list of actual arguments supplied starting at
+@var{position}.
+@end defmac
+
+@defmac ad-set-arg position value
+This sets the value of the actual argument at @var{position} to
+@var{value}
+@end defmac
+
+@defmac ad-set-args position value-list
+This sets the list of actual arguments starting at @var{position} to
+@var{value-list}.
+@end defmac
+
+  Now an example.  Suppose the function @code{foo} is defined as
+
+@example
+(defun foo (x y &optional z &rest r) ...)
+@end example
+
+@noindent
+and is then called with
+
+@example
+(foo 0 1 2 3 4 5 6)
+@end example
+
+@noindent
+which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is
+@code{(3 4 5 6)} within the body of @code{foo}.  Here is what
+@code{ad-get-arg} and @code{ad-get-args} return in this case:
+
+@example
+(ad-get-arg 0) @result{} 0
+(ad-get-arg 1) @result{} 1
+(ad-get-arg 2) @result{} 2
+(ad-get-arg 3) @result{} 3
+(ad-get-args 2) @result{} (2 3 4 5 6)
+(ad-get-args 4) @result{} (4 5 6)
+@end example
+
+  Setting arguments also makes sense in this example:
+
+@example
+(ad-set-arg 5 "five")
+@end example
+
+@noindent
+has the effect of changing the sixth argument to @code{"five"}.  If this
+happens in advice executed before the body of @code{foo} is run, then
+@var{r} will be @code{(3 4 "five" 6)} within that body.
+
+  Here is an example of setting a tail of the argument list:
+
+@example
+(ad-set-args 0 '(5 4 3 2 1 0))
+@end example
+
+@noindent
+If this happens in advice executed before the body of @code{foo} is run,
+then within that body, @var{x} will be 5, @var{y} will be 4, @var{z}
+will be 3, and @var{r} will be @code{(2 1 0)} inside the body of
+@code{foo}.
+
+  These argument constructs are not really implemented as Lisp macros.
+Instead they are implemented specially by the advice mechanism.
+
+@node Advising Primitives
+@section Advising Primitives
+@cindex advising primitives
+
+  Advising a primitive function (also called a ``subr'') is risky.
+Some primitive functions are used by the advice mechanism; advising
+them could cause an infinite recursion.  Also, many primitive
+functions are called directly from C code.  Calls to the primitive
+from Lisp code will take note of the advice, but calls from C code
+will ignore the advice.
+
+When the advice facility constructs the combined definition, it needs
+to know the argument list of the original function.  This is not
+always possible for primitive functions.  When advice cannot determine
+the argument list, it uses @code{(&rest ad-subr-args)}, which always
+works but is inefficient because it constructs a list of the argument
+values.  You can use @code{ad-define-subr-args} to declare the proper
+argument names for a primitive function:
+
+@defun ad-define-subr-args function arglist
+This function specifies that @var{arglist} should be used as the
+argument list for function @var{function}.
+@end defun
+
+For example,
+
+@example
+(ad-define-subr-args 'fset '(sym newdef))
+@end example
+
+@noindent
+specifies the argument list for the function @code{fset}.
+
+@node Combined Definition
+@section The Combined Definition
+
+  Suppose that a function has @var{n} pieces of before-advice
+(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of
+around-advice and @var{k} pieces of after-advice.  Assuming no piece
+of advice is protected, the combined definition produced to implement
+the advice for a function looks like this:
+
+@example
+(lambda @var{arglist}
+  @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]}
+  (let (ad-return-value)
+    @r{before-0-body-form}...
+         ....
+    @r{before-@var{n}@minus{}1-body-form}...
+    @r{around-0-body-form}...
+       @r{around-1-body-form}...
+             ....
+          @r{around-@var{m}@minus{}1-body-form}...
+             (setq ad-return-value
+                   @r{apply original definition to @var{arglist}})
+          @r{end-of-around-@var{m}@minus{}1-body-form}...
+             ....
+       @r{end-of-around-1-body-form}...
+    @r{end-of-around-0-body-form}...
+    @r{after-0-body-form}...
+          ....
+    @r{after-@var{k}@minus{}1-body-form}...
+    ad-return-value))
+@end example
+
+Macros are redefined as macros, which means adding @code{macro} to
+the beginning of the combined definition.
+
+The interactive form is present if the original function or some piece
+of advice specifies one.  When an interactive primitive function is
+advised, advice uses a special method: it calls the primitive with
+@code{call-interactively} so that it will read its own arguments.
+In this case, the advice cannot access the arguments.
+
+The body forms of the various advice in each class are assembled
+according to their specified order.  The forms of around-advice @var{l}
+are included in one of the forms of around-advice @var{l} @minus{} 1.
+
+The innermost part of the around advice onion is
+
+@display
+apply original definition to @var{arglist}
+@end display
+
+@noindent
+whose form depends on the type of the original function.  The variable
+@code{ad-return-value} is set to whatever this returns.  The variable is
+visible to all pieces of advice, which can access and modify it before
+it is actually returned from the advised function.
+
+The semantic structure of advised functions that contain protected
+pieces of advice is the same.  The only difference is that
+@code{unwind-protect} forms ensure that the protected advice gets
+executed even if some previous piece of advice had an error or a
+non-local exit.  If any around-advice is protected, then the whole
+around-advice onion is protected as a result.
+
+@ignore
+   arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f
+@end ignore
diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi
new file mode 100644
index 00000000000..1ec0c5ef327
--- /dev/null
+++ b/doc/lispref/anti.texi
@@ -0,0 +1,453 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1999, 2002, 2003, 2004, 2005,
+@c   2006, 2007 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+
+@c This node must have no pointers.
+
+@node Antinews, GNU Free Documentation License, System Interface, 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.
+
+@section Old Lisp Features in Emacs 21
+
+@itemize @bullet
+@item
+Many unnecessary features of redisplay have been eliminated.  (The
+earlier major release, Emacs 20, will have a completely rewritten
+redisplay engine, which will be even simpler.)
+
+@itemize @minus
+@item
+The function @code{redisplay} has been removed.  To update the display
+without delay, call @code{(sit-for 0)}.  Since it is generally
+considered wasteful to update the display if there are any pending
+input events, no replacement for @code{(redisplay t)} is provided.
+
+@item
+The function @code{force-window-update} has been removed.  It
+shouldn't be needed, since changes in window contents are detected
+automatically.  In case they aren't, call @code{redraw-display} to
+redraw everything.
+
+@item
+Point no longer moves out from underneath invisible text at the end of
+each command.  This allows the user to detect invisible text by moving
+the cursor around---if the cursor gets stuck, there is something
+invisible in the way.  If you really want cursor motion to ignore the
+text, try marking it as intangible.
+
+@item
+Support for image maps and image slices has been removed.  Emacs was
+always meant for editing text, anyway.
+
+@item
+The mode line now accepts all text properties, as well as
+@code{:propertize} and @code{:eval} forms, regardless of the
+@code{risky-local-variable} property.
+
+@item
+The @code{line-height} and @code{line-spacing} properties no longer
+have any meaning for newline characters.  Such properties wouldn't
+make sense, since newlines are not really characters; they just tell
+you where to break a line.
+
+@item
+Considerable simplifications have been made to the display
+specification @code{(space . @var{props})}, which is used for
+displaying a space of specified width and height.  Pixel-based
+specifications and Lisp expressions are no longer accepted.
+
+@item
+Many features associated with the fringe areas have been removed, to
+encourage people to concentrate on the main editing area (the fringe
+will be completely removed in Emacs 20.)  Arbitrary bitmaps can no
+longer be displayed in the fringe; an overlay arrow can still be
+displayed, but there can only be one overlay arrow at a time (any more
+would be confusing.)  The fringe widths cannot be adjusted, and
+individual windows cannot have their own fringe settings.  A mouse
+click on the fringe no longer generates a special event.
+
+@item
+Individual windows cannot have their own scroll-bar settings.
+
+@item
+You can no longer use @samp{default} in a @code{defface} to specify
+defaults for subsequent faces.
+
+@item
+The function @code{display-supports-face-attributes-p} has been
+removed.  In @code{defface} specifications, the @code{supports}
+predicate is no longer supported.
+
+@item
+The functions @code{merge-face-attribute} and
+@code{face-attribute-relative-p} have been removed.
+
+@item
+The priority of faces in a list supplied by the @code{:inherit} face
+attribute has been reversed.  We like to make changes like this once
+in a while, to keep Emacs Lisp programmers on their toes.
+
+@item
+The @code{min-colors} face attribute, used for tailoring faces to
+limited-color displays, does not exist.  If in doubt, use colors like
+``white'' and ``black,'' which ought to be defined everywhere.
+
+@item
+The @code{tty-color-mode} frame parameter does not exist.  You should
+just trust the terminal capabilities database.
+@end itemize
+
+@item
+Several simplifications have been made to mouse support:
+
+@itemize @minus
+@item
+Clicking @kbd{mouse-1} won't follow links, as that is alien to the
+spirit of Emacs.  Therefore, the @code{follow-link} property doesn't
+have any special meaning, and the function @code{mouse-on-link-p} has
+been removed.
+
+@item
+The variable @code{void-text-area-pointer} has been removed, so the
+mouse pointer shape remains unchanged when moving between valid text
+areas and void text areas.  The @code{pointer} image and text
+properties are no longer supported.
+
+@item
+Mouse events will no longer specify the timestamp, the object clicked,
+equivalent buffer positions (for marginal or fringe areas), glyph
+coordinates, or relative pixel coordinates.
+@end itemize
+
+@item
+Simplifications have also been made to the way Emacs handles keymaps
+and key sequences:
+
+@itemize @minus
+@item
+The @code{kbd} macro is now obsolete and is no longer documented.
+It isn't that difficult to write key sequences using the string and
+vector representations, and we want to encourage users to learn.
+
+@item
+Emacs no longer supports key remapping.  You can do pretty much the
+same thing with @code{substitute-key-definition}, or by advising the
+relevant command.
+
+@item
+The @code{keymap} text and overlay property is now overridden by minor
+mode keymaps, and will not work at the ends of text properties and
+overlays.
+
+@item
+The functions @code{map-keymap}, @code{keymap-prompt}, and
+@code{current-active-maps} have been removed.
+@end itemize
+
+@item
+Process support has been pared down to a functional minimum.  The
+functions @code{call-process-shell-command} and @code{process-file}
+have been deleted.  Processes no longer maintain property lists, and
+they won't ask any questions when the user tries to exit Emacs (which
+would simply be rude.)  The function @code{signal-process} won't
+accept a process object, only the process id; determining the process
+id from a process object is left as an exercise to the programmer.
+
+@item
+Networking has also been simplified: @code{make-network-process} and
+its various associated function have all been replaced with a single
+easy-to-use function, @code{open-network-stream}, which can't use UDP,
+can't act as a server, and can't set up non-blocking connections.
+Also, deleting a network process with @code{delete-process} won't call
+the sentinel.
+
+@item
+Many programming shortcuts have been deleted, to provide you with the
+enjoyment of ``rolling your own.''  The macros @code{while-no-input},
+@code{with-local-quit}, and @code{with-selected-window}, along with
+@code{dynamic-completion-table} and @code{lazy-completion-table} no
+longer exist.  Also, there are no built-in progress reporters;
+with Emacs, you can take progress for granted.
+
+@item
+Variable aliases are no longer supported.  Aliases are for functions,
+not for variables.
+
+@item
+The variables @code{most-positive-fixnum} and
+@code{most-negative-fixnum} do not exist.  On 32 bit machines, the
+most positive integer is probably 134217727, and the most negative
+integer is probably -134217728.
+
+@item
+The functions @code{eql} and @code{macroexpand-all} are no longer
+available.  However, you can find similar functions in the @code{cl}
+package.
+
+@item
+The list returned by @code{split-string} won't include null substrings
+for separators at the beginning or end of a string.  If you want to
+check for such separators, do it separately.
+
+@item
+The function @code{assoc-string} has been removed.  Use
+@code{assoc-ignore-case} or @code{assoc-ignore-representation} (which
+are no longer obsolete.)
+
+@item
+The escape sequence @samp{\s} is always interpreted as a super
+modifier, never a space.
+
+@item
+The variable @code{buffer-save-without-query} has been removed, to
+prevent Emacs from sneakily saving buffers.  Also, the hook
+@code{before-save-hook} has been removed, so if you want something to
+be done before saving, advise or redefine @code{basic-save-buffer}.
+
+@item
+The variable @code{buffer-auto-save-file-format} has been renamed to
+@code{auto-save-file-format}, and is no longer a permanent local.
+
+@item
+The function @code{visited-file-modtime} now returns a cons, instead
+of a list of two integers.  The primitive @code{set-file-times} has
+been eliminated.
+
+@item
+The function @code{file-remote-p} is no longer available.
+
+@item
+When determining the filename extension, a leading dot in a filename
+is no longer ignored.  Thus, @file{.emacs} is considered to have
+extension @file{emacs}, rather than being extensionless.
+
+@item
+Emacs looks for special file handlers in a more efficient manner: it
+will choose the first matching handler in
+@code{file-name-handler-alist}, rather than trying to figure out which
+provides the closest match.
+
+@item
+The @code{predicate} argument for @code{read-file-name} has been
+removed, and so have the variables @code{read-file-name-function} and
+@code{read-file-name-completion-ignore-case}.  The function
+@code{read-directory-name} has also been removed.
+
+@item
+The functions @code{all-completions} and @code{try-completion} will no
+longer accept lists of strings or hash tables (it will still accept
+alists, obarrays, and functions.)  In addition, the function
+@code{test-completion} is no longer available.
+
+@item
+The @samp{G} interactive code character is no longer supported.
+Use @samp{F} instead.
+
+@item
+Arbitrary Lisp functions can no longer be recorded into
+@code{buffer-undo-list}.  As a consequence, @code{yank-undo-function}
+is obsolete, and has been removed.
+
+@item
+Emacs will never complain about commands that accumulate too much undo
+information, so you no longer have to worry about binding
+@code{buffer-undo-list} to @code{t} for such commands (though you may
+want to do that anyway, to avoid taking up unnecessary memory space.)
+
+@item
+Atomic change groups are no longer supported.
+
+@item
+The list returned by @code{(match-data t)} no longer records the
+buffer as a final element.
+
+@item
+The function @code{looking-back} has been removed, so we no longer
+have the benefit of hindsight.
+
+@item
+The variable @code{search-spaces-regexp} does not exist.  Spaces
+always stand for themselves in regular expression searches.
+
+@item
+The functions @code{skip-chars-forward} and @code{skip-chars-backward}
+no longer accepts character classes such as @samp{[:alpha:]}.  All
+characters are created equal.
+
+@item
+The @code{yank-handler} text property no longer has any meaning.
+Also, @code{yank-excluded-properties}, @code{insert-for-yank}, and
+@code{insert-buffer-substring-as-yank} have all been removed.
+
+@item
+The variable @code{char-property-alias-alist} has been deleted.
+Aliases are for functions, not for properties.
+
+@item
+The function @code{get-char-property-and-overlay} has been deleted.
+If you want the properties at a point, find the text properties at the
+point; then, find the overlays at the point, and find the properties
+on those overlays.
+
+@item
+Font Lock mode only manages @code{face} properties; you can't use
+font-lock keywords to specify arbitrary text properties for it to
+manage.  After all, it is called Font Lock mode, not Arbitrary
+Properties Lock mode.
+
+@item
+The arguments to @code{remove-overlays} are no longer optional.
+
+@item
+In @code{replace-match}, the replacement text now inherits properties
+from the surrounding text.
+
+@item
+The variable @code{mode-line-format} no longer supports the @code{:propertize},
+@code{%i}, and @code{%I} constructs.  The function
+@code{format-mode-line} has been removed.
+
+@item
+The functions @code{window-inside-edges} and @code{window-body-height}
+have been removed.  You should do the relevant calculations yourself,
+starting with @code{window-width} and @code{window-height}.
+
+@item
+The functions @code{window-pixel-edges} and
+@code{window-inside-pixel-edges} have been removed.  We prefer to
+think in terms of lines and columns, not pixel coordinates.  (Sometime
+in the distant past, we will do away with graphical terminals
+entirely, in favor of text terminals.)  For similar reasons, the
+functions @code{posn-at-point}, @code{posn-at-x-y}, and
+@code{window-line-height} have been removed, and
+@code{pos-visible-in-window-p} no longer worries about partially
+visible rows.
+
+@item
+The macro @code{save-selected-window} only saves the selected window
+of the selected frame, so don't try selecting windows in other frames.
+
+@item
+The function @code{minibufferp} is no longer available.
+
+@item
+The function @code{modify-all-frames-parameters} has been removed (we
+always suspected the name was ungrammatical, anyway.)
+
+@item
+The @code{line-spacing} variable no longer accepts float values.
+
+@item
+The function @code{tool-bar-local-item-from-menu} has been deleted.
+If you need to make an entry in the tool bar, you can still use
+@code{tool-bar-add-item-from-menu}, but that modifies the binding in
+the source keymap instead of copying it into the local keymap.
+
+@item
+When determining the major mode, the file name takes precedence over
+the interpreter magic line.  The variable @code{magic-mode-alist},
+which associates certain buffer beginnings with major modes, has been
+eliminated.
+
+@item
+The hook @code{after-change-major-mode-hook} is not defined, and
+neither are @code{run-mode-hooks} and @code{delay-mode-hooks}.
+
+@item
+The variable @code{minor-mode-list} has been removed.
+
+@item
+@code{define-derived-mode} will copy abbrevs from the parent mode's
+abbrev table, instead of creating a new, empty abbrev table.
+
+@item
+There are no ``system'' abbrevs.  When the user saves into the abbrevs
+file, all abbrevs are saved.
+
+@item
+The Warnings facility has been removed.  Just use @code{error}.
+
+@item
+Several hook variables have been renamed to flout the Emacs naming
+conventions.  We feel that consistency is boring, and having
+non-standard hook names encourages users to check the documentation
+before using a hook.  For instance, the normal hook
+@code{find-file-hook} has been renamed to @code{find-file-hooks}, and
+the abnormal hook @code{delete-frame-functions} has been renamed to
+@code{delete-frame-hook}.
+
+@item
+The function @code{symbol-file} does not exist.  If you want to know
+which file defined a function or variable, try grepping for it.
+
+@item
+The variable @code{load-history} records function definitions just
+like variable definitions, instead of indicating which functions were
+previously autoloaded.
+
+@item
+There is a new variable, @code{recursive-load-depth-limit}, which
+specifies how many times files can recursively load themselves; it is
+50 by default, and @code{nil} means infinity.  Previously, Emacs signaled an
+error after just 3 recursive loads, which was boring.
+
+@item
+Byte-compiler warnings and error messages will leave out the line and
+character positions, in order to exercise your debugging skills.
+Also, there is no @code{with-no-warnings} macro---instead of
+suppressing compiler warnings, fix your code to avoid them!
+
+@item
+The function @code{unsafep} has been removed.
+
+@item
+File local variables can now specify a string with text properties.
+Since arbitrary Lisp expressions can be embedded in text properties,
+this can provide you with a great deal of flexibility and power.  On
+the other hand, @code{safe-local-eval-forms} and the
+@code{safe-local-eval-function} function property have no special
+meaning.
+
+@item
+You can no longer use @code{char-displayable-p} to test if Emacs can
+display a certain character.
+
+@item
+The function @code{string-to-multibyte} is no longer available.
+
+@item
+The @code{translation-table-for-input} translation table has been
+removed.  Also, translation hash tables are no longer available, so we
+don't need the functions @code{lookup-character} and
+@code{lookup-integer}.
+
+@item
+The @code{table} argument to @code{translate-region} can no longer be
+a char-table; it has to be a string.
+
+@item
+The variable @code{auto-coding-functions} and the two functions
+@code{merge-coding-systems} and @code{decode-coding-inserted-region}
+have been deleted.  The coding system property
+@code{mime-text-unsuitable} no longer has any special meaning.
+
+@item
+If pure storage overflows while dumping, Emacs won't tell you how much
+additional pure storage it needs.  Try adding in increments of 20000,
+until you have enough.
+
+@item
+The variables @code{gc-elapsed}, @code{gcs-done}, and
+@code{post-gc-hook} have been garbage-collected.
+@end itemize
+
+@ignore
+   arch-tag: 1d0ef137-2bad-430e-ae8e-d820d569b5a6
+@end ignore
diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi
new file mode 100644
index 00000000000..19559eab9c1
--- /dev/null
+++ b/doc/lispref/back.texi
@@ -0,0 +1,42 @@
+\input /home/gd/gnu/doc/texinfo.tex  @c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
+@c   Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@c
+@c %**start of header
+@setfilename back-cover
+@settitle GNU Emacs Lisp Reference Manual
+@c %**end of header
+.
+@sp 7
+@center @titlefont {GNU Emacs Lisp}
+@sp 1
+
+@quotation
+  Most of the GNU Emacs text editor is written in the programming
+language called Emacs Lisp.  You can write new code in Emacs Lisp and
+install it as an extension to the editor.  However, Emacs Lisp is more
+than a mere ``extension language''; it is a full computer programming
+language in its own right.  You can use it as you would any other
+programming language.
+
+  Because Emacs Lisp is designed for use in an editor, it has special
+features for scanning and parsing text as well as features for handling
+files, buffers, displays, subprocesses, and so on.  Emacs Lisp is
+closely integrated with the editing facilities; thus, editing commands
+are functions that can also conveniently be called from Lisp programs,
+and parameters for customization are ordinary Lisp variables.
+
+  This manual describes Emacs Lisp.  Generally speaking, the earlier
+chapters describe features of Emacs Lisp that have counterparts in
+many programming languages, and later chapters describe features that
+are peculiar to Emacs Lisp or relate specifically to editing.
+@end quotation
+
+@hfil
+@bye
+
+@ignore
+   arch-tag: ac7694c8-1f02-4b42-9531-33ba13b179e1
+@end ignore
diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
new file mode 100644
index 00000000000..44795557f15
--- /dev/null
+++ b/doc/lispref/backups.texi
@@ -0,0 +1,756 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2001, 2002, 2003,
+@c   2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/backups
+@node Backups and Auto-Saving, Buffers, Files, Top
+@chapter Backups and Auto-Saving
+@cindex backups and auto-saving
+
+  Backup files and auto-save files are two methods by which Emacs tries
+to protect the user from the consequences of crashes or of the user's
+own errors.  Auto-saving preserves the text from earlier in the current
+editing session; backup files preserve file contents prior to the
+current session.
+
+@menu
+* Backup Files::   How backup files are made; how their names are chosen.
+* Auto-Saving::    How auto-save files are made; how their names are chosen.
+* Reverting::      @code{revert-buffer}, and how to customize what it does.
+@end menu
+
+@node Backup Files
+@section Backup Files
+@cindex backup file
+
+  A @dfn{backup file} is a copy of the old contents of a file you are
+editing.  Emacs makes a backup file the first time you save a buffer
+into its visited file.  Thus, normally, the backup file contains the
+contents of the file as it was before the current editing session.
+The contents of the backup file normally remain unchanged once it
+exists.
+
+  Backups are usually made by renaming the visited file to a new name.
+Optionally, you can specify that backup files should be made by copying
+the visited file.  This choice makes a difference for files with
+multiple names; it also can affect whether the edited file remains owned
+by the original owner or becomes owned by the user editing it.
+
+  By default, Emacs makes a single backup file for each file edited.
+You can alternatively request numbered backups; then each new backup
+file gets a new name.  You can delete old numbered backups when you
+don't want them any more, or Emacs can delete them automatically.
+
+@menu
+* Making Backups::     How Emacs makes backup files, and when.
+* Rename or Copy::     Two alternatives: renaming the old file or copying it.
+* Numbered Backups::   Keeping multiple backups for each source file.
+* Backup Names::       How backup file names are computed; customization.
+@end menu
+
+@node Making Backups
+@subsection Making Backup Files
+
+@defun backup-buffer
+  This function makes a backup of the file visited by the current
+buffer, if appropriate.  It is called by @code{save-buffer} before
+saving the buffer the first time.
+
+If a backup was made by renaming, the return value is a cons cell of
+the form (@var{modes} . @var{backupname}), where @var{modes} are the
+mode bits of the original file, as returned by @code{file-modes}
+(@pxref{File Attributes,, Other Information about Files}), and
+@var{backupname} is the name of the backup.  In all other cases, that
+is, if a backup was made by copying or if no backup was made, this
+function returns @code{nil}.
+@end defun
+
+@defvar buffer-backed-up
+  This buffer-local variable says whether this buffer's file has
+been backed up on account of this buffer.  If it is non-@code{nil},
+the backup file has been written.  Otherwise, the file should be backed
+up when it is next saved (if backups are enabled).  This is a
+permanent local; @code{kill-all-local-variables} does not alter@tie{}it.
+@end defvar
+
+@defopt make-backup-files
+This variable determines whether or not to make backup files.  If it
+is non-@code{nil}, then Emacs creates a backup of each file when it is
+saved for the first time---provided that @code{backup-inhibited}
+is @code{nil} (see below).
+
+The following example shows how to change the @code{make-backup-files}
+variable only in the Rmail buffers and not elsewhere.  Setting it
+@code{nil} stops Emacs from making backups of these files, which may
+save disk space.  (You would put this code in your init file.)
+
+@smallexample
+@group
+(add-hook 'rmail-mode-hook
+          (function (lambda ()
+                      (make-local-variable
+                       'make-backup-files)
+                      (setq make-backup-files nil))))
+@end group
+@end smallexample
+@end defopt
+
+@defvar backup-enable-predicate
+This variable's value is a function to be called on certain occasions to
+decide whether a file should have backup files.  The function receives
+one argument, an absolute file name to consider.  If the function returns
+@code{nil}, backups are disabled for that file.  Otherwise, the other
+variables in this section say whether and how to make backups.
+
+@findex normal-backup-enable-predicate
+The default value is @code{normal-backup-enable-predicate}, which checks
+for files in @code{temporary-file-directory} and
+@code{small-temporary-file-directory}.
+@end defvar
+
+@defvar backup-inhibited
+If this variable is non-@code{nil}, backups are inhibited.  It records
+the result of testing @code{backup-enable-predicate} on the visited file
+name.  It can also coherently be used by other mechanisms that inhibit
+backups based on which file is visited.  For example, VC sets this
+variable non-@code{nil} to prevent making backups for files managed
+with a version control system.
+
+This is a permanent local, so that changing the major mode does not lose
+its value.  Major modes should not set this variable---they should set
+@code{make-backup-files} instead.
+@end defvar
+
+@defvar backup-directory-alist
+This variable's value is an alist of filename patterns and backup
+directory names.  Each element looks like
+@smallexample
+(@var{regexp} . @var{directory})
+@end smallexample
+
+@noindent
+Backups of files with names matching @var{regexp} will be made in
+@var{directory}.  @var{directory} may be relative or absolute.  If it is
+absolute, so that all matching files are backed up into the same
+directory, the file names in this directory will be the full name of the
+file backed up with all directory separators changed to @samp{!} to
+prevent clashes.  This will not work correctly if your filesystem
+truncates the resulting name.
+
+For the common case of all backups going into one directory, the alist
+should contain a single element pairing @samp{"."} with the appropriate
+directory name.
+
+If this variable is @code{nil}, or it fails to match a filename, the
+backup is made in the original file's directory.
+
+On MS-DOS filesystems without long names this variable is always
+ignored.
+@end defvar
+
+@defvar make-backup-file-name-function
+This variable's value is a function to use for making backups instead
+of the default @code{make-backup-file-name}.  A value of @code{nil}
+gives the default @code{make-backup-file-name} behavior.
+@xref{Backup Names,, Naming Backup Files}.
+
+This could be buffer-local to do something special for specific
+files.  If you define it, you may need to change
+@code{backup-file-name-p} and @code{file-name-sans-versions} too.
+@end defvar
+
+
+@node Rename or Copy
+@subsection Backup by Renaming or by Copying?
+@cindex backup files, rename or copy
+
+  There are two ways that Emacs can make a backup file:
+
+@itemize @bullet
+@item
+Emacs can rename the original file so that it becomes a backup file, and
+then write the buffer being saved into a new file.  After this
+procedure, any other names (i.e., hard links) of the original file now
+refer to the backup file.  The new file is owned by the user doing the
+editing, and its group is the default for new files written by the user
+in that directory.
+
+@item
+Emacs can copy the original file into a backup file, and then overwrite
+the original file with new contents.  After this procedure, any other
+names (i.e., hard links) of the original file continue to refer to the
+current (updated) version of the file.  The file's owner and group will
+be unchanged.
+@end itemize
+
+  The first method, renaming, is the default.
+
+  The variable @code{backup-by-copying}, if non-@code{nil}, says to use
+the second method, which is to copy the original file and overwrite it
+with the new buffer contents.  The variable @code{file-precious-flag},
+if non-@code{nil}, also has this effect (as a sideline of its main
+significance).  @xref{Saving Buffers}.
+
+@defopt backup-by-copying
+If this variable is non-@code{nil}, Emacs always makes backup files by
+copying.
+@end defopt
+
+  The following three variables, when non-@code{nil}, cause the second
+method to be used in certain special cases.  They have no effect on the
+treatment of files that don't fall into the special cases.
+
+@defopt backup-by-copying-when-linked
+If this variable is non-@code{nil}, Emacs makes backups by copying for
+files with multiple names (hard links).
+
+This variable is significant only if @code{backup-by-copying} is
+@code{nil}, since copying is always used when that variable is
+non-@code{nil}.
+@end defopt
+
+@defopt backup-by-copying-when-mismatch
+If this variable is non-@code{nil}, Emacs makes backups by copying in cases
+where renaming would change either the owner or the group of the file.
+
+The value has no effect when renaming would not alter the owner or
+group of the file; that is, for files which are owned by the user and
+whose group matches the default for a new file created there by the
+user.
+
+This variable is significant only if @code{backup-by-copying} is
+@code{nil}, since copying is always used when that variable is
+non-@code{nil}.
+@end defopt
+
+@defopt backup-by-copying-when-privileged-mismatch
+This variable, if non-@code{nil}, specifies the same behavior as
+@code{backup-by-copying-when-mismatch}, but only for certain user-id
+values: namely, those less than or equal to a certain number.  You set
+this variable to that number.
+
+Thus, if you set @code{backup-by-copying-when-privileged-mismatch}
+to 0, backup by copying is done for the superuser only,
+when necessary to prevent a change in the owner of the file.
+
+The default is 200.
+@end defopt
+
+@node Numbered Backups
+@subsection Making and Deleting Numbered Backup Files
+
+  If a file's name is @file{foo}, the names of its numbered backup
+versions are @file{foo.~@var{v}~}, for various integers @var{v}, like
+this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{},
+@file{foo.~259~}, and so on.
+
+@defopt version-control
+This variable controls whether to make a single non-numbered backup
+file or multiple numbered backups.
+
+@table @asis
+@item @code{nil}
+Make numbered backups if the visited file already has numbered backups;
+otherwise, do not.  This is the default.
+
+@item @code{never}
+Do not make numbered backups.
+
+@item @var{anything else}
+Make numbered backups.
+@end table
+@end defopt
+
+  The use of numbered backups ultimately leads to a large number of
+backup versions, which must then be deleted.  Emacs can do this
+automatically or it can ask the user whether to delete them.
+
+@defopt kept-new-versions
+The value of this variable is the number of newest versions to keep
+when a new numbered backup is made.  The newly made backup is included
+in the count.  The default value is@tie{}2.
+@end defopt
+
+@defopt kept-old-versions
+The value of this variable is the number of oldest versions to keep
+when a new numbered backup is made.  The default value is@tie{}2.
+@end defopt
+
+  If there are backups numbered 1, 2, 3, 5, and 7, and both of these
+variables have the value 2, then the backups numbered 1 and 2 are kept
+as old versions and those numbered 5 and 7 are kept as new versions;
+backup version 3 is excess.  The function @code{find-backup-file-name}
+(@pxref{Backup Names}) is responsible for determining which backup
+versions to delete, but does not delete them itself.
+
+@defopt delete-old-versions
+If this variable is @code{t}, then saving a file deletes excess
+backup versions silently.  If it is @code{nil}, that means
+to ask for confirmation before deleting excess backups.
+Otherwise, they are not deleted at all.
+@end defopt
+
+@defopt dired-kept-versions
+This variable specifies how many of the newest backup versions to keep
+in the Dired command @kbd{.} (@code{dired-clean-directory}).  That's the
+same thing @code{kept-new-versions} specifies when you make a new backup
+file.  The default is@tie{}2.
+@end defopt
+
+@node Backup Names
+@subsection Naming Backup Files
+
+  The functions in this section are documented mainly because you can
+customize the naming conventions for backup files by redefining them.
+If you change one, you probably need to change the rest.
+
+@defun backup-file-name-p filename
+This function returns a non-@code{nil} value if @var{filename} is a
+possible name for a backup file.  It just checks the name, not whether
+a file with the name @var{filename} exists.
+
+@smallexample
+@group
+(backup-file-name-p "foo")
+     @result{} nil
+@end group
+@group
+(backup-file-name-p "foo~")
+     @result{} 3
+@end group
+@end smallexample
+
+The standard definition of this function is as follows:
+
+@smallexample
+@group
+(defun backup-file-name-p (file)
+  "Return non-nil if FILE is a backup file \
+name (numeric or not)..."
+  (string-match "~\\'" file))
+@end group
+@end smallexample
+
+@noindent
+Thus, the function returns a non-@code{nil} value if the file name ends
+with a @samp{~}.  (We use a backslash to split the documentation
+string's first line into two lines in the text, but produce just one
+line in the string itself.)
+
+This simple expression is placed in a separate function to make it easy
+to redefine for customization.
+@end defun
+
+@defun make-backup-file-name filename
+This function returns a string that is the name to use for a
+non-numbered backup file for file @var{filename}.  On Unix, this is just
+@var{filename} with a tilde appended.
+
+The standard definition of this function, on most operating systems, is
+as follows:
+
+@smallexample
+@group
+(defun make-backup-file-name (file)
+  "Create the non-numeric backup file name for FILE..."
+  (concat file "~"))
+@end group
+@end smallexample
+
+You can change the backup-file naming convention by redefining this
+function.  The following example redefines @code{make-backup-file-name}
+to prepend a @samp{.} in addition to appending a tilde:
+
+@smallexample
+@group
+(defun make-backup-file-name (filename)
+  (expand-file-name
+    (concat "." (file-name-nondirectory filename) "~")
+    (file-name-directory filename)))
+@end group
+
+@group
+(make-backup-file-name "backups.texi")
+     @result{} ".backups.texi~"
+@end group
+@end smallexample
+
+Some parts of Emacs, including some Dired commands, assume that backup
+file names end with @samp{~}.  If you do not follow that convention, it
+will not cause serious problems, but these commands may give
+less-than-desirable results.
+@end defun
+
+@defun find-backup-file-name filename
+This function computes the file name for a new backup file for
+@var{filename}.  It may also propose certain existing backup files for
+deletion.  @code{find-backup-file-name} returns a list whose @sc{car} is
+the name for the new backup file and whose @sc{cdr} is a list of backup
+files whose deletion is proposed.  The value can also be @code{nil},
+which means not to make a backup.
+
+Two variables, @code{kept-old-versions} and @code{kept-new-versions},
+determine which backup versions should be kept.  This function keeps
+those versions by excluding them from the @sc{cdr} of the value.
+@xref{Numbered Backups}.
+
+In this example, the value says that @file{~rms/foo.~5~} is the name
+to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess''
+version that the caller should consider deleting now.
+
+@smallexample
+@group
+(find-backup-file-name "~rms/foo")
+     @result{} ("~rms/foo.~5~" "~rms/foo.~3~")
+@end group
+@end smallexample
+@end defun
+
+@c Emacs 19 feature
+@defun file-newest-backup filename
+This function returns the name of the most recent backup file for
+@var{filename}, or @code{nil} if that file has no backup files.
+
+Some file comparison commands use this function so that they can
+automatically compare a file with its most recent backup.
+@end defun
+
+@node Auto-Saving
+@section Auto-Saving
+@c @cindex auto-saving   Lots of symbols starting with auto-save here.
+
+  Emacs periodically saves all files that you are visiting; this is
+called @dfn{auto-saving}.  Auto-saving prevents you from losing more
+than a limited amount of work if the system crashes.  By default,
+auto-saves happen every 300 keystrokes, or after around 30 seconds of
+idle time.  @xref{Auto Save, Auto Save, Auto-Saving: Protection Against
+Disasters, emacs, The GNU Emacs Manual}, for information on auto-save
+for users.  Here we describe the functions used to implement auto-saving
+and the variables that control them.
+
+@defvar buffer-auto-save-file-name
+This buffer-local variable is the name of the file used for
+auto-saving the current buffer.  It is @code{nil} if the buffer
+should not be auto-saved.
+
+@example
+@group
+buffer-auto-save-file-name
+     @result{} "/xcssun/users/rms/lewis/#backups.texi#"
+@end group
+@end example
+@end defvar
+
+@deffn Command auto-save-mode arg
+When used interactively without an argument, this command is a toggle
+switch: it turns on auto-saving of the current buffer if it is off, and
+vice versa.  With an argument @var{arg}, the command turns auto-saving
+on if the value of @var{arg} is @code{t}, a nonempty list, or a positive
+integer.  Otherwise, it turns auto-saving off.
+@end deffn
+
+@defun auto-save-file-name-p filename
+This function returns a non-@code{nil} value if @var{filename} is a
+string that could be the name of an auto-save file.  It assumes
+the usual naming convention for auto-save files: a name that
+begins and ends with hash marks (@samp{#}) is a possible auto-save file
+name.  The argument @var{filename} should not contain a directory part.
+
+@example
+@group
+(make-auto-save-file-name)
+     @result{} "/xcssun/users/rms/lewis/#backups.texi#"
+@end group
+@group
+(auto-save-file-name-p "#backups.texi#")
+     @result{} 0
+@end group
+@group
+(auto-save-file-name-p "backups.texi")
+     @result{} nil
+@end group
+@end example
+
+The standard definition of this function is as follows:
+
+@example
+@group
+(defun auto-save-file-name-p (filename)
+  "Return non-nil if FILENAME can be yielded by..."
+  (string-match "^#.*#$" filename))
+@end group
+@end example
+
+This function exists so that you can customize it if you wish to
+change the naming convention for auto-save files.  If you redefine it,
+be sure to redefine the function @code{make-auto-save-file-name}
+correspondingly.
+@end defun
+
+@defun make-auto-save-file-name
+This function returns the file name to use for auto-saving the current
+buffer.  This is just the file name with hash marks (@samp{#}) prepended
+and appended to it.  This function does not look at the variable
+@code{auto-save-visited-file-name} (described below); callers of this
+function should check that variable first.
+
+@example
+@group
+(make-auto-save-file-name)
+     @result{} "/xcssun/users/rms/lewis/#backups.texi#"
+@end group
+@end example
+
+Here is a simplified version of the standard definition of this
+function:
+
+@example
+@group
+(defun make-auto-save-file-name ()
+  "Return file name to use for auto-saves \
+of current buffer.."
+  (if buffer-file-name
+@end group
+@group
+      (concat
+       (file-name-directory buffer-file-name)
+       "#"
+       (file-name-nondirectory buffer-file-name)
+       "#")
+    (expand-file-name
+     (concat "#%" (buffer-name) "#"))))
+@end group
+@end example
+
+This exists as a separate function so that you can redefine it to
+customize the naming convention for auto-save files.  Be sure to
+change @code{auto-save-file-name-p} in a corresponding way.
+@end defun
+
+@defopt auto-save-visited-file-name
+If this variable is non-@code{nil}, Emacs auto-saves buffers in
+the files they are visiting.  That is, the auto-save is done in the same
+file that you are editing.  Normally, this variable is @code{nil}, so
+auto-save files have distinct names that are created by
+@code{make-auto-save-file-name}.
+
+When you change the value of this variable, the new value does not take
+effect in an existing buffer until the next time auto-save mode is
+reenabled in it.  If auto-save mode is already enabled, auto-saves
+continue to go in the same file name until @code{auto-save-mode} is
+called again.
+@end defopt
+
+@defun recent-auto-save-p
+This function returns @code{t} if the current buffer has been
+auto-saved since the last time it was read in or saved.
+@end defun
+
+@defun set-buffer-auto-saved
+This function marks the current buffer as auto-saved.  The buffer will
+not be auto-saved again until the buffer text is changed again.  The
+function returns @code{nil}.
+@end defun
+
+@defopt auto-save-interval
+The value of this variable specifies how often to do auto-saving, in
+terms of number of input events.  Each time this many additional input
+events are read, Emacs does auto-saving for all buffers in which that is
+enabled.  Setting this to zero disables autosaving based on the
+number of characters typed.
+@end defopt
+
+@defopt auto-save-timeout
+The value of this variable is the number of seconds of idle time that
+should cause auto-saving.  Each time the user pauses for this long,
+Emacs does auto-saving for all buffers in which that is enabled.  (If
+the current buffer is large, the specified timeout is multiplied by a
+factor that increases as the size increases; for a million-byte
+buffer, the factor is almost 4.)
+
+If the value is zero or @code{nil}, then auto-saving is not done as a
+result of idleness, only after a certain number of input events as
+specified by @code{auto-save-interval}.
+@end defopt
+
+@defvar auto-save-hook
+This normal hook is run whenever an auto-save is about to happen.
+@end defvar
+
+@defopt auto-save-default
+If this variable is non-@code{nil}, buffers that are visiting files
+have auto-saving enabled by default.  Otherwise, they do not.
+@end defopt
+
+@deffn Command do-auto-save &optional no-message current-only
+This function auto-saves all buffers that need to be auto-saved.  It
+saves all buffers for which auto-saving is enabled and that have been
+changed since the previous auto-save.
+
+If any buffers are auto-saved, @code{do-auto-save} normally displays a
+message saying @samp{Auto-saving...} in the echo area while
+auto-saving is going on.  However, if @var{no-message} is
+non-@code{nil}, the message is inhibited.
+
+If @var{current-only} is non-@code{nil}, only the current buffer
+is auto-saved.
+@end deffn
+
+@defun delete-auto-save-file-if-necessary &optional force
+This function deletes the current buffer's auto-save file if
+@code{delete-auto-save-files} is non-@code{nil}.  It is called every
+time a buffer is saved.
+
+Unless @var{force} is non-@code{nil}, this function only deletes the
+file if it was written by the current Emacs session since the last
+true save.
+@end defun
+
+@defopt delete-auto-save-files
+This variable is used by the function
+@code{delete-auto-save-file-if-necessary}.  If it is non-@code{nil},
+Emacs deletes auto-save files when a true save is done (in the visited
+file).  This saves disk space and unclutters your directory.
+@end defopt
+
+@defun rename-auto-save-file
+This function adjusts the current buffer's auto-save file name if the
+visited file name has changed.  It also renames an existing auto-save
+file, if it was made in the current Emacs session.  If the visited
+file name has not changed, this function does nothing.
+@end defun
+
+@defvar buffer-saved-size
+The value of this buffer-local variable is the length of the current
+buffer, when it was last read in, saved, or auto-saved.  This is
+used to detect a substantial decrease in size, and turn off auto-saving
+in response.
+
+If it is @minus{}1, that means auto-saving is temporarily shut off in
+this buffer due to a substantial decrease in size.  Explicitly saving
+the buffer stores a positive value in this variable, thus reenabling
+auto-saving.  Turning auto-save mode off or on also updates this
+variable, so that the substantial decrease in size is forgotten.
+@end defvar
+
+@defvar auto-save-list-file-name
+This variable (if non-@code{nil}) specifies a file for recording the
+names of all the auto-save files.  Each time Emacs does auto-saving, it
+writes two lines into this file for each buffer that has auto-saving
+enabled.  The first line gives the name of the visited file (it's empty
+if the buffer has none), and the second gives the name of the auto-save
+file.
+
+When Emacs exits normally, it deletes this file; if Emacs crashes, you
+can look in the file to find all the auto-save files that might contain
+work that was otherwise lost.  The @code{recover-session} command uses
+this file to find them.
+
+The default name for this file specifies your home directory and starts
+with @samp{.saves-}.  It also contains the Emacs process @acronym{ID} and the
+host name.
+@end defvar
+
+@defvar auto-save-list-file-prefix
+After Emacs reads your init file, it initializes
+@code{auto-save-list-file-name} (if you have not already set it
+non-@code{nil}) based on this prefix, adding the host name and process
+ID.  If you set this to @code{nil} in your init file, then Emacs does
+not initialize @code{auto-save-list-file-name}.
+@end defvar
+
+@node Reverting
+@section Reverting
+
+  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 with the @code{revert-buffer} command.  @xref{Reverting, ,
+Reverting a Buffer, emacs, The GNU Emacs Manual}.
+
+@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes
+This command replaces the buffer text with the text of the visited
+file on disk.  This action undoes all changes since the file was visited
+or saved.
+
+By default, if the latest auto-save file is more recent than the visited
+file, and the argument @var{ignore-auto} is @code{nil},
+@code{revert-buffer} asks the user whether to use that auto-save
+instead.  When you invoke this command interactively, @var{ignore-auto}
+is @code{t} if there is no numeric prefix argument; thus, the
+interactive default is not to check the auto-save file.
+
+Normally, @code{revert-buffer} asks for confirmation before it changes
+the buffer; but if the argument @var{noconfirm} is non-@code{nil},
+@code{revert-buffer} does not ask for confirmation.
+
+Normally, this command reinitializes the buffer's major and minor modes
+using @code{normal-mode}.  But if @var{preserve-modes} is
+non-@code{nil}, the modes remain unchanged.
+
+Reverting tries to preserve marker positions in the buffer by using the
+replacement feature of @code{insert-file-contents}.  If the buffer
+contents and the file contents are identical before the revert
+operation, reverting preserves all the markers.  If they are not
+identical, reverting does change the buffer; in that case, it preserves
+the markers in the unchanged text (if any) at the beginning and end of
+the buffer.  Preserving any additional markers would be problematical.
+@end deffn
+
+You can customize how @code{revert-buffer} does its work by setting
+the variables described in the rest of this section.
+
+@defopt revert-without-query
+This variable holds a list of files that should be reverted without
+query.  The value is a list of regular expressions.  If the visited file
+name matches one of these regular expressions, and the file has changed
+on disk but the buffer is not modified, then @code{revert-buffer}
+reverts the file without asking the user for confirmation.
+@end defopt
+
+  Some major modes customize @code{revert-buffer} by making
+buffer-local bindings for these variables:
+
+@defvar revert-buffer-function
+@anchor{Definition of revert-buffer-function}
+The value of this variable is the function to use to revert this
+buffer.  If non-@code{nil}, it should be a function with two optional
+arguments to do the work of reverting.  The two optional arguments,
+@var{ignore-auto} and @var{noconfirm}, are the arguments that
+@code{revert-buffer} received.  If the value is @code{nil}, reverting
+works the usual way.
+
+Modes such as Dired mode, in which the text being edited does not
+consist of a file's contents but can be regenerated in some other
+fashion, can give this variable a buffer-local value that is a function to
+regenerate the contents.
+@end defvar
+
+@defvar revert-buffer-insert-file-contents-function
+The value of this variable, if non-@code{nil}, specifies the function to use to
+insert the updated contents when reverting this buffer.  The function
+receives two arguments: first the file name to use; second, @code{t} if
+the user has asked to read the auto-save file.
+
+The reason for a mode to set this variable instead of
+@code{revert-buffer-function} is to avoid duplicating or replacing the
+rest of what @code{revert-buffer} does: asking for confirmation,
+clearing the undo list, deciding the proper major mode, and running the
+hooks listed below.
+@end defvar
+
+@defvar before-revert-hook
+This normal hook is run by @code{revert-buffer} before
+inserting the modified contents---but only if
+@code{revert-buffer-function} is @code{nil}.
+@end defvar
+
+@defvar after-revert-hook
+This normal hook is run by @code{revert-buffer} after inserting
+the modified contents---but only if @code{revert-buffer-function} is
+@code{nil}.
+@end defvar
+
+@ignore
+   arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f
+@end ignore
diff --git a/doc/lispref/book-spine.texinfo b/doc/lispref/book-spine.texinfo
new file mode 100644
index 00000000000..7355c4530ae
--- /dev/null
+++ b/doc/lispref/book-spine.texinfo
@@ -0,0 +1,29 @@
+\input texinfo  @c -*-texinfo-*-
+@c %**start of header
+@setfilename book-spine
+@settitle book-spine
+@c %**end of header
+
+@c need dot in text so first space command works!
+.
+@sp 7
+
+@center @titlefont{GNU Emacs Lisp Reference Manual}
+@sp 5
+@center GNU
+@center Emacs Version 22.1
+@center for Unix Users
+@sp 5
+
+@center by
+@center Bil Lewis,
+@center Dan LaLiberte,
+@center and the
+@center GNU Manual Group
+@sp 5
+@center Free Software Foundation
+@bye
+
+@ignore
+   arch-tag: 4466c7ca-e549-4119-948c-6eed34e1ff87
+@end ignore
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
new file mode 100644
index 00000000000..e9cafb69fb5
--- /dev/null
+++ b/doc/lispref/buffers.texi
@@ -0,0 +1,1165 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/buffers
+@node Buffers, Windows, Backups and Auto-Saving, Top
+@chapter Buffers
+@cindex buffer
+
+  A @dfn{buffer} is a Lisp object containing text to be edited.  Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files.  While several buffers may
+exist at one time, only one buffer is designated the @dfn{current
+buffer} at any time.  Most editing commands act on the contents of the
+current buffer.  Each buffer, including the current buffer, may or may
+not be displayed in any windows.
+
+@menu
+* Buffer Basics::       What is a buffer?
+* Current Buffer::      Designating a buffer as current
+                          so that primitives will access its contents.
+* Buffer Names::        Accessing and changing buffer names.
+* Buffer File Name::    The buffer file name indicates which file is visited.
+* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
+* Modification Time::   Determining whether the visited file was changed
+                         ``behind Emacs's back''.
+* Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
+* The Buffer List::     How to look at all the existing buffers.
+* Creating Buffers::    Functions that create buffers.
+* Killing Buffers::     Buffers exist until explicitly killed.
+* Indirect Buffers::    An indirect buffer shares text with some other buffer.
+* Buffer Gap::          The gap in the buffer.
+@end menu
+
+@node Buffer Basics
+@comment  node-name,  next,  previous,  up
+@section Buffer Basics
+
+@ifnottex
+  A @dfn{buffer} is a Lisp object containing text to be edited.  Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files.  Although several buffers
+normally exist, only one buffer is designated the @dfn{current
+buffer} at any time.  Most editing commands act on the contents of the
+current buffer.  Each buffer, including the current buffer, may or may
+not be displayed in any windows.
+@end ifnottex
+
+  Buffers in Emacs editing are objects that have distinct names and hold
+text that can be edited.  Buffers appear to Lisp programs as a special
+data type.  You can think of the contents of a buffer as a string that
+you can extend; insertions and deletions may occur in any part of the
+buffer.  @xref{Text}.
+
+  A Lisp buffer object contains numerous pieces of information.  Some of
+this information is directly accessible to the programmer through
+variables, while other information is accessible only through
+special-purpose functions.  For example, the visited file name is
+directly accessible through a variable, while the value of point is
+accessible only through a primitive function.
+
+  Buffer-specific information that is directly accessible is stored in
+@dfn{buffer-local} variable bindings, which are variable values that are
+effective only in a particular buffer.  This feature allows each buffer
+to override the values of certain variables.  Most major modes override
+variables such as @code{fill-column} or @code{comment-column} in this
+way.  For more information about buffer-local variables and functions
+related to them, see @ref{Buffer-Local Variables}.
+
+  For functions and variables related to visiting files in buffers, see
+@ref{Visiting Files} and @ref{Saving Buffers}.  For functions and
+variables related to the display of buffers in windows, see
+@ref{Buffers and Windows}.
+
+@defun bufferp object
+This function returns @code{t} if @var{object} is a buffer,
+@code{nil} otherwise.
+@end defun
+
+@node Current Buffer
+@section The Current Buffer
+@cindex selecting a buffer
+@cindex changing to another buffer
+@cindex current buffer
+
+  There are, in general, many buffers in an Emacs session.  At any time,
+one of them is designated as the @dfn{current buffer}.  This is the
+buffer in which most editing takes place, because most of the primitives
+for examining or changing text in a buffer operate implicitly on the
+current buffer (@pxref{Text}).  Normally the buffer that is displayed on
+the screen in the selected window is the current buffer, but this is not
+always so: a Lisp program can temporarily designate any buffer as
+current in order to operate on its contents, without changing what is
+displayed on the screen.
+
+  The way to designate a current buffer in a Lisp program is by calling
+@code{set-buffer}.  The specified buffer remains current until a new one
+is designated.
+
+  When an editing command returns to the editor command loop, the
+command loop designates the buffer displayed in the selected window as
+current, to prevent confusion: the buffer that the cursor is in when
+Emacs reads a command is the buffer that the command will apply to.
+(@xref{Command Loop}.)  Therefore, @code{set-buffer} is not the way to
+switch visibly to a different buffer so that the user can edit it.  For
+that, you must use the functions described in @ref{Displaying Buffers}.
+
+  @strong{Warning:} Lisp functions that change to a different current buffer
+should not depend on the command loop to set it back afterwards.
+Editing commands written in Emacs Lisp can be called from other programs
+as well as from the command loop; it is convenient for the caller if
+the subroutine does not change which buffer is current (unless, of
+course, that is the subroutine's purpose).  Therefore, you should
+normally use @code{set-buffer} within a @code{save-current-buffer} or
+@code{save-excursion} (@pxref{Excursions}) form that will restore the
+current buffer when your function is done.  Here is an example, the
+code for the command @code{append-to-buffer} (with the documentation
+string abridged):
+
+@example
+@group
+(defun append-to-buffer (buffer start end)
+  "Append to specified buffer the text of the region.
+@dots{}"
+  (interactive "BAppend to buffer: \nr")
+  (let ((oldbuf (current-buffer)))
+    (save-current-buffer
+      (set-buffer (get-buffer-create buffer))
+      (insert-buffer-substring oldbuf start end))))
+@end group
+@end example
+
+@noindent
+This function binds a local variable to record the current buffer, and
+then @code{save-current-buffer} arranges to make it current again.
+Next, @code{set-buffer} makes the specified buffer current.  Finally,
+@code{insert-buffer-substring} copies the string from the original
+current buffer to the specified (and now current) buffer.
+
+  If the buffer appended to happens to be displayed in some window,
+the next redisplay will show how its text has changed.  Otherwise, you
+will not see the change immediately on the screen.  The buffer becomes
+current temporarily during the execution of the command, but this does
+not cause it to be displayed.
+
+  If you make local bindings (with @code{let} or function arguments) for
+a variable that may also have buffer-local bindings, make sure that the
+same buffer is current at the beginning and at the end of the local
+binding's scope.  Otherwise you might bind it in one buffer and unbind
+it in another!  There are two ways to do this.  In simple cases, you may
+see that nothing ever changes the current buffer within the scope of the
+binding.  Otherwise, use @code{save-current-buffer} or
+@code{save-excursion} to make sure that the buffer current at the
+beginning is current again whenever the variable is unbound.
+
+  Do not rely on using @code{set-buffer} to change the current buffer
+back, because that won't do the job if a quit happens while the wrong
+buffer is current.  Here is what @emph{not} to do:
+
+@example
+@group
+(let (buffer-read-only
+      (obuf (current-buffer)))
+  (set-buffer @dots{})
+  @dots{}
+  (set-buffer obuf))
+@end group
+@end example
+
+@noindent
+Using @code{save-current-buffer}, as shown here, handles quitting,
+errors, and @code{throw}, as well as ordinary evaluation.
+
+@example
+@group
+(let (buffer-read-only)
+  (save-current-buffer
+    (set-buffer @dots{})
+    @dots{}))
+@end group
+@end example
+
+@defun current-buffer
+This function returns the current buffer.
+
+@example
+@group
+(current-buffer)
+     @result{} #<buffer buffers.texi>
+@end group
+@end example
+@end defun
+
+@defun set-buffer buffer-or-name
+This function makes @var{buffer-or-name} the current buffer.  This does
+not display the buffer in any window, so the user cannot necessarily see
+the buffer.  But Lisp programs will now operate on it.
+
+This function returns the buffer identified by @var{buffer-or-name}.
+An error is signaled if @var{buffer-or-name} does not identify an
+existing buffer.
+@end defun
+
+@defspec save-current-buffer body@dots{}
+The @code{save-current-buffer} special form saves the identity of the
+current buffer, evaluates the @var{body} forms, and finally restores
+that buffer as current.  The return value is the value of the last
+form in @var{body}.  The current buffer is restored even in case of an
+abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
+
+If the buffer that used to be current has been killed by the time of
+exit from @code{save-current-buffer}, then it is not made current again,
+of course.  Instead, whichever buffer was current just before exit
+remains current.
+@end defspec
+
+@defmac with-current-buffer buffer-or-name body@dots{}
+The @code{with-current-buffer} macro saves the identity of the current
+buffer, makes @var{buffer-or-name} current, evaluates the @var{body}
+forms, and finally restores the buffer.  The return value is the value
+of the last form in @var{body}.  The current buffer is restored even
+in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
+Exits}).
+
+An error is signaled if @var{buffer-or-name} does not identify an
+existing buffer.
+@end defmac
+
+@defmac with-temp-buffer body@dots{}
+@anchor{Definition of with-temp-buffer}
+The @code{with-temp-buffer} macro evaluates the @var{body} forms
+with a temporary buffer as the current buffer.  It saves the identity of
+the current buffer, creates a temporary buffer and makes it current,
+evaluates the @var{body} forms, and finally restores the previous
+current buffer while killing the temporary buffer.  By default, undo
+information (@pxref{Undo}) is not recorded in the buffer created by
+this macro (but @var{body} can enable that, if needed).
+
+The return value is the value of the last form in @var{body}.  You can
+return the contents of the temporary buffer by using
+@code{(buffer-string)} as the last form.
+
+The current buffer is restored even in case of an abnormal exit via
+@code{throw} or error (@pxref{Nonlocal Exits}).
+
+See also @code{with-temp-file} in @ref{Definition of with-temp-file,,
+Writing to Files}.
+@end defmac
+
+@node Buffer Names
+@section Buffer Names
+@cindex buffer names
+
+  Each buffer has a unique name, which is a string.  Many of the
+functions that work on buffers accept either a buffer or a buffer name
+as an argument.  Any argument called @var{buffer-or-name} is of this
+sort, and an error is signaled if it is neither a string nor a buffer.
+Any argument called @var{buffer} must be an actual buffer
+object, not a name.
+
+@cindex hidden buffers
+@cindex buffers without undo information
+  Buffers that are ephemeral and generally uninteresting to the user
+have names starting with a space, so that the @code{list-buffers} and
+@code{buffer-menu} commands don't mention them (but if such a buffer
+visits a file, it @strong{is} mentioned).  A name starting with
+space also initially disables recording undo information; see
+@ref{Undo}.
+
+@defun buffer-name &optional buffer
+This function returns the name of @var{buffer} as a string.  If
+@var{buffer} is not supplied, it defaults to the current buffer.
+
+If @code{buffer-name} returns @code{nil}, it means that @var{buffer}
+has been killed.  @xref{Killing Buffers}.
+
+@example
+@group
+(buffer-name)
+     @result{} "buffers.texi"
+@end group
+
+@group
+(setq foo (get-buffer "temp"))
+     @result{} #<buffer temp>
+@end group
+@group
+(kill-buffer foo)
+     @result{} nil
+@end group
+@group
+(buffer-name foo)
+     @result{} nil
+@end group
+@group
+foo
+     @result{} #<killed buffer>
+@end group
+@end example
+@end defun
+
+@deffn Command rename-buffer newname &optional unique
+This function renames the current buffer to @var{newname}.  An error
+is signaled if @var{newname} is not a string.
+
+@c Emacs 19 feature
+Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
+already in use.  However, if @var{unique} is non-@code{nil}, it modifies
+@var{newname} to make a name that is not in use.  Interactively, you can
+make @var{unique} non-@code{nil} with a numeric prefix argument.
+(This is how the command @code{rename-uniquely} is implemented.)
+
+This function returns the name actually given to the buffer.
+@end deffn
+
+@defun get-buffer buffer-or-name
+This function returns the buffer specified by @var{buffer-or-name}.
+If @var{buffer-or-name} is a string and there is no buffer with that
+name, the value is @code{nil}.  If @var{buffer-or-name} is a buffer, it
+is returned as given; that is not very useful, so the argument is usually
+a name.  For example:
+
+@example
+@group
+(setq b (get-buffer "lewis"))
+     @result{} #<buffer lewis>
+@end group
+@group
+(get-buffer b)
+     @result{} #<buffer lewis>
+@end group
+@group
+(get-buffer "Frazzle-nots")
+     @result{} nil
+@end group
+@end example
+
+See also the function @code{get-buffer-create} in @ref{Creating Buffers}.
+@end defun
+
+@c Emacs 19 feature
+@defun generate-new-buffer-name starting-name &optional ignore
+This function returns a name that would be unique for a new buffer---but
+does not create the buffer.  It starts with @var{starting-name}, and
+produces a name not currently in use for any buffer by appending a
+number inside of @samp{<@dots{}>}.  It starts at 2 and keeps
+incrementing the number until it is not the name of an existing buffer.
+
+If the optional second argument @var{ignore} is non-@code{nil}, it
+should be a string, a potential buffer name.  It means to consider
+that potential buffer acceptable, if it is tried, even it is the name
+of an existing buffer (which would normally be rejected).  Thus, if
+buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and
+@samp{foo<4>} exist,
+
+@example
+(generate-new-buffer-name "foo")
+     @result{} "foo<5>"
+(generate-new-buffer-name "foo" "foo<3>")
+     @result{} "foo<3>"
+(generate-new-buffer-name "foo" "foo<6>")
+     @result{} "foo<5>"
+@end example
+
+See the related function @code{generate-new-buffer} in @ref{Creating
+Buffers}.
+@end defun
+
+@node Buffer File Name
+@section Buffer File Name
+@cindex visited file
+@cindex buffer file name
+@cindex file name of buffer
+
+  The @dfn{buffer file name} is the name of the file that is visited in
+that buffer.  When a buffer is not visiting a file, its buffer file name
+is @code{nil}.  Most of the time, the buffer name is the same as the
+nondirectory part of the buffer file name, but the buffer file name and
+the buffer name are distinct and can be set independently.
+@xref{Visiting Files}.
+
+@defun buffer-file-name &optional buffer
+This function returns the absolute file name of the file that
+@var{buffer} is visiting.  If @var{buffer} is not visiting any file,
+@code{buffer-file-name} returns @code{nil}.  If @var{buffer} is not
+supplied, it defaults to the current buffer.
+
+@example
+@group
+(buffer-file-name (other-buffer))
+     @result{} "/usr/user/lewis/manual/files.texi"
+@end group
+@end example
+@end defun
+
+@defvar buffer-file-name
+This buffer-local variable contains the name of the file being visited
+in the current buffer, or @code{nil} if it is not visiting a file.  It
+is a permanent local variable, unaffected by
+@code{kill-all-local-variables}.
+
+@example
+@group
+buffer-file-name
+     @result{} "/usr/user/lewis/manual/buffers.texi"
+@end group
+@end example
+
+It is risky to change this variable's value without doing various other
+things.  Normally it is better to use @code{set-visited-file-name} (see
+below); some of the things done there, such as changing the buffer name,
+are not strictly necessary, but others are essential to avoid confusing
+Emacs.
+@end defvar
+
+@defvar buffer-file-truename
+This buffer-local variable holds the abbreviated truename of the file
+visited in the current buffer, or @code{nil} if no file is visited.
+It is a permanent local, unaffected by
+@code{kill-all-local-variables}.  @xref{Truenames}, and
+@ref{Definition of abbreviate-file-name}.
+@end defvar
+
+@defvar buffer-file-number
+This buffer-local variable holds the file number and directory device
+number of the file visited in the current buffer, or @code{nil} if no
+file or a nonexistent file is visited.  It is a permanent local,
+unaffected by @code{kill-all-local-variables}.
+
+The value is normally a list of the form @code{(@var{filenum}
+@var{devnum})}.  This pair of numbers uniquely identifies the file among
+all files accessible on the system.  See the function
+@code{file-attributes}, in @ref{File Attributes}, for more information
+about them.
+
+If @code{buffer-file-name} is the name of a symbolic link, then both
+numbers refer to the recursive target.
+@end defvar
+
+@defun get-file-buffer filename
+This function returns the buffer visiting file @var{filename}.  If
+there is no such buffer, it returns @code{nil}.  The argument
+@var{filename}, which must be a string, is expanded (@pxref{File Name
+Expansion}), then compared against the visited file names of all live
+buffers.  Note that the buffer's @code{buffer-file-name} must match
+the expansion of @var{filename} exactly.  This function will not
+recognize other names for the same file.
+
+@example
+@group
+(get-file-buffer "buffers.texi")
+    @result{} #<buffer buffers.texi>
+@end group
+@end example
+
+In unusual circumstances, there can be more than one buffer visiting
+the same file name.  In such cases, this function returns the first
+such buffer in the buffer list.
+@end defun
+
+@defun find-buffer-visiting filename &optional predicate
+This is like @code{get-file-buffer}, except that it can return any
+buffer visiting the file @emph{possibly under a different name}.  That
+is, the buffer's @code{buffer-file-name} does not need to match the
+expansion of @var{filename} exactly, it only needs to refer to the
+same file.  If @var{predicate} is non-@code{nil}, it should be a
+function of one argument, a buffer visiting @var{filename}.  The
+buffer is only considered a suitable return value if @var{predicate}
+returns non-@code{nil}.  If it can not find a suitable buffer to
+return, @code{find-buffer-visiting} returns @code{nil}.
+@end defun
+
+@deffn Command set-visited-file-name filename &optional no-query along-with-file
+If @var{filename} is a non-empty string, this function changes the
+name of the file visited in the current buffer to @var{filename}.  (If the
+buffer had no visited file, this gives it one.)  The @emph{next time}
+the buffer is saved it will go in the newly-specified file.
+
+This command marks the buffer as modified, since it does not (as far
+as Emacs knows) match the contents of @var{filename}, even if it
+matched the former visited file.  It also renames the buffer to
+correspond to the new file name, unless the new name is already in
+use.
+
+If @var{filename} is @code{nil} or the empty string, that stands for
+``no visited file.''  In this case, @code{set-visited-file-name} marks
+the buffer as having no visited file, without changing the buffer's
+modified flag.
+
+Normally, this function asks the user for confirmation if there
+already is a buffer visiting @var{filename}.  If @var{no-query} is
+non-@code{nil}, that prevents asking this question.  If there already
+is a buffer visiting @var{filename}, and the user confirms or
+@var{query} is non-@code{nil}, this function makes the new buffer name
+unique by appending a number inside of @samp{<@dots{}>} to @var{filename}.
+
+If @var{along-with-file} is non-@code{nil}, that means to assume that
+the former visited file has been renamed to @var{filename}.  In this
+case, the command does not change the buffer's modified flag, nor the
+buffer's recorded last file modification time as reported by
+@code{visited-file-modtime} (@pxref{Modification Time}).  If
+@var{along-with-file} is @code{nil}, this function clears the recorded
+last file modification time, after which @code{visited-file-modtime}
+returns zero.
+
+@c Wordy to avoid overfull hbox.  --rjc 16mar92
+When the function @code{set-visited-file-name} is called interactively, it
+prompts for @var{filename} in the minibuffer.
+@end deffn
+
+@defvar list-buffers-directory
+This buffer-local variable specifies a string to display in a buffer
+listing where the visited file name would go, for buffers that don't
+have a visited file name.  Dired buffers use this variable.
+@end defvar
+
+@node Buffer Modification
+@section Buffer Modification
+@cindex buffer modification
+@cindex modification flag (of buffer)
+
+  Emacs keeps a flag called the @dfn{modified flag} for each buffer, to
+record whether you have changed the text of the buffer.  This flag is
+set to @code{t} whenever you alter the contents of the buffer, and
+cleared to @code{nil} when you save it.  Thus, the flag shows whether
+there are unsaved changes.  The flag value is normally shown in the mode
+line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving
+Buffers}) and auto-saving (@pxref{Auto-Saving}).
+
+  Some Lisp programs set the flag explicitly.  For example, the function
+@code{set-visited-file-name} sets the flag to @code{t}, because the text
+does not match the newly-visited file, even if it is unchanged from the
+file formerly visited.
+
+  The functions that modify the contents of buffers are described in
+@ref{Text}.
+
+@defun buffer-modified-p &optional buffer
+This function returns @code{t} if the buffer @var{buffer} has been modified
+since it was last read in from a file or saved, or @code{nil}
+otherwise.  If @var{buffer} is not supplied, the current buffer
+is tested.
+@end defun
+
+@defun set-buffer-modified-p flag
+This function marks the current buffer as modified if @var{flag} is
+non-@code{nil}, or as unmodified if the flag is @code{nil}.
+
+Another effect of calling this function is to cause unconditional
+redisplay of the mode line for the current buffer.  In fact, the
+function @code{force-mode-line-update} works by doing this:
+
+@example
+@group
+(set-buffer-modified-p (buffer-modified-p))
+@end group
+@end example
+@end defun
+
+@defun restore-buffer-modified-p flag
+Like @code{set-buffer-modified-p}, but does not force redisplay
+of mode lines.
+@end defun
+
+@deffn Command not-modified &optional arg
+This command marks the current buffer as unmodified, and not needing
+to be saved.  If @var{arg} is non-@code{nil}, it marks the buffer as
+modified, so that it will be saved at the next suitable occasion.
+Interactively, @var{arg} is the prefix argument.
+
+Don't use this function in programs, since it prints a message in the
+echo area; use @code{set-buffer-modified-p} (above) instead.
+@end deffn
+
+@defun buffer-modified-tick &optional buffer
+This function returns @var{buffer}'s modification-count.  This is a
+counter that increments every time the buffer is modified.  If
+@var{buffer} is @code{nil} (or omitted), the current buffer is used.
+The counter can wrap around occasionally.
+@end defun
+
+@defun buffer-chars-modified-tick &optional buffer
+This function returns @var{buffer}'s character-change modification-count.
+Changes to text properties leave this counter unchanged; however, each
+time text is inserted or removed from the buffer, the counter is reset
+to the value that would be returned @code{buffer-modified-tick}.
+By comparing the values returned by two @code{buffer-chars-modified-tick}
+calls, you can tell whether a character change occurred in that buffer
+in between the calls.  If @var{buffer} is @code{nil} (or omitted), the
+current buffer is used.
+@end defun
+
+@node Modification Time
+@comment  node-name,  next,  previous,  up
+@section Buffer Modification Time
+@cindex comparing file modification time
+@cindex modification time of buffer
+
+  Suppose that you visit a file and make changes in its buffer, and
+meanwhile the file itself is changed on disk.  At this point, saving the
+buffer would overwrite the changes in the file.  Occasionally this may
+be what you want, but usually it would lose valuable information.  Emacs
+therefore checks the file's modification time using the functions
+described below before saving the file.  (@xref{File Attributes},
+for how to examine a file's modification time.)
+
+@defun verify-visited-file-modtime buffer
+This function compares what @var{buffer} has recorded for the
+modification time of its visited file against the actual modification
+time of the file as recorded by the operating system.  The two should be
+the same unless some other process has written the file since Emacs
+visited or saved it.
+
+The function returns @code{t} if the last actual modification time and
+Emacs's recorded modification time are the same, @code{nil} otherwise.
+It also returns @code{t} if the buffer has no recorded last
+modification time, that is if @code{visited-file-modtime} would return
+zero.
+
+It always returns @code{t} for buffers that are not visiting a file,
+even if @code{visited-file-modtime} returns a non-zero value.  For
+instance, it always returns @code{t} for dired buffers.  It returns
+@code{t} for buffers that are visiting a file that does not exist and
+never existed, but @code{nil} for file-visiting buffers whose file has
+been deleted.
+@end defun
+
+@defun clear-visited-file-modtime
+This function clears out the record of the last modification time of
+the file being visited by the current buffer.  As a result, the next
+attempt to save this buffer will not complain of a discrepancy in
+file modification times.
+
+This function is called in @code{set-visited-file-name} and other
+exceptional places where the usual test to avoid overwriting a changed
+file should not be done.
+@end defun
+
+@c Emacs 19 feature
+@defun visited-file-modtime
+This function returns the current buffer's recorded last file
+modification time, as a list of the form @code{(@var{high} @var{low})}.
+(This is the same format that @code{file-attributes} uses to return
+time values; see @ref{File Attributes}.)
+
+If the buffer has no recorded last modification time, this function
+returns zero.  This case occurs, for instance, if the buffer is not
+visiting a file or if the time has been explicitly cleared by
+@code{clear-visited-file-modtime}.  Note, however, that
+@code{visited-file-modtime} returns a list for some non-file buffers
+too.  For instance, in a Dired buffer listing a directory, it returns
+the last modification time of that directory, as recorded by Dired.
+
+For a new buffer visiting a not yet existing file, @var{high} is
+@minus{}1 and @var{low} is 65535, that is,
+@ifnottex
+@w{2**16 - 1.}
+@end ifnottex
+@tex
+@math{2^{16}-1}.
+@end tex
+@end defun
+
+@c Emacs 19 feature
+@defun set-visited-file-modtime &optional time
+This function updates the buffer's record of the last modification time
+of the visited file, to the value specified by @var{time} if @var{time}
+is not @code{nil}, and otherwise to the last modification time of the
+visited file.
+
+If @var{time} is neither @code{nil} nor zero, it should have the form
+@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
+either case containing two integers, each of which holds 16 bits of the
+time.
+
+This function is useful if the buffer was not read from the file
+normally, or if the file itself has been changed for some known benign
+reason.
+@end defun
+
+@defun ask-user-about-supersession-threat filename
+This function is used to ask a user how to proceed after an attempt to
+modify an buffer visiting file @var{filename} when the file is newer
+than the buffer text.  Emacs detects this because the modification
+time of the file on disk is newer than the last save-time of the
+buffer.  This means some other program has probably altered the file.
+
+@kindex file-supersession
+Depending on the user's answer, the function may return normally, in
+which case the modification of the buffer proceeds, or it may signal a
+@code{file-supersession} error with data @code{(@var{filename})}, in which
+case the proposed buffer modification is not allowed.
+
+This function is called automatically by Emacs on the proper
+occasions.  It exists so you can customize Emacs by redefining it.
+See the file @file{userlock.el} for the standard definition.
+
+See also the file locking mechanism in @ref{File Locks}.
+@end defun
+
+@node Read Only Buffers
+@section Read-Only Buffers
+@cindex read-only buffer
+@cindex buffer, read-only
+
+  If a buffer is @dfn{read-only}, then you cannot change its contents,
+although you may change your view of the contents by scrolling and
+narrowing.
+
+  Read-only buffers are used in two kinds of situations:
+
+@itemize @bullet
+@item
+A buffer visiting a write-protected file is normally read-only.
+
+Here, the purpose is to inform the user that editing the buffer with the
+aim of saving it in the file may be futile or undesirable.  The user who
+wants to change the buffer text despite this can do so after clearing
+the read-only flag with @kbd{C-x C-q}.
+
+@item
+Modes such as Dired and Rmail make buffers read-only when altering the
+contents with the usual editing commands would probably be a mistake.
+
+The special commands of these modes bind @code{buffer-read-only} to
+@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to
+@code{t} around the places where they themselves change the text.
+@end itemize
+
+@defvar buffer-read-only
+This buffer-local variable specifies whether the buffer is read-only.
+The buffer is read-only if this variable is non-@code{nil}.
+@end defvar
+
+@defvar inhibit-read-only
+If this variable is non-@code{nil}, then read-only buffers and,
+depending on the actual value, some or all read-only characters may be
+modified.  Read-only characters in a buffer are those that have
+non-@code{nil} @code{read-only} properties (either text properties or
+overlay properties).  @xref{Special Properties}, for more information
+about text properties.  @xref{Overlays}, for more information about
+overlays and their properties.
+
+If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
+properties have no effect.  If @code{inhibit-read-only} is a list, then
+@code{read-only} character properties have no effect if they are members
+of the list (comparison is done with @code{eq}).
+@end defvar
+
+@deffn Command toggle-read-only &optional arg
+This command toggles whether the current buffer is read-only.  It is
+intended for interactive use; do not use it in programs.  At any given
+point in a program, you should know whether you want the read-only flag
+on or off; so you can set @code{buffer-read-only} explicitly to the
+proper value, @code{t} or @code{nil}.
+
+If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
+@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
+the numeric value of that prefix argument is positive and to
+@code{nil} otherwise.  @xref{Prefix Command Arguments}.
+@end deffn
+
+@defun barf-if-buffer-read-only
+This function signals a @code{buffer-read-only} error if the current
+buffer is read-only.  @xref{Using Interactive}, for another way to
+signal an error if the current buffer is read-only.
+@end defun
+
+@node The Buffer List
+@section The Buffer List
+@cindex buffer list
+
+  The @dfn{buffer list} is a list of all live buffers.  The order of
+the buffers in the list is based primarily on how recently each buffer
+has been displayed in a window.  Several functions, notably
+@code{other-buffer}, use this ordering.  A buffer list displayed for
+the user also follows this order.
+
+  Creating a buffer adds it to the end of the buffer list, and killing
+a buffer removes it.  Buffers move to the front of the list when they
+are selected for display in a window (@pxref{Displaying Buffers}), and
+to the end when they are buried (see @code{bury-buffer}, below).
+There are no functions available to the Lisp programmer which directly
+manipulate the buffer list.
+  
+  In addition to the fundamental Emacs buffer list, each frame has its
+own version of the buffer list, in which the buffers that have been
+selected in that frame come first, starting with the buffers most
+recently selected @emph{in that frame}.  (This order is recorded in
+@var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer
+Parameters}.)  The buffers that were never selected in @var{frame} come
+afterward, ordered according to the fundamental Emacs buffer list.
+
+@defun buffer-list &optional frame
+This function returns the buffer list, including all buffers, even those
+whose names begin with a space.  The elements are actual buffers, not
+their names.
+
+If @var{frame} is a frame, this returns @var{frame}'s buffer list.  If
+@var{frame} is @code{nil}, the fundamental Emacs buffer list is used:
+all the buffers appear in order of most recent selection, regardless of
+which frames they were selected in.
+
+@example
+@group
+(buffer-list)
+     @result{} (#<buffer buffers.texi>
+         #<buffer  *Minibuf-1*> #<buffer buffer.c>
+         #<buffer *Help*> #<buffer TAGS>)
+@end group
+
+@group
+;; @r{Note that the name of the minibuffer}
+;;   @r{begins with a space!}
+(mapcar (function buffer-name) (buffer-list))
+    @result{} ("buffers.texi" " *Minibuf-1*"
+        "buffer.c" "*Help*" "TAGS")
+@end group
+@end example
+@end defun
+
+  The list that @code{buffer-list} returns is constructed specifically
+by @code{buffer-list}; it is not an internal Emacs data structure, and
+modifying it has no effect on the order of buffers.  If you want to
+change the order of buffers in the frame-independent buffer list, here
+is an easy way:
+
+@example
+(defun reorder-buffer-list (new-list)
+  (while new-list
+    (bury-buffer (car new-list))
+    (setq new-list (cdr new-list))))
+@end example
+
+  With this method, you can specify any order for the list, but there is
+no danger of losing a buffer or adding something that is not a valid
+live buffer.
+
+  To change the order or value of a frame's buffer list, set the frame's
+@code{buffer-list} frame parameter with @code{modify-frame-parameters}
+(@pxref{Parameter Access}).
+
+@defun other-buffer &optional buffer visible-ok frame
+This function returns the first buffer in the buffer list other than
+@var{buffer}.  Usually this is the buffer selected most recently (in
+frame @var{frame} or else the currently selected frame, @pxref{Input
+Focus}), aside from @var{buffer}.  Buffers whose names start with a
+space are not considered at all.
+
+If @var{buffer} is not supplied (or if it is not a buffer), then
+@code{other-buffer} returns the first buffer in the selected frame's
+buffer list that is not now visible in any window in a visible frame.
+
+If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter,
+then @code{other-buffer} uses that predicate to decide which buffers to
+consider.  It calls the predicate once for each buffer, and if the value
+is @code{nil}, that buffer is ignored.  @xref{Buffer Parameters}.
+
+@c Emacs 19 feature
+If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
+a buffer visible in any window on any visible frame, except as a last
+resort.   If @var{visible-ok} is non-@code{nil}, then it does not matter
+whether a buffer is displayed somewhere or not.
+
+If no suitable buffer exists, the buffer @samp{*scratch*} is returned
+(and created, if necessary).
+@end defun
+
+@deffn Command bury-buffer &optional buffer-or-name
+This function puts @var{buffer-or-name} at the end of the buffer list,
+without changing the order of any of the other buffers on the list.
+This buffer therefore becomes the least desirable candidate for
+@code{other-buffer} to return.  The argument can be either a buffer
+itself or the name of one.
+
+@code{bury-buffer} operates on each frame's @code{buffer-list} parameter
+as well as the frame-independent Emacs buffer list; therefore, the
+buffer that you bury will come last in the value of @code{(buffer-list
+@var{frame})} and in the value of @code{(buffer-list nil)}.
+
+If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
+current buffer.  In addition, if the buffer is displayed in the selected
+window, this switches to some other buffer (obtained using
+@code{other-buffer}) in the selected window.  But if the buffer is
+displayed in some other window, it remains displayed there.
+
+To replace a buffer in all the windows that display it, use
+@code{replace-buffer-in-windows}.  @xref{Buffers and Windows}.
+@end deffn
+
+@node Creating Buffers
+@section Creating Buffers
+@cindex creating buffers
+@cindex buffers, creating
+
+  This section describes the two primitives for creating buffers.
+@code{get-buffer-create} creates a buffer if it finds no existing buffer
+with the specified name; @code{generate-new-buffer} always creates a new
+buffer and gives it a unique name.
+
+  Other functions you can use to create buffers include
+@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and
+@code{create-file-buffer} (@pxref{Visiting Files}).  Starting a
+subprocess can also create a buffer (@pxref{Processes}).
+
+@defun get-buffer-create name
+This function returns a buffer named @var{name}.  It returns a live
+buffer with that name, if one exists; otherwise, it creates a new
+buffer.  The buffer does not become the current buffer---this function
+does not change which buffer is current.
+
+If @var{name} is a buffer instead of a string, it is returned, even if
+it is dead.  An error is signaled if @var{name} is neither a string
+nor a buffer.
+
+@example
+@group
+(get-buffer-create "foo")
+     @result{} #<buffer foo>
+@end group
+@end example
+
+The major mode for a newly created buffer is set to Fundamental mode.
+(The variable @code{default-major-mode} is handled at a higher level;
+see @ref{Auto Major Mode}.)  If the name begins with a space, the
+buffer initially disables undo information recording (@pxref{Undo}).
+@end defun
+
+@defun generate-new-buffer name
+This function returns a newly created, empty buffer, but does not make
+it current.  If there is no buffer named @var{name}, then that is the
+name of the new buffer.  If that name is in use, this function adds
+suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
+integer.  It tries successive integers starting with 2 until it finds an
+available name.
+
+An error is signaled if @var{name} is not a string.
+
+@example
+@group
+(generate-new-buffer "bar")
+     @result{} #<buffer bar>
+@end group
+@group
+(generate-new-buffer "bar")
+     @result{} #<buffer bar<2>>
+@end group
+@group
+(generate-new-buffer "bar")
+     @result{} #<buffer bar<3>>
+@end group
+@end example
+
+The major mode for the new buffer is set to Fundamental mode.  The
+variable @code{default-major-mode} is handled at a higher level.
+@xref{Auto Major Mode}.
+
+See the related function @code{generate-new-buffer-name} in @ref{Buffer
+Names}.
+@end defun
+
+@node Killing Buffers
+@section Killing Buffers
+@cindex killing buffers
+@cindex buffers, killing
+
+  @dfn{Killing a buffer} makes its name unknown to Emacs and makes the
+memory space it occupied available for other use.
+
+  The buffer object for the buffer that has been killed remains in
+existence as long as anything refers to it, but it is specially marked
+so that you cannot make it current or display it.  Killed buffers retain
+their identity, however; if you kill two distinct buffers, they remain
+distinct according to @code{eq} although both are dead.
+
+  If you kill a buffer that is current or displayed in a window, Emacs
+automatically selects or displays some other buffer instead.  This means
+that killing a buffer can in general change the current buffer.
+Therefore, when you kill a buffer, you should also take the precautions
+associated with changing the current buffer (unless you happen to know
+that the buffer being killed isn't current).  @xref{Current Buffer}.
+
+  If you kill a buffer that is the base buffer of one or more indirect
+buffers, the indirect buffers are automatically killed as well.
+
+  The @code{buffer-name} of a killed buffer is @code{nil}.  You can use
+this feature to test whether a buffer has been killed:
+
+@example
+@group
+(defun buffer-killed-p (buffer)
+  "Return t if BUFFER is killed."
+  (not (buffer-name buffer)))
+@end group
+@end example
+
+@deffn Command kill-buffer buffer-or-name
+This function kills the buffer @var{buffer-or-name}, freeing all its
+memory for other uses or to be returned to the operating system.  If
+@var{buffer-or-name} is @code{nil}, it kills the current buffer.
+
+Any processes that have this buffer as the @code{process-buffer} are
+sent the @code{SIGHUP} signal, which normally causes them to terminate.
+(The basic meaning of @code{SIGHUP} is that a dialup line has been
+disconnected.)  @xref{Signals to Processes}.
+
+If the buffer is visiting a file and contains unsaved changes,
+@code{kill-buffer} asks the user to confirm before the buffer is killed.
+It does this even if not called interactively.  To prevent the request
+for confirmation, clear the modified flag before calling
+@code{kill-buffer}.  @xref{Buffer Modification}.
+
+Killing a buffer that is already dead has no effect.
+
+This function returns @code{t} if it actually killed the buffer.  It
+returns @code{nil} if the user refuses to confirm or if
+@var{buffer-or-name} was already dead.
+
+@smallexample
+(kill-buffer "foo.unchanged")
+     @result{} t
+(kill-buffer "foo.changed")
+
+---------- Buffer: Minibuffer ----------
+Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
+---------- Buffer: Minibuffer ----------
+
+     @result{} t
+@end smallexample
+@end deffn
+
+@defvar kill-buffer-query-functions
+After confirming unsaved changes, @code{kill-buffer} calls the functions
+in the list @code{kill-buffer-query-functions}, in order of appearance,
+with no arguments.  The buffer being killed is the current buffer when
+they are called.  The idea of this feature is that these functions will
+ask for confirmation from the user.  If any of them returns @code{nil},
+@code{kill-buffer} spares the buffer's life.
+@end defvar
+
+@defvar kill-buffer-hook
+This is a normal hook run by @code{kill-buffer} after asking all the
+questions it is going to ask, just before actually killing the buffer.
+The buffer to be killed is current when the hook functions run.
+@xref{Hooks}.  This variable is a permanent local, so its local binding
+is not cleared by changing major modes.
+@end defvar
+
+@defvar buffer-offer-save
+This variable, if non-@code{nil} in a particular buffer, tells
+@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the
+second optional argument to that function is @code{t}) to offer to
+save that buffer, just as they offer to save file-visiting buffers.
+@xref{Definition of save-some-buffers}.  The variable
+@code{buffer-offer-save} automatically becomes buffer-local when set
+for any reason.  @xref{Buffer-Local Variables}.
+@end defvar
+
+@defvar buffer-save-without-query
+This variable, if non-@code{nil} in a particular buffer, tells
+@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save
+this buffer (if it's modified) without asking the user.  The variable
+automatically becomes buffer-local when set for any reason.
+@end defvar
+
+@defun buffer-live-p object
+This function returns @code{t} if @var{object} is a buffer which has
+not been killed, @code{nil} otherwise.
+@end defun
+
+@node Indirect Buffers
+@section Indirect Buffers
+@cindex indirect buffers
+@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 among files.  The base
+buffer may not itself be an indirect buffer.
+
+  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.  This includes the text properties as well as the characters
+themselves.
+
+  In all other respects, the indirect buffer and its base buffer are
+completely separate.  They have different names, independent values of
+point, independent narrowing, independent markers and overlays (though
+inserting or deleting text in either buffer relocates the markers and
+overlays for both), independent major modes, and independent
+buffer-local variable bindings.
+
+  An indirect buffer cannot visit a file, but its base buffer can.  If
+you try to save the indirect buffer, that actually saves the base
+buffer.
+
+  Killing an indirect buffer has no effect on its base buffer.  Killing
+the base buffer effectively kills the indirect buffer in that it cannot
+ever again be the current buffer.
+
+@deffn Command make-indirect-buffer base-buffer name &optional clone
+This creates and returns an indirect buffer named @var{name} whose
+base buffer is @var{base-buffer}.  The argument @var{base-buffer} may
+be a live buffer or the name (a string) of an existing buffer.  If
+@var{name} is the name of an existing buffer, an error is signaled.
+
+If @var{clone} is non-@code{nil}, then the indirect buffer originally
+shares the ``state'' of @var{base-buffer} such as major mode, minor
+modes, buffer local variables and so on.  If @var{clone} is omitted
+or @code{nil} the indirect buffer's state is set to the default state
+for new buffers.
+
+If @var{base-buffer} is an indirect buffer, its base buffer is used as
+the base for the new buffer.  If, in addition, @var{clone} is
+non-@code{nil}, the initial state is copied from the actual base
+buffer, not from @var{base-buffer}.
+@end deffn
+
+@defun clone-indirect-buffer newname display-flag &optional norecord
+This function creates and returns a new indirect buffer that shares
+the current buffer's base buffer and copies the rest of the current
+buffer's attributes.  (If the current buffer is not indirect, it is
+used as the base buffer.)
+
+If @var{display-flag} is non-@code{nil}, that means to display the new
+buffer by calling @code{pop-to-buffer}.  If @var{norecord} is
+non-@code{nil}, that means not to put the new buffer to the front of
+the buffer list.
+@end defun
+
+@defun buffer-base-buffer &optional buffer
+This function returns the base buffer of @var{buffer}, which defaults
+to the current buffer.  If @var{buffer} is not indirect, the value is
+@code{nil}.  Otherwise, the value is another buffer, which is never an
+indirect buffer.
+@end defun
+
+@node Buffer Gap
+@section The Buffer Gap
+
+  Emacs buffers are implemented using an invisible @dfn{gap} to make
+insertion and deletion faster.  Insertion works by filling in part of
+the gap, and deletion adds to the gap.  Of course, this means that the
+gap must first be moved to the locus of the insertion or deletion.
+Emacs moves the gap only when you try to insert or delete.  This is why
+your first editing command in one part of a large buffer, after
+previously editing in another far-away part, sometimes involves a
+noticeable delay.
+
+  This mechanism works invisibly, and Lisp code should never be affected
+by the gap's current location, but these functions are available for
+getting information about the gap status.
+
+@defun gap-position
+This function returns the current gap position in the current buffer.
+@end defun
+
+@defun gap-size
+This function returns the current gap size of the current buffer.
+@end defun
+
+@ignore
+   arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c
+@end ignore
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
new file mode 100644
index 00000000000..fabe38f9428
--- /dev/null
+++ b/doc/lispref/commands.texi
@@ -0,0 +1,3290 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/commands
+@node Command Loop, Keymaps, Minibuffers, Top
+@chapter Command Loop
+@cindex editor command loop
+@cindex command loop
+
+  When you run Emacs, it enters the @dfn{editor command loop} almost
+immediately.  This loop reads key sequences, executes their definitions,
+and displays the results.  In this chapter, we describe how these things
+are done, and the subroutines that allow Lisp programs to do them.
+
+@menu
+* Command Overview::    How the command loop reads commands.
+* Defining Commands::   Specifying how a function should read arguments.
+* Interactive Call::    Calling a command, so that it will read arguments.
+* Command Loop Info::   Variables set by the command loop for you to examine.
+* Adjusting Point::     Adjustment of point after a command.
+* Input Events::	What input looks like when you read it.
+* Reading Input::       How to read input events from the keyboard or mouse.
+* Special Events::      Events processed immediately and individually.
+* Waiting::             Waiting for user input or elapsed time.
+* Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
+* Prefix Command Arguments::    How the commands to set prefix args work.
+* Recursive Editing::   Entering a recursive edit,
+                          and why you usually shouldn't.
+* Disabling Commands::  How the command loop handles disabled commands.
+* Command History::     How the command history is set up, and how accessed.
+* Keyboard Macros::     How keyboard macros are implemented.
+@end menu
+
+@node Command Overview
+@section Command Loop Overview
+
+  The first thing the command loop must do is read a key sequence, which
+is a sequence of events that translates into a command.  It does this by
+calling the function @code{read-key-sequence}.  Your Lisp code can also
+call this function (@pxref{Key Sequence Input}).  Lisp programs can also
+do input at a lower level with @code{read-event} (@pxref{Reading One
+Event}) or discard pending input with @code{discard-input}
+(@pxref{Event Input Misc}).
+
+  The key sequence is translated into a command through the currently
+active keymaps.  @xref{Key Lookup}, for information on how this is done.
+The result should be a keyboard macro or an interactively callable
+function.  If the key is @kbd{M-x}, then it reads the name of another
+command, which it then calls.  This is done by the command
+@code{execute-extended-command} (@pxref{Interactive Call}).
+
+  To execute a command requires first reading the arguments for it.
+This is done by calling @code{command-execute} (@pxref{Interactive
+Call}).  For commands written in Lisp, the @code{interactive}
+specification says how to read the arguments.  This may use the prefix
+argument (@pxref{Prefix Command Arguments}) or may read with prompting
+in the minibuffer (@pxref{Minibuffers}).  For example, the command
+@code{find-file} has an @code{interactive} specification which says to
+read a file name using the minibuffer.  The command's function body does
+not use the minibuffer; if you call this command from Lisp code as a
+function, you must supply the file name string as an ordinary Lisp
+function argument.
+
+  If the command is a string or vector (i.e., a keyboard macro) then
+@code{execute-kbd-macro} is used to execute it.  You can call this
+function yourself (@pxref{Keyboard Macros}).
+
+  To terminate the execution of a running command, type @kbd{C-g}.  This
+character causes @dfn{quitting} (@pxref{Quitting}).
+
+@defvar pre-command-hook
+The editor command loop runs this normal hook before each command.  At
+that time, @code{this-command} contains the command that is about to
+run, and @code{last-command} describes the previous command.
+@xref{Command Loop Info}.
+@end defvar
+
+@defvar post-command-hook
+The editor command loop runs this normal hook after each command
+(including commands terminated prematurely by quitting or by errors),
+and also when the command loop is first entered.  At that time,
+@code{this-command} refers to the command that just ran, and
+@code{last-command} refers to the command before that.
+@end defvar
+
+  Quitting is suppressed while running @code{pre-command-hook} and
+@code{post-command-hook}.  If an error happens while executing one of
+these hooks, it terminates execution of the hook, and clears the hook
+variable to @code{nil} so as to prevent an infinite loop of errors.
+
+  A request coming into the Emacs server (@pxref{Emacs Server,,,
+emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
+command does.
+
+@node Defining Commands
+@section Defining Commands
+@cindex defining commands
+@cindex commands, defining
+@cindex functions, making them interactive
+@cindex interactive function
+
+  A Lisp function becomes a command when its body contains, at top
+level, a form that calls the special form @code{interactive}.  This
+form does nothing when actually executed, but its presence serves as a
+flag to indicate that interactive calling is permitted.  Its argument
+controls the reading of arguments for an interactive call.
+
+@menu
+* Using Interactive::     General rules for @code{interactive}.
+* Interactive Codes::     The standard letter-codes for reading arguments
+                             in various ways.
+* Interactive Examples::  Examples of how to read interactive arguments.
+@end menu
+
+@node Using Interactive
+@subsection Using @code{interactive}
+@cindex arguments, interactive entry
+
+  This section describes how to write the @code{interactive} form that
+makes a Lisp function an interactively-callable command, and how to
+examine a command's @code{interactive} form.
+
+@defspec interactive arg-descriptor
+This special form declares that the function in which it appears is a
+command, and that it may therefore be called interactively (via
+@kbd{M-x} or by entering a key sequence bound to it).  The argument
+@var{arg-descriptor} declares how to compute the arguments to the
+command when the command is called interactively.
+
+A command may be called from Lisp programs like any other function, but
+then the caller supplies the arguments and @var{arg-descriptor} has no
+effect.
+
+The @code{interactive} form has its effect because the command loop
+(actually, its subroutine @code{call-interactively}) scans through the
+function definition looking for it, before calling the function.  Once
+the function is called, all its body forms including the
+@code{interactive} form are executed, but at this time
+@code{interactive} simply returns @code{nil} without even evaluating its
+argument.
+@end defspec
+
+There are three possibilities for the argument @var{arg-descriptor}:
+
+@itemize @bullet
+@item
+It may be omitted or @code{nil}; then the command is called with no
+arguments.  This leads quickly to an error if the command requires one
+or more arguments.
+
+@item
+It may be a string; then its contents should consist of a code character
+followed by a prompt (which some code characters use and some ignore).
+The prompt ends either with the end of the string or with a newline.
+Here is a simple example:
+
+@smallexample
+(interactive "bFrobnicate buffer: ")
+@end smallexample
+
+@noindent
+The code letter @samp{b} says to read the name of an existing buffer,
+with completion.  The buffer name is the sole argument passed to the
+command.  The rest of the string is a prompt.
+
+If there is a newline character in the string, it terminates the prompt.
+If the string does not end there, then the rest of the string should
+contain another code character and prompt, specifying another argument.
+You can specify any number of arguments in this way.
+
+@c Emacs 19 feature
+The prompt string can use @samp{%} to include previous argument values
+(starting with the first argument) in the prompt.  This is done using
+@code{format} (@pxref{Formatting Strings}).  For example, here is how
+you could read the name of an existing buffer followed by a new name to
+give to that buffer:
+
+@smallexample
+@group
+(interactive "bBuffer to rename: \nsRename buffer %s to: ")
+@end group
+@end smallexample
+
+@cindex @samp{*} in @code{interactive}
+@cindex read-only buffers in interactive
+If the first character in the string is @samp{*}, then an error is
+signaled if the buffer is read-only.
+
+@cindex @samp{@@} in @code{interactive}
+@c Emacs 19 feature
+If the first character in the string is @samp{@@}, and if the key
+sequence used to invoke the command includes any mouse events, then
+the window associated with the first of those events is selected
+before the command is run.
+
+You can use @samp{*} and @samp{@@} together; the order does not matter.
+Actual reading of arguments is controlled by the rest of the prompt
+string (starting with the first character that is not @samp{*} or
+@samp{@@}).
+
+@item
+It may be a Lisp expression that is not a string; then it should be a
+form that is evaluated to get a list of arguments to pass to the
+command.  Usually this form will call various functions to read input
+from the user, most often through the minibuffer (@pxref{Minibuffers})
+or directly from the keyboard (@pxref{Reading Input}).
+
+Providing point or the mark as an argument value is also common, but
+if you do this @emph{and} read input (whether using the minibuffer or
+not), be sure to get the integer values of point or the mark after
+reading.  The current buffer may be receiving subprocess output; if
+subprocess output arrives while the command is waiting for input, it
+could relocate point and the mark.
+
+Here's an example of what @emph{not} to do:
+
+@smallexample
+(interactive
+ (list (region-beginning) (region-end)
+       (read-string "Foo: " nil 'my-history)))
+@end smallexample
+
+@noindent
+Here's how to avoid the problem, by examining point and the mark after
+reading the keyboard input:
+
+@smallexample
+(interactive
+ (let ((string (read-string "Foo: " nil 'my-history)))
+   (list (region-beginning) (region-end) string)))
+@end smallexample
+
+@strong{Warning:} the argument values should not include any data
+types that can't be printed and then read.  Some facilities save
+@code{command-history} in a file to be read in the subsequent
+sessions; if a command's arguments contain a data type that prints
+using @samp{#<@dots{}>} syntax, those facilities won't work.
+
+There are, however, a few exceptions: it is ok to use a limited set of
+expressions such as @code{(point)}, @code{(mark)},
+@code{(region-beginning)}, and @code{(region-end)}, because Emacs
+recognizes them specially and puts the expression (rather than its
+value) into the command history.  To see whether the expression you
+wrote is one of these exceptions, run the command, then examine
+@code{(car command-history)}.
+@end itemize
+
+@cindex examining the @code{interactive} form
+@defun interactive-form function
+This function returns the @code{interactive} form of @var{function}.
+If @var{function} is an interactively callable function
+(@pxref{Interactive Call}), the value is the command's
+@code{interactive} form @code{(interactive @var{spec})}, which
+specifies how to compute its arguments.  Otherwise, the value is
+@code{nil}.  If @var{function} is a symbol, its function definition is
+used.
+@end defun
+
+@node Interactive Codes
+@comment  node-name,  next,  previous,  up
+@subsection Code Characters for @code{interactive}
+@cindex interactive code description
+@cindex description for interactive codes
+@cindex codes, interactive, description of
+@cindex characters for interactive codes
+
+  The code character descriptions below contain a number of key words,
+defined here as follows:
+
+@table @b
+@item Completion
+@cindex interactive completion
+Provide completion.  @key{TAB}, @key{SPC}, and @key{RET} perform name
+completion because the argument is read using @code{completing-read}
+(@pxref{Completion}).  @kbd{?} displays a list of possible completions.
+
+@item Existing
+Require the name of an existing object.  An invalid name is not
+accepted; the commands to exit the minibuffer do not exit if the current
+input is not valid.
+
+@item Default
+@cindex default argument string
+A default value of some sort is used if the user enters no text in the
+minibuffer.  The default depends on the code character.
+
+@item No I/O
+This code letter computes an argument without reading any input.
+Therefore, it does not use a prompt string, and any prompt string you
+supply is ignored.
+
+Even though the code letter doesn't use a prompt string, you must follow
+it with a newline if it is not the last code character in the string.
+
+@item Prompt
+A prompt immediately follows the code character.  The prompt ends either
+with the end of the string or with a newline.
+
+@item Special
+This code character is meaningful only at the beginning of the
+interactive string, and it does not look for a prompt or a newline.
+It is a single, isolated character.
+@end table
+
+@cindex reading interactive arguments
+  Here are the code character descriptions for use with @code{interactive}:
+
+@table @samp
+@item *
+Signal an error if the current buffer is read-only.  Special.
+
+@item @@
+Select the window mentioned in the first mouse event in the key
+sequence that invoked this command.  Special.
+
+@item a
+A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
+Completion, Prompt.
+
+@item b
+The name of an existing buffer.  By default, uses the name of the
+current buffer (@pxref{Buffers}).  Existing, Completion, Default,
+Prompt.
+
+@item B
+A buffer name.  The buffer need not exist.  By default, uses the name of
+a recently used buffer other than the current buffer.  Completion,
+Default, Prompt.
+
+@item c
+A character.  The cursor does not move into the echo area.  Prompt.
+
+@item C
+A command name (i.e., a symbol satisfying @code{commandp}).  Existing,
+Completion, Prompt.
+
+@item d
+@cindex position argument
+The position of point, as an integer (@pxref{Point}).  No I/O.
+
+@item D
+A directory name.  The default is the current default directory of the
+current buffer, @code{default-directory} (@pxref{File Name Expansion}).
+Existing, Completion, Default, Prompt.
+
+@item e
+The first or next mouse event in the key sequence that invoked the command.
+More precisely, @samp{e} gets events that are lists, so you can look at
+the data in the lists.  @xref{Input Events}.  No I/O.
+
+You can use @samp{e} more than once in a single command's interactive
+specification.  If the key sequence that invoked the command has
+@var{n} events that are lists, the @var{n}th @samp{e} provides the
+@var{n}th such event.  Events that are not lists, such as function keys
+and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
+
+@item f
+A file name of an existing file (@pxref{File Names}).  The default
+directory is @code{default-directory}.  Existing, Completion, Default,
+Prompt.
+
+@item F
+A file name.  The file need not exist.  Completion, Default, Prompt.
+
+@item G
+A file name.  The file need not exist.  If the user enters just a
+directory name, then the value is just that directory name, with no
+file name within the directory added.  Completion, Default, Prompt.
+
+@item i
+An irrelevant argument.  This code always supplies @code{nil} as
+the argument's value.  No I/O.
+
+@item k
+A key sequence (@pxref{Key Sequences}).  This keeps reading events
+until a command (or undefined command) is found in the current key
+maps.  The key sequence argument is represented as a string or vector.
+The cursor does not move into the echo area.  Prompt.
+
+If @samp{k} reads a key sequence that ends with a down-event, it also
+reads and discards the following up-event.  You can get access to that
+up-event with the @samp{U} code character.
+
+This kind of input is used by commands such as @code{describe-key} and
+@code{global-set-key}.
+
+@item K
+A key sequence, whose definition you intend to change.  This works like
+@samp{k}, except that it suppresses, for the last input event in the key
+sequence, the conversions that are normally used (when necessary) to
+convert an undefined key into a defined one.
+
+@item m
+@cindex marker argument
+The position of the mark, as an integer.  No I/O.
+
+@item M
+Arbitrary text, read in the minibuffer using the current buffer's input
+method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
+Emacs Manual}).  Prompt.
+
+@item n
+A number, read with the minibuffer.  If the input is not a number, the
+user has to try again.  @samp{n} never uses the prefix argument.
+Prompt.
+
+@item N
+The numeric prefix argument; but if there is no prefix argument, read
+a number as with @kbd{n}.  The value is always a number.  @xref{Prefix
+Command Arguments}.  Prompt.
+
+@item p
+@cindex numeric prefix argument usage
+The numeric prefix argument.  (Note that this @samp{p} is lower case.)
+No I/O.
+
+@item P
+@cindex raw prefix argument usage
+The raw prefix argument.  (Note that this @samp{P} is upper case.)  No
+I/O.
+
+@item r
+@cindex region argument
+Point and the mark, as two numeric arguments, smallest first.  This is
+the only code letter that specifies two successive arguments rather than
+one.  No I/O.
+
+@item s
+Arbitrary text, read in the minibuffer and returned as a string
+(@pxref{Text from Minibuffer}).  Terminate the input with either
+@kbd{C-j} or @key{RET}.  (@kbd{C-q} may be used to include either of
+these characters in the input.)  Prompt.
+
+@item S
+An interned symbol whose name is read in the minibuffer.  Any whitespace
+character terminates the input.  (Use @kbd{C-q} to include whitespace in
+the string.)  Other characters that normally terminate a symbol (e.g.,
+parentheses and brackets) do not do so here.  Prompt.
+
+@item U
+A key sequence or @code{nil}.  Can be used after a @samp{k} or
+@samp{K} argument to get the up-event that was discarded (if any)
+after @samp{k} or @samp{K} read a down-event.  If no up-event has been
+discarded, @samp{U} provides @code{nil} as the argument.  No I/O.
+
+@item v
+A variable declared to be a user option (i.e., satisfying the
+predicate @code{user-variable-p}).  This reads the variable using
+@code{read-variable}.  @xref{Definition of read-variable}.  Existing,
+Completion, Prompt.
+
+@item x
+A Lisp object, specified with its read syntax, terminated with a
+@kbd{C-j} or @key{RET}.  The object is not evaluated.  @xref{Object from
+Minibuffer}.  Prompt.
+
+@item X
+@cindex evaluated expression argument
+A Lisp form's value.  @samp{X} reads as @samp{x} does, then evaluates
+the form so that its value becomes the argument for the command.
+Prompt.
+
+@item z
+A coding system name (a symbol).  If the user enters null input, the
+argument value is @code{nil}.  @xref{Coding Systems}.  Completion,
+Existing, Prompt.
+
+@item Z
+A coding system name (a symbol)---but only if this command has a prefix
+argument.  With no prefix argument, @samp{Z} provides @code{nil} as the
+argument value.  Completion, Existing, Prompt.
+@end table
+
+@node Interactive Examples
+@comment  node-name,  next,  previous,  up
+@subsection Examples of Using @code{interactive}
+@cindex examples of using @code{interactive}
+@cindex @code{interactive}, examples of using
+
+  Here are some examples of @code{interactive}:
+
+@example
+@group
+(defun foo1 ()              ; @r{@code{foo1} takes no arguments,}
+    (interactive)           ;   @r{just moves forward two words.}
+    (forward-word 2))
+     @result{} foo1
+@end group
+
+@group
+(defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
+    (interactive "p")       ;   @r{which is the numeric prefix.}
+    (forward-word (* 2 n)))
+     @result{} foo2
+@end group
+
+@group
+(defun foo3 (n)             ; @r{@code{foo3} takes one argument,}
+    (interactive "nCount:") ;   @r{which is read with the Minibuffer.}
+    (forward-word (* 2 n)))
+     @result{} foo3
+@end group
+
+@group
+(defun three-b (b1 b2 b3)
+  "Select three existing buffers.
+Put them into three windows, selecting the last one."
+@end group
+    (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
+    (delete-other-windows)
+    (split-window (selected-window) 8)
+    (switch-to-buffer b1)
+    (other-window 1)
+    (split-window (selected-window) 8)
+    (switch-to-buffer b2)
+    (other-window 1)
+    (switch-to-buffer b3))
+     @result{} three-b
+@group
+(three-b "*scratch*" "declarations.texi" "*mail*")
+     @result{} nil
+@end group
+@end example
+
+@node Interactive Call
+@section Interactive Call
+@cindex interactive call
+
+  After the command loop has translated a key sequence into a command it
+invokes that command using the function @code{command-execute}.  If the
+command is a function, @code{command-execute} calls
+@code{call-interactively}, which reads the arguments and calls the
+command.  You can also call these functions yourself.
+
+@defun commandp object &optional for-call-interactively
+Returns @code{t} if @var{object} is suitable for calling interactively;
+that is, if @var{object} is a command.  Otherwise, returns @code{nil}.
+
+The interactively callable objects include strings and vectors (treated
+as keyboard macros), lambda expressions that contain a top-level call to
+@code{interactive}, byte-code function objects made from such lambda
+expressions, autoload objects that are declared as interactive
+(non-@code{nil} fourth argument to @code{autoload}), and some of the
+primitive functions.
+
+A symbol satisfies @code{commandp} if its function definition
+satisfies @code{commandp}.  Keys and keymaps are not commands.
+Rather, they are used to look up commands (@pxref{Keymaps}).
+
+If @var{for-call-interactively} is non-@code{nil}, then
+@code{commandp} returns @code{t} only for objects that
+@code{call-interactively} could call---thus, not for keyboard macros.
+
+See @code{documentation} in @ref{Accessing Documentation}, for a
+realistic example of using @code{commandp}.
+@end defun
+
+@defun call-interactively command &optional record-flag keys
+This function calls the interactively callable function @var{command},
+reading arguments according to its interactive calling specifications.
+It returns whatever @var{command} returns.  An error is signaled if
+@var{command} is not a function or if it cannot be called
+interactively (i.e., is not a command).  Note that keyboard macros
+(strings and vectors) are not accepted, even though they are
+considered commands, because they are not functions.  If @var{command}
+is a symbol, then @code{call-interactively} uses its function definition.
+
+@cindex record command history
+If @var{record-flag} is non-@code{nil}, then this command and its
+arguments are unconditionally added to the list @code{command-history}.
+Otherwise, the command is added only if it uses the minibuffer to read
+an argument.  @xref{Command History}.
+
+The argument @var{keys}, if given, should be a vector which specifies
+the sequence of events to supply if the command inquires which events
+were used to invoke it.  If @var{keys} is omitted or @code{nil}, the
+default is the return value of @code{this-command-keys-vector}.
+@xref{Definition of this-command-keys-vector}.
+@end defun
+
+@defun command-execute command &optional record-flag keys special
+@cindex keyboard macro execution
+This function executes @var{command}.  The argument @var{command} must
+satisfy the @code{commandp} predicate; i.e., it must be an interactively
+callable function or a keyboard macro.
+
+A string or vector as @var{command} is executed with
+@code{execute-kbd-macro}.  A function is passed to
+@code{call-interactively}, along with the optional @var{record-flag}
+and @var{keys}.
+
+A symbol is handled by using its function definition in its place.  A
+symbol with an @code{autoload} definition counts as a command if it was
+declared to stand for an interactively callable function.  Such a
+definition is handled by loading the specified library and then
+rechecking the definition of the symbol.
+
+The argument @var{special}, if given, means to ignore the prefix
+argument and not clear it.  This is used for executing special events
+(@pxref{Special Events}).
+@end defun
+
+@deffn Command execute-extended-command prefix-argument
+@cindex read command name
+This function reads a command name from the minibuffer using
+@code{completing-read} (@pxref{Completion}).  Then it uses
+@code{command-execute} to call the specified command.  Whatever that
+command returns becomes the value of @code{execute-extended-command}.
+
+@cindex execute with prefix argument
+If the command asks for a prefix argument, it receives the value
+@var{prefix-argument}.  If @code{execute-extended-command} is called
+interactively, the current raw prefix argument is used for
+@var{prefix-argument}, and thus passed on to whatever command is run.
+
+@c !!! Should this be @kindex?
+@cindex @kbd{M-x}
+@code{execute-extended-command} is the normal definition of @kbd{M-x},
+so it uses the string @w{@samp{M-x }} as a prompt.  (It would be better
+to take the prompt from the events used to invoke
+@code{execute-extended-command}, but that is painful to implement.)  A
+description of the value of the prefix argument, if any, also becomes
+part of the prompt.
+
+@example
+@group
+(execute-extended-command 3)
+---------- Buffer: Minibuffer ----------
+3 M-x forward-word RET
+---------- Buffer: Minibuffer ----------
+     @result{} t
+@end group
+@end example
+@end deffn
+
+@defun interactive-p
+This function returns @code{t} if the containing function (the one
+whose code includes the call to @code{interactive-p}) was called in
+direct response to user input.  This means that it was called with the
+function @code{call-interactively}, and that a keyboard macro is
+not running, and that Emacs is not running in batch mode.
+
+If the containing function was called by Lisp evaluation (or with
+@code{apply} or @code{funcall}), then it was not called interactively.
+@end defun
+
+  The most common use of @code{interactive-p} is for deciding whether
+to give the user additional visual feedback (such as by printing an
+informative message).  For example:
+
+@example
+@group
+;; @r{Here's the usual way to use @code{interactive-p}.}
+(defun foo ()
+  (interactive)
+  (when (interactive-p)
+    (message "foo")))
+     @result{} foo
+@end group
+
+@group
+;; @r{This function is just to illustrate the behavior.}
+(defun bar ()
+  (interactive)
+  (setq foobar (list (foo) (interactive-p))))
+     @result{} bar
+@end group
+
+@group
+;; @r{Type @kbd{M-x foo}.}
+     @print{} foo
+@end group
+
+@group
+;; @r{Type @kbd{M-x bar}.}
+;; @r{This does not display a message.}
+@end group
+
+@group
+foobar
+     @result{} (nil t)
+@end group
+@end example
+
+  If you want to test @emph{only} whether the function was called
+using @code{call-interactively}, add an optional argument
+@code{print-message} which should be non-@code{nil} in an interactive
+call, and use the @code{interactive} spec to make sure it is
+non-@code{nil}.  Here's an example:
+
+@example
+(defun foo (&optional print-message)
+  (interactive "p")
+  (when print-message
+    (message "foo")))
+@end example
+
+@noindent
+Defined in this way, the function does display the message when called
+from a keyboard macro.  We use @code{"p"} because the numeric prefix
+argument is never @code{nil}.
+
+@defun called-interactively-p
+This function returns @code{t} when the calling function was called
+using @code{call-interactively}.
+
+When possible, instead of using this function, you should use the
+method in the example above; that method makes it possible for a
+caller to ``pretend'' that the function was called interactively.
+@end defun
+
+@node Command Loop Info
+@comment  node-name,  next,  previous,  up
+@section Information from the Command Loop
+
+The editor command loop sets several Lisp variables to keep status
+records for itself and for commands that are run.
+
+@defvar last-command
+This variable records the name of the previous command executed by the
+command loop (the one before the current command).  Normally the value
+is a symbol with a function definition, but this is not guaranteed.
+
+The value is copied from @code{this-command} when a command returns to
+the command loop, except when the command has specified a prefix
+argument for the following command.
+
+This variable is always local to the current terminal and cannot be
+buffer-local.  @xref{Multiple Displays}.
+@end defvar
+
+@defvar real-last-command
+This variable is set up by Emacs just like @code{last-command},
+but never altered by Lisp programs.
+@end defvar
+
+@defvar this-command
+@cindex current command
+This variable records the name of the command now being executed by
+the editor command loop.  Like @code{last-command}, it is normally a symbol
+with a function definition.
+
+The command loop sets this variable just before running a command, and
+copies its value into @code{last-command} when the command finishes
+(unless the command specified a prefix argument for the following
+command).
+
+@cindex kill command repetition
+Some commands set this variable during their execution, as a flag for
+whatever command runs next.  In particular, the functions for killing text
+set @code{this-command} to @code{kill-region} so that any kill commands
+immediately following will know to append the killed text to the
+previous kill.
+@end defvar
+
+If you do not want a particular command to be recognized as the previous
+command in the case where it got an error, you must code that command to
+prevent this.  One way is to set @code{this-command} to @code{t} at the
+beginning of the command, and set @code{this-command} back to its proper
+value at the end, like this:
+
+@example
+(defun foo (args@dots{})
+  (interactive @dots{})
+  (let ((old-this-command this-command))
+    (setq this-command t)
+    @r{@dots{}do the work@dots{}}
+    (setq this-command old-this-command)))
+@end example
+
+@noindent
+We do not bind @code{this-command} with @code{let} because that would
+restore the old value in case of error---a feature of @code{let} which
+in this case does precisely what we want to avoid.
+
+@defvar this-original-command
+This has the same value as @code{this-command} except when command
+remapping occurs (@pxref{Remapping Commands}).  In that case,
+@code{this-command} gives the command actually run (the result of
+remapping), and @code{this-original-command} gives the command that
+was specified to run but remapped into another command.
+@end defvar
+
+@defun this-command-keys
+This function returns a string or vector containing the key sequence
+that invoked the present command, plus any previous commands that
+generated the prefix argument for this command.  Any events read by the
+command using @code{read-event} without a timeout get tacked on to the end.
+
+However, if the command has called @code{read-key-sequence}, it
+returns the last read key sequence.  @xref{Key Sequence Input}.  The
+value is a string if all events in the sequence were characters that
+fit in a string.  @xref{Input Events}.
+
+@example
+@group
+(this-command-keys)
+;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
+     @result{} "^U^X^E"
+@end group
+@end example
+@end defun
+
+@defun this-command-keys-vector
+@anchor{Definition of this-command-keys-vector}
+Like @code{this-command-keys}, except that it always returns the events
+in a vector, so you don't need to deal with the complexities of storing
+input events in a string (@pxref{Strings of Events}).
+@end defun
+
+@defun clear-this-command-keys &optional keep-record
+This function empties out the table of events for
+@code{this-command-keys} to return.  Unless @var{keep-record} is
+non-@code{nil}, it also empties the records that the function
+@code{recent-keys} (@pxref{Recording Input}) will subsequently return.
+This is useful after reading a password, to prevent the password from
+echoing inadvertently as part of the next command in certain cases.
+@end defun
+
+@defvar last-nonmenu-event
+This variable holds the last input event read as part of a key sequence,
+not counting events resulting from mouse menus.
+
+One use of this variable is for telling @code{x-popup-menu} where to pop
+up a menu.  It is also used internally by @code{y-or-n-p}
+(@pxref{Yes-or-No Queries}).
+@end defvar
+
+@defvar last-command-event
+@defvarx last-command-char
+This variable is set to the last input event that was read by the
+command loop as part of a command.  The principal use of this variable
+is in @code{self-insert-command}, which uses it to decide which
+character to insert.
+
+@example
+@group
+last-command-event
+;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
+     @result{} 5
+@end group
+@end example
+
+@noindent
+The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
+
+The alias @code{last-command-char} exists for compatibility with
+Emacs version 18.
+@end defvar
+
+@c Emacs 19 feature
+@defvar last-event-frame
+This variable records which frame the last input event was directed to.
+Usually this is the frame that was selected when the event was
+generated, but if that frame has redirected input focus to another
+frame, the value is the frame to which the event was redirected.
+@xref{Input Focus}.
+
+If the last event came from a keyboard macro, the value is @code{macro}.
+@end defvar
+
+@node Adjusting Point
+@section Adjusting Point After Commands
+@cindex adjusting point
+@cindex invisible/intangible text, and point
+@cindex @code{display} property, and point display
+@cindex @code{composition} property, and point display
+
+  It is not easy to display a value of point in the middle of a
+sequence of text that has the @code{display}, @code{composition} or
+@code{intangible} property, or is invisible.  Therefore, after a
+command finishes and returns to the command loop, if point is within
+such a sequence, the command loop normally moves point to the edge of
+the sequence.
+
+  A command can inhibit this feature by setting the variable
+@code{disable-point-adjustment}:
+
+@defvar disable-point-adjustment
+If this variable is non-@code{nil} when a command returns to the
+command loop, then the command loop does not check for those text
+properties, and does not move point out of sequences that have them.
+
+The command loop sets this variable to @code{nil} before each command,
+so if a command sets it, the effect applies only to that command.
+@end defvar
+
+@defvar global-disable-point-adjustment
+If you set this variable to a non-@code{nil} value, the feature of
+moving point out of these sequences is completely turned off.
+@end defvar
+
+@node Input Events
+@section Input Events
+@cindex events
+@cindex input events
+
+The Emacs command loop reads a sequence of @dfn{input events} that
+represent keyboard or mouse activity.  The events for keyboard activity
+are characters or symbols; mouse events are always lists.  This section
+describes the representation and meaning of input events in detail.
+
+@defun eventp object
+This function returns non-@code{nil} if @var{object} is an input event
+or event type.
+
+Note that any symbol might be used as an event or an event type.
+@code{eventp} cannot distinguish whether a symbol is intended by Lisp
+code to be used as an event.  Instead, it distinguishes whether the
+symbol has actually been used in an event that has been read as input in
+the current Emacs session.  If a symbol has not yet been so used,
+@code{eventp} returns @code{nil}.
+@end defun
+
+@menu
+* Keyboard Events::		Ordinary characters--keys with symbols on them.
+* Function Keys::		Function keys--keys with names, not symbols.
+* Mouse Events::                Overview of mouse events.
+* Click Events::		Pushing and releasing a mouse button.
+* Drag Events::			Moving the mouse before releasing the button.
+* Button-Down Events::		A button was pushed and not yet released.
+* Repeat Events::               Double and triple click (or drag, or down).
+* Motion Events::		Just moving the mouse, not pushing a button.
+* Focus Events::		Moving the mouse between frames.
+* Misc Events::                 Other events the system can generate.
+* Event Examples::		Examples of the lists for mouse events.
+* Classifying Events::		Finding the modifier keys in an event symbol.
+				Event types.
+* Accessing Events::		Functions to extract info from events.
+* Strings of Events::           Special considerations for putting
+				  keyboard character events in a string.
+@end menu
+
+@node Keyboard Events
+@subsection Keyboard Events
+@cindex keyboard events
+
+There are two kinds of input you can get from the keyboard: ordinary
+keys, and function keys.  Ordinary keys correspond to characters; the
+events they generate are represented in Lisp as characters.  The event
+type of a character event is the character itself (an integer); see
+@ref{Classifying Events}.
+
+@cindex modifier bits (of input character)
+@cindex basic code (of input character)
+An input character event consists of a @dfn{basic code} between 0 and
+524287, plus any or all of these @dfn{modifier bits}:
+
+@table @asis
+@item meta
+The
+@tex
+@math{2^{27}}
+@end tex
+@ifnottex
+2**27
+@end ifnottex
+bit in the character code indicates a character
+typed with the meta key held down.
+
+@item control
+The
+@tex
+@math{2^{26}}
+@end tex
+@ifnottex
+2**26
+@end ifnottex
+bit in the character code indicates a non-@acronym{ASCII}
+control character.
+
+@sc{ascii} control characters such as @kbd{C-a} have special basic
+codes of their own, so Emacs needs no special bit to indicate them.
+Thus, the code for @kbd{C-a} is just 1.
+
+But if you type a control combination not in @acronym{ASCII}, such as
+@kbd{%} with the control key, the numeric value you get is the code
+for @kbd{%} plus
+@tex
+@math{2^{26}}
+@end tex
+@ifnottex
+2**26
+@end ifnottex
+(assuming the terminal supports non-@acronym{ASCII}
+control characters).
+
+@item shift
+The
+@tex
+@math{2^{25}}
+@end tex
+@ifnottex
+2**25
+@end ifnottex
+bit in the character code indicates an @acronym{ASCII} control
+character typed with the shift key held down.
+
+For letters, the basic code itself indicates upper versus lower case;
+for digits and punctuation, the shift key selects an entirely different
+character with a different basic code.  In order to keep within the
+@acronym{ASCII} character set whenever possible, Emacs avoids using the
+@tex
+@math{2^{25}}
+@end tex
+@ifnottex
+2**25
+@end ifnottex
+bit for those characters.
+
+However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
+@kbd{C-a}, so Emacs uses the
+@tex
+@math{2^{25}}
+@end tex
+@ifnottex
+2**25
+@end ifnottex
+bit in @kbd{C-A} and not in
+@kbd{C-a}.
+
+@item hyper
+The
+@tex
+@math{2^{24}}
+@end tex
+@ifnottex
+2**24
+@end ifnottex
+bit in the character code indicates a character
+typed with the hyper key held down.
+
+@item super
+The
+@tex
+@math{2^{23}}
+@end tex
+@ifnottex
+2**23
+@end ifnottex
+bit in the character code indicates a character
+typed with the super key held down.
+
+@item alt
+The
+@tex
+@math{2^{22}}
+@end tex
+@ifnottex
+2**22
+@end ifnottex
+bit in the character code indicates a character typed with
+the alt key held down.  (On some terminals, the key labeled @key{ALT}
+is actually the meta key.)
+@end table
+
+  It is best to avoid mentioning specific bit numbers in your program.
+To test the modifier bits of a character, use the function
+@code{event-modifiers} (@pxref{Classifying Events}).  When making key
+bindings, you can use the read syntax for characters with modifier bits
+(@samp{\C-}, @samp{\M-}, and so on).  For making key bindings with
+@code{define-key}, you can use lists such as @code{(control hyper ?x)} to
+specify the characters (@pxref{Changing Key Bindings}).  The function
+@code{event-convert-list} converts such a list into an event type
+(@pxref{Classifying Events}).
+
+@node Function Keys
+@subsection Function Keys
+
+@cindex function keys
+Most keyboards also have @dfn{function keys}---keys that have names or
+symbols that are not characters.  Function keys are represented in Emacs
+Lisp as symbols; the symbol's name is the function key's label, in lower
+case.  For example, pressing a key labeled @key{F1} places the symbol
+@code{f1} in the input stream.
+
+The event type of a function key event is the event symbol itself.
+@xref{Classifying Events}.
+
+Here are a few special cases in the symbol-naming convention for
+function keys:
+
+@table @asis
+@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
+These keys correspond to common @acronym{ASCII} control characters that have
+special keys on most keyboards.
+
+In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character.  If the
+terminal can distinguish between them, Emacs conveys the distinction to
+Lisp programs by representing the former as the integer 9, and the
+latter as the symbol @code{tab}.
+
+Most of the time, it's not useful to distinguish the two.  So normally
+@code{function-key-map} (@pxref{Translation Keymaps}) is set up to map
+@code{tab} into 9.  Thus, a key binding for character code 9 (the
+character @kbd{C-i}) also applies to @code{tab}.  Likewise for the other
+symbols in this group.  The function @code{read-char} likewise converts
+these events into characters.
+
+In @acronym{ASCII}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
+converts into the character code 127 (@key{DEL}), not into code 8
+(@key{BS}).  This is what most users prefer.
+
+@item @code{left}, @code{up}, @code{right}, @code{down}
+Cursor arrow keys
+@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
+Keypad keys (to the right of the regular keyboard).
+@item @code{kp-0}, @code{kp-1}, @dots{}
+Keypad keys with digits.
+@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
+Keypad PF keys.
+@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
+Keypad arrow keys.  Emacs normally translates these into the
+corresponding non-keypad keys @code{home}, @code{left}, @dots{}
+@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
+Additional keypad duplicates of keys ordinarily found elsewhere.  Emacs
+normally translates these into the like-named non-keypad keys.
+@end table
+
+You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
+@key{META}, @key{SHIFT}, and @key{SUPER} with function keys.  The way to
+represent them is with prefixes in the symbol name:
+
+@table @samp
+@item A-
+The alt modifier.
+@item C-
+The control modifier.
+@item H-
+The hyper modifier.
+@item M-
+The meta modifier.
+@item S-
+The shift modifier.
+@item s-
+The super modifier.
+@end table
+
+Thus, the symbol for the key @key{F3} with @key{META} held down is
+@code{M-f3}.  When you use more than one prefix, we recommend you
+write them in alphabetical order; but the order does not matter in
+arguments to the key-binding lookup and modification functions.
+
+@node Mouse Events
+@subsection Mouse Events
+
+Emacs supports four kinds of mouse events: click events, drag events,
+button-down events, and motion events.  All mouse events are represented
+as lists.  The @sc{car} of the list is the event type; this says which
+mouse button was involved, and which modifier keys were used with it.
+The event type can also distinguish double or triple button presses
+(@pxref{Repeat Events}).  The rest of the list elements give position
+and time information.
+
+For key lookup, only the event type matters: two events of the same type
+necessarily run the same command.  The command can access the full
+values of these events using the @samp{e} interactive code.
+@xref{Interactive Codes}.
+
+A key sequence that starts with a mouse event is read using the keymaps
+of the buffer in the window that the mouse was in, not the current
+buffer.  This does not imply that clicking in a window selects that
+window or its buffer---that is entirely under the control of the command
+binding of the key sequence.
+
+@node Click Events
+@subsection Click Events
+@cindex click event
+@cindex mouse click event
+
+When the user presses a mouse button and releases it at the same
+location, that generates a @dfn{click} event.  All mouse click event
+share the same format:
+
+@example
+(@var{event-type} @var{position} @var{click-count})
+@end example
+
+@table @asis
+@item @var{event-type}
+This is a symbol that indicates which mouse button was used.  It is
+one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
+buttons are numbered left to right.
+
+You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
+@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
+and super, just as you would with function keys.
+
+This symbol also serves as the event type of the event.  Key bindings
+describe events by their types; thus, if there is a key binding for
+@code{mouse-1}, that binding would apply to all events whose
+@var{event-type} is @code{mouse-1}.
+
+@item @var{position}
+This is the position where the mouse click occurred.  The actual
+format of @var{position} depends on what part of a window was clicked
+on.
+
+For mouse click events in the text area, mode line, header line, or in
+the marginal areas, @var{position} has this form:
+
+@example
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
+ @var{object} @var{text-pos} (@var{col} . @var{row})
+ @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
+@end example
+
+@table @asis
+@item @var{window}
+This is the window in which the click occurred.
+
+@item @var{pos-or-area}
+This is the buffer position of the character clicked on in the text
+area, or if clicked outside the text area, it is the window area in
+which the click occurred.  It is one of the symbols @code{mode-line},
+@code{header-line}, @code{vertical-line}, @code{left-margin},
+@code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
+
+In one special case, @var{pos-or-area} is a list containing a symbol (one
+of the symbols listed above) instead of just the symbol.  This happens
+after the imaginary prefix keys for the event are inserted into the
+input stream.  @xref{Key Sequence Input}.
+
+
+@item @var{x}, @var{y}
+These are the pixel coordinates of the click, relative to
+the top left corner of @var{window}, which is @code{(0 . 0)}.
+For the mode or header line, @var{y} does not have meaningful data.
+For the vertical line, @var{x} does not have meaningful data.
+
+@item @var{timestamp}
+This is the time at which the event occurred, in milliseconds.
+
+@item @var{object}
+This is the object on which the click occurred.  It is either
+@code{nil} if there is no string property, or it has the form
+(@var{string} . @var{string-pos}) when there is a string-type text
+property at the click position.
+
+@table @asis
+@item @var{string}
+This is the string on which the click occurred, including any
+properties.
+
+@item @var{string-pos}
+This is the position in the string on which the click occurred,
+relevant if properties at the click need to be looked up.
+@end table
+
+@item @var{text-pos}
+For clicks on a marginal area or on a fringe, this is the buffer
+position of the first visible character in the corresponding line in
+the window.  For other events, it is the current buffer position in
+the window.
+
+@item @var{col}, @var{row}
+These are the actual coordinates of the glyph under the @var{x},
+@var{y} position, possibly padded with default character width
+glyphs if @var{x} is beyond the last glyph on the line.
+
+@item @var{image}
+This is the image object on which the click occurred.  It is either
+@code{nil} if there is no image at the position clicked on, or it is
+an image object as returned by @code{find-image} if click was in an image.
+
+@item @var{dx}, @var{dy}
+These are the pixel coordinates of the click, relative to
+the top left corner of @var{object}, which is @code{(0 . 0)}.  If
+@var{object} is @code{nil}, the coordinates are relative to the top
+left corner of the character glyph clicked on.
+
+@item @var{width}, @var{height}
+These are the pixel width and height of @var{object} or, if this is
+@code{nil}, those of the character glyph clicked on.
+@end table
+ 
+@sp 1
+For mouse clicks on a scroll-bar, @var{position} has this form:
+
+@example
+(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
+@end example
+
+@table @asis
+@item @var{window}
+This is the window whose scroll-bar was clicked on.
+
+@item @var{area}
+This is the scroll bar where the click occurred.  It is one of the
+symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
+
+@item @var{portion}
+This is the distance of the click from the top or left end of
+the scroll bar.
+
+@item @var{whole}
+This is the length of the entire scroll bar.
+
+@item @var{timestamp}
+This is the time at which the event occurred, in milliseconds.
+
+@item @var{part}
+This is the part of the scroll-bar which was clicked on.  It is one
+of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
+@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
+@end table
+
+@item @var{click-count}
+This is the number of rapid repeated presses so far of the same mouse
+button.  @xref{Repeat Events}.
+@end table
+
+@node Drag Events
+@subsection Drag Events
+@cindex drag event
+@cindex mouse drag event
+
+With Emacs, you can have a drag event without even changing your
+clothes.  A @dfn{drag event} happens every time the user presses a mouse
+button and then moves the mouse to a different character position before
+releasing the button.  Like all mouse events, drag events are
+represented in Lisp as lists.  The lists record both the starting mouse
+position and the final position, like this:
+
+@example
+(@var{event-type}
+ (@var{window1} START-POSITION)
+ (@var{window2} END-POSITION))
+@end example
+
+For a drag event, the name of the symbol @var{event-type} contains the
+prefix @samp{drag-}.  For example, dragging the mouse with button 2
+held down generates a @code{drag-mouse-2} event.  The second and third
+elements of the event give the starting and ending position of the
+drag.  They have the same form as @var{position} in a click event
+(@pxref{Click Events}) that is not on the scroll bar part of the
+window.  You can access the second element of any mouse event in the
+same way, with no need to distinguish drag events from others.
+
+The @samp{drag-} prefix follows the modifier key prefixes such as
+@samp{C-} and @samp{M-}.
+
+If @code{read-key-sequence} receives a drag event that has no key
+binding, and the corresponding click event does have a binding, it
+changes the drag event into a click event at the drag's starting
+position.  This means that you don't have to distinguish between click
+and drag events unless you want to.
+
+@node Button-Down Events
+@subsection Button-Down Events
+@cindex button-down event
+
+Click and drag events happen when the user releases a mouse button.
+They cannot happen earlier, because there is no way to distinguish a
+click from a drag until the button is released.
+
+If you want to take action as soon as a button is pressed, you need to
+handle @dfn{button-down} events.@footnote{Button-down is the
+conservative antithesis of drag.}  These occur as soon as a button is
+pressed.  They are represented by lists that look exactly like click
+events (@pxref{Click Events}), except that the @var{event-type} symbol
+name contains the prefix @samp{down-}.  The @samp{down-} prefix follows
+modifier key prefixes such as @samp{C-} and @samp{M-}.
+
+The function @code{read-key-sequence} ignores any button-down events
+that don't have command bindings; therefore, the Emacs command loop
+ignores them too.  This means that you need not worry about defining
+button-down events unless you want them to do something.  The usual
+reason to define a button-down event is so that you can track mouse
+motion (by reading motion events) until the button is released.
+@xref{Motion Events}.
+
+@node Repeat Events
+@subsection Repeat Events
+@cindex repeat events
+@cindex double-click events
+@cindex triple-click events
+@cindex mouse events, repeated
+
+If you press the same mouse button more than once in quick succession
+without moving the mouse, Emacs generates special @dfn{repeat} mouse
+events for the second and subsequent presses.
+
+The most common repeat events are @dfn{double-click} events.  Emacs
+generates a double-click event when you click a button twice; the event
+happens when you release the button (as is normal for all click
+events).
+
+The event type of a double-click event contains the prefix
+@samp{double-}.  Thus, a double click on the second mouse button with
+@key{meta} held down comes to the Lisp program as
+@code{M-double-mouse-2}.  If a double-click event has no binding, the
+binding of the corresponding ordinary click event is used to execute
+it.  Thus, you need not pay attention to the double click feature
+unless you really want to.
+
+When the user performs a double click, Emacs generates first an ordinary
+click event, and then a double-click event.  Therefore, you must design
+the command binding of the double click event to assume that the
+single-click command has already run.  It must produce the desired
+results of a double click, starting from the results of a single click.
+
+This is convenient, if the meaning of a double click somehow ``builds
+on'' the meaning of a single click---which is recommended user interface
+design practice for double clicks.
+
+If you click a button, then press it down again and start moving the
+mouse with the button held down, then you get a @dfn{double-drag} event
+when you ultimately release the button.  Its event type contains
+@samp{double-drag} instead of just @samp{drag}.  If a double-drag event
+has no binding, Emacs looks for an alternate binding as if the event
+were an ordinary drag.
+
+Before the double-click or double-drag event, Emacs generates a
+@dfn{double-down} event when the user presses the button down for the
+second time.  Its event type contains @samp{double-down} instead of just
+@samp{down}.  If a double-down event has no binding, Emacs looks for an
+alternate binding as if the event were an ordinary button-down event.
+If it finds no binding that way either, the double-down event is
+ignored.
+
+To summarize, when you click a button and then press it again right
+away, Emacs generates a down event and a click event for the first
+click, a double-down event when you press the button again, and finally
+either a double-click or a double-drag event.
+
+If you click a button twice and then press it again, all in quick
+succession, Emacs generates a @dfn{triple-down} event, followed by
+either a @dfn{triple-click} or a @dfn{triple-drag}.  The event types of
+these events contain @samp{triple} instead of @samp{double}.  If any
+triple event has no binding, Emacs uses the binding that it would use
+for the corresponding double event.
+
+If you click a button three or more times and then press it again, the
+events for the presses beyond the third are all triple events.  Emacs
+does not have separate event types for quadruple, quintuple, etc.@:
+events.  However, you can look at the event list to find out precisely
+how many times the button was pressed.
+
+@defun event-click-count event
+This function returns the number of consecutive button presses that led
+up to @var{event}.  If @var{event} is a double-down, double-click or
+double-drag event, the value is 2.  If @var{event} is a triple event,
+the value is 3 or greater.  If @var{event} is an ordinary mouse event
+(not a repeat event), the value is 1.
+@end defun
+
+@defopt double-click-fuzz
+To generate repeat events, successive mouse button presses must be at
+approximately the same screen position.  The value of
+@code{double-click-fuzz} specifies the maximum number of pixels the
+mouse may be moved (horizontally or vertically) between two successive
+clicks to make a double-click.
+
+This variable is also the threshold for motion of the mouse to count
+as a drag.
+@end defopt
+
+@defopt double-click-time
+To generate repeat events, the number of milliseconds between
+successive button presses must be less than the value of
+@code{double-click-time}.  Setting @code{double-click-time} to
+@code{nil} disables multi-click detection entirely.  Setting it to
+@code{t} removes the time limit; Emacs then detects multi-clicks by
+position only.
+@end defopt
+
+@node Motion Events
+@subsection Motion Events
+@cindex motion event
+@cindex mouse motion events
+
+Emacs sometimes generates @dfn{mouse motion} events to describe motion
+of the mouse without any button activity.  Mouse motion events are
+represented by lists that look like this:
+
+@example
+(mouse-movement (POSITION))
+@end example
+
+The second element of the list describes the current position of the
+mouse, just as in a click event (@pxref{Click Events}).
+
+The special form @code{track-mouse} enables generation of motion events
+within its body.  Outside of @code{track-mouse} forms, Emacs does not
+generate events for mere motion of the mouse, and these events do not
+appear.  @xref{Mouse Tracking}.
+
+@node Focus Events
+@subsection Focus Events
+@cindex focus event
+
+Window systems provide general ways for the user to control which window
+gets keyboard input.  This choice of window is called the @dfn{focus}.
+When the user does something to switch between Emacs frames, that
+generates a @dfn{focus event}.  The normal definition of a focus event,
+in the global keymap, is to select a new frame within Emacs, as the user
+would expect.  @xref{Input Focus}.
+
+Focus events are represented in Lisp as lists that look like this:
+
+@example
+(switch-frame @var{new-frame})
+@end example
+
+@noindent
+where @var{new-frame} is the frame switched to.
+
+Most X window managers are set up so that just moving the mouse into a
+window is enough to set the focus there.  Emacs appears to do this,
+because it changes the cursor to solid in the new frame.  However, there
+is no need for the Lisp program to know about the focus change until
+some other kind of input arrives.  So Emacs generates a focus event only
+when the user actually types a keyboard key or presses a mouse button in
+the new frame; just moving the mouse between frames does not generate a
+focus event.
+
+A focus event in the middle of a key sequence would garble the
+sequence.  So Emacs never generates a focus event in the middle of a key
+sequence.  If the user changes focus in the middle of a key
+sequence---that is, after a prefix key---then Emacs reorders the events
+so that the focus event comes either before or after the multi-event key
+sequence, and not within it.
+
+@node Misc Events
+@subsection Miscellaneous System Events
+
+A few other event types represent occurrences within the system.
+
+@table @code
+@cindex @code{delete-frame} event
+@item (delete-frame (@var{frame}))
+This kind of event indicates that the user gave the window manager
+a command to delete a particular window, which happens to be an Emacs frame.
+
+The standard definition of the @code{delete-frame} event is to delete @var{frame}.
+
+@cindex @code{iconify-frame} event
+@item (iconify-frame (@var{frame}))
+This kind of event indicates that the user iconified @var{frame} using
+the window manager.  Its standard definition is @code{ignore}; since the
+frame has already been iconified, Emacs has no work to do.  The purpose
+of this event type is so that you can keep track of such events if you
+want to.
+
+@cindex @code{make-frame-visible} event
+@item (make-frame-visible (@var{frame}))
+This kind of event indicates that the user deiconified @var{frame} using
+the window manager.  Its standard definition is @code{ignore}; since the
+frame has already been made visible, Emacs has no work to do.
+
+@cindex @code{wheel-up} event
+@cindex @code{wheel-down} event
+@item (wheel-up @var{position})
+@item (wheel-down @var{position})
+These kinds of event are generated by moving a mouse wheel.  Their
+usual meaning is a kind of scroll or zoom.
+
+The element @var{position} is a list describing the position of the
+event, in the same format as used in a mouse-click event.
+
+This kind of event is generated only on some kinds of systems. On some
+systems, @code{mouse-4} and @code{mouse-5} are used instead.  For
+portable code, use the variables @code{mouse-wheel-up-event} and
+@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
+what event types to expect for the mouse wheel.
+
+@cindex @code{drag-n-drop} event
+@item (drag-n-drop @var{position} @var{files})
+This kind of event is generated when a group of files is
+selected in an application outside of Emacs, and then dragged and
+dropped onto an Emacs frame.
+
+The element @var{position} is a list describing the position of the
+event, in the same format as used in a mouse-click event, and
+@var{files} is the list of file names that were dragged and dropped.
+The usual way to handle this event is by visiting these files.
+
+This kind of event is generated, at present, only on some kinds of
+systems.
+
+@cindex @code{help-echo} event
+@item help-echo
+This kind of event is generated when a mouse pointer moves onto a
+portion of buffer text which has a @code{help-echo} text property.
+The generated event has this form:
+
+@example
+(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
+@end example
+
+@noindent
+The precise meaning of the event parameters and the way these
+parameters are used to display the help-echo text are described in
+@ref{Text help-echo}.
+
+@cindex @code{sigusr1} event
+@cindex @code{sigusr2} event
+@cindex user signals
+@item sigusr1
+@itemx sigusr2
+These events are generated when the Emacs process receives
+the signals @code{SIGUSR1} and @code{SIGUSR2}.  They contain no
+additional data because signals do not carry additional information.
+
+To catch a user signal, bind the corresponding event to an interactive
+command in the @code{special-event-map} (@pxref{Active Keymaps}).
+The command is called with no arguments, and the specific signal event is
+available in @code{last-input-event}.  For example:
+
+@smallexample
+(defun sigusr-handler ()
+  (interactive)
+  (message "Caught signal %S" last-input-event))
+
+(define-key special-event-map [sigusr1] 'sigusr-handler)
+@end smallexample
+
+To test the signal handler, you can make Emacs send a signal to itself:
+
+@smallexample
+(signal-process (emacs-pid) 'sigusr1)
+@end smallexample
+@end table
+
+  If one of these events arrives in the middle of a key sequence---that
+is, after a prefix key---then Emacs reorders the events so that this
+event comes either before or after the multi-event key sequence, not
+within it.
+
+@node Event Examples
+@subsection Event Examples
+
+If the user presses and releases the left mouse button over the same
+location, that generates a sequence of events like this:
+
+@smallexample
+(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
+(mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))
+@end smallexample
+
+While holding the control key down, the user might hold down the
+second mouse button, and drag the mouse from one line to the next.
+That produces two events, as shown here:
+
+@smallexample
+(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
+(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
+                (#<window 18 on NEWS> 3510 (0 . 28) -729648))
+@end smallexample
+
+While holding down the meta and shift keys, the user might press the
+second mouse button on the window's mode line, and then drag the mouse
+into another window.  That produces a pair of events like these:
+
+@smallexample
+(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
+(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
+                  (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
+                   -453816))
+@end smallexample
+
+To handle a SIGUSR1 signal, define an interactive function, and
+bind it to the @code{signal usr1} event sequence:
+
+@smallexample
+(defun usr1-handler ()
+  (interactive)
+  (message "Got USR1 signal"))
+(global-set-key [signal usr1] 'usr1-handler)
+@end smallexample
+
+@node Classifying Events
+@subsection Classifying Events
+@cindex event type
+
+  Every event has an @dfn{event type}, which classifies the event for
+key binding purposes.  For a keyboard event, the event type equals the
+event value; thus, the event type for a character is the character, and
+the event type for a function key symbol is the symbol itself.  For
+events that are lists, the event type is the symbol in the @sc{car} of
+the list.  Thus, the event type is always a symbol or a character.
+
+  Two events of the same type are equivalent where key bindings are
+concerned; thus, they always run the same command.  That does not
+necessarily mean they do the same things, however, as some commands look
+at the whole event to decide what to do.  For example, some commands use
+the location of a mouse event to decide where in the buffer to act.
+
+  Sometimes broader classifications of events are useful.  For example,
+you might want to ask whether an event involved the @key{META} key,
+regardless of which other key or mouse button was used.
+
+  The functions @code{event-modifiers} and @code{event-basic-type} are
+provided to get such information conveniently.
+
+@defun event-modifiers event
+This function returns a list of the modifiers that @var{event} has.  The
+modifiers are symbols; they include @code{shift}, @code{control},
+@code{meta}, @code{alt}, @code{hyper} and @code{super}.  In addition,
+the modifiers list of a mouse event symbol always contains one of
+@code{click}, @code{drag}, and @code{down}.  For double or triple
+events, it also contains @code{double} or @code{triple}.
+
+The argument @var{event} may be an entire event object, or just an
+event type.  If @var{event} is a symbol that has never been used in an
+event that has been read as input in the current Emacs session, then
+@code{event-modifiers} can return @code{nil}, even when @var{event}
+actually has modifiers.
+
+Here are some examples:
+
+@example
+(event-modifiers ?a)
+     @result{} nil
+(event-modifiers ?A)
+     @result{} (shift)
+(event-modifiers ?\C-a)
+     @result{} (control)
+(event-modifiers ?\C-%)
+     @result{} (control)
+(event-modifiers ?\C-\S-a)
+     @result{} (control shift)
+(event-modifiers 'f5)
+     @result{} nil
+(event-modifiers 's-f5)
+     @result{} (super)
+(event-modifiers 'M-S-f5)
+     @result{} (meta shift)
+(event-modifiers 'mouse-1)
+     @result{} (click)
+(event-modifiers 'down-mouse-1)
+     @result{} (down)
+@end example
+
+The modifiers list for a click event explicitly contains @code{click},
+but the event symbol name itself does not contain @samp{click}.
+@end defun
+
+@defun event-basic-type event
+This function returns the key or mouse button that @var{event}
+describes, with all modifiers removed.  The @var{event} argument is as
+in @code{event-modifiers}.  For example:
+
+@example
+(event-basic-type ?a)
+     @result{} 97
+(event-basic-type ?A)
+     @result{} 97
+(event-basic-type ?\C-a)
+     @result{} 97
+(event-basic-type ?\C-\S-a)
+     @result{} 97
+(event-basic-type 'f5)
+     @result{} f5
+(event-basic-type 's-f5)
+     @result{} f5
+(event-basic-type 'M-S-f5)
+     @result{} f5
+(event-basic-type 'down-mouse-1)
+     @result{} mouse-1
+@end example
+@end defun
+
+@defun mouse-movement-p object
+This function returns non-@code{nil} if @var{object} is a mouse movement
+event.
+@end defun
+
+@defun event-convert-list list
+This function converts a list of modifier names and a basic event type
+to an event type which specifies all of them.  The basic event type
+must be the last element of the list.  For example,
+
+@example
+(event-convert-list '(control ?a))
+     @result{} 1
+(event-convert-list '(control meta ?a))
+     @result{} -134217727
+(event-convert-list '(control super f1))
+     @result{} C-s-f1
+@end example
+@end defun
+
+@node Accessing Events
+@subsection Accessing Events
+@cindex mouse events, data in
+
+  This section describes convenient functions for accessing the data in
+a mouse button or motion event.
+
+  These two functions return the starting or ending position of a
+mouse-button event, as a list of this form:
+
+@example
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
+ @var{object} @var{text-pos} (@var{col} . @var{row})
+ @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
+@end example
+
+@defun event-start event
+This returns the starting position of @var{event}.
+
+If @var{event} is a click or button-down event, this returns the
+location of the event.  If @var{event} is a drag event, this returns the
+drag's starting position.
+@end defun
+
+@defun event-end event
+This returns the ending position of @var{event}.
+
+If @var{event} is a drag event, this returns the position where the user
+released the mouse button.  If @var{event} is a click or button-down
+event, the value is actually the starting position, which is the only
+position such events have.
+@end defun
+
+@cindex mouse position list, accessing
+  These functions take a position list as described above, and
+return various parts of it.
+
+@defun posn-window position
+Return the window that @var{position} is in.
+@end defun
+
+@defun posn-area position
+Return the window area recorded in @var{position}.  It returns @code{nil}
+when the event occurred in the text area of the window; otherwise, it
+is a symbol identifying the area in which the event occurred.
+@end defun
+
+@defun posn-point position
+Return the buffer position in @var{position}.  When the event occurred
+in the text area of the window, in a marginal area, or on a fringe,
+this is an integer specifying a buffer position.  Otherwise, the value
+is undefined.
+@end defun
+
+@defun posn-x-y position
+Return the pixel-based x and y coordinates in @var{position}, as a
+cons cell @code{(@var{x} . @var{y})}.  These coordinates are relative
+to the window given by @code{posn-window}.
+
+This example shows how to convert these window-relative coordinates
+into frame-relative coordinates:
+
+@example
+(defun frame-relative-coordinates (position)
+  "Return frame-relative coordinates from POSITION."
+  (let* ((x-y (posn-x-y position))
+         (window (posn-window position))
+         (edges (window-inside-pixel-edges window)))
+    (cons (+ (car x-y) (car edges))
+          (+ (cdr x-y) (cadr edges)))))
+@end example
+@end defun
+
+@defun posn-col-row position
+Return the row and column (in units of the frame's default character
+height and width) of @var{position}, as a cons cell @code{(@var{col} .
+@var{row})}.  These are computed from the @var{x} and @var{y} values
+actually found in @var{position}.
+@end defun
+
+@defun posn-actual-col-row position
+Return the actual row and column in @var{position}, as a cons cell
+@code{(@var{col} . @var{row})}.  The values are the actual row number
+in the window, and the actual character number in that row.  It returns
+@code{nil} if @var{position} does not include actual positions values.
+You can use @code{posn-col-row} to get approximate values.
+@end defun
+
+@defun posn-string position
+Return the string object in @var{position}, either @code{nil}, or a
+cons cell @code{(@var{string} . @var{string-pos})}.
+@end defun
+
+@defun posn-image position
+Return the image object in @var{position}, either @code{nil}, or an
+image @code{(image ...)}.
+@end defun
+
+@defun posn-object position
+Return the image or string object in @var{position}, either
+@code{nil}, an image @code{(image ...)}, or a cons cell
+@code{(@var{string} . @var{string-pos})}.
+@end defun
+
+@defun posn-object-x-y position
+Return the pixel-based x and y coordinates relative to the upper left
+corner of the object in @var{position} as a cons cell @code{(@var{dx}
+. @var{dy})}.  If the @var{position} is a buffer position, return the
+relative position in the character at that position.
+@end defun
+
+@defun posn-object-width-height position
+Return the pixel width and height of the object in @var{position} as a
+cons cell @code{(@var{width} . @var{height})}.  If the @var{position}
+is a buffer position, return the size of the character at that position.
+@end defun
+
+@cindex timestamp of a mouse event
+@defun posn-timestamp position
+Return the timestamp in @var{position}.  This is the time at which the
+event occurred, in milliseconds.
+@end defun
+
+  These functions compute a position list given particular buffer
+position or screen position.  You can access the data in this position
+list with the functions described above.
+
+@defun posn-at-point &optional pos window
+This function returns a position list for position @var{pos} in
+@var{window}.  @var{pos} defaults to point in @var{window};
+@var{window} defaults to the selected window.
+
+@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
+@var{window}.
+@end defun
+
+@defun posn-at-x-y x y &optional frame-or-window whole
+This function returns position information corresponding to pixel
+coordinates @var{x} and @var{y} in a specified frame or window,
+@var{frame-or-window}, which defaults to the selected window.
+The coordinates @var{x} and @var{y} are relative to the
+frame or window used.
+If @var{whole} is @code{nil}, the coordinates are relative
+to the window text area, otherwise they are relative to
+the entire window area including scroll bars, margins and fringes.
+@end defun
+
+  These functions are useful for decoding scroll bar events.
+
+@defun scroll-bar-event-ratio event
+This function returns the fractional vertical position of a scroll bar
+event within the scroll bar.  The value is a cons cell
+@code{(@var{portion} . @var{whole})} containing two integers whose ratio
+is the fractional position.
+@end defun
+
+@defun scroll-bar-scale ratio total
+This function multiplies (in effect) @var{ratio} by @var{total},
+rounding the result to an integer.  The argument @var{ratio} is not a
+number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
+value returned by @code{scroll-bar-event-ratio}.
+
+This function is handy for scaling a position on a scroll bar into a
+buffer position.  Here's how to do that:
+
+@example
+(+ (point-min)
+   (scroll-bar-scale
+      (posn-x-y (event-start event))
+      (- (point-max) (point-min))))
+@end example
+
+Recall that scroll bar events have two integers forming a ratio, in place
+of a pair of x and y coordinates.
+@end defun
+
+@node Strings of Events
+@subsection Putting Keyboard Events in Strings
+@cindex keyboard events in strings
+@cindex strings with keyboard events
+
+  In most of the places where strings are used, we conceptualize the
+string as containing text characters---the same kind of characters found
+in buffers or files.  Occasionally Lisp programs use strings that
+conceptually contain keyboard characters; for example, they may be key
+sequences or keyboard macro definitions.  However, storing keyboard
+characters in a string is a complex matter, for reasons of historical
+compatibility, and it is not always possible.
+
+  We recommend that new programs avoid dealing with these complexities
+by not storing keyboard events in strings.  Here is how to do that:
+
+@itemize @bullet
+@item
+Use vectors instead of strings for key sequences, when you plan to use
+them for anything other than as arguments to @code{lookup-key} and
+@code{define-key}.  For example, you can use
+@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
+@code{this-command-keys-vector} instead of @code{this-command-keys}.
+
+@item
+Use vectors to write key sequence constants containing meta characters,
+even when passing them directly to @code{define-key}.
+
+@item
+When you have to look at the contents of a key sequence that might be a
+string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
+first, to convert it to a list.
+@end itemize
+
+  The complexities stem from the modifier bits that keyboard input
+characters can include.  Aside from the Meta modifier, none of these
+modifier bits can be included in a string, and the Meta modifier is
+allowed only in special cases.
+
+  The earliest GNU Emacs versions represented meta characters as codes
+in the range of 128 to 255.  At that time, the basic character codes
+ranged from 0 to 127, so all keyboard character codes did fit in a
+string.  Many Lisp programs used @samp{\M-} in string constants to stand
+for meta characters, especially in arguments to @code{define-key} and
+similar functions, and key sequences and sequences of events were always
+represented as strings.
+
+  When we added support for larger basic character codes beyond 127, and
+additional modifier bits, we had to change the representation of meta
+characters.  Now the flag that represents the Meta modifier in a
+character is
+@tex
+@math{2^{27}}
+@end tex
+@ifnottex
+2**27
+@end ifnottex
+and such numbers cannot be included in a string.
+
+  To support programs with @samp{\M-} in string constants, there are
+special rules for including certain meta characters in a string.
+Here are the rules for interpreting a string as a sequence of input
+characters:
+
+@itemize @bullet
+@item
+If the keyboard character value is in the range of 0 to 127, it can go
+in the string unchanged.
+
+@item
+The meta variants of those characters, with codes in the range of
+@tex
+@math{2^{27}}
+@end tex
+@ifnottex
+2**27
+@end ifnottex
+to
+@tex
+@math{2^{27} + 127},
+@end tex
+@ifnottex
+2**27+127,
+@end ifnottex
+can also go in the string, but you must change their
+numeric values.  You must set the
+@tex
+@math{2^{7}}
+@end tex
+@ifnottex
+2**7
+@end ifnottex
+bit instead of the
+@tex
+@math{2^{27}}
+@end tex
+@ifnottex
+2**27
+@end ifnottex
+bit, resulting in a value between 128 and 255.  Only a unibyte string
+can include these codes.
+
+@item
+Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
+
+@item
+Other keyboard character events cannot fit in a string.  This includes
+keyboard events in the range of 128 to 255.
+@end itemize
+
+  Functions such as @code{read-key-sequence} that construct strings of
+keyboard input characters follow these rules: they construct vectors
+instead of strings, when the events won't fit in a string.
+
+  When you use the read syntax @samp{\M-} in a string, it produces a
+code in the range of 128 to 255---the same code that you get if you
+modify the corresponding keyboard event to put it in the string.  Thus,
+meta events in strings work consistently regardless of how they get into
+the strings.
+
+  However, most programs would do well to avoid these issues by
+following the recommendations at the beginning of this section.
+
+@node Reading Input
+@section Reading Input
+@cindex read input
+@cindex keyboard input
+
+  The editor command loop reads key sequences using the function
+@code{read-key-sequence}, which uses @code{read-event}.  These and other
+functions for event input are also available for use in Lisp programs.
+See also @code{momentary-string-display} in @ref{Temporary Displays},
+and @code{sit-for} in @ref{Waiting}.  @xref{Terminal Input}, for
+functions and variables for controlling terminal input modes and
+debugging terminal input.
+
+  For higher-level input facilities, see @ref{Minibuffers}.
+
+@menu
+* Key Sequence Input::		How to read one key sequence.
+* Reading One Event::		How to read just one event.
+* Event Mod::                   How Emacs modifies events as they are read.
+* Invoking the Input Method::   How reading an event uses the input method.
+* Quoted Character Input::	Asking the user to specify a character.
+* Event Input Misc::    	How to reread or throw away input events.
+@end menu
+
+@node Key Sequence Input
+@subsection Key Sequence Input
+@cindex key sequence input
+
+  The command loop reads input a key sequence at a time, by calling
+@code{read-key-sequence}.  Lisp programs can also call this function;
+for example, @code{describe-key} uses it to read the key to describe.
+
+@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
+This function reads a key sequence and returns it as a string or
+vector.  It keeps reading events until it has accumulated a complete key
+sequence; that is, enough to specify a non-prefix command using the
+currently active keymaps.  (Remember that a key sequence that starts
+with a mouse event is read using the keymaps of the buffer in the
+window that the mouse was in, not the current buffer.)
+
+If the events are all characters and all can fit in a string, then
+@code{read-key-sequence} returns a string (@pxref{Strings of Events}).
+Otherwise, it returns a vector, since a vector can hold all kinds of
+events---characters, symbols, and lists.  The elements of the string or
+vector are the events in the key sequence.
+
+Reading a key sequence includes translating the events in various
+ways.  @xref{Translation Keymaps}.
+
+The argument @var{prompt} is either a string to be displayed in the
+echo area as a prompt, or @code{nil}, meaning not to display a prompt.
+The argument @var{continue-echo}, if non-@code{nil}, means to echo
+this key as a continuation of the previous key.
+
+Normally any upper case event is converted to lower case if the
+original event is undefined and the lower case equivalent is defined.
+The argument @var{dont-downcase-last}, if non-@code{nil}, means do not
+convert the last event to lower case.  This is appropriate for reading
+a key sequence to be defined.
+
+The argument @var{switch-frame-ok}, if non-@code{nil}, means that this
+function should process a @code{switch-frame} event if the user
+switches frames before typing anything.  If the user switches frames
+in the middle of a key sequence, or at the start of the sequence but
+@var{switch-frame-ok} is @code{nil}, then the event will be put off
+until after the current key sequence.
+
+The argument @var{command-loop}, if non-@code{nil}, means that this
+key sequence is being read by something that will read commands one
+after another.  It should be @code{nil} if the caller will read just
+one key sequence.
+
+In the following example, Emacs displays the prompt @samp{?} in the
+echo area, and then the user types @kbd{C-x C-f}.
+
+@example
+(read-key-sequence "?")
+
+@group
+---------- Echo Area ----------
+?@kbd{C-x C-f}
+---------- Echo Area ----------
+
+     @result{} "^X^F"
+@end group
+@end example
+
+The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
+typed while reading with this function works like any other character,
+and does not set @code{quit-flag}.  @xref{Quitting}.
+@end defun
+
+@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
+This is like @code{read-key-sequence} except that it always
+returns the key sequence as a vector, never as a string.
+@xref{Strings of Events}.
+@end defun
+
+@cindex upper case key sequence
+@cindex downcasing in @code{lookup-key}
+If an input character is upper-case (or has the shift modifier) and
+has no key binding, but its lower-case equivalent has one, then
+@code{read-key-sequence} converts the character to lower case.  Note
+that @code{lookup-key} does not perform case conversion in this way.
+
+The function @code{read-key-sequence} also transforms some mouse events.
+It converts unbound drag events into click events, and discards unbound
+button-down events entirely.  It also reshuffles focus events and
+miscellaneous window events so that they never appear in a key sequence
+with any other events.
+
+@cindex @code{header-line} prefix key
+@cindex @code{mode-line} prefix key
+@cindex @code{vertical-line} prefix key
+@cindex @code{horizontal-scroll-bar} prefix key
+@cindex @code{vertical-scroll-bar} prefix key
+@cindex @code{menu-bar} prefix key
+@cindex mouse events, in special parts of frame
+When mouse events occur in special parts of a window, such as a mode
+line or a scroll bar, the event type shows nothing special---it is the
+same symbol that would normally represent that combination of mouse
+button and modifier keys.  The information about the window part is kept
+elsewhere in the event---in the coordinates.  But
+@code{read-key-sequence} translates this information into imaginary
+``prefix keys,'' all of which are symbols: @code{header-line},
+@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
+@code{vertical-line}, and @code{vertical-scroll-bar}.  You can define
+meanings for mouse clicks in special window parts by defining key
+sequences using these imaginary prefix keys.
+
+For example, if you call @code{read-key-sequence} and then click the
+mouse on the window's mode line, you get two events, like this:
+
+@example
+(read-key-sequence "Click on the mode line: ")
+     @result{} [mode-line
+         (mouse-1
+          (#<window 6 on NEWS> mode-line
+           (40 . 63) 5959987))]
+@end example
+
+@defvar num-input-keys
+@c Emacs 19 feature
+This variable's value is the number of key sequences processed so far in
+this Emacs session.  This includes key sequences read from the terminal
+and key sequences read from keyboard macros being executed.
+@end defvar
+
+@node Reading One Event
+@subsection Reading One Event
+@cindex reading a single event
+@cindex event, reading only one
+
+  The lowest level functions for command input are those that read a
+single event.
+
+None of the three functions below suppresses quitting.
+
+@defun read-event &optional prompt inherit-input-method seconds
+This function reads and returns the next event of command input, waiting
+if necessary until an event is available.  Events can come directly from
+the user or from a keyboard macro.
+
+If the optional argument @var{prompt} is non-@code{nil}, it should be a
+string to display in the echo area as a prompt.  Otherwise,
+@code{read-event} does not display any message to indicate it is waiting
+for input; instead, it prompts by echoing: it displays descriptions of
+the events that led to or were read by the current command.  @xref{The
+Echo Area}.
+
+If @var{inherit-input-method} is non-@code{nil}, then the current input
+method (if any) is employed to make it possible to enter a
+non-@acronym{ASCII} character.  Otherwise, input method handling is disabled
+for reading this event.
+
+If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
+moves the cursor temporarily to the echo area, to the end of any message
+displayed there.  Otherwise @code{read-event} does not move the cursor.
+
+If @var{seconds} is non-@code{nil}, it should be a number specifying
+the maximum time to wait for input, in seconds.  If no input arrives
+within that time, @code{read-event} stops waiting and returns
+@code{nil}.  A floating-point value for @var{seconds} means to wait
+for a fractional number of seconds.  Some systems support only a whole
+number of seconds; on these systems, @var{seconds} is rounded down.
+If @var{seconds} is @code{nil}, @code{read-event} waits as long as
+necessary for input to arrive.
+
+If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
+for user input to arrive.  Idle timers---those created with
+@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
+period.  However, if @var{seconds} is non-@code{nil}, the state of
+idleness remains unchanged.  If Emacs is non-idle when
+@code{read-event} is called, it remains non-idle throughout the
+operation of @code{read-event}; if Emacs is idle (which can happen if
+the call happens inside an idle timer), it remains idle.
+
+If @code{read-event} gets an event that is defined as a help character,
+then in some cases @code{read-event} processes the event directly without
+returning.  @xref{Help Functions}.  Certain other events, called
+@dfn{special events}, are also processed directly within
+@code{read-event} (@pxref{Special Events}).
+
+Here is what happens if you call @code{read-event} and then press the
+right-arrow function key:
+
+@example
+@group
+(read-event)
+     @result{} right
+@end group
+@end example
+@end defun
+
+@defun read-char &optional prompt inherit-input-method seconds
+This function reads and returns a character of command input.  If the
+user generates an event which is not a character (i.e. a mouse click or
+function key event), @code{read-char} signals an error.  The arguments
+work as in @code{read-event}.
+
+In the first example, the user types the character @kbd{1} (@acronym{ASCII}
+code 49).  The second example shows a keyboard macro definition that
+calls @code{read-char} from the minibuffer using @code{eval-expression}.
+@code{read-char} reads the keyboard macro's very next character, which
+is @kbd{1}.  Then @code{eval-expression} displays its return value in
+the echo area.
+
+@example
+@group
+(read-char)
+     @result{} 49
+@end group
+
+@group
+;; @r{We assume here you use @kbd{M-:} to evaluate this.}
+(symbol-function 'foo)
+     @result{} "^[:(read-char)^M1"
+@end group
+@group
+(execute-kbd-macro 'foo)
+     @print{} 49
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun read-char-exclusive &optional prompt inherit-input-method seconds
+This function reads and returns a character of command input.  If the
+user generates an event which is not a character,
+@code{read-char-exclusive} ignores it and reads another event, until it
+gets a character.  The arguments work as in @code{read-event}.
+@end defun
+
+@defvar num-nonmacro-input-events
+This variable holds the total number of input events received so far
+from the terminal---not counting those generated by keyboard macros.
+@end defvar
+
+@node Event Mod
+@subsection Modifying and Translating Input Events
+
+  Emacs modifies every event it reads according to
+@code{extra-keyboard-modifiers}, then translates it through
+@code{keyboard-translate-table} (if applicable), before returning it
+from @code{read-event}.
+
+@c Emacs 19 feature
+@defvar extra-keyboard-modifiers
+This variable lets Lisp programs ``press'' the modifier keys on the
+keyboard.  The value is a character.  Only the modifiers of the
+character matter.  Each time the user types a keyboard key, it is
+altered as if those modifier keys were held down.  For instance, if
+you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
+keyboard input characters typed during the scope of the binding will
+have the control and meta modifiers applied to them.  The character
+@code{?\C-@@}, equivalent to the integer 0, does not count as a control
+character for this purpose, but as a character with no modifiers.
+Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
+modification.
+
+When using a window system, the program can ``press'' any of the
+modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
+keys can be virtually pressed.
+
+Note that this variable applies only to events that really come from
+the keyboard, and has no effect on mouse events or any other events.
+@end defvar
+
+@defvar keyboard-translate-table
+This variable is the translate table for keyboard characters.  It lets
+you reshuffle the keys on the keyboard without changing any command
+bindings.  Its value is normally a char-table, or else @code{nil}.
+(It can also be a string or vector, but this is considered obsolete.)
+
+If @code{keyboard-translate-table} is a char-table
+(@pxref{Char-Tables}), then each character read from the keyboard is
+looked up in this char-table.  If the value found there is
+non-@code{nil}, then it is used instead of the actual input character.
+
+Note that this translation is the first thing that happens to a
+character after it is read from the terminal.  Record-keeping features
+such as @code{recent-keys} and dribble files record the characters after
+translation.
+
+Note also that this translation is done before the characters are
+supplied to input methods (@pxref{Input Methods}).  Use
+@code{translation-table-for-input} (@pxref{Translation of Characters}),
+if you want to translate characters after input methods operate.
+@end defvar
+
+@defun keyboard-translate from to
+This function modifies @code{keyboard-translate-table} to translate
+character code @var{from} into character code @var{to}.  It creates
+the keyboard translate table if necessary.
+@end defun
+
+  Here's an example of using the @code{keyboard-translate-table} to
+make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
+operations:
+
+@example
+(keyboard-translate ?\C-x 'control-x)
+(keyboard-translate ?\C-c 'control-c)
+(keyboard-translate ?\C-v 'control-v)
+(global-set-key [control-x] 'kill-region)
+(global-set-key [control-c] 'kill-ring-save)
+(global-set-key [control-v] 'yank)
+@end example
+
+@noindent
+On a graphical terminal that supports extended @acronym{ASCII} input,
+you can still get the standard Emacs meanings of one of those
+characters by typing it with the shift key.  That makes it a different
+character as far as keyboard translation is concerned, but it has the
+same usual meaning.
+
+  @xref{Translation Keymaps}, for mechanisms that translate event sequences
+at the level of @code{read-key-sequence}.
+
+@node Invoking the Input Method
+@subsection Invoking the Input Method
+
+  The event-reading functions invoke the current input method, if any
+(@pxref{Input Methods}).  If the value of @code{input-method-function}
+is non-@code{nil}, it should be a function; when @code{read-event} reads
+a printing character (including @key{SPC}) with no modifier bits, it
+calls that function, passing the character as an argument.
+
+@defvar input-method-function
+If this is non-@code{nil}, its value specifies the current input method
+function.
+
+@strong{Warning:} don't bind this variable with @code{let}.  It is often
+buffer-local, and if you bind it around reading input (which is exactly
+when you @emph{would} bind it), switching buffers asynchronously while
+Emacs is waiting will cause the value to be restored in the wrong
+buffer.
+@end defvar
+
+  The input method function should return a list of events which should
+be used as input.  (If the list is @code{nil}, that means there is no
+input, so @code{read-event} waits for another event.)  These events are
+processed before the events in @code{unread-command-events}
+(@pxref{Event Input Misc}).  Events
+returned by the input method function are not passed to the input method
+function again, even if they are printing characters with no modifier
+bits.
+
+  If the input method function calls @code{read-event} or
+@code{read-key-sequence}, it should bind @code{input-method-function} to
+@code{nil} first, to prevent recursion.
+
+  The input method function is not called when reading the second and
+subsequent events of a key sequence.  Thus, these characters are not
+subject to input method processing.  The input method function should
+test the values of @code{overriding-local-map} and
+@code{overriding-terminal-local-map}; if either of these variables is
+non-@code{nil}, the input method should put its argument into a list and
+return that list with no further processing.
+
+@node Quoted Character Input
+@subsection Quoted Character Input
+@cindex quoted character input
+
+  You can use the function @code{read-quoted-char} to ask the user to
+specify a character, and allow the user to specify a control or meta
+character conveniently, either literally or as an octal character code.
+The command @code{quoted-insert} uses this function.
+
+@defun read-quoted-char &optional prompt
+@cindex octal character input
+@cindex control characters, reading
+@cindex nonprinting characters, reading
+This function is like @code{read-char}, except that if the first
+character read is an octal digit (0-7), it reads any number of octal
+digits (but stopping if a non-octal digit is found), and returns the
+character represented by that numeric character code.  If the
+character that terminates the sequence of octal digits is @key{RET},
+it is discarded.  Any other terminating character is used as input
+after this function returns.
+
+Quitting is suppressed when the first character is read, so that the
+user can enter a @kbd{C-g}.  @xref{Quitting}.
+
+If @var{prompt} is supplied, it specifies a string for prompting the
+user.  The prompt string is always displayed in the echo area, followed
+by a single @samp{-}.
+
+In the following example, the user types in the octal number 177 (which
+is 127 in decimal).
+
+@example
+(read-quoted-char "What character")
+
+@group
+---------- Echo Area ----------
+What character @kbd{1 7 7}-
+---------- Echo Area ----------
+
+     @result{} 127
+@end group
+@end example
+@end defun
+
+@need 2000
+@node Event Input Misc
+@subsection Miscellaneous Event Input Features
+
+This section describes how to ``peek ahead'' at events without using
+them up, how to check for pending input, and how to discard pending
+input.  See also the function @code{read-passwd} (@pxref{Reading a
+Password}).
+
+@defvar unread-command-events
+@cindex next input
+@cindex peeking at input
+This variable holds a list of events waiting to be read as command
+input.  The events are used in the order they appear in the list, and
+removed one by one as they are used.
+
+The variable is needed because in some cases a function reads an event
+and then decides not to use it.  Storing the event in this variable
+causes it to be processed normally, by the command loop or by the
+functions to read command input.
+
+@cindex prefix argument unreading
+For example, the function that implements numeric prefix arguments reads
+any number of digits.  When it finds a non-digit event, it must unread
+the event so that it can be read normally by the command loop.
+Likewise, incremental search uses this feature to unread events with no
+special meaning in a search, because these events should exit the search
+and then execute normally.
+
+The reliable and easy way to extract events from a key sequence so as to
+put them in @code{unread-command-events} is to use
+@code{listify-key-sequence} (@pxref{Strings of Events}).
+
+Normally you add events to the front of this list, so that the events
+most recently unread will be reread first.
+
+Events read from this list are not normally added to the current
+command's key sequence (as returned by e.g. @code{this-command-keys}),
+as the events will already have been added once as they were read for
+the first time.  An element of the form @code{(@code{t} . @var{event})}
+forces @var{event} to be added to the current command's key sequence.
+@end defvar
+
+@defun listify-key-sequence key
+This function converts the string or vector @var{key} to a list of
+individual events, which you can put in @code{unread-command-events}.
+@end defun
+
+@defvar unread-command-char
+This variable holds a character to be read as command input.
+A value of -1 means ``empty.''
+
+This variable is mostly obsolete now that you can use
+@code{unread-command-events} instead; it exists only to support programs
+written for Emacs versions 18 and earlier.
+@end defvar
+
+@defun input-pending-p
+@cindex waiting for command key input
+This function determines whether any command input is currently
+available to be read.  It returns immediately, with value @code{t} if
+there is available input, @code{nil} otherwise.  On rare occasions it
+may return @code{t} when no input is available.
+@end defun
+
+@defvar last-input-event
+@defvarx last-input-char
+This variable records the last terminal input event read, whether
+as part of a command or explicitly by a Lisp program.
+
+In the example below, the Lisp program reads the character @kbd{1},
+@acronym{ASCII} code 49.  It becomes the value of @code{last-input-event},
+while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
+this expression) remains the value of @code{last-command-event}.
+
+@example
+@group
+(progn (print (read-char))
+       (print last-command-event)
+       last-input-event)
+     @print{} 49
+     @print{} 5
+     @result{} 49
+@end group
+@end example
+
+The alias @code{last-input-char} exists for compatibility with
+Emacs version 18.
+@end defvar
+
+@defmac while-no-input body@dots{}
+This construct runs the @var{body} forms and returns the value of the
+last one---but only if no input arrives.  If any input arrives during
+the execution of the @var{body} forms, it aborts them (working much
+like a quit).  The @code{while-no-input} form returns @code{nil} if
+aborted by a real quit, and returns @code{t} if aborted by arrival of
+other input.
+
+If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
+arrival of input during those parts won't cause an abort until
+the end of that part.
+
+If you want to be able to distinguish all possible values computed
+by @var{body} from both kinds of abort conditions, write the code
+like this:
+
+@example
+(while-no-input
+  (list
+    (progn . @var{body})))
+@end example
+@end defmac
+
+@defun discard-input
+@cindex flushing input
+@cindex discarding input
+@cindex keyboard macro, terminating
+This function discards the contents of the terminal input buffer and
+cancels any keyboard macro that might be in the process of definition.
+It returns @code{nil}.
+
+In the following example, the user may type a number of characters right
+after starting the evaluation of the form.  After the @code{sleep-for}
+finishes sleeping, @code{discard-input} discards any characters typed
+during the sleep.
+
+@example
+(progn (sleep-for 2)
+       (discard-input))
+     @result{} nil
+@end example
+@end defun
+
+@node Special Events
+@section Special Events
+
+@cindex special events
+Special events are handled at a very low level---as soon as they are
+read.  The @code{read-event} function processes these events itself, and
+never returns them.  Instead, it keeps waiting for the first event
+that is not special and returns that one.
+
+Events that are handled in this way do not echo, they are never grouped
+into key sequences, and they never appear in the value of
+@code{last-command-event} or @code{(this-command-keys)}.  They do not
+discard a numeric argument, they cannot be unread with
+@code{unread-command-events}, they may not appear in a keyboard macro,
+and they are not recorded in a keyboard macro while you are defining
+one.
+
+These events do, however, appear in @code{last-input-event} immediately
+after they are read, and this is the way for the event's definition to
+find the actual event.
+
+The events types @code{iconify-frame}, @code{make-frame-visible},
+@code{delete-frame}, @code{drag-n-drop}, and user signals like
+@code{sigusr1} are normally handled in this way.  The keymap which
+defines how to handle special events---and which events are special---is
+in the variable @code{special-event-map} (@pxref{Active Keymaps}).
+
+@node Waiting
+@section Waiting for Elapsed Time or Input
+@cindex waiting
+
+  The wait functions are designed to wait for a certain amount of time
+to pass or until there is input.  For example, you may wish to pause in
+the middle of a computation to allow the user time to view the display.
+@code{sit-for} pauses and updates the screen, and returns immediately if
+input comes in, while @code{sleep-for} pauses without updating the
+screen.
+
+@defun sit-for seconds &optional nodisp
+This function performs redisplay (provided there is no pending input
+from the user), then waits @var{seconds} seconds, or until input is
+available.  The usual purpose of @code{sit-for} is to give the user
+time to read text that you display.  The value is @code{t} if
+@code{sit-for} waited the full time with no input arriving
+(@pxref{Event Input Misc}).  Otherwise, the value is @code{nil}.
+
+The argument @var{seconds} need not be an integer.  If it is a floating
+point number, @code{sit-for} waits for a fractional number of seconds.
+Some systems support only a whole number of seconds; on these systems,
+@var{seconds} is rounded down.
+
+The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)},
+i.e. it requests a redisplay, without any delay, if there is no pending input.
+@xref{Forcing Redisplay}.
+
+If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
+redisplay, but it still returns as soon as input is available (or when
+the timeout elapses).
+
+In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be
+interrupted, even by input from the standard input descriptor.  It is
+thus equivalent to @code{sleep-for}, which is described below.
+
+It is also possible to call @code{sit-for} with three arguments,
+as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
+but that is considered obsolete.
+@end defun
+
+@defun sleep-for seconds &optional millisec
+This function simply pauses for @var{seconds} seconds without updating
+the display.  It pays no attention to available input.  It returns
+@code{nil}.
+
+The argument @var{seconds} need not be an integer.  If it is a floating
+point number, @code{sleep-for} waits for a fractional number of seconds.
+Some systems support only a whole number of seconds; on these systems,
+@var{seconds} is rounded down.
+
+The optional argument @var{millisec} specifies an additional waiting
+period measured in milliseconds.  This adds to the period specified by
+@var{seconds}.  If the system doesn't support waiting fractions of a
+second, you get an error if you specify nonzero @var{millisec}.
+
+Use @code{sleep-for} when you wish to guarantee a delay.
+@end defun
+
+  @xref{Time of Day}, for functions to get the current time.
+
+@node Quitting
+@section Quitting
+@cindex @kbd{C-g}
+@cindex quitting
+@cindex interrupt Lisp functions
+
+  Typing @kbd{C-g} while a Lisp function is running causes Emacs to
+@dfn{quit} whatever it is doing.  This means that control returns to the
+innermost active command loop.
+
+  Typing @kbd{C-g} while the command loop is waiting for keyboard input
+does not cause a quit; it acts as an ordinary input character.  In the
+simplest case, you cannot tell the difference, because @kbd{C-g}
+normally runs the command @code{keyboard-quit}, whose effect is to quit.
+However, when @kbd{C-g} follows a prefix key, they combine to form an
+undefined key.  The effect is to cancel the prefix key as well as any
+prefix argument.
+
+  In the minibuffer, @kbd{C-g} has a different definition: it aborts out
+of the minibuffer.  This means, in effect, that it exits the minibuffer
+and then quits.  (Simply quitting would return to the command loop
+@emph{within} the minibuffer.)  The reason why @kbd{C-g} does not quit
+directly when the command reader is reading input is so that its meaning
+can be redefined in the minibuffer in this way.  @kbd{C-g} following a
+prefix key is not redefined in the minibuffer, and it has its normal
+effect of canceling the prefix key and prefix argument.  This too
+would not be possible if @kbd{C-g} always quit directly.
+
+  When @kbd{C-g} does directly quit, it does so by setting the variable
+@code{quit-flag} to @code{t}.  Emacs checks this variable at appropriate
+times and quits if it is not @code{nil}.  Setting @code{quit-flag}
+non-@code{nil} in any way thus causes a quit.
+
+  At the level of C code, quitting cannot happen just anywhere; only at the
+special places that check @code{quit-flag}.  The reason for this is
+that quitting at other places might leave an inconsistency in Emacs's
+internal state.  Because quitting is delayed until a safe place, quitting
+cannot make Emacs crash.
+
+  Certain functions such as @code{read-key-sequence} or
+@code{read-quoted-char} prevent quitting entirely even though they wait
+for input.  Instead of quitting, @kbd{C-g} serves as the requested
+input.  In the case of @code{read-key-sequence}, this serves to bring
+about the special behavior of @kbd{C-g} in the command loop.  In the
+case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
+to quote a @kbd{C-g}.
+
+@cindex preventing quitting
+  You can prevent quitting for a portion of a Lisp function by binding
+the variable @code{inhibit-quit} to a non-@code{nil} value.  Then,
+although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
+usual result of this---a quit---is prevented.  Eventually,
+@code{inhibit-quit} will become @code{nil} again, such as when its
+binding is unwound at the end of a @code{let} form.  At that time, if
+@code{quit-flag} is still non-@code{nil}, the requested quit happens
+immediately.  This behavior is ideal when you wish to make sure that
+quitting does not happen within a ``critical section'' of the program.
+
+@cindex @code{read-quoted-char} quitting
+  In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
+handled in a special way that does not involve quitting.  This is done
+by reading the input with @code{inhibit-quit} bound to @code{t}, and
+setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
+becomes @code{nil} again.  This excerpt from the definition of
+@code{read-quoted-char} shows how this is done; it also shows that
+normal quitting is permitted after the first character of input.
+
+@example
+(defun read-quoted-char (&optional prompt)
+  "@dots{}@var{documentation}@dots{}"
+  (let ((message-log-max nil) done (first t) (code 0) char)
+    (while (not done)
+      (let ((inhibit-quit first)
+            @dots{})
+	(and prompt (message "%s-" prompt))
+	(setq char (read-event))
+	(if inhibit-quit (setq quit-flag nil)))
+      @r{@dots{}set the variable @code{code}@dots{}})
+    code))
+@end example
+
+@defvar quit-flag
+If this variable is non-@code{nil}, then Emacs quits immediately, unless
+@code{inhibit-quit} is non-@code{nil}.  Typing @kbd{C-g} ordinarily sets
+@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
+@end defvar
+
+@defvar inhibit-quit
+This variable determines whether Emacs should quit when @code{quit-flag}
+is set to a value other than @code{nil}.  If @code{inhibit-quit} is
+non-@code{nil}, then @code{quit-flag} has no special effect.
+@end defvar
+
+@defmac with-local-quit body@dots{}
+This macro executes @var{body} forms in sequence, but allows quitting, at
+least locally, within @var{body} even if @code{inhibit-quit} was
+non-@code{nil} outside this construct.  It returns the value of the
+last form in @var{body}, unless exited by quitting, in which case
+it returns @code{nil}.
+
+If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
+it only executes the @var{body}, and setting @code{quit-flag} causes
+a normal quit.  However, if @code{inhibit-quit} is non-@code{nil} so
+that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
+triggers a special kind of local quit.  This ends the execution of
+@var{body} and exits the @code{with-local-quit} body with
+@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
+will happen as soon as that is allowed.  If @code{quit-flag} is
+already non-@code{nil} at the beginning of @var{body}, the local quit
+happens immediately and the body doesn't execute at all.
+
+This macro is mainly useful in functions that can be called from
+timers, process filters, process sentinels, @code{pre-command-hook},
+@code{post-command-hook}, and other places where @code{inhibit-quit} is
+normally bound to @code{t}.
+@end defmac
+
+@deffn Command keyboard-quit
+This function signals the @code{quit} condition with @code{(signal 'quit
+nil)}.  This is the same thing that quitting does.  (See @code{signal}
+in @ref{Errors}.)
+@end deffn
+
+  You can specify a character other than @kbd{C-g} to use for quitting.
+See the function @code{set-input-mode} in @ref{Terminal Input}.
+
+@node Prefix Command Arguments
+@section Prefix Command Arguments
+@cindex prefix argument
+@cindex raw prefix argument
+@cindex numeric prefix argument
+
+  Most Emacs commands can use a @dfn{prefix argument}, a number
+specified before the command itself.  (Don't confuse prefix arguments
+with prefix keys.)  The prefix argument is at all times represented by a
+value, which may be @code{nil}, meaning there is currently no prefix
+argument.  Each command may use the prefix argument or ignore it.
+
+  There are two representations of the prefix argument: @dfn{raw} and
+@dfn{numeric}.  The editor command loop uses the raw representation
+internally, and so do the Lisp variables that store the information, but
+commands can request either representation.
+
+  Here are the possible values of a raw prefix argument:
+
+@itemize @bullet
+@item
+@code{nil}, meaning there is no prefix argument.  Its numeric value is
+1, but numerous commands make a distinction between @code{nil} and the
+integer 1.
+
+@item
+An integer, which stands for itself.
+
+@item
+A list of one element, which is an integer.  This form of prefix
+argument results from one or a succession of @kbd{C-u}'s with no
+digits.  The numeric value is the integer in the list, but some
+commands make a distinction between such a list and an integer alone.
+
+@item
+The symbol @code{-}.  This indicates that @kbd{M--} or @kbd{C-u -} was
+typed, without following digits.  The equivalent numeric value is
+@minus{}1, but some commands make a distinction between the integer
+@minus{}1 and the symbol @code{-}.
+@end itemize
+
+We illustrate these possibilities by calling the following function with
+various prefixes:
+
+@example
+@group
+(defun display-prefix (arg)
+  "Display the value of the raw prefix arg."
+  (interactive "P")
+  (message "%s" arg))
+@end group
+@end example
+
+@noindent
+Here are the results of calling @code{display-prefix} with various
+raw prefix arguments:
+
+@example
+        M-x display-prefix  @print{} nil
+
+C-u     M-x display-prefix  @print{} (4)
+
+C-u C-u M-x display-prefix  @print{} (16)
+
+C-u 3   M-x display-prefix  @print{} 3
+
+M-3     M-x display-prefix  @print{} 3      ; @r{(Same as @code{C-u 3}.)}
+
+C-u -   M-x display-prefix  @print{} -
+
+M--     M-x display-prefix  @print{} -      ; @r{(Same as @code{C-u -}.)}
+
+C-u - 7 M-x display-prefix  @print{} -7
+
+M-- 7   M-x display-prefix  @print{} -7     ; @r{(Same as @code{C-u -7}.)}
+@end example
+
+  Emacs uses two variables to store the prefix argument:
+@code{prefix-arg} and @code{current-prefix-arg}.  Commands such as
+@code{universal-argument} that set up prefix arguments for other
+commands store them in @code{prefix-arg}.  In contrast,
+@code{current-prefix-arg} conveys the prefix argument to the current
+command, so setting it has no effect on the prefix arguments for future
+commands.
+
+  Normally, commands specify which representation to use for the prefix
+argument, either numeric or raw, in the @code{interactive} specification.
+(@xref{Using Interactive}.)  Alternatively, functions may look at the
+value of the prefix argument directly in the variable
+@code{current-prefix-arg}, but this is less clean.
+
+@defun prefix-numeric-value arg
+This function returns the numeric meaning of a valid raw prefix argument
+value, @var{arg}.  The argument may be a symbol, a number, or a list.
+If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
+value @minus{}1 is returned; if it is a number, that number is returned;
+if it is a list, the @sc{car} of that list (which should be a number) is
+returned.
+@end defun
+
+@defvar current-prefix-arg
+This variable holds the raw prefix argument for the @emph{current}
+command.  Commands may examine it directly, but the usual method for
+accessing it is with @code{(interactive "P")}.
+@end defvar
+
+@defvar prefix-arg
+The value of this variable is the raw prefix argument for the
+@emph{next} editing command.  Commands such as @code{universal-argument}
+that specify prefix arguments for the following command work by setting
+this variable.
+@end defvar
+
+@defvar last-prefix-arg
+The raw prefix argument value used by the previous command.
+@end defvar
+
+  The following commands exist to set up prefix arguments for the
+following command.  Do not call them for any other reason.
+
+@deffn Command universal-argument
+This command reads input and specifies a prefix argument for the
+following command.  Don't call this command yourself unless you know
+what you are doing.
+@end deffn
+
+@deffn Command digit-argument arg
+This command adds to the prefix argument for the following command.  The
+argument @var{arg} is the raw prefix argument as it was before this
+command; it is used to compute the updated prefix argument.  Don't call
+this command yourself unless you know what you are doing.
+@end deffn
+
+@deffn Command negative-argument arg
+This command adds to the numeric argument for the next command.  The
+argument @var{arg} is the raw prefix argument as it was before this
+command; its value is negated to form the new prefix argument.  Don't
+call this command yourself unless you know what you are doing.
+@end deffn
+
+@node Recursive Editing
+@section Recursive Editing
+@cindex recursive command loop
+@cindex recursive editing level
+@cindex command loop, recursive
+
+  The Emacs command loop is entered automatically when Emacs starts up.
+This top-level invocation of the command loop never exits; it keeps
+running as long as Emacs does.  Lisp programs can also invoke the
+command loop.  Since this makes more than one activation of the command
+loop, we call it @dfn{recursive editing}.  A recursive editing level has
+the effect of suspending whatever command invoked it and permitting the
+user to do arbitrary editing before resuming that command.
+
+  The commands available during recursive editing are the same ones
+available in the top-level editing loop and defined in the keymaps.
+Only a few special commands exit the recursive editing level; the others
+return to the recursive editing level when they finish.  (The special
+commands for exiting are always available, but they do nothing when
+recursive editing is not in progress.)
+
+  All command loops, including recursive ones, set up all-purpose error
+handlers so that an error in a command run from the command loop will
+not exit the loop.
+
+@cindex minibuffer input
+  Minibuffer input is a special kind of recursive editing.  It has a few
+special wrinkles, such as enabling display of the minibuffer and the
+minibuffer window, but fewer than you might suppose.  Certain keys
+behave differently in the minibuffer, but that is only because of the
+minibuffer's local map; if you switch windows, you get the usual Emacs
+commands.
+
+@cindex @code{throw} example
+@kindex exit
+@cindex exit recursive editing
+@cindex aborting
+  To invoke a recursive editing level, call the function
+@code{recursive-edit}.  This function contains the command loop; it also
+contains a call to @code{catch} with tag @code{exit}, which makes it
+possible to exit the recursive editing level by throwing to @code{exit}
+(@pxref{Catch and Throw}).  If you throw a value other than @code{t},
+then @code{recursive-edit} returns normally to the function that called
+it.  The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
+Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
+control returns to the command loop one level up.  This is called
+@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
+
+  Most applications should not use recursive editing, except as part of
+using the minibuffer.  Usually it is more convenient for the user if you
+change the major mode of the current buffer temporarily to a special
+major mode, which should have a command to go back to the previous mode.
+(The @kbd{e} command in Rmail uses this technique.)  Or, if you wish to
+give the user different text to edit ``recursively,'' create and select
+a new buffer in a special mode.  In this mode, define a command to
+complete the processing and go back to the previous buffer.  (The
+@kbd{m} command in Rmail does this.)
+
+  Recursive edits are useful in debugging.  You can insert a call to
+@code{debug} into a function definition as a sort of breakpoint, so that
+you can look around when the function gets there.  @code{debug} invokes
+a recursive edit but also provides the other features of the debugger.
+
+  Recursive editing levels are also used when you type @kbd{C-r} in
+@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
+
+@defun recursive-edit
+@cindex suspend evaluation
+This function invokes the editor command loop.  It is called
+automatically by the initialization of Emacs, to let the user begin
+editing.  When called from a Lisp program, it enters a recursive editing
+level.
+
+If the current buffer is not the same as the selected window's buffer,
+@code{recursive-edit} saves and restores the current buffer.  Otherwise,
+if you switch buffers, the buffer you switched to is current after
+@code{recursive-edit} returns.
+
+In the following example, the function @code{simple-rec} first
+advances point one word, then enters a recursive edit, printing out a
+message in the echo area.  The user can then do any editing desired, and
+then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
+
+@example
+(defun simple-rec ()
+  (forward-word 1)
+  (message "Recursive edit in progress")
+  (recursive-edit)
+  (forward-word 1))
+     @result{} simple-rec
+(simple-rec)
+     @result{} nil
+@end example
+@end defun
+
+@deffn Command exit-recursive-edit
+This function exits from the innermost recursive edit (including
+minibuffer input).  Its definition is effectively @code{(throw 'exit
+nil)}.
+@end deffn
+
+@deffn Command abort-recursive-edit
+This function aborts the command that requested the innermost recursive
+edit (including minibuffer input), by signaling @code{quit}
+after exiting the recursive edit.  Its definition is effectively
+@code{(throw 'exit t)}.  @xref{Quitting}.
+@end deffn
+
+@deffn Command top-level
+This function exits all recursive editing levels; it does not return a
+value, as it jumps completely out of any computation directly back to
+the main command loop.
+@end deffn
+
+@defun recursion-depth
+This function returns the current depth of recursive edits.  When no
+recursive edit is active, it returns 0.
+@end defun
+
+@node Disabling Commands
+@section Disabling Commands
+@cindex disabled command
+
+  @dfn{Disabling a command} marks the command as requiring user
+confirmation before it can be executed.  Disabling is used for commands
+which might be confusing to beginning users, to prevent them from using
+the commands by accident.
+
+@kindex disabled
+  The low-level mechanism for disabling a command is to put a
+non-@code{nil} @code{disabled} property on the Lisp symbol for the
+command.  These properties are normally set up by the user's
+init file (@pxref{Init File}) with Lisp expressions such as this:
+
+@example
+(put 'upcase-region 'disabled t)
+@end example
+
+@noindent
+For a few commands, these properties are present by default (you can
+remove them in your init file if you wish).
+
+  If the value of the @code{disabled} property is a string, the message
+saying the command is disabled includes that string.  For example:
+
+@example
+(put 'delete-region 'disabled
+     "Text deleted this way cannot be yanked back!\n")
+@end example
+
+  @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
+what happens when a disabled command is invoked interactively.
+Disabling a command has no effect on calling it as a function from Lisp
+programs.
+
+@deffn Command enable-command command
+Allow @var{command} (a symbol) to be executed without special
+confirmation from now on, and alter the user's init file (@pxref{Init
+File}) so that this will apply to future sessions.
+@end deffn
+
+@deffn Command disable-command command
+Require special confirmation to execute @var{command} from now on, and
+alter the user's init file so that this will apply to future sessions.
+@end deffn
+
+@defvar disabled-command-function
+The value of this variable should be a function.  When the user
+invokes a disabled command interactively, this function is called
+instead of the disabled command.  It can use @code{this-command-keys}
+to determine what the user typed to run the command, and thus find the
+command itself.
+
+The value may also be @code{nil}.  Then all commands work normally,
+even disabled ones.
+
+By default, the value is a function that asks the user whether to
+proceed.
+@end defvar
+
+@node Command History
+@section Command History
+@cindex command history
+@cindex complex command
+@cindex history of commands
+
+  The command loop keeps a history of the complex commands that have
+been executed, to make it convenient to repeat these commands.  A
+@dfn{complex command} is one for which the interactive argument reading
+uses the minibuffer.  This includes any @kbd{M-x} command, any
+@kbd{M-:} command, and any command whose @code{interactive}
+specification reads an argument from the minibuffer.  Explicit use of
+the minibuffer during the execution of the command itself does not cause
+the command to be considered complex.
+
+@defvar command-history
+This variable's value is a list of recent complex commands, each
+represented as a form to evaluate.  It continues to accumulate all
+complex commands for the duration of the editing session, but when it
+reaches the maximum size (@pxref{Minibuffer History}), the oldest
+elements are deleted as new ones are added.
+
+@example
+@group
+command-history
+@result{} ((switch-to-buffer "chistory.texi")
+    (describe-key "^X^[")
+    (visit-tags-table "~/emacs/src/")
+    (find-tag "repeat-complex-command"))
+@end group
+@end example
+@end defvar
+
+  This history list is actually a special case of minibuffer history
+(@pxref{Minibuffer History}), with one special twist: the elements are
+expressions rather than strings.
+
+  There are a number of commands devoted to the editing and recall of
+previous commands.  The commands @code{repeat-complex-command}, and
+@code{list-command-history} are described in the user manual
+(@pxref{Repetition,,, emacs, The GNU Emacs Manual}).  Within the
+minibuffer, the usual minibuffer history commands are available.
+
+@node Keyboard Macros
+@section Keyboard Macros
+@cindex keyboard macros
+
+  A @dfn{keyboard macro} is a canned sequence of input events that can
+be considered a command and made the definition of a key.  The Lisp
+representation of a keyboard macro is a string or vector containing the
+events.  Don't confuse keyboard macros with Lisp macros
+(@pxref{Macros}).
+
+@defun execute-kbd-macro kbdmacro &optional count loopfunc
+This function executes @var{kbdmacro} as a sequence of events.  If
+@var{kbdmacro} is a string or vector, then the events in it are executed
+exactly as if they had been input by the user.  The sequence is
+@emph{not} expected to be a single key sequence; normally a keyboard
+macro definition consists of several key sequences concatenated.
+
+If @var{kbdmacro} is a symbol, then its function definition is used in
+place of @var{kbdmacro}.  If that is another symbol, this process repeats.
+Eventually the result should be a string or vector.  If the result is
+not a symbol, string, or vector, an error is signaled.
+
+The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
+many times.  If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
+executed once.  If it is 0, @var{kbdmacro} is executed over and over until it
+encounters an error or a failing search.
+
+If @var{loopfunc} is non-@code{nil}, it is a function that is called,
+without arguments, prior to each iteration of the macro.  If
+@var{loopfunc} returns @code{nil}, then this stops execution of the macro.
+
+@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
+@end defun
+
+@defvar executing-kbd-macro
+This variable contains the string or vector that defines the keyboard
+macro that is currently executing.  It is @code{nil} if no macro is
+currently executing.  A command can test this variable so as to behave
+differently when run from an executing macro.  Do not set this variable
+yourself.
+@end defvar
+
+@defvar defining-kbd-macro
+This variable is non-@code{nil} if and only if a keyboard macro is
+being defined.  A command can test this variable so as to behave
+differently while a macro is being defined.  The value is
+@code{append} while appending to the definition of an existing macro.
+The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and
+@code{end-kbd-macro} set this variable---do not set it yourself.
+
+The variable is always local to the current terminal and cannot be
+buffer-local.  @xref{Multiple Displays}.
+@end defvar
+
+@defvar last-kbd-macro
+This variable is the definition of the most recently defined keyboard
+macro.  Its value is a string or vector, or @code{nil}.
+
+The variable is always local to the current terminal and cannot be
+buffer-local.  @xref{Multiple Displays}.
+@end defvar
+
+@defvar kbd-macro-termination-hook
+This normal hook (@pxref{Standard Hooks}) is run when a keyboard
+macro terminates, regardless of what caused it to terminate (reaching
+the macro end or an error which ended the macro prematurely).
+@end defvar
+
+@ignore
+   arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1
+@end ignore
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
new file mode 100644
index 00000000000..8f5c047fd6b
--- /dev/null
+++ b/doc/lispref/compile.texi
@@ -0,0 +1,886 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/compile
+@node Byte Compilation, Advising Functions, Loading, Top
+@chapter Byte Compilation
+@cindex byte compilation
+@cindex byte-code
+@cindex compilation (Emacs Lisp)
+
+  Emacs Lisp has a @dfn{compiler} that translates functions written
+in Lisp into a special representation called @dfn{byte-code} that can be
+executed more efficiently.  The compiler replaces Lisp function
+definitions with byte-code.  When a byte-code function is called, its
+definition is evaluated by the @dfn{byte-code interpreter}.
+
+  Because the byte-compiled code is evaluated by the byte-code
+interpreter, instead of being executed directly by the machine's
+hardware (as true compiled code is), byte-code is completely
+transportable from machine to machine without recompilation.  It is not,
+however, as fast as true compiled code.
+
+  Compiling a Lisp file with the Emacs byte compiler always reads the
+file as multibyte text, even if Emacs was started with @samp{--unibyte},
+unless the file specifies otherwise.  This is so that compilation gives
+results compatible with running the same file without compilation.
+@xref{Loading Non-ASCII}.
+
+  In general, any version of Emacs can run byte-compiled code produced
+by recent earlier versions of Emacs, but the reverse is not true.
+
+@vindex no-byte-compile
+  If you do not want a Lisp file to be compiled, ever, put a file-local
+variable binding for @code{no-byte-compile} into it, like this:
+
+@example
+;; -*-no-byte-compile: t; -*-
+@end example
+
+  @xref{Compilation Errors}, for how to investigate errors occurring in
+byte compilation.
+
+@menu
+* Speed of Byte-Code::          An example of speedup from byte compilation.
+* Compilation Functions::       Byte compilation functions.
+* Docs and Compilation::        Dynamic loading of documentation strings.
+* Dynamic Loading::             Dynamic loading of individual functions.
+* Eval During Compile::  	Code to be evaluated when you compile.
+* Compiler Errors::             Handling compiler error messages.
+* Byte-Code Objects::		The data type used for byte-compiled functions.
+* Disassembly::                 Disassembling byte-code; how to read byte-code.
+@end menu
+
+@node Speed of Byte-Code
+@section Performance of Byte-Compiled Code
+
+  A byte-compiled function is not as efficient as a primitive function
+written in C, but runs much faster than the version written in Lisp.
+Here is an example:
+
+@example
+@group
+(defun silly-loop (n)
+  "Return time before and after N iterations of a loop."
+  (let ((t1 (current-time-string)))
+    (while (> (setq n (1- n))
+              0))
+    (list t1 (current-time-string))))
+@result{} silly-loop
+@end group
+
+@group
+(silly-loop 100000)
+@result{} ("Fri Mar 18 17:25:57 1994"
+    "Fri Mar 18 17:26:28 1994")  ; @r{31 seconds}
+@end group
+
+@group
+(byte-compile 'silly-loop)
+@result{} @r{[Compiled code not shown]}
+@end group
+
+@group
+(silly-loop 100000)
+@result{} ("Fri Mar 18 17:26:52 1994"
+    "Fri Mar 18 17:26:58 1994")  ; @r{6 seconds}
+@end group
+@end example
+
+  In this example, the interpreted code required 31 seconds to run,
+whereas the byte-compiled code required 6 seconds.  These results are
+representative, but actual results will vary greatly.
+
+@node Compilation Functions
+@comment  node-name,  next,  previous,  up
+@section The Compilation Functions
+@cindex compilation functions
+
+  You can byte-compile an individual function or macro definition with
+the @code{byte-compile} function.  You can compile a whole file with
+@code{byte-compile-file}, or several files with
+@code{byte-recompile-directory} or @code{batch-byte-compile}.
+
+  The byte compiler produces error messages and warnings about each file
+in a buffer called @samp{*Compile-Log*}.  These report things in your
+program that suggest a problem but are not necessarily erroneous.
+
+@cindex macro compilation
+  Be careful when writing macro calls in files that you may someday
+byte-compile.  Macro calls are expanded when they are compiled, so the
+macros must already be defined for proper compilation.  For more
+details, see @ref{Compiling Macros}.  If a program does not work the
+same way when compiled as it does when interpreted, erroneous macro
+definitions are one likely cause (@pxref{Problems with Macros}).
+Inline (@code{defsubst}) functions are less troublesome; if you
+compile a call to such a function before its definition is known, the
+call will still work right, it will just run slower.
+
+  Normally, compiling a file does not evaluate the file's contents or
+load the file.  But it does execute any @code{require} calls at top
+level in the file.  One way to ensure that necessary macro definitions
+are available during compilation is to require the file that defines
+them (@pxref{Named Features}).  To avoid loading the macro definition files
+when someone @emph{runs} the compiled program, write
+@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
+During Compile}).
+
+@defun byte-compile symbol
+This function byte-compiles the function definition of @var{symbol},
+replacing the previous definition with the compiled one.  The function
+definition of @var{symbol} must be the actual code for the function;
+i.e., the compiler does not follow indirection to another symbol.
+@code{byte-compile} returns the new, compiled definition of
+@var{symbol}.
+
+  If @var{symbol}'s definition is a byte-code function object,
+@code{byte-compile} does nothing and returns @code{nil}.  Lisp records
+only one function definition for any symbol, and if that is already
+compiled, non-compiled code is not available anywhere.  So there is no
+way to ``compile the same definition again.''
+
+@example
+@group
+(defun factorial (integer)
+  "Compute factorial of INTEGER."
+  (if (= 1 integer) 1
+    (* integer (factorial (1- integer)))))
+@result{} factorial
+@end group
+
+@group
+(byte-compile 'factorial)
+@result{}
+#[(integer)
+  "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
+  [integer 1 * factorial]
+  4 "Compute factorial of INTEGER."]
+@end group
+@end example
+
+@noindent
+The result is a byte-code function object.  The string it contains is
+the actual byte-code; each character in it is an instruction or an
+operand of an instruction.  The vector contains all the constants,
+variable names and function names used by the function, except for
+certain primitives that are coded as special instructions.
+
+If the argument to @code{byte-compile} is a @code{lambda} expression,
+it returns the corresponding compiled code, but does not store
+it anywhere.
+@end defun
+
+@deffn Command compile-defun &optional arg
+This command reads the defun containing point, compiles it, and
+evaluates the result.  If you use this on a defun that is actually a
+function definition, the effect is to install a compiled version of that
+function.
+
+@code{compile-defun} normally displays the result of evaluation in the
+echo area, but if @var{arg} is non-@code{nil}, it inserts the result
+in the current buffer after the form it compiled.
+@end deffn
+
+@deffn Command byte-compile-file filename &optional load
+This function compiles a file of Lisp code named @var{filename} into a
+file of byte-code.  The output file's name is made by changing the
+@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
+@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
+
+Compilation works by reading the input file one form at a time.  If it
+is a definition of a function or macro, the compiled function or macro
+definition is written out.  Other forms are batched together, then each
+batch is compiled, and written so that its compiled code will be
+executed when the file is read.  All comments are discarded when the
+input file is read.
+
+This command returns @code{t} if there were no errors and @code{nil}
+otherwise.  When called interactively, it prompts for the file name.
+
+If @var{load} is non-@code{nil}, this command loads the compiled file
+after compiling it.  Interactively, @var{load} is the prefix argument.
+
+@example
+@group
+% ls -l push*
+-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
+@end group
+
+@group
+(byte-compile-file "~/emacs/push.el")
+     @result{} t
+@end group
+
+@group
+% ls -l push*
+-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
+-rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc
+@end group
+@end example
+@end deffn
+
+@deffn Command byte-recompile-directory directory &optional flag force
+@cindex library compilation
+This command recompiles every @samp{.el} file in @var{directory} (or
+its subdirectories) that needs recompilation.  A file needs
+recompilation if a @samp{.elc} file exists but is older than the
+@samp{.el} file.
+
+When a @samp{.el} file has no corresponding @samp{.elc} file,
+@var{flag} says what to do.  If it is @code{nil}, this command ignores
+these files.  If @var{flag} is 0, it compiles them.  If it is neither
+@code{nil} nor 0, it asks the user whether to compile each such file,
+and asks about each subdirectory as well.
+
+Interactively, @code{byte-recompile-directory} prompts for
+@var{directory} and @var{flag} is the prefix argument.
+
+If @var{force} is non-@code{nil}, this command recompiles every
+@samp{.el} file that has a @samp{.elc} file.
+
+The returned value is unpredictable.
+@end deffn
+
+@defun batch-byte-compile &optional noforce
+This function runs @code{byte-compile-file} on files specified on the
+command line.  This function must be used only in a batch execution of
+Emacs, as it kills Emacs on completion.  An error in one file does not
+prevent processing of subsequent files, but no output file will be
+generated for it, and the Emacs process will terminate with a nonzero
+status code.
+
+If @var{noforce} is non-@code{nil}, this function does not recompile
+files that have an up-to-date @samp{.elc} file.
+
+@example
+% emacs -batch -f batch-byte-compile *.el
+@end example
+@end defun
+
+@defun byte-code code-string data-vector max-stack
+@cindex byte-code interpreter
+This function actually interprets byte-code.  A byte-compiled function
+is actually defined with a body that calls @code{byte-code}.  Don't call
+this function yourself---only the byte compiler knows how to generate
+valid calls to this function.
+
+In Emacs version 18, byte-code was always executed by way of a call to
+the function @code{byte-code}.  Nowadays, byte-code is usually executed
+as part of a byte-code function object, and only rarely through an
+explicit call to @code{byte-code}.
+@end defun
+
+@node Docs and Compilation
+@section Documentation Strings and Compilation
+@cindex dynamic loading of documentation
+
+  Functions and variables loaded from a byte-compiled file access their
+documentation strings dynamically from the file whenever needed.  This
+saves space within Emacs, and makes loading faster because the
+documentation strings themselves need not be processed while loading the
+file.  Actual access to the documentation strings becomes slower as a
+result, but this normally is not enough to bother users.
+
+  Dynamic access to documentation strings does have drawbacks:
+
+@itemize @bullet
+@item
+If you delete or move the compiled file after loading it, Emacs can no
+longer access the documentation strings for the functions and variables
+in the file.
+
+@item
+If you alter the compiled file (such as by compiling a new version),
+then further access to documentation strings in this file will
+probably give nonsense results.
+@end itemize
+
+  If your site installs Emacs following the usual procedures, these
+problems will never normally occur.  Installing a new version uses a new
+directory with a different name; as long as the old version remains
+installed, its files will remain unmodified in the places where they are
+expected to be.
+
+  However, if you have built Emacs yourself and use it from the
+directory where you built it, you will experience this problem
+occasionally if you edit and recompile Lisp files.  When it happens, you
+can cure the problem by reloading the file after recompiling it.
+
+  You can turn off this feature at compile time by setting
+@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful
+mainly if you expect to change the file, and you want Emacs processes
+that have already loaded it to keep working when the file changes.
+You can do this globally, or for one source file by specifying a
+file-local binding for the variable.  One way to do that is by adding
+this string to the file's first line:
+
+@example
+-*-byte-compile-dynamic-docstrings: nil;-*-
+@end example
+
+@defvar byte-compile-dynamic-docstrings
+If this is non-@code{nil}, the byte compiler generates compiled files
+that are set up for dynamic loading of documentation strings.
+@end defvar
+
+@cindex @samp{#@@@var{count}}
+@cindex @samp{#$}
+  The dynamic documentation string feature writes compiled files that
+use a special Lisp reader construct, @samp{#@@@var{count}}.  This
+construct skips the next @var{count} characters.  It also uses the
+@samp{#$} construct, which stands for ``the name of this file, as a
+string.''  It is usually best not to use these constructs in Lisp source
+files, since they are not designed to be clear to humans reading the
+file.
+
+@node Dynamic Loading
+@section Dynamic Loading of Individual Functions
+
+@cindex dynamic loading of functions
+@cindex lazy loading
+  When you compile a file, you can optionally enable the @dfn{dynamic
+function loading} feature (also known as @dfn{lazy loading}).  With
+dynamic function loading, loading the file doesn't fully read the
+function definitions in the file.  Instead, each function definition
+contains a place-holder which refers to the file.  The first time each
+function is called, it reads the full definition from the file, to
+replace the place-holder.
+
+  The advantage of dynamic function loading is that loading the file
+becomes much faster.  This is a good thing for a file which contains
+many separate user-callable functions, if using one of them does not
+imply you will probably also use the rest.  A specialized mode which
+provides many keyboard commands often has that usage pattern: a user may
+invoke the mode, but use only a few of the commands it provides.
+
+  The dynamic loading feature has certain disadvantages:
+
+@itemize @bullet
+@item
+If you delete or move the compiled file after loading it, Emacs can no
+longer load the remaining function definitions not already loaded.
+
+@item
+If you alter the compiled file (such as by compiling a new version),
+then trying to load any function not already loaded will usually yield
+nonsense results.
+@end itemize
+
+  These problems will never happen in normal circumstances with
+installed Emacs files.  But they are quite likely to happen with Lisp
+files that you are changing.  The easiest way to prevent these problems
+is to reload the new compiled file immediately after each recompilation.
+
+  The byte compiler uses the dynamic function loading feature if the
+variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
+time.  Do not set this variable globally, since dynamic loading is
+desirable only for certain files.  Instead, enable the feature for
+specific source files with file-local variable bindings.  For example,
+you could do it by writing this text in the source file's first line:
+
+@example
+-*-byte-compile-dynamic: t;-*-
+@end example
+
+@defvar byte-compile-dynamic
+If this is non-@code{nil}, the byte compiler generates compiled files
+that are set up for dynamic function loading.
+@end defvar
+
+@defun fetch-bytecode function
+If @var{function} is a byte-code function object, this immediately
+finishes loading the byte code of @var{function} from its
+byte-compiled file, if it is not fully loaded already.  Otherwise,
+it does nothing.  It always returns @var{function}.
+@end defun
+
+@node Eval During Compile
+@section Evaluation During Compilation
+
+  These features permit you to write code to be evaluated during
+compilation of a program.
+
+@defspec eval-and-compile body@dots{}
+This form marks @var{body} to be evaluated both when you compile the
+containing code and when you run it (whether compiled or not).
+
+You can get a similar result by putting @var{body} in a separate file
+and referring to that file with @code{require}.  That method is
+preferable when @var{body} is large.  Effectively @code{require} is
+automatically @code{eval-and-compile}, the package is loaded both when
+compiling and executing.
+
+@code{autoload} is also effectively @code{eval-and-compile} too.  It's
+recognized when compiling, so uses of such a function don't produce
+``not known to be defined'' warnings.
+
+Most uses of @code{eval-and-compile} are fairly sophisticated.
+
+If a macro has a helper function to build its result, and that macro
+is used both locally and outside the package, then
+@code{eval-and-compile} should be used to get the helper both when
+compiling and then later when running.
+
+If functions are defined programmatically (with @code{fset} say), then
+@code{eval-and-compile} can be used to have that done at compile-time
+as well as run-time, so calls to those functions are checked (and
+warnings about ``not known to be defined'' suppressed).
+@end defspec
+
+@defspec eval-when-compile body@dots{}
+This form marks @var{body} to be evaluated at compile time but not when
+the compiled program is loaded.  The result of evaluation by the
+compiler becomes a constant which appears in the compiled program.  If
+you load the source file, rather than compiling it, @var{body} is
+evaluated normally.
+
+@cindex compile-time constant
+If you have a constant that needs some calculation to produce,
+@code{eval-when-compile} can do that at compile-time.  For example,
+
+@lisp
+(defvar my-regexp
+  (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
+@end lisp
+
+@cindex macros, at compile time
+If you're using another package, but only need macros from it (the
+byte compiler will expand those), then @code{eval-when-compile} can be
+used to load it for compiling, but not executing.  For example,
+
+@lisp
+(eval-when-compile
+  (require 'my-macro-package))  ;; only macros needed from this
+@end lisp
+
+The same sort of thing goes for macros and @code{defsubst} functions
+defined locally and only for use within the file.  They are needed for
+compiling the file, but in most cases they are not needed for
+execution of the compiled file.  For example,
+
+@lisp
+(eval-when-compile
+  (unless (fboundp 'some-new-thing)
+    (defmacro 'some-new-thing ()
+      (compatibility code))))
+@end lisp
+
+@noindent
+This is often good for code that's only a fallback for compatibility
+with other versions of Emacs.
+
+@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common
+Lisp idiom @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the
+Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
+to what @code{eval-when-compile} does.
+@end defspec
+
+@node Compiler Errors
+@section Compiler Errors
+@cindex compiler errors
+
+  Byte compilation outputs all errors and warnings into the buffer
+@samp{*Compile-Log*}.  The messages include file names and line
+numbers that identify the location of the problem.  The usual Emacs
+commands for operating on compiler diagnostics work properly on
+these messages.
+
+  However, the warnings about functions that were used but not
+defined are always ``located'' at the end of the file, so these
+commands won't find the places they are really used.  To do that,
+you must search for the function names.
+
+  You can suppress the compiler warning for calling an undefined
+function @var{func} by conditionalizing the function call on an
+@code{fboundp} test, like this:
+
+@example
+(if (fboundp '@var{func}) ...(@var{func} ...)...)
+@end example
+
+@noindent
+The call to @var{func} must be in the @var{then-form} of the
+@code{if}, and @var{func} must appear quoted in the call to
+@code{fboundp}.  (This feature operates for @code{cond} as well.)
+
+  Likewise, you can suppress a compiler warning for an unbound variable
+@var{variable} by conditionalizing its use on a @code{boundp} test,
+like this:
+
+@example
+(if (boundp '@var{variable}) ...@var{variable}...)
+@end example
+
+@noindent
+The reference to @var{variable} must be in the @var{then-form} of the
+@code{if}, and @var{variable} must appear quoted in the call to
+@code{boundp}.
+
+  You can suppress any compiler warnings using the construct
+@code{with-no-warnings}:
+
+@c This is implemented with a defun, but conceptually it is
+@c a special form.
+
+@defspec with-no-warnings body@dots{}
+In execution, this is equivalent to @code{(progn @var{body}...)},
+but the compiler does not issue warnings for anything that occurs
+inside @var{body}.
+
+We recommend that you use this construct around the smallest
+possible piece of code.
+@end defspec
+
+@node Byte-Code Objects
+@section Byte-Code Function Objects
+@cindex compiled function
+@cindex byte-code function
+
+  Byte-compiled functions have a special data type: they are
+@dfn{byte-code function objects}.
+
+  Internally, a byte-code function object is much like a vector;
+however, the evaluator handles this data type specially when it appears
+as a function to be called.  The printed representation for a byte-code
+function object is like that for a vector, with an additional @samp{#}
+before the opening @samp{[}.
+
+  A byte-code function object must have at least four elements; there is
+no maximum number, but only the first six elements have any normal use.
+They are:
+
+@table @var
+@item arglist
+The list of argument symbols.
+
+@item byte-code
+The string containing the byte-code instructions.
+
+@item constants
+The vector of Lisp objects referenced by the byte code.  These include
+symbols used as function names and variable names.
+
+@item stacksize
+The maximum stack size this function needs.
+
+@item docstring
+The documentation string (if any); otherwise, @code{nil}.  The value may
+be a number or a list, in case the documentation string is stored in a
+file.  Use the function @code{documentation} to get the real
+documentation string (@pxref{Accessing Documentation}).
+
+@item interactive
+The interactive spec (if any).  This can be a string or a Lisp
+expression.  It is @code{nil} for a function that isn't interactive.
+@end table
+
+Here's an example of a byte-code function object, in printed
+representation.  It is the definition of the command
+@code{backward-sexp}.
+
+@example
+#[(&optional arg)
+  "^H\204^F^@@\301^P\302^H[!\207"
+  [arg 1 forward-sexp]
+  2
+  254435
+  "p"]
+@end example
+
+  The primitive way to create a byte-code object is with
+@code{make-byte-code}:
+
+@defun make-byte-code &rest elements
+This function constructs and returns a byte-code function object
+with @var{elements} as its elements.
+@end defun
+
+  You should not try to come up with the elements for a byte-code
+function yourself, because if they are inconsistent, Emacs may crash
+when you call the function.  Always leave it to the byte compiler to
+create these objects; it makes the elements consistent (we hope).
+
+  You can access the elements of a byte-code object using @code{aref};
+you can also use @code{vconcat} to create a vector with the same
+elements.
+
+@node Disassembly
+@section Disassembled Byte-Code
+@cindex disassembled byte-code
+
+  People do not write byte-code; that job is left to the byte compiler.
+But we provide a disassembler to satisfy a cat-like curiosity.  The
+disassembler converts the byte-compiled code into humanly readable
+form.
+
+  The byte-code interpreter is implemented as a simple stack machine.
+It pushes values onto a stack of its own, then pops them off to use them
+in calculations whose results are themselves pushed back on the stack.
+When a byte-code function returns, it pops a value off the stack and
+returns it as the value of the function.
+
+  In addition to the stack, byte-code functions can use, bind, and set
+ordinary Lisp variables, by transferring values between variables and
+the stack.
+
+@deffn Command disassemble object &optional buffer-or-name
+This command displays the disassembled code for @var{object}.  In
+interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
+the output goes in a buffer named @samp{*Disassemble*}.  If
+@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
+name of an existing buffer.  Then the output goes there, at point, and
+point is left before the output.
+
+The argument @var{object} can be a function name, a lambda expression
+or a byte-code object.  If it is a lambda expression, @code{disassemble}
+compiles it and disassembles the resulting compiled code.
+@end deffn
+
+  Here are two examples of using the @code{disassemble} function.  We
+have added explanatory comments to help you relate the byte-code to the
+Lisp source; these do not appear in the output of @code{disassemble}.
+These examples show unoptimized byte-code.  Nowadays byte-code is
+usually optimized, but we did not want to rewrite these examples, since
+they still serve their purpose.
+
+@example
+@group
+(defun factorial (integer)
+  "Compute factorial of an integer."
+  (if (= 1 integer) 1
+    (* integer (factorial (1- integer)))))
+     @result{} factorial
+@end group
+
+@group
+(factorial 4)
+     @result{} 24
+@end group
+
+@group
+(disassemble 'factorial)
+     @print{} byte-code for factorial:
+ doc: Compute factorial of an integer.
+ args: (integer)
+@end group
+
+@group
+0   constant 1              ; @r{Push 1 onto stack.}
+
+1   varref   integer        ; @r{Get value of @code{integer}}
+                            ;   @r{from the environment}
+                            ;   @r{and push the value}
+                            ;   @r{onto the stack.}
+@end group
+
+@group
+2   eqlsign                 ; @r{Pop top two values off stack,}
+                            ;   @r{compare them,}
+                            ;   @r{and push result onto stack.}
+@end group
+
+@group
+3   goto-if-nil 10          ; @r{Pop and test top of stack;}
+                            ;   @r{if @code{nil}, go to 10,}
+                            ;   @r{else continue.}
+@end group
+
+@group
+6   constant 1              ; @r{Push 1 onto top of stack.}
+
+7   goto     17             ; @r{Go to 17 (in this case, 1 will be}
+                            ;   @r{returned by the function).}
+@end group
+
+@group
+10  constant *              ; @r{Push symbol @code{*} onto stack.}
+
+11  varref   integer        ; @r{Push value of @code{integer} onto stack.}
+@end group
+
+@group
+12  constant factorial      ; @r{Push @code{factorial} onto stack.}
+
+13  varref   integer        ; @r{Push value of @code{integer} onto stack.}
+
+14  sub1                    ; @r{Pop @code{integer}, decrement value,}
+                            ;   @r{push new value onto stack.}
+@end group
+
+@group
+                            ; @r{Stack now contains:}
+                            ;   @minus{} @r{decremented value of @code{integer}}
+                            ;   @minus{} @r{@code{factorial}}
+                            ;   @minus{} @r{value of @code{integer}}
+                            ;   @minus{} @r{@code{*}}
+@end group
+
+@group
+15  call     1              ; @r{Call function @code{factorial} using}
+                            ;   @r{the first (i.e., the top) element}
+                            ;   @r{of the stack as the argument;}
+                            ;   @r{push returned value onto stack.}
+@end group
+
+@group
+                            ; @r{Stack now contains:}
+                            ;   @minus{} @r{result of recursive}
+                            ;        @r{call to @code{factorial}}
+                            ;   @minus{} @r{value of @code{integer}}
+                            ;   @minus{} @r{@code{*}}
+@end group
+
+@group
+16  call     2              ; @r{Using the first two}
+                            ;   @r{(i.e., the top two)}
+                            ;   @r{elements of the stack}
+                            ;   @r{as arguments,}
+                            ;   @r{call the function @code{*},}
+                            ;   @r{pushing the result onto the stack.}
+@end group
+
+@group
+17  return                  ; @r{Return the top element}
+                            ;   @r{of the stack.}
+     @result{} nil
+@end group
+@end example
+
+The @code{silly-loop} function is somewhat more complex:
+
+@example
+@group
+(defun silly-loop (n)
+  "Return time before and after N iterations of a loop."
+  (let ((t1 (current-time-string)))
+    (while (> (setq n (1- n))
+              0))
+    (list t1 (current-time-string))))
+     @result{} silly-loop
+@end group
+
+@group
+(disassemble 'silly-loop)
+     @print{} byte-code for silly-loop:
+ doc: Return time before and after N iterations of a loop.
+ args: (n)
+
+0   constant current-time-string  ; @r{Push}
+                                  ;   @r{@code{current-time-string}}
+                                  ;   @r{onto top of stack.}
+@end group
+
+@group
+1   call     0              ; @r{Call @code{current-time-string}}
+                            ;   @r{ with no argument,}
+                            ;   @r{ pushing result onto stack.}
+@end group
+
+@group
+2   varbind  t1             ; @r{Pop stack and bind @code{t1}}
+                            ;   @r{to popped value.}
+@end group
+
+@group
+3   varref   n              ; @r{Get value of @code{n} from}
+                            ;   @r{the environment and push}
+                            ;   @r{the value onto the stack.}
+@end group
+
+@group
+4   sub1                    ; @r{Subtract 1 from top of stack.}
+@end group
+
+@group
+5   dup                     ; @r{Duplicate the top of the stack;}
+                            ;   @r{i.e., copy the top of}
+                            ;   @r{the stack and push the}
+                            ;   @r{copy onto the stack.}
+@end group
+
+@group
+6   varset   n              ; @r{Pop the top of the stack,}
+                            ;   @r{and bind @code{n} to the value.}
+
+                            ; @r{In effect, the sequence @code{dup varset}}
+                            ;   @r{copies the top of the stack}
+                            ;   @r{into the value of @code{n}}
+                            ;   @r{without popping it.}
+@end group
+
+@group
+7   constant 0              ; @r{Push 0 onto stack.}
+@end group
+
+@group
+8   gtr                     ; @r{Pop top two values off stack,}
+                            ;   @r{test if @var{n} is greater than 0}
+                            ;   @r{and push result onto stack.}
+@end group
+
+@group
+9   goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
+                            ;   @r{(this exits the while loop).}
+                            ;   @r{else pop top of stack}
+                            ;   @r{and continue}
+@end group
+
+@group
+12  constant nil            ; @r{Push @code{nil} onto stack}
+                            ;   @r{(this is the body of the loop).}
+@end group
+
+@group
+13  discard                 ; @r{Discard result of the body}
+                            ;   @r{of the loop (a while loop}
+                            ;   @r{is always evaluated for}
+                            ;   @r{its side effects).}
+@end group
+
+@group
+14  goto     3              ; @r{Jump back to beginning}
+                            ;   @r{of while loop.}
+@end group
+
+@group
+17  discard                 ; @r{Discard result of while loop}
+                            ;   @r{by popping top of stack.}
+                            ;   @r{This result is the value @code{nil} that}
+                            ;   @r{was not popped by the goto at 9.}
+@end group
+
+@group
+18  varref   t1             ; @r{Push value of @code{t1} onto stack.}
+@end group
+
+@group
+19  constant current-time-string  ; @r{Push}
+                                  ;   @r{@code{current-time-string}}
+                                  ;   @r{onto top of stack.}
+@end group
+
+@group
+20  call     0              ; @r{Call @code{current-time-string} again.}
+@end group
+
+@group
+21  list2                   ; @r{Pop top two elements off stack,}
+                            ;   @r{create a list of them,}
+                            ;   @r{and push list onto stack.}
+@end group
+
+@group
+22  unbind   1              ; @r{Unbind @code{t1} in local environment.}
+
+23  return                  ; @r{Return value of the top of stack.}
+
+     @result{} nil
+@end group
+@end example
+
+
+@ignore
+   arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289
+@end ignore
diff --git a/doc/lispref/configure b/doc/lispref/configure
new file mode 100755
index 00000000000..7f67f08dfa3
--- /dev/null
+++ b/doc/lispref/configure
@@ -0,0 +1,775 @@
+#! /bin/sh
+
+# Guess values for system-dependent variables and create Makefiles.
+# Generated automatically using autoconf version 2.13
+# Copyright (C) 1992, 1993, 1994, 1995, 1996, 2001, 2002, 2003, 2004,
+#   2005, 2006, 2007  Free Software Foundation, Inc.
+#
+# This configure script is free software; the Free Software Foundation
+# gives unlimited permission to copy, distribute and modify it.
+
+# Defaults:
+ac_help=
+ac_default_prefix=/usr/local
+# Any additions from configure.in:
+
+# Initialize some variables set by options.
+# The variables have the same names as the options, with
+# dashes changed to underlines.
+build=NONE
+cache_file=./config.cache
+exec_prefix=NONE
+host=NONE
+no_create=
+nonopt=NONE
+no_recursion=
+prefix=NONE
+program_prefix=NONE
+program_suffix=NONE
+program_transform_name=s,x,x,
+silent=
+site=
+srcdir=
+target=NONE
+verbose=
+x_includes=NONE
+x_libraries=NONE
+bindir='${exec_prefix}/bin'
+sbindir='${exec_prefix}/sbin'
+libexecdir='${exec_prefix}/libexec'
+datadir='${prefix}/share'
+sysconfdir='${prefix}/etc'
+sharedstatedir='${prefix}/com'
+localstatedir='${prefix}/var'
+libdir='${exec_prefix}/lib'
+includedir='${prefix}/include'
+oldincludedir='/usr/include'
+infodir='${prefix}/info'
+mandir='${prefix}/man'
+
+# Initialize some other variables.
+subdirs=
+MFLAGS= MAKEFLAGS=
+SHELL=${CONFIG_SHELL-/bin/sh}
+# Maximum number of lines to put in a shell here document.
+ac_max_here_lines=12
+
+ac_prev=
+for ac_option
+do
+
+  # If the previous option needs an argument, assign it.
+  if test -n "$ac_prev"; then
+    eval "$ac_prev=\$ac_option"
+    ac_prev=
+    continue
+  fi
+
+  case "$ac_option" in
+  -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
+  *) ac_optarg= ;;
+  esac
+
+  # Accept the important Cygnus configure options, so we can diagnose typos.
+
+  case "$ac_option" in
+
+  -bindir | --bindir | --bindi | --bind | --bin | --bi)
+    ac_prev=bindir ;;
+  -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*)
+    bindir="$ac_optarg" ;;
+
+  -build | --build | --buil | --bui | --bu)
+    ac_prev=build ;;
+  -build=* | --build=* | --buil=* | --bui=* | --bu=*)
+    build="$ac_optarg" ;;
+
+  -cache-file | --cache-file | --cache-fil | --cache-fi \
+  | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c)
+    ac_prev=cache_file ;;
+  -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \
+  | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*)
+    cache_file="$ac_optarg" ;;
+
+  -datadir | --datadir | --datadi | --datad | --data | --dat | --da)
+    ac_prev=datadir ;;
+  -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \
+  | --da=*)
+    datadir="$ac_optarg" ;;
+
+  -disable-* | --disable-*)
+    ac_feature=`echo $ac_option|sed -e 's/-*disable-//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then
+      { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
+    fi
+    ac_feature=`echo $ac_feature| sed 's/-/_/g'`
+    eval "enable_${ac_feature}=no" ;;
+
+  -enable-* | --enable-*)
+    ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then
+      { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
+    fi
+    ac_feature=`echo $ac_feature| sed 's/-/_/g'`
+    case "$ac_option" in
+      *=*) ;;
+      *) ac_optarg=yes ;;
+    esac
+    eval "enable_${ac_feature}='$ac_optarg'" ;;
+
+  -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \
+  | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \
+  | --exec | --exe | --ex)
+    ac_prev=exec_prefix ;;
+  -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \
+  | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \
+  | --exec=* | --exe=* | --ex=*)
+    exec_prefix="$ac_optarg" ;;
+
+  -gas | --gas | --ga | --g)
+    # Obsolete; use --with-gas.
+    with_gas=yes ;;
+
+  -help | --help | --hel | --he)
+    # Omit some internal or obsolete options to make the list less imposing.
+    # This message is too long to be a string in the A/UX 3.1 sh.
+    cat << EOF
+Usage: configure [options] [host]
+Options: [defaults in brackets after descriptions]
+Configuration:
+  --cache-file=FILE       cache test results in FILE
+  --help                  print this message
+  --no-create             do not create output files
+  --quiet, --silent       do not print \`checking...' messages
+  --version               print the version of autoconf that created configure
+Directory and file names:
+  --prefix=PREFIX         install architecture-independent files in PREFIX
+                          [$ac_default_prefix]
+  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
+                          [same as prefix]
+  --bindir=DIR            user executables in DIR [EPREFIX/bin]
+  --sbindir=DIR           system admin executables in DIR [EPREFIX/sbin]
+  --libexecdir=DIR        program executables in DIR [EPREFIX/libexec]
+  --datadir=DIR           read-only architecture-independent data in DIR
+                          [PREFIX/share]
+  --sysconfdir=DIR        read-only single-machine data in DIR [PREFIX/etc]
+  --sharedstatedir=DIR    modifiable architecture-independent data in DIR
+                          [PREFIX/com]
+  --localstatedir=DIR     modifiable single-machine data in DIR [PREFIX/var]
+  --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
+  --includedir=DIR        C header files in DIR [PREFIX/include]
+  --oldincludedir=DIR     C header files for non-gcc in DIR [/usr/include]
+  --infodir=DIR           info documentation in DIR [PREFIX/info]
+  --mandir=DIR            man documentation in DIR [PREFIX/man]
+  --srcdir=DIR            find the sources in DIR [configure dir or ..]
+  --program-prefix=PREFIX prepend PREFIX to installed program names
+  --program-suffix=SUFFIX append SUFFIX to installed program names
+  --program-transform-name=PROGRAM
+                          run sed PROGRAM on installed program names
+EOF
+    cat << EOF
+Host type:
+  --build=BUILD           configure for building on BUILD [BUILD=HOST]
+  --host=HOST             configure for HOST [guessed]
+  --target=TARGET         configure for TARGET [TARGET=HOST]
+Features and packages:
+  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
+  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
+  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
+  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
+  --x-includes=DIR        X include files are in DIR
+  --x-libraries=DIR       X library files are in DIR
+EOF
+    if test -n "$ac_help"; then
+      echo "--enable and --with options recognized:$ac_help"
+    fi
+    exit 0 ;;
+
+  -host | --host | --hos | --ho)
+    ac_prev=host ;;
+  -host=* | --host=* | --hos=* | --ho=*)
+    host="$ac_optarg" ;;
+
+  -includedir | --includedir | --includedi | --included | --include \
+  | --includ | --inclu | --incl | --inc)
+    ac_prev=includedir ;;
+  -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \
+  | --includ=* | --inclu=* | --incl=* | --inc=*)
+    includedir="$ac_optarg" ;;
+
+  -infodir | --infodir | --infodi | --infod | --info | --inf)
+    ac_prev=infodir ;;
+  -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*)
+    infodir="$ac_optarg" ;;
+
+  -libdir | --libdir | --libdi | --libd)
+    ac_prev=libdir ;;
+  -libdir=* | --libdir=* | --libdi=* | --libd=*)
+    libdir="$ac_optarg" ;;
+
+  -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \
+  | --libexe | --libex | --libe)
+    ac_prev=libexecdir ;;
+  -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \
+  | --libexe=* | --libex=* | --libe=*)
+    libexecdir="$ac_optarg" ;;
+
+  -localstatedir | --localstatedir | --localstatedi | --localstated \
+  | --localstate | --localstat | --localsta | --localst \
+  | --locals | --local | --loca | --loc | --lo)
+    ac_prev=localstatedir ;;
+  -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \
+  | --localstate=* | --localstat=* | --localsta=* | --localst=* \
+  | --locals=* | --local=* | --loca=* | --loc=* | --lo=*)
+    localstatedir="$ac_optarg" ;;
+
+  -mandir | --mandir | --mandi | --mand | --man | --ma | --m)
+    ac_prev=mandir ;;
+  -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*)
+    mandir="$ac_optarg" ;;
+
+  -nfp | --nfp | --nf)
+    # Obsolete; use --without-fp.
+    with_fp=no ;;
+
+  -no-create | --no-create | --no-creat | --no-crea | --no-cre \
+  | --no-cr | --no-c)
+    no_create=yes ;;
+
+  -no-recursion | --no-recursion | --no-recursio | --no-recursi \
+  | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r)
+    no_recursion=yes ;;
+
+  -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \
+  | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \
+  | --oldin | --oldi | --old | --ol | --o)
+    ac_prev=oldincludedir ;;
+  -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \
+  | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \
+  | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*)
+    oldincludedir="$ac_optarg" ;;
+
+  -prefix | --prefix | --prefi | --pref | --pre | --pr | --p)
+    ac_prev=prefix ;;
+  -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*)
+    prefix="$ac_optarg" ;;
+
+  -program-prefix | --program-prefix | --program-prefi | --program-pref \
+  | --program-pre | --program-pr | --program-p)
+    ac_prev=program_prefix ;;
+  -program-prefix=* | --program-prefix=* | --program-prefi=* \
+  | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*)
+    program_prefix="$ac_optarg" ;;
+
+  -program-suffix | --program-suffix | --program-suffi | --program-suff \
+  | --program-suf | --program-su | --program-s)
+    ac_prev=program_suffix ;;
+  -program-suffix=* | --program-suffix=* | --program-suffi=* \
+  | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*)
+    program_suffix="$ac_optarg" ;;
+
+  -program-transform-name | --program-transform-name \
+  | --program-transform-nam | --program-transform-na \
+  | --program-transform-n | --program-transform- \
+  | --program-transform | --program-transfor \
+  | --program-transfo | --program-transf \
+  | --program-trans | --program-tran \
+  | --progr-tra | --program-tr | --program-t)
+    ac_prev=program_transform_name ;;
+  -program-transform-name=* | --program-transform-name=* \
+  | --program-transform-nam=* | --program-transform-na=* \
+  | --program-transform-n=* | --program-transform-=* \
+  | --program-transform=* | --program-transfor=* \
+  | --program-transfo=* | --program-transf=* \
+  | --program-trans=* | --program-tran=* \
+  | --progr-tra=* | --program-tr=* | --program-t=*)
+    program_transform_name="$ac_optarg" ;;
+
+  -q | -quiet | --quiet | --quie | --qui | --qu | --q \
+  | -silent | --silent | --silen | --sile | --sil)
+    silent=yes ;;
+
+  -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
+    ac_prev=sbindir ;;
+  -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
+  | --sbi=* | --sb=*)
+    sbindir="$ac_optarg" ;;
+
+  -sharedstatedir | --sharedstatedir | --sharedstatedi \
+  | --sharedstated | --sharedstate | --sharedstat | --sharedsta \
+  | --sharedst | --shareds | --shared | --share | --shar \
+  | --sha | --sh)
+    ac_prev=sharedstatedir ;;
+  -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \
+  | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \
+  | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \
+  | --sha=* | --sh=*)
+    sharedstatedir="$ac_optarg" ;;
+
+  -site | --site | --sit)
+    ac_prev=site ;;
+  -site=* | --site=* | --sit=*)
+    site="$ac_optarg" ;;
+
+  -srcdir | --srcdir | --srcdi | --srcd | --src | --sr)
+    ac_prev=srcdir ;;
+  -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*)
+    srcdir="$ac_optarg" ;;
+
+  -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \
+  | --syscon | --sysco | --sysc | --sys | --sy)
+    ac_prev=sysconfdir ;;
+  -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \
+  | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*)
+    sysconfdir="$ac_optarg" ;;
+
+  -target | --target | --targe | --targ | --tar | --ta | --t)
+    ac_prev=target ;;
+  -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*)
+    target="$ac_optarg" ;;
+
+  -v | -verbose | --verbose | --verbos | --verbo | --verb)
+    verbose=yes ;;
+
+  -version | --version | --versio | --versi | --vers)
+    echo "configure generated by autoconf version 2.13"
+    exit 0 ;;
+
+  -with-* | --with-*)
+    ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then
+      { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
+    fi
+    ac_package=`echo $ac_package| sed 's/-/_/g'`
+    case "$ac_option" in
+      *=*) ;;
+      *) ac_optarg=yes ;;
+    esac
+    eval "with_${ac_package}='$ac_optarg'" ;;
+
+  -without-* | --without-*)
+    ac_package=`echo $ac_option|sed -e 's/-*without-//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then
+      { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
+    fi
+    ac_package=`echo $ac_package| sed 's/-/_/g'`
+    eval "with_${ac_package}=no" ;;
+
+  --x)
+    # Obsolete; use --with-x.
+    with_x=yes ;;
+
+  -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \
+  | --x-incl | --x-inc | --x-in | --x-i)
+    ac_prev=x_includes ;;
+  -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \
+  | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*)
+    x_includes="$ac_optarg" ;;
+
+  -x-libraries | --x-libraries | --x-librarie | --x-librari \
+  | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l)
+    ac_prev=x_libraries ;;
+  -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \
+  | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*)
+    x_libraries="$ac_optarg" ;;
+
+  -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; }
+    ;;
+
+  *)
+    if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then
+      echo "configure: warning: $ac_option: invalid host type" 1>&2
+    fi
+    if test "x$nonopt" != xNONE; then
+      { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; }
+    fi
+    nonopt="$ac_option"
+    ;;
+
+  esac
+done
+
+if test -n "$ac_prev"; then
+  { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; }
+fi
+
+trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
+
+# File descriptor usage:
+# 0 standard input
+# 1 file creation
+# 2 errors and warnings
+# 3 some systems may open it to /dev/tty
+# 4 used on the Kubota Titan
+# 6 checking for... messages and results
+# 5 compiler messages saved in config.log
+if test "$silent" = yes; then
+  exec 6>/dev/null
+else
+  exec 6>&1
+fi
+exec 5>./config.log
+
+echo "\
+This file contains any messages produced by compilers while
+running configure, to aid debugging if configure makes a mistake.
+" 1>&5
+
+# Strip out --no-create and --no-recursion so they do not pile up.
+# Also quote any args containing shell metacharacters.
+ac_configure_args=
+for ac_arg
+do
+  case "$ac_arg" in
+  -no-create | --no-create | --no-creat | --no-crea | --no-cre \
+  | --no-cr | --no-c) ;;
+  -no-recursion | --no-recursion | --no-recursio | --no-recursi \
+  | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;;
+  *" "*|*"	"*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*)
+  ac_configure_args="$ac_configure_args '$ac_arg'" ;;
+  *) ac_configure_args="$ac_configure_args $ac_arg" ;;
+  esac
+done
+
+# NLS nuisances.
+# Only set these to C if already set.  These must not be set unconditionally
+# because not all systems understand e.g. LANG=C (notably SCO).
+# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'!
+# Non-C LC_CTYPE values break the ctype check.
+if test "${LANG+set}"   = set; then LANG=C;   export LANG;   fi
+if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi
+if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi
+if test "${LC_CTYPE+set}"    = set; then LC_CTYPE=C;    export LC_CTYPE;    fi
+
+# confdefs.h avoids OS command line length limits that DEFS can exceed.
+rm -rf conftest* confdefs.h
+# AIX cpp loses on an empty file, so make sure it contains at least a newline.
+echo > confdefs.h
+
+# A filename unique to this package, relative to the directory that
+# configure is in, which we can look for to find out if srcdir is correct.
+ac_unique_file=elisp.texi
+
+# Find the source files, if location was not specified.
+if test -z "$srcdir"; then
+  ac_srcdir_defaulted=yes
+  # Try the directory containing this script, then its parent.
+  ac_prog=$0
+  ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'`
+  test "x$ac_confdir" = "x$ac_prog" && ac_confdir=.
+  srcdir=$ac_confdir
+  if test ! -r $srcdir/$ac_unique_file; then
+    srcdir=..
+  fi
+else
+  ac_srcdir_defaulted=no
+fi
+if test ! -r $srcdir/$ac_unique_file; then
+  if test "$ac_srcdir_defaulted" = yes; then
+    { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; }
+  else
+    { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; }
+  fi
+fi
+srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'`
+
+# Prefer explicitly selected file to automatically selected ones.
+if test -z "$CONFIG_SITE"; then
+  if test "x$prefix" != xNONE; then
+    CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site"
+  else
+    CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site"
+  fi
+fi
+for ac_site_file in $CONFIG_SITE; do
+  if test -r "$ac_site_file"; then
+    echo "loading site script $ac_site_file"
+    . "$ac_site_file"
+  fi
+done
+
+if test -r "$cache_file"; then
+  echo "loading cache $cache_file"
+  . $cache_file
+else
+  echo "creating cache $cache_file"
+  > $cache_file
+fi
+
+ac_ext=c
+# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options.
+ac_cpp='$CPP $CPPFLAGS'
+ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5'
+ac_link='${CC-cc} -o conftest${ac_exeext} $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5'
+cross_compiling=$ac_cv_prog_cc_cross
+
+ac_exeext=
+ac_objext=o
+if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then
+  # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu.
+  if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then
+    ac_n= ac_c='
+' ac_t='	'
+  else
+    ac_n=-n ac_c= ac_t=
+  fi
+else
+  ac_n= ac_c='\c' ac_t=
+fi
+
+
+trap '' 1 2 15
+cat > confcache <<\EOF
+# This file is a shell script that caches the results of configure
+# tests run on this system so they can be shared between configure
+# scripts and configure runs.  It is not useful on other systems.
+# If it contains results you don't want to keep, you may remove or edit it.
+#
+# By default, configure uses ./config.cache as the cache file,
+# creating it if it does not exist already.  You can give configure
+# the --cache-file=FILE option to use a different cache file; that is
+# what configure does when it calls configure scripts in
+# subdirectories, so they share the cache.
+# Giving --cache-file=/dev/null disables caching, for debugging configure.
+# config.status only pays attention to the cache file if you give it the
+# --recheck option to rerun configure.
+#
+EOF
+# The following way of writing the cache mishandles newlines in values,
+# but we know of no workaround that is simple, portable, and efficient.
+# So, don't put newlines in cache variables' values.
+# Ultrix sh set writes to stderr and can't be redirected directly,
+# and sets the high bit in the cache file unless we assign to the vars.
+(set) 2>&1 |
+  case `(ac_space=' '; set | grep ac_space) 2>&1` in
+  *ac_space=\ *)
+    # `set' does not quote correctly, so add quotes (double-quote substitution
+    # turns \\\\ into \\, and sed turns \\ into \).
+    sed -n \
+      -e "s/'/'\\\\''/g" \
+      -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p"
+    ;;
+  *)
+    # `set' quotes correctly as required by POSIX, so do not add quotes.
+    sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p'
+    ;;
+  esac >> confcache
+if cmp -s $cache_file confcache; then
+  :
+else
+  if test -w $cache_file; then
+    echo "updating cache $cache_file"
+    cat confcache > $cache_file
+  else
+    echo "not updating unwritable cache $cache_file"
+  fi
+fi
+rm -f confcache
+
+trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
+
+test "x$prefix" = xNONE && prefix=$ac_default_prefix
+# Let make expand exec_prefix.
+test "x$exec_prefix" = xNONE && exec_prefix='${prefix}'
+
+# Any assignment to VPATH causes Sun make to only execute
+# the first set of double-colon rules, so remove it if not needed.
+# If there is a colon in the path, we need to keep it.
+if test "x$srcdir" = x.; then
+  ac_vpsub='/^[ 	]*VPATH[ 	]*=[^:]*$/d'
+fi
+
+trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15
+
+# Transform confdefs.h into DEFS.
+# Protect against shell expansion while executing Makefile rules.
+# Protect against Makefile macro expansion.
+cat > conftest.defs <<\EOF
+s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g
+s%[ 	`~#$^&*(){}\\|;'"<>?]%\\&%g
+s%\[%\\&%g
+s%\]%\\&%g
+s%\$%$$%g
+EOF
+DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '`
+rm -f conftest.defs
+
+
+# Without the "./", some shells look in PATH for config.status.
+: ${CONFIG_STATUS=./config.status}
+
+echo creating $CONFIG_STATUS
+rm -f $CONFIG_STATUS
+cat > $CONFIG_STATUS <<EOF
+#! /bin/sh
+# Generated automatically by configure.
+# Run this file to recreate the current configuration.
+# This directory was configured as follows,
+# on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
+#
+# $0 $ac_configure_args
+#
+# Compiler output produced by configure, useful for debugging
+# configure, is in ./config.log if it exists.
+
+ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]"
+for ac_option
+do
+  case "\$ac_option" in
+  -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r)
+    echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion"
+    exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;;
+  -version | --version | --versio | --versi | --vers | --ver | --ve | --v)
+    echo "$CONFIG_STATUS generated by autoconf version 2.13"
+    exit 0 ;;
+  -help | --help | --hel | --he | --h)
+    echo "\$ac_cs_usage"; exit 0 ;;
+  *) echo "\$ac_cs_usage"; exit 1 ;;
+  esac
+done
+
+ac_given_srcdir=$srcdir
+
+trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15
+EOF
+cat >> $CONFIG_STATUS <<EOF
+
+# Protect against being on the right side of a sed subst in config.status.
+sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g;
+ s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF
+$ac_vpsub
+$extrasub
+s%@SHELL@%$SHELL%g
+s%@CFLAGS@%$CFLAGS%g
+s%@CPPFLAGS@%$CPPFLAGS%g
+s%@CXXFLAGS@%$CXXFLAGS%g
+s%@FFLAGS@%$FFLAGS%g
+s%@DEFS@%$DEFS%g
+s%@LDFLAGS@%$LDFLAGS%g
+s%@LIBS@%$LIBS%g
+s%@exec_prefix@%$exec_prefix%g
+s%@prefix@%$prefix%g
+s%@program_transform_name@%$program_transform_name%g
+s%@bindir@%$bindir%g
+s%@sbindir@%$sbindir%g
+s%@libexecdir@%$libexecdir%g
+s%@datadir@%$datadir%g
+s%@sysconfdir@%$sysconfdir%g
+s%@sharedstatedir@%$sharedstatedir%g
+s%@localstatedir@%$localstatedir%g
+s%@libdir@%$libdir%g
+s%@includedir@%$includedir%g
+s%@oldincludedir@%$oldincludedir%g
+s%@infodir@%$infodir%g
+s%@mandir@%$mandir%g
+
+CEOF
+EOF
+
+cat >> $CONFIG_STATUS <<\EOF
+
+# Split the substitutions into bite-sized pieces for seds with
+# small command number limits, like on Digital OSF/1 and HP-UX.
+ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script.
+ac_file=1 # Number of current file.
+ac_beg=1 # First line for current file.
+ac_end=$ac_max_sed_cmds # Line after last line for current file.
+ac_more_lines=:
+ac_sed_cmds=""
+while $ac_more_lines; do
+  if test $ac_beg -gt 1; then
+    sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file
+  else
+    sed "${ac_end}q" conftest.subs > conftest.s$ac_file
+  fi
+  if test ! -s conftest.s$ac_file; then
+    ac_more_lines=false
+    rm -f conftest.s$ac_file
+  else
+    if test -z "$ac_sed_cmds"; then
+      ac_sed_cmds="sed -f conftest.s$ac_file"
+    else
+      ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file"
+    fi
+    ac_file=`expr $ac_file + 1`
+    ac_beg=$ac_end
+    ac_end=`expr $ac_end + $ac_max_sed_cmds`
+  fi
+done
+if test -z "$ac_sed_cmds"; then
+  ac_sed_cmds=cat
+fi
+EOF
+
+cat >> $CONFIG_STATUS <<EOF
+
+CONFIG_FILES=\${CONFIG_FILES-"Makefile"}
+EOF
+cat >> $CONFIG_STATUS <<\EOF
+for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then
+  # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in".
+  case "$ac_file" in
+  *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'`
+       ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;;
+  *) ac_file_in="${ac_file}.in" ;;
+  esac
+
+  # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories.
+
+  # Remove last slash and all that follows it.  Not all systems have dirname.
+  ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'`
+  if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then
+    # The file is in a subdirectory.
+    test ! -d "$ac_dir" && mkdir "$ac_dir"
+    ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`"
+    # A "../" for each directory in $ac_dir_suffix.
+    ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'`
+  else
+    ac_dir_suffix= ac_dots=
+  fi
+
+  case "$ac_given_srcdir" in
+  .)  srcdir=.
+      if test -z "$ac_dots"; then top_srcdir=.
+      else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;;
+  /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;;
+  *) # Relative path.
+    srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix"
+    top_srcdir="$ac_dots$ac_given_srcdir" ;;
+  esac
+
+
+  echo creating "$ac_file"
+  rm -f "$ac_file"
+  configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure."
+  case "$ac_file" in
+  *Makefile*) ac_comsub="1i\\
+# $configure_input" ;;
+  *) ac_comsub= ;;
+  esac
+
+  ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"`
+  sed -e "$ac_comsub
+s%@configure_input@%$configure_input%g
+s%@srcdir@%$srcdir%g
+s%@top_srcdir@%$top_srcdir%g
+" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file
+fi; done
+rm -f conftest.s*
+
+EOF
+cat >> $CONFIG_STATUS <<EOF
+
+EOF
+cat >> $CONFIG_STATUS <<\EOF
+
+exit 0
+EOF
+chmod +x $CONFIG_STATUS
+rm -fr confdefs* $ac_clean_files
+test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1
+
diff --git a/doc/lispref/configure.in b/doc/lispref/configure.in
new file mode 100644
index 00000000000..7db2f8cab5e
--- /dev/null
+++ b/doc/lispref/configure.in
@@ -0,0 +1,7 @@
+dnl Process this file with autoconf to produce a configure script.
+AC_INIT(elisp.texi)
+AC_OUTPUT(Makefile)
+
+m4_if(dnl	Do not change this comment
+   arch-tag: 61db4227-0d2b-4c4d-ad54-ca9a1ee518ea
+)dnl
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
new file mode 100644
index 00000000000..e99a6329f3e
--- /dev/null
+++ b/doc/lispref/control.texi
@@ -0,0 +1,1291 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/control
+@node Control Structures, Variables, Evaluation, Top
+@chapter Control Structures
+@cindex special forms for control structures
+@cindex control structures
+
+  A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}).
+We control the order of execution of these forms by enclosing them in
+@dfn{control structures}.  Control structures are special forms which
+control when, whether, or how many times to execute the forms they
+contain.
+
+  The simplest order of execution is sequential execution: first form
+@var{a}, then form @var{b}, and so on.  This is what happens when you
+write several forms in succession in the body of a function, or at top
+level in a file of Lisp code---the forms are executed in the order
+written.  We call this @dfn{textual order}.  For example, if a function
+body consists of two forms @var{a} and @var{b}, evaluation of the
+function evaluates first @var{a} and then @var{b}.  The result of
+evaluating @var{b} becomes the value of the function.
+
+  Explicit control structures make possible an order of execution other
+than sequential.
+
+  Emacs Lisp provides several kinds of control structure, including
+other varieties of sequencing, conditionals, iteration, and (controlled)
+jumps---all discussed below.  The built-in control structures are
+special forms since their subforms are not necessarily evaluated or not
+evaluated sequentially.  You can use macros to define your own control
+structure constructs (@pxref{Macros}).
+
+@menu
+* Sequencing::             Evaluation in textual order.
+* Conditionals::           @code{if}, @code{cond}, @code{when}, @code{unless}.
+* Combining Conditions::   @code{and}, @code{or}, @code{not}.
+* Iteration::              @code{while} loops.
+* Nonlocal Exits::         Jumping out of a sequence.
+@end menu
+
+@node Sequencing
+@section Sequencing
+
+  Evaluating forms in the order they appear is the most common way
+control passes from one form to another.  In some contexts, such as in a
+function body, this happens automatically.  Elsewhere you must use a
+control structure construct to do this: @code{progn}, the simplest
+control construct of Lisp.
+
+  A @code{progn} special form looks like this:
+
+@example
+@group
+(progn @var{a} @var{b} @var{c} @dots{})
+@end group
+@end example
+
+@noindent
+and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in
+that order.  These forms are called the @dfn{body} of the @code{progn} form.
+The value of the last form in the body becomes the value of the entire
+@code{progn}.  @code{(progn)} returns @code{nil}.
+
+@cindex implicit @code{progn}
+  In the early days of Lisp, @code{progn} was the only way to execute
+two or more forms in succession and use the value of the last of them.
+But programmers found they often needed to use a @code{progn} in the
+body of a function, where (at that time) only one form was allowed.  So
+the body of a function was made into an ``implicit @code{progn}'':
+several forms are allowed just as in the body of an actual @code{progn}.
+Many other control structures likewise contain an implicit @code{progn}.
+As a result, @code{progn} is not used as much as it was many years ago.
+It is needed now most often inside an @code{unwind-protect}, @code{and},
+@code{or}, or in the @var{then}-part of an @code{if}.
+
+@defspec progn forms@dots{}
+This special form evaluates all of the @var{forms}, in textual
+order, returning the result of the final form.
+
+@example
+@group
+(progn (print "The first form")
+       (print "The second form")
+       (print "The third form"))
+     @print{} "The first form"
+     @print{} "The second form"
+     @print{} "The third form"
+@result{} "The third form"
+@end group
+@end example
+@end defspec
+
+  Two other control constructs likewise evaluate a series of forms but return
+a different value:
+
+@defspec prog1 form1 forms@dots{}
+This special form evaluates @var{form1} and all of the @var{forms}, in
+textual order, returning the result of @var{form1}.
+
+@example
+@group
+(prog1 (print "The first form")
+       (print "The second form")
+       (print "The third form"))
+     @print{} "The first form"
+     @print{} "The second form"
+     @print{} "The third form"
+@result{} "The first form"
+@end group
+@end example
+
+Here is a way to remove the first element from a list in the variable
+@code{x}, then return the value of that former element:
+
+@example
+(prog1 (car x) (setq x (cdr x)))
+@end example
+@end defspec
+
+@defspec prog2 form1 form2 forms@dots{}
+This special form evaluates @var{form1}, @var{form2}, and all of the
+following @var{forms}, in textual order, returning the result of
+@var{form2}.
+
+@example
+@group
+(prog2 (print "The first form")
+       (print "The second form")
+       (print "The third form"))
+     @print{} "The first form"
+     @print{} "The second form"
+     @print{} "The third form"
+@result{} "The second form"
+@end group
+@end example
+@end defspec
+
+@node Conditionals
+@section Conditionals
+@cindex conditional evaluation
+
+  Conditional control structures choose among alternatives.  Emacs Lisp
+has four conditional forms: @code{if}, which is much the same as in
+other languages; @code{when} and @code{unless}, which are variants of
+@code{if}; and @code{cond}, which is a generalized case statement.
+
+@defspec if condition then-form else-forms@dots{}
+@code{if} chooses between the @var{then-form} and the @var{else-forms}
+based on the value of @var{condition}.  If the evaluated @var{condition} is
+non-@code{nil}, @var{then-form} is evaluated and the result returned.
+Otherwise, the @var{else-forms} are evaluated in textual order, and the
+value of the last one is returned.  (The @var{else} part of @code{if} is
+an example of an implicit @code{progn}.  @xref{Sequencing}.)
+
+If @var{condition} has the value @code{nil}, and no @var{else-forms} are
+given, @code{if} returns @code{nil}.
+
+@code{if} is a special form because the branch that is not selected is
+never evaluated---it is ignored.  Thus, in the example below,
+@code{true} is not printed because @code{print} is never called.
+
+@example
+@group
+(if nil
+    (print 'true)
+  'very-false)
+@result{} very-false
+@end group
+@end example
+@end defspec
+
+@defmac when condition then-forms@dots{}
+This is a variant of @code{if} where there are no @var{else-forms},
+and possibly several @var{then-forms}.  In particular,
+
+@example
+(when @var{condition} @var{a} @var{b} @var{c})
+@end example
+
+@noindent
+is entirely equivalent to
+
+@example
+(if @var{condition} (progn @var{a} @var{b} @var{c}) nil)
+@end example
+@end defmac
+
+@defmac unless condition forms@dots{}
+This is a variant of @code{if} where there is no @var{then-form}:
+
+@example
+(unless @var{condition} @var{a} @var{b} @var{c})
+@end example
+
+@noindent
+is entirely equivalent to
+
+@example
+(if @var{condition} nil
+   @var{a} @var{b} @var{c})
+@end example
+@end defmac
+
+@defspec cond clause@dots{}
+@code{cond} chooses among an arbitrary number of alternatives.  Each
+@var{clause} in the @code{cond} must be a list.  The @sc{car} of this
+list is the @var{condition}; the remaining elements, if any, the
+@var{body-forms}.  Thus, a clause looks like this:
+
+@example
+(@var{condition} @var{body-forms}@dots{})
+@end example
+
+@code{cond} tries the clauses in textual order, by evaluating the
+@var{condition} of each clause.  If the value of @var{condition} is
+non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its
+@var{body-forms}, and the value of the last of @var{body-forms} becomes
+the value of the @code{cond}.  The remaining clauses are ignored.
+
+If the value of @var{condition} is @code{nil}, the clause ``fails,'' so
+the @code{cond} moves on to the following clause, trying its
+@var{condition}.
+
+If every @var{condition} evaluates to @code{nil}, so that every clause
+fails, @code{cond} returns @code{nil}.
+
+A clause may also look like this:
+
+@example
+(@var{condition})
+@end example
+
+@noindent
+Then, if @var{condition} is non-@code{nil} when tested, the value of
+@var{condition} becomes the value of the @code{cond} form.
+
+The following example has four clauses, which test for the cases where
+the value of @code{x} is a number, string, buffer and symbol,
+respectively:
+
+@example
+@group
+(cond ((numberp x) x)
+      ((stringp x) x)
+      ((bufferp x)
+       (setq temporary-hack x) ; @r{multiple body-forms}
+       (buffer-name x))        ; @r{in one clause}
+      ((symbolp x) (symbol-value x)))
+@end group
+@end example
+
+Often we want to execute the last clause whenever none of the previous
+clauses was successful.  To do this, we use @code{t} as the
+@var{condition} of the last clause, like this: @code{(t
+@var{body-forms})}.  The form @code{t} evaluates to @code{t}, which is
+never @code{nil}, so this clause never fails, provided the @code{cond}
+gets to it at all.
+
+For example,
+
+@example
+@group
+(setq a 5)
+(cond ((eq a 'hack) 'foo)
+      (t "default"))
+@result{} "default"
+@end group
+@end example
+
+@noindent
+This @code{cond} expression returns @code{foo} if the value of @code{a}
+is @code{hack}, and returns the string @code{"default"} otherwise.
+@end defspec
+
+Any conditional construct can be expressed with @code{cond} or with
+@code{if}.  Therefore, the choice between them is a matter of style.
+For example:
+
+@example
+@group
+(if @var{a} @var{b} @var{c})
+@equiv{}
+(cond (@var{a} @var{b}) (t @var{c}))
+@end group
+@end example
+
+@node Combining Conditions
+@section Constructs for Combining Conditions
+
+  This section describes three constructs that are often used together
+with @code{if} and @code{cond} to express complicated conditions.  The
+constructs @code{and} and @code{or} can also be used individually as
+kinds of multiple conditional constructs.
+
+@defun not condition
+This function tests for the falsehood of @var{condition}.  It returns
+@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise.
+The function @code{not} is identical to @code{null}, and we recommend
+using the name @code{null} if you are testing for an empty list.
+@end defun
+
+@defspec and conditions@dots{}
+The @code{and} special form tests whether all the @var{conditions} are
+true.  It works by evaluating the @var{conditions} one by one in the
+order written.
+
+If any of the @var{conditions} evaluates to @code{nil}, then the result
+of the @code{and} must be @code{nil} regardless of the remaining
+@var{conditions}; so @code{and} returns @code{nil} right away, ignoring
+the remaining @var{conditions}.
+
+If all the @var{conditions} turn out non-@code{nil}, then the value of
+the last of them becomes the value of the @code{and} form.  Just
+@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate
+because all the @var{conditions} turned out non-@code{nil}.  (Think
+about it; which one did not?)
+
+Here is an example.  The first condition returns the integer 1, which is
+not @code{nil}.  Similarly, the second condition returns the integer 2,
+which is not @code{nil}.  The third condition is @code{nil}, so the
+remaining condition is never evaluated.
+
+@example
+@group
+(and (print 1) (print 2) nil (print 3))
+     @print{} 1
+     @print{} 2
+@result{} nil
+@end group
+@end example
+
+Here is a more realistic example of using @code{and}:
+
+@example
+@group
+(if (and (consp foo) (eq (car foo) 'x))
+    (message "foo is a list starting with x"))
+@end group
+@end example
+
+@noindent
+Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
+@code{nil}, thus avoiding an error.
+
+@code{and} expressions can also be written using either @code{if} or
+@code{cond}.  Here's how:
+
+@example
+@group
+(and @var{arg1} @var{arg2} @var{arg3})
+@equiv{}
+(if @var{arg1} (if @var{arg2} @var{arg3}))
+@equiv{}
+(cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
+@end group
+@end example
+@end defspec
+
+@defspec or conditions@dots{}
+The @code{or} special form tests whether at least one of the
+@var{conditions} is true.  It works by evaluating all the
+@var{conditions} one by one in the order written.
+
+If any of the @var{conditions} evaluates to a non-@code{nil} value, then
+the result of the @code{or} must be non-@code{nil}; so @code{or} returns
+right away, ignoring the remaining @var{conditions}.  The value it
+returns is the non-@code{nil} value of the condition just evaluated.
+
+If all the @var{conditions} turn out @code{nil}, then the @code{or}
+expression returns @code{nil}.  Just @code{(or)}, with no
+@var{conditions}, returns @code{nil}, appropriate because all the
+@var{conditions} turned out @code{nil}.  (Think about it; which one
+did not?)
+
+For example, this expression tests whether @code{x} is either
+@code{nil} or the integer zero:
+
+@example
+(or (eq x nil) (eq x 0))
+@end example
+
+Like the @code{and} construct, @code{or} can be written in terms of
+@code{cond}.  For example:
+
+@example
+@group
+(or @var{arg1} @var{arg2} @var{arg3})
+@equiv{}
+(cond (@var{arg1})
+      (@var{arg2})
+      (@var{arg3}))
+@end group
+@end example
+
+You could almost write @code{or} in terms of @code{if}, but not quite:
+
+@example
+@group
+(if @var{arg1} @var{arg1}
+  (if @var{arg2} @var{arg2}
+    @var{arg3}))
+@end group
+@end example
+
+@noindent
+This is not completely equivalent because it can evaluate @var{arg1} or
+@var{arg2} twice.  By contrast, @code{(or @var{arg1} @var{arg2}
+@var{arg3})} never evaluates any argument more than once.
+@end defspec
+
+@node Iteration
+@section Iteration
+@cindex iteration
+@cindex recursion
+
+  Iteration means executing part of a program repetitively.  For
+example, you might want to repeat some computation once for each element
+of a list, or once for each integer from 0 to @var{n}.  You can do this
+in Emacs Lisp with the special form @code{while}:
+
+@defspec while condition forms@dots{}
+@code{while} first evaluates @var{condition}.  If the result is
+non-@code{nil}, it evaluates @var{forms} in textual order.  Then it
+reevaluates @var{condition}, and if the result is non-@code{nil}, it
+evaluates @var{forms} again.  This process repeats until @var{condition}
+evaluates to @code{nil}.
+
+There is no limit on the number of iterations that may occur.  The loop
+will continue until either @var{condition} evaluates to @code{nil} or
+until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}).
+
+The value of a @code{while} form is always @code{nil}.
+
+@example
+@group
+(setq num 0)
+     @result{} 0
+@end group
+@group
+(while (< num 4)
+  (princ (format "Iteration %d." num))
+  (setq num (1+ num)))
+     @print{} Iteration 0.
+     @print{} Iteration 1.
+     @print{} Iteration 2.
+     @print{} Iteration 3.
+     @result{} nil
+@end group
+@end example
+
+To write a ``repeat...until'' loop, which will execute something on each
+iteration and then do the end-test, put the body followed by the
+end-test in a @code{progn} as the first argument of @code{while}, as
+shown here:
+
+@example
+@group
+(while (progn
+         (forward-line 1)
+         (not (looking-at "^$"))))
+@end group
+@end example
+
+@noindent
+This moves forward one line and continues moving by lines until it
+reaches an empty line.  It is peculiar in that the @code{while} has no
+body, just the end test (which also does the real work of moving point).
+@end defspec
+
+  The @code{dolist} and @code{dotimes} macros provide convenient ways to
+write two common kinds of loops.
+
+@defmac dolist (var list [result]) body@dots{}
+This construct executes @var{body} once for each element of
+@var{list}, binding the variable @var{var} locally to hold the current
+element.  Then it returns the value of evaluating @var{result}, or
+@code{nil} if @var{result} is omitted.  For example, here is how you
+could use @code{dolist} to define the @code{reverse} function:
+
+@example
+(defun reverse (list)
+  (let (value)
+    (dolist (elt list value)
+      (setq value (cons elt value)))))
+@end example
+@end defmac
+
+@defmac dotimes (var count [result]) body@dots{}
+This construct executes @var{body} once for each integer from 0
+(inclusive) to @var{count} (exclusive), binding the variable @var{var}
+to the integer for the current iteration.  Then it returns the value
+of evaluating @var{result}, or @code{nil} if @var{result} is omitted.
+Here is an example of using @code{dotimes} to do something 100 times:
+
+@example
+(dotimes (i 100)
+  (insert "I will not obey absurd orders\n"))
+@end example
+@end defmac
+
+@node Nonlocal Exits
+@section Nonlocal Exits
+@cindex nonlocal exits
+
+  A @dfn{nonlocal exit} is a transfer of control from one point in a
+program to another remote point.  Nonlocal exits can occur in Emacs Lisp
+as a result of errors; you can also use them under explicit control.
+Nonlocal exits unbind all variable bindings made by the constructs being
+exited.
+
+@menu
+* Catch and Throw::     Nonlocal exits for the program's own purposes.
+* Examples of Catch::   Showing how such nonlocal exits can be written.
+* Errors::              How errors are signaled and handled.
+* Cleanups::            Arranging to run a cleanup form if an error happens.
+@end menu
+
+@node Catch and Throw
+@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw}
+
+  Most control constructs affect only the flow of control within the
+construct itself.  The function @code{throw} is the exception to this
+rule of normal program execution: it performs a nonlocal exit on
+request.  (There are other exceptions, but they are for error handling
+only.)  @code{throw} is used inside a @code{catch}, and jumps back to
+that @code{catch}.  For example:
+
+@example
+@group
+(defun foo-outer ()
+  (catch 'foo
+    (foo-inner)))
+
+(defun foo-inner ()
+  @dots{}
+  (if x
+      (throw 'foo t))
+  @dots{})
+@end group
+@end example
+
+@noindent
+The @code{throw} form, if executed, transfers control straight back to
+the corresponding @code{catch}, which returns immediately.  The code
+following the @code{throw} is not executed.  The second argument of
+@code{throw} is used as the return value of the @code{catch}.
+
+  The function @code{throw} finds the matching @code{catch} based on the
+first argument: it searches for a @code{catch} whose first argument is
+@code{eq} to the one specified in the @code{throw}.  If there is more
+than one applicable @code{catch}, the innermost one takes precedence.
+Thus, in the above example, the @code{throw} specifies @code{foo}, and
+the @code{catch} in @code{foo-outer} specifies the same symbol, so that
+@code{catch} is the applicable one (assuming there is no other matching
+@code{catch} in between).
+
+  Executing @code{throw} exits all Lisp constructs up to the matching
+@code{catch}, including function calls.  When binding constructs such as
+@code{let} or function calls are exited in this way, the bindings are
+unbound, just as they are when these constructs exit normally
+(@pxref{Local Variables}).  Likewise, @code{throw} restores the buffer
+and position saved by @code{save-excursion} (@pxref{Excursions}), and
+the narrowing status saved by @code{save-restriction} and the window
+selection saved by @code{save-window-excursion} (@pxref{Window
+Configurations}).  It also runs any cleanups established with the
+@code{unwind-protect} special form when it exits that form
+(@pxref{Cleanups}).
+
+  The @code{throw} need not appear lexically within the @code{catch}
+that it jumps to.  It can equally well be called from another function
+called within the @code{catch}.  As long as the @code{throw} takes place
+chronologically after entry to the @code{catch}, and chronologically
+before exit from it, it has access to that @code{catch}.  This is why
+@code{throw} can be used in commands such as @code{exit-recursive-edit}
+that throw back to the editor command loop (@pxref{Recursive Editing}).
+
+@cindex CL note---only @code{throw} in Emacs
+@quotation
+@b{Common Lisp note:} Most other versions of Lisp, including Common Lisp,
+have several ways of transferring control nonsequentially: @code{return},
+@code{return-from}, and @code{go}, for example.  Emacs Lisp has only
+@code{throw}.
+@end quotation
+
+@defspec catch tag body@dots{}
+@cindex tag on run time stack
+@code{catch} establishes a return point for the @code{throw} function.
+The return point is distinguished from other such return points by
+@var{tag}, which may be any Lisp object except @code{nil}.  The argument
+@var{tag} is evaluated normally before the return point is established.
+
+With the return point in effect, @code{catch} evaluates the forms of the
+@var{body} in textual order.  If the forms execute normally (without
+error or nonlocal exit) the value of the last body form is returned from
+the @code{catch}.
+
+If a @code{throw} is executed during the execution of @var{body},
+specifying the same value @var{tag}, the @code{catch} form exits
+immediately; the value it returns is whatever was specified as the
+second argument of @code{throw}.
+@end defspec
+
+@defun throw tag value
+The purpose of @code{throw} is to return from a return point previously
+established with @code{catch}.  The argument @var{tag} is used to choose
+among the various existing return points; it must be @code{eq} to the value
+specified in the @code{catch}.  If multiple return points match @var{tag},
+the innermost one is used.
+
+The argument @var{value} is used as the value to return from that
+@code{catch}.
+
+@kindex no-catch
+If no return point is in effect with tag @var{tag}, then a @code{no-catch}
+error is signaled with data @code{(@var{tag} @var{value})}.
+@end defun
+
+@node Examples of Catch
+@subsection Examples of @code{catch} and @code{throw}
+
+  One way to use @code{catch} and @code{throw} is to exit from a doubly
+nested loop.  (In most languages, this would be done with a ``go to.'')
+Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j}
+varying from 0 to 9:
+
+@example
+@group
+(defun search-foo ()
+  (catch 'loop
+    (let ((i 0))
+      (while (< i 10)
+        (let ((j 0))
+          (while (< j 10)
+            (if (foo i j)
+                (throw 'loop (list i j)))
+            (setq j (1+ j))))
+        (setq i (1+ i))))))
+@end group
+@end example
+
+@noindent
+If @code{foo} ever returns non-@code{nil}, we stop immediately and return a
+list of @var{i} and @var{j}.  If @code{foo} always returns @code{nil}, the
+@code{catch} returns normally, and the value is @code{nil}, since that
+is the result of the @code{while}.
+
+  Here are two tricky examples, slightly different, showing two
+return points at once.  First, two return points with the same tag,
+@code{hack}:
+
+@example
+@group
+(defun catch2 (tag)
+  (catch tag
+    (throw 'hack 'yes)))
+@result{} catch2
+@end group
+
+@group
+(catch 'hack
+  (print (catch2 'hack))
+  'no)
+@print{} yes
+@result{} no
+@end group
+@end example
+
+@noindent
+Since both return points have tags that match the @code{throw}, it goes to
+the inner one, the one established in @code{catch2}.  Therefore,
+@code{catch2} returns normally with value @code{yes}, and this value is
+printed.  Finally the second body form in the outer @code{catch}, which is
+@code{'no}, is evaluated and returned from the outer @code{catch}.
+
+  Now let's change the argument given to @code{catch2}:
+
+@example
+@group
+(catch 'hack
+  (print (catch2 'quux))
+  'no)
+@result{} yes
+@end group
+@end example
+
+@noindent
+We still have two return points, but this time only the outer one has
+the tag @code{hack}; the inner one has the tag @code{quux} instead.
+Therefore, @code{throw} makes the outer @code{catch} return the value
+@code{yes}.  The function @code{print} is never called, and the
+body-form @code{'no} is never evaluated.
+
+@node Errors
+@subsection Errors
+@cindex errors
+
+  When Emacs Lisp attempts to evaluate a form that, for some reason,
+cannot be evaluated, it @dfn{signals} an @dfn{error}.
+
+  When an error is signaled, Emacs's default reaction is to print an
+error message and terminate execution of the current command.  This is
+the right thing to do in most cases, such as if you type @kbd{C-f} at
+the end of the buffer.
+
+  In complicated programs, simple termination may not be what you want.
+For example, the program may have made temporary changes in data
+structures, or created temporary buffers that should be deleted before
+the program is finished.  In such cases, you would use
+@code{unwind-protect} to establish @dfn{cleanup expressions} to be
+evaluated in case of error.  (@xref{Cleanups}.)  Occasionally, you may
+wish the program to continue execution despite an error in a subroutine.
+In these cases, you would use @code{condition-case} to establish
+@dfn{error handlers} to recover control in case of error.
+
+  Resist the temptation to use error handling to transfer control from
+one part of the program to another; use @code{catch} and @code{throw}
+instead.  @xref{Catch and Throw}.
+
+@menu
+* Signaling Errors::      How to report an error.
+* Processing of Errors::  What Emacs does when you report an error.
+* Handling Errors::       How you can trap errors and continue execution.
+* Error Symbols::         How errors are classified for trapping them.
+@end menu
+
+@node Signaling Errors
+@subsubsection How to Signal an Error
+@cindex signaling errors
+
+   @dfn{Signaling} an error means beginning error processing.  Error
+processing normally aborts all or part of the running program and
+returns to a point that is set up to handle the error
+(@pxref{Processing of Errors}).  Here we describe how to signal an
+error.
+
+  Most errors are signaled ``automatically'' within Lisp primitives
+which you call for other purposes, such as if you try to take the
+@sc{car} of an integer or move forward a character at the end of the
+buffer.  You can also signal errors explicitly with the functions
+@code{error} and @code{signal}.
+
+  Quitting, which happens when the user types @kbd{C-g}, is not
+considered an error, but it is handled almost like an error.
+@xref{Quitting}.
+
+  Every error specifies an error message, one way or another.  The
+message should state what is wrong (``File does not exist''), not how
+things ought to be (``File must exist'').  The convention in Emacs
+Lisp is that error messages should start with a capital letter, but
+should not end with any sort of punctuation.
+
+@defun error format-string &rest args
+This function signals an error with an error message constructed by
+applying @code{format} (@pxref{Formatting Strings}) to
+@var{format-string} and @var{args}.
+
+These examples show typical uses of @code{error}:
+
+@example
+@group
+(error "That is an error -- try something else")
+     @error{} That is an error -- try something else
+@end group
+
+@group
+(error "You have committed %d errors" 10)
+     @error{} You have committed 10 errors
+@end group
+@end example
+
+@code{error} works by calling @code{signal} with two arguments: the
+error symbol @code{error}, and a list containing the string returned by
+@code{format}.
+
+@strong{Warning:} If you want to use your own string as an error message
+verbatim, don't just write @code{(error @var{string})}.  If @var{string}
+contains @samp{%}, it will be interpreted as a format specifier, with
+undesirable results.  Instead, use @code{(error "%s" @var{string})}.
+@end defun
+
+@defun signal error-symbol data
+@anchor{Definition of signal}
+This function signals an error named by @var{error-symbol}.  The
+argument @var{data} is a list of additional Lisp objects relevant to
+the circumstances of the error.
+
+The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol
+bearing a property @code{error-conditions} whose value is a list of
+condition names.  This is how Emacs Lisp classifies different sorts of
+errors. @xref{Error Symbols}, for a description of error symbols,
+error conditions and condition names.
+
+If the error is not handled, the two arguments are used in printing
+the error message.  Normally, this error message is provided by the
+@code{error-message} property of @var{error-symbol}.  If @var{data} is
+non-@code{nil}, this is followed by a colon and a comma separated list
+of the unevaluated elements of @var{data}.  For @code{error}, the
+error message is the @sc{car} of @var{data} (that must be a string).
+Subcategories of @code{file-error} are handled specially.
+
+The number and significance of the objects in @var{data} depends on
+@var{error-symbol}.  For example, with a @code{wrong-type-arg} error,
+there should be two objects in the list: a predicate that describes the type
+that was expected, and the object that failed to fit that type.
+
+Both @var{error-symbol} and @var{data} are available to any error
+handlers that handle the error: @code{condition-case} binds a local
+variable to a list of the form @code{(@var{error-symbol} .@:
+@var{data})} (@pxref{Handling Errors}).
+
+The function @code{signal} never returns (though in older Emacs versions
+it could sometimes return).
+
+@smallexample
+@group
+(signal 'wrong-number-of-arguments '(x y))
+     @error{} Wrong number of arguments: x, y
+@end group
+
+@group
+(signal 'no-such-error '("My unknown error condition"))
+     @error{} peculiar error: "My unknown error condition"
+@end group
+@end smallexample
+@end defun
+
+@cindex CL note---no continuable errors
+@quotation
+@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp
+concept of continuable errors.
+@end quotation
+
+@node Processing of Errors
+@subsubsection How Emacs Processes Errors
+
+When an error is signaled, @code{signal} searches for an active
+@dfn{handler} for the error.  A handler is a sequence of Lisp
+expressions designated to be executed if an error happens in part of the
+Lisp program.  If the error has an applicable handler, the handler is
+executed, and control resumes following the handler.  The handler
+executes in the environment of the @code{condition-case} that
+established it; all functions called within that @code{condition-case}
+have already been exited, and the handler cannot return to them.
+
+If there is no applicable handler for the error, it terminates the
+current command and returns control to the editor command loop.  (The
+command loop has an implicit handler for all kinds of errors.)  The
+command loop's handler uses the error symbol and associated data to
+print an error message.  You can use the variable
+@code{command-error-function} to control how this is done:
+
+@defvar command-error-function
+This variable, if non-@code{nil}, specifies a function to use to
+handle errors that return control to the Emacs command loop.  The
+function should take three arguments: @var{data}, a list of the same
+form that @code{condition-case} would bind to its variable;
+@var{context}, a string describing the situation in which the error
+occurred, or (more often) @code{nil}; and @var{caller}, the Lisp
+function which called the primitive that signaled the error.
+@end defvar
+
+@cindex @code{debug-on-error} use
+An error that has no explicit handler may call the Lisp debugger.  The
+debugger is enabled if the variable @code{debug-on-error} (@pxref{Error
+Debugging}) is non-@code{nil}.  Unlike error handlers, the debugger runs
+in the environment of the error, so that you can examine values of
+variables precisely as they were at the time of the error.
+
+@node Handling Errors
+@subsubsection Writing Code to Handle Errors
+@cindex error handler
+@cindex handling errors
+
+  The usual effect of signaling an error is to terminate the command
+that is running and return immediately to the Emacs editor command loop.
+You can arrange to trap errors occurring in a part of your program by
+establishing an error handler, with the special form
+@code{condition-case}.  A simple example looks like this:
+
+@example
+@group
+(condition-case nil
+    (delete-file filename)
+  (error nil))
+@end group
+@end example
+
+@noindent
+This deletes the file named @var{filename}, catching any error and
+returning @code{nil} if an error occurs.
+
+  The @code{condition-case} construct is often used to trap errors that
+are predictable, such as failure to open a file in a call to
+@code{insert-file-contents}.  It is also used to trap errors that are
+totally unpredictable, such as when the program evaluates an expression
+read from the user.
+
+  The second argument of @code{condition-case} is called the
+@dfn{protected form}.  (In the example above, the protected form is a
+call to @code{delete-file}.)  The error handlers go into effect when
+this form begins execution and are deactivated when this form returns.
+They remain in effect for all the intervening time.  In particular, they
+are in effect during the execution of functions called by this form, in
+their subroutines, and so on.  This is a good thing, since, strictly
+speaking, errors can be signaled only by Lisp primitives (including
+@code{signal} and @code{error}) called by the protected form, not by the
+protected form itself.
+
+  The arguments after the protected form are handlers.  Each handler
+lists one or more @dfn{condition names} (which are symbols) to specify
+which errors it will handle.  The error symbol specified when an error
+is signaled also defines a list of condition names.  A handler applies
+to an error if they have any condition names in common.  In the example
+above, there is one handler, and it specifies one condition name,
+@code{error}, which covers all errors.
+
+  The search for an applicable handler checks all the established handlers
+starting with the most recently established one.  Thus, if two nested
+@code{condition-case} forms offer to handle the same error, the inner of
+the two gets to handle it.
+
+  If an error is handled by some @code{condition-case} form, this
+ordinarily prevents the debugger from being run, even if
+@code{debug-on-error} says this error should invoke the debugger.
+
+  If you want to be able to debug errors that are caught by a
+@code{condition-case}, set the variable @code{debug-on-signal} to a
+non-@code{nil} value.  You can also specify that a particular handler
+should let the debugger run first, by writing @code{debug} among the
+conditions, like this:
+
+@example
+@group
+(condition-case nil
+    (delete-file filename)
+  ((debug error) nil))
+@end group
+@end example
+
+@noindent
+The effect of @code{debug} here is only to prevent
+@code{condition-case} from suppressing the call to the debugger.  Any
+given error will invoke the debugger only if @code{debug-on-error} and
+the other usual filtering mechanisms say it should.  @xref{Error Debugging}.
+
+  Once Emacs decides that a certain handler handles the error, it
+returns control to that handler.  To do so, Emacs unbinds all variable
+bindings made by binding constructs that are being exited, and
+executes the cleanups of all @code{unwind-protect} forms that are
+being exited.  Once control arrives at the handler, the body of the
+handler executes normally.
+
+  After execution of the handler body, execution returns from the
+@code{condition-case} form.  Because the protected form is exited
+completely before execution of the handler, the handler cannot resume
+execution at the point of the error, nor can it examine variable
+bindings that were made within the protected form.  All it can do is
+clean up and proceed.
+
+  Error signaling and handling have some resemblance to @code{throw} and
+@code{catch} (@pxref{Catch and Throw}), but they are entirely separate
+facilities.  An error cannot be caught by a @code{catch}, and a
+@code{throw} cannot be handled by an error handler (though using
+@code{throw} when there is no suitable @code{catch} signals an error
+that can be handled).
+
+@defspec condition-case var protected-form handlers@dots{}
+This special form establishes the error handlers @var{handlers} around
+the execution of @var{protected-form}.  If @var{protected-form} executes
+without error, the value it returns becomes the value of the
+@code{condition-case} form; in this case, the @code{condition-case} has
+no effect.  The @code{condition-case} form makes a difference when an
+error occurs during @var{protected-form}.
+
+Each of the @var{handlers} is a list of the form @code{(@var{conditions}
+@var{body}@dots{})}.  Here @var{conditions} is an error condition name
+to be handled, or a list of condition names (which can include @code{debug}
+to allow the debugger to run before the handler); @var{body} is one or more
+Lisp expressions to be executed when this handler handles an error.
+Here are examples of handlers:
+
+@smallexample
+@group
+(error nil)
+
+(arith-error (message "Division by zero"))
+
+((arith-error file-error)
+ (message
+  "Either division by zero or failure to open a file"))
+@end group
+@end smallexample
+
+Each error that occurs has an @dfn{error symbol} that describes what
+kind of error it is.  The @code{error-conditions} property of this
+symbol is a list of condition names (@pxref{Error Symbols}).  Emacs
+searches all the active @code{condition-case} forms for a handler that
+specifies one or more of these condition names; the innermost matching
+@code{condition-case} handles the error.  Within this
+@code{condition-case}, the first applicable handler handles the error.
+
+After executing the body of the handler, the @code{condition-case}
+returns normally, using the value of the last form in the handler body
+as the overall value.
+
+@cindex error description
+The argument @var{var} is a variable.  @code{condition-case} does not
+bind this variable when executing the @var{protected-form}, only when it
+handles an error.  At that time, it binds @var{var} locally to an
+@dfn{error description}, which is a list giving the particulars of the
+error.  The error description has the form @code{(@var{error-symbol}
+. @var{data})}.  The handler can refer to this list to decide what to
+do.  For example, if the error is for failure opening a file, the file
+name is the second element of @var{data}---the third element of the
+error description.
+
+If @var{var} is @code{nil}, that means no variable is bound.  Then the
+error symbol and associated data are not available to the handler.
+@end defspec
+
+@defun error-message-string error-description
+This function returns the error message string for a given error
+descriptor.  It is useful if you want to handle an error by printing the
+usual error message for that error.  @xref{Definition of signal}.
+@end defun
+
+@cindex @code{arith-error} example
+Here is an example of using @code{condition-case} to handle the error
+that results from dividing by zero.  The handler displays the error
+message (but without a beep), then returns a very large number.
+
+@smallexample
+@group
+(defun safe-divide (dividend divisor)
+  (condition-case err
+      ;; @r{Protected form.}
+      (/ dividend divisor)
+@end group
+@group
+    ;; @r{The handler.}
+    (arith-error                        ; @r{Condition.}
+     ;; @r{Display the usual message for this error.}
+     (message "%s" (error-message-string err))
+     1000000)))
+@result{} safe-divide
+@end group
+
+@group
+(safe-divide 5 0)
+     @print{} Arithmetic error: (arith-error)
+@result{} 1000000
+@end group
+@end smallexample
+
+@noindent
+The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors.  Other kinds of errors will not be handled, at least not by this @code{condition-case}.  Thus,
+
+@smallexample
+@group
+(safe-divide nil 3)
+     @error{} Wrong type argument: number-or-marker-p, nil
+@end group
+@end smallexample
+
+  Here is a @code{condition-case} that catches all kinds of errors,
+including those signaled with @code{error}:
+
+@smallexample
+@group
+(setq baz 34)
+     @result{} 34
+@end group
+
+@group
+(condition-case err
+    (if (eq baz 35)
+        t
+      ;; @r{This is a call to the function @code{error}.}
+      (error "Rats!  The variable %s was %s, not 35" 'baz baz))
+  ;; @r{This is the handler; it is not a form.}
+  (error (princ (format "The error was: %s" err))
+         2))
+@print{} The error was: (error "Rats!  The variable baz was 34, not 35")
+@result{} 2
+@end group
+@end smallexample
+
+@node Error Symbols
+@subsubsection Error Symbols and Condition Names
+@cindex error symbol
+@cindex error name
+@cindex condition name
+@cindex user-defined error
+@kindex error-conditions
+
+  When you signal an error, you specify an @dfn{error symbol} to specify
+the kind of error you have in mind.  Each error has one and only one
+error symbol to categorize it.  This is the finest classification of
+errors defined by the Emacs Lisp language.
+
+  These narrow classifications are grouped into a hierarchy of wider
+classes called @dfn{error conditions}, identified by @dfn{condition
+names}.  The narrowest such classes belong to the error symbols
+themselves: each error symbol is also a condition name.  There are also
+condition names for more extensive classes, up to the condition name
+@code{error} which takes in all kinds of errors (but not @code{quit}).
+Thus, each error has one or more condition names: @code{error}, the
+error symbol if that is distinct from @code{error}, and perhaps some
+intermediate classifications.
+
+  In order for a symbol to be an error symbol, it must have an
+@code{error-conditions} property which gives a list of condition names.
+This list defines the conditions that this kind of error belongs to.
+(The error symbol itself, and the symbol @code{error}, should always be
+members of this list.)  Thus, the hierarchy of condition names is
+defined by the @code{error-conditions} properties of the error symbols.
+Because quitting is not considered an error, the value of the
+@code{error-conditions} property of @code{quit} is just @code{(quit)}.
+
+@cindex peculiar error
+  In addition to the @code{error-conditions} list, the error symbol
+should have an @code{error-message} property whose value is a string to
+be printed when that error is signaled but not handled.  If the
+error symbol has no @code{error-message} property or if the
+@code{error-message} property exists, but is not a string, the error
+message @samp{peculiar error} is used.  @xref{Definition of signal}.
+
+  Here is how we define a new error symbol, @code{new-error}:
+
+@example
+@group
+(put 'new-error
+     'error-conditions
+     '(error my-own-errors new-error))
+@result{} (error my-own-errors new-error)
+@end group
+@group
+(put 'new-error 'error-message "A new error")
+@result{} "A new error"
+@end group
+@end example
+
+@noindent
+This error has three condition names: @code{new-error}, the narrowest
+classification; @code{my-own-errors}, which we imagine is a wider
+classification; and @code{error}, which is the widest of all.
+
+  The error string should start with a capital letter but it should
+not end with a period.  This is for consistency with the rest of Emacs.
+
+  Naturally, Emacs will never signal @code{new-error} on its own; only
+an explicit call to @code{signal} (@pxref{Definition of signal}) in
+your code can do this:
+
+@example
+@group
+(signal 'new-error '(x y))
+     @error{} A new error: x, y
+@end group
+@end example
+
+  This error can be handled through any of the three condition names.
+This example handles @code{new-error} and any other errors in the class
+@code{my-own-errors}:
+
+@example
+@group
+(condition-case foo
+    (bar nil t)
+  (my-own-errors nil))
+@end group
+@end example
+
+  The significant way that errors are classified is by their condition
+names---the names used to match errors with handlers.  An error symbol
+serves only as a convenient way to specify the intended error message
+and list of condition names.  It would be cumbersome to give
+@code{signal} a list of condition names rather than one error symbol.
+
+  By contrast, using only error symbols without condition names would
+seriously decrease the power of @code{condition-case}.  Condition names
+make it possible to categorize errors at various levels of generality
+when you write an error handler.  Using error symbols alone would
+eliminate all but the narrowest level of classification.
+
+  @xref{Standard Errors}, for a list of all the standard error symbols
+and their conditions.
+
+@node Cleanups
+@subsection Cleaning Up from Nonlocal Exits
+
+  The @code{unwind-protect} construct is essential whenever you
+temporarily put a data structure in an inconsistent state; it permits
+you to make the data consistent again in the event of an error or
+throw.  (Another more specific cleanup construct that is used only for
+changes in buffer contents is the atomic change group; @ref{Atomic
+Changes}.)
+
+@defspec unwind-protect body-form cleanup-forms@dots{}
+@cindex cleanup forms
+@cindex protected forms
+@cindex error cleanup
+@cindex unwinding
+@code{unwind-protect} executes @var{body-form} with a guarantee that
+the @var{cleanup-forms} will be evaluated if control leaves
+@var{body-form}, no matter how that happens.  @var{body-form} may
+complete normally, or execute a @code{throw} out of the
+@code{unwind-protect}, or cause an error; in all cases, the
+@var{cleanup-forms} will be evaluated.
+
+If @var{body-form} finishes normally, @code{unwind-protect} returns the
+value of @var{body-form}, after it evaluates the @var{cleanup-forms}.
+If @var{body-form} does not finish, @code{unwind-protect} does not
+return any value in the normal sense.
+
+Only @var{body-form} is protected by the @code{unwind-protect}.  If any
+of the @var{cleanup-forms} themselves exits nonlocally (via a
+@code{throw} or an error), @code{unwind-protect} is @emph{not}
+guaranteed to evaluate the rest of them.  If the failure of one of the
+@var{cleanup-forms} has the potential to cause trouble, then protect
+it with another @code{unwind-protect} around that form.
+
+The number of currently active @code{unwind-protect} forms counts,
+together with the number of local variable bindings, against the limit
+@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local
+Variables}).
+@end defspec
+
+  For example, here we make an invisible buffer for temporary use, and
+make sure to kill it before finishing:
+
+@smallexample
+@group
+(save-excursion
+  (let ((buffer (get-buffer-create " *temp*")))
+    (set-buffer buffer)
+    (unwind-protect
+        @var{body-form}
+      (kill-buffer buffer))))
+@end group
+@end smallexample
+
+@noindent
+You might think that we could just as well write @code{(kill-buffer
+(current-buffer))} and dispense with the variable @code{buffer}.
+However, the way shown above is safer, if @var{body-form} happens to
+get an error after switching to a different buffer!  (Alternatively,
+you could write another @code{save-excursion} around @var{body-form},
+to ensure that the temporary buffer becomes current again in time to
+kill it.)
+
+  Emacs includes a standard macro called @code{with-temp-buffer} which
+expands into more or less the code shown above (@pxref{Definition of
+with-temp-buffer,, Current Buffer}).  Several of the macros defined in
+this manual use @code{unwind-protect} in this way.
+
+@findex ftp-login
+  Here is an actual example derived from an FTP package.  It creates a
+process (@pxref{Processes}) to try to establish a connection to a remote
+machine.  As the function @code{ftp-login} is highly susceptible to
+numerous problems that the writer of the function cannot anticipate, it
+is protected with a form that guarantees deletion of the process in the
+event of failure.  Otherwise, Emacs might fill up with useless
+subprocesses.
+
+@smallexample
+@group
+(let ((win nil))
+  (unwind-protect
+      (progn
+        (setq process (ftp-setup-buffer host file))
+        (if (setq win (ftp-login process host user password))
+            (message "Logged in")
+          (error "Ftp login failed")))
+    (or win (and process (delete-process process)))))
+@end group
+@end smallexample
+
+  This example has a small bug: if the user types @kbd{C-g} to
+quit, and the quit happens immediately after the function
+@code{ftp-setup-buffer} returns but before the variable @code{process} is
+set, the process will not be killed.  There is no easy way to fix this bug,
+but at least it is very unlikely.
+
+@ignore
+   arch-tag: 8abc30d4-4d3a-47f9-b908-e9e971c18c6d
+@end ignore
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
new file mode 100644
index 00000000000..8b1b1a9b91f
--- /dev/null
+++ b/doc/lispref/customize.texi
@@ -0,0 +1,1253 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/customize
+@node Customization, Loading, Macros, Top
+@chapter Writing Customization Definitions
+
+@cindex customization definitions
+  This chapter describes how to declare user options for customization,
+and also customization groups for classifying them.  We use the term
+@dfn{customization item} to include both kinds of customization
+definitions---as well as face definitions (@pxref{Defining Faces}).
+
+@menu
+* Common Keywords::      Common keyword arguments for all kinds of
+                           customization declarations.
+* Group Definitions::    Writing customization group definitions.
+* Variable Definitions:: Declaring user options.
+* Customization Types::  Specifying the type of a user option.
+@end menu
+
+@node Common Keywords
+@section Common Item Keywords
+
+@cindex customization keywords
+  All kinds of customization declarations (for variables and groups, and
+for faces) accept keyword arguments for specifying various information.
+This section describes some keywords that apply to all kinds.
+
+  All of these keywords, except @code{:tag}, can be used more than once
+in a given item.  Each use of the keyword has an independent effect.
+The keyword @code{:tag} is an exception because any given item can only
+display one name.
+
+@table @code
+@item :tag @var{label}
+@kindex tag@r{, customization keyword}
+Use @var{label}, a string, instead of the item's name, to label the
+item in customization menus and buffers.  @strong{Don't use a tag
+which is substantially different from the item's real name; that would
+cause confusion.}  One legitimate case for use of @code{:tag} is to
+specify a dash where normally a hyphen would be converted to a space:
+
+@example
+(defcustom cursor-in-non-selected-windows @dots{}
+  :tag "Cursor In Non-selected Windows"
+@end example
+
+@kindex group@r{, customization keyword}
+@item :group @var{group}
+Put this customization item in group @var{group}.  When you use
+@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
+@var{group}.
+
+If you use this keyword more than once, you can put a single item into
+more than one group.  Displaying any of those groups will show this
+item.  Please don't overdo this, since the result would be annoying.
+
+@item :link @var{link-data}
+@kindex link@r{, customization keyword}
+Include an external link after the documentation string for this item.
+This is a sentence containing an active field which references some
+other documentation.
+
+There are several alternatives you can use for @var{link-data}:
+
+@table @code
+@item (custom-manual @var{info-node})
+Link to an Info node; @var{info-node} is a string which specifies the
+node name, as in @code{"(emacs)Top"}.  The link appears as
+@samp{[Manual]} in the customization buffer and enters the built-in
+Info reader on @var{info-node}.
+
+@item (info-link @var{info-node})
+Like @code{custom-manual} except that the link appears
+in the customization buffer with the Info node name.
+
+@item (url-link @var{url})
+Link to a web page; @var{url} is a string which specifies the
+@acronym{URL}.  The link appears in the customization buffer as
+@var{url} and invokes the WWW browser specified by
+@code{browse-url-browser-function}.
+
+@item (emacs-commentary-link @var{library})
+Link to the commentary section of a library; @var{library} is a string
+which specifies the library name.
+
+@item (emacs-library-link @var{library})
+Link to an Emacs Lisp library file; @var{library} is a string which
+specifies the library name.
+
+@item (file-link @var{file})
+Link to a file; @var{file} is a string which specifies the name of the
+file to visit with @code{find-file} when the user invokes this link.
+
+@item (function-link @var{function})
+Link to the documentation of a function; @var{function} is a string
+which specifies the name of the function to describe with
+@code{describe-function} when the user invokes this link.
+
+@item (variable-link @var{variable})
+Link to the documentation of a variable; @var{variable} is a string
+which specifies the name of the variable to describe with
+@code{describe-variable} when the user invokes this link.
+
+@item (custom-group-link @var{group})
+Link to another customization group.  Invoking it creates a new
+customization buffer for @var{group}.
+@end table
+
+You can specify the text to use in the customization buffer by adding
+@code{:tag @var{name}} after the first element of the @var{link-data};
+for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
+the Emacs manual which appears in the buffer as @samp{foo}.
+
+An item can have more than one external link; however, most items have
+none at all.
+
+@item :load @var{file}
+@kindex load@r{, customization keyword}
+Load file @var{file} (a string) before displaying this customization
+item.  Loading is done with @code{load-library}, and only if the file is
+not already loaded.
+
+@item :require @var{feature}
+@kindex require@r{, customization keyword}
+Execute @code{(require '@var{feature})} when your saved customizations
+set the value of this item.  @var{feature} should be a symbol.
+
+The most common reason to use @code{:require} is when a variable enables
+a feature such as a minor mode, and just setting the variable won't have
+any effect unless the code which implements the mode is loaded.
+
+@item :version @var{version}
+@kindex version@r{, customization keyword}
+This keyword specifies that the item was first introduced in Emacs
+version @var{version}, or that its default value was changed in that
+version.  The value @var{version} must be a string.
+
+@item :package-version '(@var{package} . @var{version})
+@kindex package-version@r{, customization keyword}
+This keyword specifies that the item was first introduced in
+@var{package} version @var{version}, or that its meaning or default
+value was changed in that version.  The value of @var{package} is a
+symbol and @var{version} is a string.
+
+This keyword takes priority over @code{:version}.
+
+@var{package} should be the official name of the package, such as MH-E
+or Gnus.  If the package @var{package} is released as part of Emacs,
+@var{package} and @var{version} should appear in the value of
+@code{customize-package-emacs-version-alist}.
+@end table
+
+Packages distributed as part of Emacs that use the
+@code{:package-version} keyword must also update the
+@code{customize-package-emacs-version-alist} variable.
+
+@defvar customize-package-emacs-version-alist
+This alist provides a mapping for the versions of Emacs that are
+associated with versions of a package listed in the
+@code{:package-version} keyword.  Its elements look like this:
+
+@example
+(@var{package} (@var{pversion} . @var{eversion})@dots{})
+@end example
+
+For each @var{package}, which is a symbol, there are one or more
+elements that contain a package version @var{pversion} with an
+associated Emacs version @var{eversion}.  These versions are strings.
+For example, the MH-E package updates this alist with the following:
+
+@smallexample
+(add-to-list 'customize-package-emacs-version-alist
+             '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
+                    ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
+                    ("7.4" . "22.1") ("8.0" . "22.1")))
+@end smallexample
+
+The value of @var{package} needs to be unique and it needs to match
+the @var{package} value appearing in the @code{:package-version}
+keyword.  Since the user might see the value in a error message, a good
+choice is the official name of the package, such as MH-E or Gnus.
+@end defvar
+
+@node Group Definitions
+@section Defining Customization Groups
+@cindex define customization group
+@cindex customization groups, defining
+
+  Each Emacs Lisp package should have one main customization group which
+contains all the options, faces and other groups in the package.  If the
+package has a small number of options and faces, use just one group and
+put everything in it.  When there are more than twelve or so options and
+faces, then you should structure them into subgroups, and put the
+subgroups under the package's main customization group.  It is OK to
+put some of the options and faces in the package's main group alongside
+the subgroups.
+
+  The package's main or only group should be a member of one or more of
+the standard customization groups.  (To display the full list of them,
+use @kbd{M-x customize}.)  Choose one or more of them (but not too
+many), and add your group to each of them using the @code{:group}
+keyword.
+
+  The way to declare new customization groups is with @code{defgroup}.
+
+@defmac defgroup group members doc [keyword value]@dots{}
+Declare @var{group} as a customization group containing @var{members}.
+Do not quote the symbol @var{group}.  The argument @var{doc} specifies
+the documentation string for the group.
+
+The argument @var{members} is a list specifying an initial set of
+customization items to be members of the group.  However, most often
+@var{members} is @code{nil}, and you specify the group's members by
+using the @code{:group} keyword when defining those members.
+
+If you want to specify group members through @var{members}, each element
+should have the form @code{(@var{name} @var{widget})}.  Here @var{name}
+is a symbol, and @var{widget} is a widget type for editing that symbol.
+Useful widgets are @code{custom-variable} for a variable,
+@code{custom-face} for a face, and @code{custom-group} for a group.
+
+When you introduce a new group into Emacs, use the @code{:version}
+keyword in the @code{defgroup}; then you need not use it for
+the individual members of the group.
+
+In addition to the common keywords (@pxref{Common Keywords}), you can
+also use this keyword in @code{defgroup}:
+
+@table @code
+@item :prefix @var{prefix}
+@kindex prefix@r{, @code{defgroup} keyword}
+If the name of an item in the group starts with @var{prefix}, then the
+tag for that item is constructed (by default) by omitting @var{prefix}.
+
+One group can have any number of prefixes.
+@end table
+@end defmac
+
+  The prefix-discarding feature is currently turned off, which means
+that @code{:prefix} currently has no effect.  We did this because we
+found that discarding the specified prefixes often led to confusing
+names for options.  This happened because the people who wrote the
+@code{defgroup} definitions for various groups added @code{:prefix}
+keywords whenever they make logical sense---that is, whenever the
+variables in the library have a common prefix.
+
+  In order to obtain good results with @code{:prefix}, it would be
+necessary to check the specific effects of discarding a particular
+prefix, given the specific items in a group and their names and
+documentation.  If the resulting text is not clear, then @code{:prefix}
+should not be used in that case.
+
+  It should be possible to recheck all the customization groups, delete
+the @code{:prefix} specifications which give unclear results, and then
+turn this feature back on, if someone would like to do the work.
+
+@node Variable Definitions
+@section Defining Customization Variables
+@cindex define customization options
+@cindex customization variables, how to define
+
+  Use @code{defcustom} to declare user-customizable variables.
+
+@defmac defcustom option standard doc [keyword value]@dots{}
+This construct declares @var{option} as a customizable user option
+variable.  You should not quote @var{option}.  The argument @var{doc}
+specifies the documentation string for the variable.  There is no need
+to start it with a @samp{*}, because @code{defcustom} automatically
+marks @var{option} as a @dfn{user option} (@pxref{Defining
+Variables}).
+
+The argument @var{standard} is an expression that specifies the
+standard value for @var{option}.  Evaluating the @code{defcustom} form
+evaluates @var{standard}, but does not necessarily install the
+standard value.  If @var{option} already has a default value,
+@code{defcustom} does not change it.  If the user has saved a
+customization for @var{option}, @code{defcustom} installs the user's
+customized value as @var{option}'s default value.  If neither of those
+cases applies, @code{defcustom} installs the result of evaluating
+@var{standard} as the default value.
+
+The expression @var{standard} can be evaluated at various other times,
+too---whenever the customization facility needs to know @var{option}'s
+standard value.  So be sure to use an expression which is harmless to
+evaluate at any time.  We recommend avoiding backquotes in
+@var{standard}, because they are not expanded when editing the value,
+so list values will appear to have the wrong structure.
+
+Every @code{defcustom} should specify @code{:group} at least once.
+
+If you specify the @code{:set} keyword, to make the variable take other
+special actions when set through the customization buffer, the
+variable's documentation string should tell the user specifically how
+to do the same job in hand-written Lisp code.
+
+When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
+mode (@code{eval-defun}), a special feature of @code{eval-defun}
+arranges to set the variable unconditionally, without testing whether
+its value is void.  (The same feature applies to @code{defvar}.)
+@xref{Defining Variables}.
+@end defmac
+
+  @code{defcustom} accepts the following additional keywords:
+
+@table @code
+@item :type @var{type}
+Use @var{type} as the data type for this option.  It specifies which
+values are legitimate, and how to display the value.
+@xref{Customization Types}, for more information.
+
+@item :options @var{value-list}
+@kindex options@r{, @code{defcustom} keyword}
+Specify the list of reasonable values for use in this
+option.  The user is not restricted to using only these values, but they
+are offered as convenient alternatives.
+
+This is meaningful only for certain types, currently including
+@code{hook}, @code{plist} and @code{alist}.  See the definition of the
+individual types for a description of how to use @code{:options}.
+
+@item :set @var{setfunction}
+@kindex set@r{, @code{defcustom} keyword}
+Specify @var{setfunction} as the way to change the value of this
+option.  The function @var{setfunction} should take two arguments, a
+symbol (the option name) and the new value, and should do whatever is
+necessary to update the value properly for this option (which may not
+mean simply setting the option as a Lisp variable).  The default for
+@var{setfunction} is @code{set-default}.
+
+@item :get @var{getfunction}
+@kindex get@r{, @code{defcustom} keyword}
+Specify @var{getfunction} as the way to extract the value of this
+option.  The function @var{getfunction} should take one argument, a
+symbol, and should return whatever customize should use as the
+``current value'' for that symbol (which need not be the symbol's Lisp
+value).  The default is @code{default-value}.
+
+You have to really understand the workings of Custom to use
+@code{:get} correctly.  It is meant for values that are treated in
+Custom as variables but are not actually stored in Lisp variables.  It
+is almost surely a mistake to specify @code{getfunction} for a value
+that really is stored in a Lisp variable.
+
+@item :initialize @var{function}
+@kindex initialize@r{, @code{defcustom} keyword}
+@var{function} should be a function used to initialize the variable
+when the @code{defcustom} is evaluated.  It should take two arguments,
+the option name (a symbol) and the value.  Here are some predefined
+functions meant for use in this way:
+
+@table @code
+@item custom-initialize-set
+Use the variable's @code{:set} function to initialize the variable, but
+do not reinitialize it if it is already non-void.
+
+@item custom-initialize-default
+Like @code{custom-initialize-set}, but use the function
+@code{set-default} to set the variable, instead of the variable's
+@code{:set} function.  This is the usual choice for a variable whose
+@code{:set} function enables or disables a minor mode; with this choice,
+defining the variable will not call the minor mode function, but
+customizing the variable will do so.
+
+@item custom-initialize-reset
+Always use the @code{:set} function to initialize the variable.  If
+the variable is already non-void, reset it by calling the @code{:set}
+function using the current value (returned by the @code{:get} method).
+This is the default @code{:initialize} function.
+
+@item custom-initialize-changed
+Use the @code{:set} function to initialize the variable, if it is
+already set or has been customized; otherwise, just use
+@code{set-default}.
+
+@item custom-initialize-safe-set
+@itemx custom-initialize-safe-default
+These functions behave like @code{custom-initialize-set}
+(@code{custom-initialize-default}, respectively), but catch errors.
+If an error occurs during initialization, they set the variable to
+@code{nil} using @code{set-default}, and throw no error.
+
+These two functions are only meant for options defined in pre-loaded
+files, where some variables or functions used to compute the option's
+value may not yet be defined.  The option normally gets updated in
+@file{startup.el}, ignoring the previously computed value.  Because of
+this typical usage, the value which these two functions compute
+normally only matters when, after startup, one unsets the option's
+value and then reevaluates the defcustom.  By that time, the necessary
+variables and functions will be defined, so there will not be an error.
+@end table
+
+@item :set-after @var{variables}
+@kindex set-after@r{, @code{defcustom} keyword}
+When setting variables according to saved customizations, make sure to
+set the variables @var{variables} before this one; in other words, delay
+setting this variable until after those others have been handled.  Use
+@code{:set-after} if setting this variable won't work properly unless
+those other variables already have their intended values.
+@end table
+
+  The @code{:require} keyword is useful for an option that turns on the
+operation of a certain feature.  Assuming that the package is coded to
+check the value of the option, you still need to arrange for the package
+to be loaded.  You can do that with @code{:require}.  @xref{Common
+Keywords}.  Here is an example, from the library @file{saveplace.el}:
+
+@example
+(defcustom save-place nil
+  "Non-nil means automatically save place in each file..."
+  :type 'boolean
+  :require 'saveplace
+  :group 'save-place)
+@end example
+
+If a customization item has a type such as @code{hook} or
+@code{alist}, which supports @code{:options}, you can add additional
+values to the list from outside the @code{defcustom} declaration by
+calling @code{custom-add-frequent-value}.  For example, if you define a
+function @code{my-lisp-mode-initialization} intended to be called from
+@code{emacs-lisp-mode-hook}, you might want to add that to the list of
+reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
+its definition.  You can do it thus:
+
+@example
+(custom-add-frequent-value 'emacs-lisp-mode-hook
+   'my-lisp-mode-initialization)
+@end example
+
+@defun custom-add-frequent-value symbol value
+For the customization option @var{symbol}, add @var{value} to the
+list of reasonable values.
+
+The precise effect of adding a value depends on the customization type
+of @var{symbol}.
+@end defun
+
+Internally, @code{defcustom} uses the symbol property
+@code{standard-value} to record the expression for the standard value,
+and @code{saved-value} to record the value saved by the user with the
+customization buffer.  Both properties are actually lists whose car is
+an expression which evaluates to the value.
+
+@node Customization Types
+@section Customization Types
+
+@cindex customization types
+  When you define a user option with @code{defcustom}, you must specify
+its @dfn{customization type}.  That is a Lisp object which describes (1)
+which values are legitimate and (2) how to display the value in the
+customization buffer for editing.
+
+@kindex type@r{, @code{defcustom} keyword}
+  You specify the customization type in @code{defcustom} with the
+@code{:type} keyword.  The argument of @code{:type} is evaluated, but
+only once when the @code{defcustom} is executed, so it isn't useful
+for the value to vary.  Normally we use a quoted constant.  For
+example:
+
+@example
+(defcustom diff-command "diff"
+  "The command to use to run diff."
+  :type '(string)
+  :group 'diff)
+@end example
+
+  In general, a customization type is a list whose first element is a
+symbol, one of the customization type names defined in the following
+sections.  After this symbol come a number of arguments, depending on
+the symbol.  Between the type symbol and its arguments, you can
+optionally write keyword-value pairs (@pxref{Type Keywords}).
+
+  Some of the type symbols do not use any arguments; those are called
+@dfn{simple types}.  For a simple type, if you do not use any
+keyword-value pairs, you can omit the parentheses around the type
+symbol.  For example just @code{string} as a customization type is
+equivalent to @code{(string)}.
+
+@menu
+* Simple Types::
+* Composite Types::
+* Splicing into Lists::
+* Type Keywords::
+* Defining New Types::
+@end menu
+
+All customization types are implemented as widgets; see @ref{Top, ,
+Introduction, widget, The Emacs Widget Library}, for details.
+
+@node Simple Types
+@subsection Simple Types
+
+  This section describes all the simple customization types.
+
+@table @code
+@item sexp
+The value may be any Lisp object that can be printed and read back.  You
+can use @code{sexp} as a fall-back for any option, if you don't want to
+take the time to work out a more specific type to use.
+
+@item integer
+The value must be an integer, and is represented textually
+in the customization buffer.
+
+@item number
+The value must be a number (floating point or integer), and is
+represented textually in the customization buffer.
+
+@item float
+The value must be a floating point number, and is represented
+textually in the customization buffer.
+
+@item string
+The value must be a string, and the customization buffer shows just the
+contents, with no delimiting @samp{"} characters and no quoting with
+@samp{\}.
+
+@item regexp
+Like @code{string} except that the string must be a valid regular
+expression.
+
+@item character
+The value must be a character code.  A character code is actually an
+integer, but this type shows the value by inserting the character in the
+buffer, rather than by showing the number.
+
+@item file
+The value must be a file name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item (file :must-match t)
+The value must be a file name for an existing file, and you can do
+completion with @kbd{M-@key{TAB}}.
+
+@item directory
+The value must be a directory name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item hook
+The value must be a list of functions (or a single function, but that is
+obsolete usage).  This customization type is used for hook variables.
+You can use the @code{:options} keyword in a hook variable's
+@code{defcustom} to specify a list of functions recommended for use in
+the hook; see @ref{Variable Definitions}.
+
+@item alist
+The value must be a list of cons-cells, the @sc{car} of each cell
+representing a key, and the @sc{cdr} of the same cell representing an
+associated value.  The user can add and delete key/value pairs, and
+edit both the key and the value of each pair.
+
+You can specify the key and value types like this:
+
+@smallexample
+(alist :key-type @var{key-type} :value-type @var{value-type})
+@end smallexample
+
+@noindent
+where @var{key-type} and @var{value-type} are customization type
+specifications.  The default key type is @code{sexp}, and the default
+value type is @code{sexp}.
+
+The user can add any key matching the specified key type, but you can
+give some keys a preferential treatment by specifying them with the
+@code{:options} (see @ref{Variable Definitions}).  The specified keys
+will always be shown in the customize buffer (together with a suitable
+value), with a checkbox to include or exclude or disable the key/value
+pair from the alist.  The user will not be able to edit the keys
+specified by the @code{:options} keyword argument.
+
+The argument to the @code{:options} keywords should be a list of
+specifications for reasonable keys in the alist.  Ordinarily, they are
+simply atoms, which stand for themselves as.  For example:
+
+@smallexample
+:options '("foo" "bar" "baz")
+@end smallexample
+
+@noindent
+specifies that there are three ``known'' keys, namely @code{"foo"},
+@code{"bar"} and @code{"baz"}, which will always be shown first.
+
+You may want to restrict the value type for specific keys, for
+example, the value associated with the @code{"bar"} key can only be an
+integer.  You can specify this by using a list instead of an atom in
+the list.  The first element will specify the key, like before, while
+the second element will specify the value type.  For example:
+
+@smallexample
+:options '("foo" ("bar" integer) "baz")
+@end smallexample
+
+Finally, you may want to change how the key is presented.  By default,
+the key is simply shown as a @code{const}, since the user cannot change
+the special keys specified with the @code{:options} keyword.  However,
+you may want to use a more specialized type for presenting the key, like
+@code{function-item} if you know it is a symbol with a function binding.
+This is done by using a customization type specification instead of a
+symbol for the key.
+
+@smallexample
+:options '("foo" ((function-item some-function) integer)
+           "baz")
+@end smallexample
+
+Many alists use lists with two elements, instead of cons cells.  For
+example,
+
+@smallexample
+(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
+  "Each element is a list of the form (KEY VALUE).")
+@end smallexample
+
+@noindent
+instead of
+
+@smallexample
+(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
+  "Each element is a cons-cell (KEY . VALUE).")
+@end smallexample
+
+Because of the way lists are implemented on top of cons cells, you can
+treat @code{list-alist} in the example above as a cons cell alist, where
+the value type is a list with a single element containing the real
+value.
+
+@smallexample
+(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
+  "Each element is a list of the form (KEY VALUE)."
+  :type '(alist :value-type (group integer)))
+@end smallexample
+
+The @code{group} widget is used here instead of @code{list} only because
+the formatting is better suited for the purpose.
+
+Similarly, you can have alists with more values associated with each
+key, using variations of this trick:
+
+@smallexample
+(defcustom person-data '(("brian"  50 t)
+                         ("dorith" 55 nil)
+                         ("ken"    52 t))
+  "Alist of basic info about people.
+Each element has the form (NAME AGE MALE-FLAG)."
+  :type '(alist :value-type (group integer boolean)))
+
+(defcustom pets '(("brian")
+                  ("dorith" "dog" "guppy")
+                  ("ken" "cat"))
+  "Alist of people's pets.
+In an element (KEY . VALUE), KEY is the person's name,
+and the VALUE is a list of that person's pets."
+  :type '(alist :value-type (repeat string)))
+@end smallexample
+
+@item plist
+The @code{plist} custom type is similar to the @code{alist} (see above),
+except that the information is stored as a property list, i.e. a list of
+this form:
+
+@smallexample
+(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
+@end smallexample
+
+The default @code{:key-type} for @code{plist} is @code{symbol},
+rather than @code{sexp}.
+
+@item symbol
+The value must be a symbol.  It appears in the customization buffer as
+the name of the symbol.
+
+@item function
+The value must be either a lambda expression or a function name.  When
+it is a function name, you can do completion with @kbd{M-@key{TAB}}.
+
+@item variable
+The value must be a variable name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item face
+The value must be a symbol which is a face name, and you can do
+completion with @kbd{M-@key{TAB}}.
+
+@item boolean
+The value is boolean---either @code{nil} or @code{t}.  Note that by
+using @code{choice} and @code{const} together (see the next section),
+you can specify that the value must be @code{nil} or @code{t}, but also
+specify the text to describe each value in a way that fits the specific
+meaning of the alternative.
+
+@item coding-system
+The value must be a coding-system name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item color
+The value must be a valid color name, and you can do completion with
+@kbd{M-@key{TAB}}.  A sample is provided.
+@end table
+
+@node Composite Types
+@subsection Composite Types
+@cindex Composite Types (customization)
+
+  When none of the simple types is appropriate, you can use composite
+types, which build new types from other types or from specified data.
+The specified types or data are called the @dfn{arguments} of the
+composite type.  The composite type normally looks like this:
+
+@example
+(@var{constructor} @var{arguments}@dots{})
+@end example
+
+@noindent
+but you can also add keyword-value pairs before the arguments, like
+this:
+
+@example
+(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
+@end example
+
+  Here is a table of constructors and how to use them to write
+composite types:
+
+@table @code
+@item (cons @var{car-type} @var{cdr-type})
+The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
+its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(cons string
+symbol)} is a customization type which matches values such as
+@code{("foo" . foo)}.
+
+In the customization buffer, the @sc{car} and the @sc{cdr} are
+displayed and edited separately, each according to the type
+that you specify for it.
+
+@item (list @var{element-types}@dots{})
+The value must be a list with exactly as many elements as the
+@var{element-types} given; and each element must fit the
+corresponding @var{element-type}.
+
+For example, @code{(list integer string function)} describes a list of
+three elements; the first element must be an integer, the second a
+string, and the third a function.
+
+In the customization buffer, each element is displayed and edited
+separately, according to the type specified for it.
+
+@item (vector @var{element-types}@dots{})
+Like @code{list} except that the value must be a vector instead of a
+list.  The elements work the same as in @code{list}.
+
+@item (choice @var{alternative-types}@dots{})
+The value must fit at least one of @var{alternative-types}.
+For example, @code{(choice integer string)} allows either an
+integer or a string.
+
+In the customization buffer, the user selects an alternative
+using a menu, and can then edit the value in the usual way for that
+alternative.
+
+Normally the strings in this menu are determined automatically from the
+choices; however, you can specify different strings for the menu by
+including the @code{:tag} keyword in the alternatives.  For example, if
+an integer stands for a number of spaces, while a string is text to use
+verbatim, you might write the customization type this way,
+
+@example
+(choice (integer :tag "Number of spaces")
+        (string :tag "Literal text"))
+@end example
+
+@noindent
+so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
+
+In any alternative for which @code{nil} is not a valid value, other than
+a @code{const}, you should specify a valid default for that alternative
+using the @code{:value} keyword.  @xref{Type Keywords}.
+
+If some values are covered by more than one of the alternatives,
+customize will choose the first alternative that the value fits.  This
+means you should always list the most specific types first, and the
+most general last.  Here's an example of proper usage:
+
+@example
+(choice (const :tag "Off" nil)
+        symbol (sexp :tag "Other"))
+@end example
+
+@noindent
+This way, the special value @code{nil} is not treated like other
+symbols, and symbols are not treated like other Lisp expressions.
+
+@item (radio @var{element-types}@dots{})
+This is similar to @code{choice}, except that the choices are displayed
+using `radio buttons' rather than a menu.  This has the advantage of
+displaying documentation for the choices when applicable and so is often
+a good choice for a choice between constant functions
+(@code{function-item} customization types).
+
+@item (const @var{value})
+The value must be @var{value}---nothing else is allowed.
+
+The main use of @code{const} is inside of @code{choice}.  For example,
+@code{(choice integer (const nil))} allows either an integer or
+@code{nil}.
+
+@code{:tag} is often used with @code{const}, inside of @code{choice}.
+For example,
+
+@example
+(choice (const :tag "Yes" t)
+        (const :tag "No" nil)
+        (const :tag "Ask" foo))
+@end example
+
+@noindent
+describes a variable for which @code{t} means yes, @code{nil} means no,
+and @code{foo} means ``ask.''
+
+@item (other @var{value})
+This alternative can match any Lisp value, but if the user chooses this
+alternative, that selects the value @var{value}.
+
+The main use of @code{other} is as the last element of @code{choice}.
+For example,
+
+@example
+(choice (const :tag "Yes" t)
+        (const :tag "No" nil)
+        (other :tag "Ask" foo))
+@end example
+
+@noindent
+describes a variable for which @code{t} means yes, @code{nil} means no,
+and anything else means ``ask.''  If the user chooses @samp{Ask} from
+the menu of alternatives, that specifies the value @code{foo}; but any
+other value (not @code{t}, @code{nil} or @code{foo}) displays as
+@samp{Ask}, just like @code{foo}.
+
+@item (function-item @var{function})
+Like @code{const}, but used for values which are functions.  This
+displays the documentation string as well as the function name.
+The documentation string is either the one you specify with
+@code{:doc}, or @var{function}'s own documentation string.
+
+@item (variable-item @var{variable})
+Like @code{const}, but used for values which are variable names.  This
+displays the documentation string as well as the variable name.  The
+documentation string is either the one you specify with @code{:doc}, or
+@var{variable}'s own documentation string.
+
+@item (set @var{types}@dots{})
+The value must be a list, and each element of the list must match one of
+the @var{types} specified.
+
+This appears in the customization buffer as a checklist, so that each of
+@var{types} may have either one corresponding element or none.  It is
+not possible to specify two different elements that match the same one
+of @var{types}.  For example, @code{(set integer symbol)} allows one
+integer and/or one symbol in the list; it does not allow multiple
+integers or multiple symbols.  As a result, it is rare to use
+nonspecific types such as @code{integer} in a @code{set}.
+
+Most often, the @var{types} in a @code{set} are @code{const} types, as
+shown here:
+
+@example
+(set (const :bold) (const :italic))
+@end example
+
+Sometimes they describe possible elements in an alist:
+
+@example
+(set (cons :tag "Height" (const height) integer)
+     (cons :tag "Width" (const width) integer))
+@end example
+
+@noindent
+That lets the user specify a height value optionally
+and a width value optionally.
+
+@item (repeat @var{element-type})
+The value must be a list and each element of the list must fit the type
+@var{element-type}.  This appears in the customization buffer as a
+list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
+more elements or removing elements.
+
+@item (restricted-sexp :match-alternatives @var{criteria})
+This is the most general composite type construct.  The value may be
+any Lisp object that satisfies one of @var{criteria}.  @var{criteria}
+should be a list, and each element should be one of these
+possibilities:
+
+@itemize @bullet
+@item
+A predicate---that is, a function of one argument that has no side
+effects, and returns either @code{nil} or non-@code{nil} according to
+the argument.  Using a predicate in the list says that objects for which
+the predicate returns non-@code{nil} are acceptable.
+
+@item
+A quoted constant---that is, @code{'@var{object}}.  This sort of element
+in the list says that @var{object} itself is an acceptable value.
+@end itemize
+
+For example,
+
+@example
+(restricted-sexp :match-alternatives
+                 (integerp 't 'nil))
+@end example
+
+@noindent
+allows integers, @code{t} and @code{nil} as legitimate values.
+
+The customization buffer shows all legitimate values using their read
+syntax, and the user edits them textually.
+@end table
+
+  Here is a table of the keywords you can use in keyword-value pairs
+in a composite type:
+
+@table @code
+@item :tag @var{tag}
+Use @var{tag} as the name of this alternative, for user communication
+purposes.  This is useful for a type that appears inside of a
+@code{choice}.
+
+@item :match-alternatives @var{criteria}
+@kindex match-alternatives@r{, customization keyword}
+Use @var{criteria} to match possible values.  This is used only in
+@code{restricted-sexp}.
+
+@item :args @var{argument-list}
+@kindex args@r{, customization keyword}
+Use the elements of @var{argument-list} as the arguments of the type
+construct.  For instance, @code{(const :args (foo))} is equivalent to
+@code{(const foo)}.  You rarely need to write @code{:args} explicitly,
+because normally the arguments are recognized automatically as
+whatever follows the last keyword-value pair.
+@end table
+
+@node Splicing into Lists
+@subsection Splicing into Lists
+
+  The @code{:inline} feature lets you splice a variable number of
+elements into the middle of a list or vector.  You use it in a
+@code{set}, @code{choice} or @code{repeat} type which appears among the
+element-types of a @code{list} or @code{vector}.
+
+  Normally, each of the element-types in a @code{list} or @code{vector}
+describes one and only one element of the list or vector.  Thus, if an
+element-type is a @code{repeat}, that specifies a list of unspecified
+length which appears as one element.
+
+  But when the element-type uses @code{:inline}, the value it matches is
+merged directly into the containing sequence.  For example, if it
+matches a list with three elements, those become three elements of the
+overall sequence.  This is analogous to using @samp{,@@} in the backquote
+construct.
+
+  For example, to specify a list whose first element must be @code{baz}
+and whose remaining arguments should be zero or more of @code{foo} and
+@code{bar}, use this customization type:
+
+@example
+(list (const baz) (set :inline t (const foo) (const bar)))
+@end example
+
+@noindent
+This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
+and @code{(baz foo bar)}.
+
+  When the element-type is a @code{choice}, you use @code{:inline} not
+in the @code{choice} itself, but in (some of) the alternatives of the
+@code{choice}.  For example, to match a list which must start with a
+file name, followed either by the symbol @code{t} or two strings, use
+this customization type:
+
+@example
+(list file
+      (choice (const t)
+              (list :inline t string string)))
+@end example
+
+@noindent
+If the user chooses the first alternative in the choice, then the
+overall list has two elements and the second element is @code{t}.  If
+the user chooses the second alternative, then the overall list has three
+elements and the second and third must be strings.
+
+@node Type Keywords
+@subsection Type Keywords
+
+You can specify keyword-argument pairs in a customization type after the
+type name symbol.  Here are the keywords you can use, and their
+meanings:
+
+@table @code
+@item :value @var{default}
+This is used for a type that appears as an alternative inside of
+@code{choice}; it specifies the default value to use, at first, if and
+when the user selects this alternative with the menu in the
+customization buffer.
+
+Of course, if the actual value of the option fits this alternative, it
+will appear showing the actual value, not @var{default}.
+
+If @code{nil} is not a valid value for the alternative, then it is
+essential to specify a valid default with @code{:value}.
+
+@item :format @var{format-string}
+@kindex format@r{, customization keyword}
+This string will be inserted in the buffer to represent the value
+corresponding to the type.  The following @samp{%} escapes are available
+for use in @var{format-string}:
+
+@table @samp
+@item %[@var{button}%]
+Display the text @var{button} marked as a button.  The @code{:action}
+attribute specifies what the button will do if the user invokes it;
+its value is a function which takes two arguments---the widget which
+the button appears in, and the event.
+
+There is no way to specify two different buttons with different
+actions.
+
+@item %@{@var{sample}%@}
+Show @var{sample} in a special face specified by @code{:sample-face}.
+
+@item %v
+Substitute the item's value.  How the value is represented depends on
+the kind of item, and (for variables) on the customization type.
+
+@item %d
+Substitute the item's documentation string.
+
+@item %h
+Like @samp{%d}, but if the documentation string is more than one line,
+add an active field to control whether to show all of it or just the
+first line.
+
+@item %t
+Substitute the tag here.  You specify the tag with the @code{:tag}
+keyword.
+
+@item %%
+Display a literal @samp{%}.
+@end table
+
+@item :action @var{action}
+@kindex action@r{, customization keyword}
+Perform @var{action} if the user clicks on a button.
+
+@item :button-face @var{face}
+@kindex button-face@r{, customization keyword}
+Use the face @var{face} (a face name or a list of face names) for button
+text displayed with @samp{%[@dots{}%]}.
+
+@item :button-prefix @var{prefix}
+@itemx :button-suffix @var{suffix}
+@kindex button-prefix@r{, customization keyword}
+@kindex button-suffix@r{, customization keyword}
+These specify the text to display before and after a button.
+Each can be:
+
+@table @asis
+@item @code{nil}
+No text is inserted.
+
+@item a string
+The string is inserted literally.
+
+@item a symbol
+The symbol's value is used.
+@end table
+
+@item :tag @var{tag}
+Use @var{tag} (a string) as the tag for the value (or part of the value)
+that corresponds to this type.
+
+@item :doc @var{doc}
+@kindex doc@r{, customization keyword}
+Use @var{doc} as the documentation string for this value (or part of the
+value) that corresponds to this type.  In order for this to work, you
+must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
+in that value.
+
+The usual reason to specify a documentation string for a type is to
+provide more information about the meanings of alternatives inside a
+@code{:choice} type or the parts of some other composite type.
+
+@item :help-echo @var{motion-doc}
+@kindex help-echo@r{, customization keyword}
+When you move to this item with @code{widget-forward} or
+@code{widget-backward}, it will display the string @var{motion-doc} in
+the echo area.  In addition, @var{motion-doc} is used as the mouse
+@code{help-echo} string and may actually be a function or form evaluated
+to yield a help string.  If it is a function, it is called with one
+argument, the widget.
+
+@item :match @var{function}
+@kindex match@r{, customization keyword}
+Specify how to decide whether a value matches the type.  The
+corresponding value, @var{function}, should be a function that accepts
+two arguments, a widget and a value; it should return non-@code{nil} if
+the value is acceptable.
+
+@ignore
+@item :indent @var{columns}
+Indent this item by @var{columns} columns.  The indentation is used for
+@samp{%n}, and automatically for group names, for checklists and radio
+buttons, and for editable lists.  It affects the whole of the
+item except for the first line.
+
+@item :offset @var{columns}
+An integer indicating how many extra spaces to indent the subitems of
+this item.  By default, subitems are indented the same as their parent.
+
+@item :extra-offset
+An integer indicating how many extra spaces to add to this item's
+indentation, compared to its parent.
+
+@item :notify
+A function called each time the item or a subitem is changed.  The
+function is called with two or three arguments.  The first argument is
+the item itself, the second argument is the item that was changed, and
+the third argument is the event leading to the change, if any.
+
+@item :menu-tag
+A tag used in the menu when the widget is used as an option in a
+@code{menu-choice} widget.
+
+@item :menu-tag-get
+A function used for finding the tag when the widget is used as an option
+in a @code{menu-choice} widget.  By default, the tag used will be either the
+@code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
+representation of the @code{:value} property if not.
+
+@item :validate
+A function which takes a widget as an argument, and return @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.
+
+You can use the function @code{widget-children-validate} for this job;
+it tests that all children of @var{widget} are valid.
+
+@item :tab-order
+Specify the order in which widgets are traversed with
+@code{widget-forward} or @code{widget-backward}.  This is only partially
+implemented.
+
+@enumerate a
+@item
+Widgets with tabbing order @code{-1} are ignored.
+
+@item
+(Unimplemented) When on a widget with tabbing order @var{n}, go to the
+next widget in the buffer with tabbing order @var{n+1} or @code{nil},
+whichever comes first.
+
+@item
+When on a widget with no tabbing order specified, go to the next widget
+in the buffer with a positive tabbing order, or @code{nil}
+@end enumerate
+
+@item :parent
+The parent of a nested widget (e.g., a @code{menu-choice} item or an
+element of a @code{editable-list} widget).
+
+@item :sibling-args
+This keyword is only used for members of a @code{radio-button-choice} or
+@code{checklist}.  The value should be a list of extra keyword
+arguments, which will be used when creating the @code{radio-button} or
+@code{checkbox} associated with this item.
+@end ignore
+@end table
+
+@node Defining New Types
+@subsection Defining New Types
+
+In the previous sections we have described how to construct elaborate
+type specifications for @code{defcustom}.  In some cases you may want
+to give such a type specification a name.  The obvious case is when
+you are using the same type for many user options: rather than repeat
+the specification for each option, you can give the type specification
+a name, and use that name each @code{defcustom}.  The other case is
+when a user option's value is a recursive data structure.  To make it
+possible for a datatype to refer to itself, it needs to have a name.
+
+Since custom types are implemented as widgets, the way to define a new
+customize type is to define a new widget.  We are not going to describe
+the widget interface here in details, see @ref{Top, , Introduction,
+widget, The Emacs Widget Library}, for that.  Instead we are going to
+demonstrate the minimal functionality needed for defining new customize
+types by a simple example.
+
+@example
+(define-widget 'binary-tree-of-string 'lazy
+  "A binary tree made of cons-cells and strings."
+  :offset 4
+  :tag "Node"
+  :type '(choice (string :tag "Leaf" :value "")
+                 (cons :tag "Interior"
+                       :value ("" . "")
+                       binary-tree-of-string
+                       binary-tree-of-string)))
+
+(defcustom foo-bar ""
+  "Sample variable holding a binary tree of strings."
+  :type 'binary-tree-of-string)
+@end example
+
+The function to define a new widget is called @code{define-widget}.  The
+first argument is the symbol we want to make a new widget type.  The
+second argument is a symbol representing an existing widget, the new
+widget is going to be defined in terms of difference from the existing
+widget.  For the purpose of defining new customization types, the
+@code{lazy} widget is perfect, because it accepts a @code{:type} keyword
+argument with the same syntax as the keyword argument to
+@code{defcustom} with the same name.  The third argument is a
+documentation string for the new widget.  You will be able to see that
+string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
+@key{RET}} command.
+
+After these mandatory arguments follow the keyword arguments.  The most
+important is @code{:type}, which describes the data type we want to match
+with this widget.  Here a @code{binary-tree-of-string} is described as
+being either a string, or a cons-cell whose car and cdr are themselves
+both @code{binary-tree-of-string}.  Note the reference to the widget
+type we are currently in the process of defining.  The @code{:tag}
+attribute is a string to name the widget in the user interface, and the
+@code{:offset} argument is there to ensure that child nodes are
+indented four spaces relative to the parent node, making the tree
+structure apparent in the customization buffer.
+
+The @code{defcustom} shows how the new widget can be used as an ordinary
+customization type.
+
+The reason for the name @code{lazy} is that the other composite
+widgets convert their inferior widgets to internal form when the
+widget is instantiated in a buffer.  This conversion is recursive, so
+the inferior widgets will convert @emph{their} inferior widgets.  If
+the data structure is itself recursive, this conversion is an infinite
+recursion.  The @code{lazy} widget prevents the recursion: it convert
+its @code{:type} argument only when needed.
+
+@ignore
+   arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
+@end ignore
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
new file mode 100644
index 00000000000..a427e746b27
--- /dev/null
+++ b/doc/lispref/debugging.texi
@@ -0,0 +1,834 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003,
+@c   2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/debugging
+@node Debugging, Read and Print, Advising Functions, Top
+@chapter Debugging Lisp Programs
+
+  There are three ways to investigate a problem in an Emacs Lisp program,
+depending on what you are doing with the program when the problem appears.
+
+@itemize @bullet
+@item
+If the problem occurs when you run the program, you can use a Lisp
+debugger to investigate what is happening during execution.  In addition
+to the ordinary debugger, Emacs comes with a source-level debugger,
+Edebug.  This chapter describes both of them.
+
+@item
+If the problem is syntactic, so that Lisp cannot even read the program,
+you can use the Emacs facilities for editing Lisp to localize it.
+
+@item
+If the problem occurs when trying to compile the program with the byte
+compiler, you need to know how to examine the compiler's input buffer.
+@end itemize
+
+@menu
+* Debugger::            How the Emacs Lisp debugger is implemented.
+* Edebug::		A source-level Emacs Lisp debugger.
+* Syntax Errors::       How to find syntax errors.
+* Test Coverage::       Ensuring you have tested all branches in your code.
+* Compilation Errors::  How to find errors that show up in byte compilation.
+@end menu
+
+  Another useful debugging tool is the dribble file.  When a dribble
+file is open, Emacs copies all keyboard input characters to that file.
+Afterward, you can examine the file to find out what input was used.
+@xref{Terminal Input}.
+
+  For debugging problems in terminal descriptions, the
+@code{open-termscript} function can be useful.  @xref{Terminal Output}.
+
+@node Debugger
+@section The Lisp Debugger
+@cindex debugger for Emacs Lisp
+@cindex Lisp debugger
+@cindex break
+
+  The ordinary @dfn{Lisp debugger} provides the ability to suspend
+evaluation of a form.  While evaluation is suspended (a state that is
+commonly known as a @dfn{break}), you may examine the run time stack,
+examine the values of local or global variables, or change those values.
+Since a break is a recursive edit, all the usual editing facilities of
+Emacs are available; you can even run programs that will enter the
+debugger recursively.  @xref{Recursive Editing}.
+
+@menu
+* Error Debugging::       Entering the debugger when an error happens.
+* Infinite Loops::	  Stopping and debugging a program that doesn't exit.
+* Function Debugging::    Entering it when a certain function is called.
+* Explicit Debug::        Entering it at a certain point in the program.
+* Using Debugger::        What the debugger does; what you see while in it.
+* Debugger Commands::     Commands used while in the debugger.
+* Invoking the Debugger:: How to call the function @code{debug}.
+* Internals of Debugger:: Subroutines of the debugger, and global variables.
+@end menu
+
+@node Error Debugging
+@subsection Entering the Debugger on an Error
+@cindex error debugging
+@cindex debugging errors
+
+  The most important time to enter the debugger is when a Lisp error
+happens.  This allows you to investigate the immediate causes of the
+error.
+
+  However, entry to the debugger is not a normal consequence of an
+error.  Many commands frequently cause Lisp errors when invoked
+inappropriately (such as @kbd{C-f} at the end of the buffer), and during
+ordinary editing it would be very inconvenient to enter the debugger
+each time this happens.  So if you want errors to enter the debugger, set
+the variable @code{debug-on-error} to non-@code{nil}.  (The command
+@code{toggle-debug-on-error} provides an easy way to do this.)
+
+@defopt debug-on-error
+This variable determines whether the debugger is called when an error is
+signaled and not handled.  If @code{debug-on-error} is @code{t}, all
+kinds of errors call the debugger (except those listed in
+@code{debug-ignored-errors}).  If it is @code{nil}, none call the
+debugger.
+
+The value can also be a list of error conditions that should call the
+debugger.  For example, if you set it to the list
+@code{(void-variable)}, then only errors about a variable that has no
+value invoke the debugger.
+
+When this variable is non-@code{nil}, Emacs does not create an error
+handler around process filter functions and sentinels.  Therefore,
+errors in these functions also invoke the debugger.  @xref{Processes}.
+@end defopt
+
+@defopt debug-ignored-errors
+This variable specifies certain kinds of errors that should not enter
+the debugger.  Its value is a list of error condition symbols and/or
+regular expressions.  If the error has any of those condition symbols,
+or if the error message matches any of the regular expressions, then
+that error does not enter the debugger, regardless of the value of
+@code{debug-on-error}.
+
+The normal value of this variable lists several errors that happen often
+during editing but rarely result from bugs in Lisp programs.  However,
+``rarely'' is not ``never''; if your program fails with an error that
+matches this list, you will need to change this list in order to debug
+the error.  The easiest way is usually to set
+@code{debug-ignored-errors} to @code{nil}.
+@end defopt
+
+@defopt eval-expression-debug-on-error
+If this variable has a non-@code{nil} value, then
+@code{debug-on-error} is set to @code{t} when evaluating with the
+command @code{eval-expression}.  If
+@code{eval-expression-debug-on-error} is @code{nil}, then the value of
+@code{debug-on-error} is not changed.  @xref{Lisp Eval,, Evaluating
+Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}.
+@end defopt
+
+@defopt debug-on-signal
+Normally, errors that are caught by @code{condition-case} never run the
+debugger, even if @code{debug-on-error} is non-@code{nil}.  In other
+words, @code{condition-case} gets a chance to handle the error before
+the debugger gets a chance.
+
+If you set @code{debug-on-signal} to a non-@code{nil} value, then the
+debugger gets the first chance at every error; an error will invoke the
+debugger regardless of any @code{condition-case}, if it fits the
+criteria specified by the values of @code{debug-on-error} and
+@code{debug-ignored-errors}.
+
+@strong{Warning:} This variable is strong medicine!  Various parts of
+Emacs handle errors in the normal course of affairs, and you may not
+even realize that errors happen there.  If you set
+@code{debug-on-signal} to a non-@code{nil} value, those errors will
+enter the debugger.
+
+@strong{Warning:} @code{debug-on-signal} has no effect when
+@code{debug-on-error} is @code{nil}.
+@end defopt
+
+  To debug an error that happens during loading of the init
+file, use the option @samp{--debug-init}.  This binds
+@code{debug-on-error} to @code{t} while loading the init file, and
+bypasses the @code{condition-case} which normally catches errors in the
+init file.
+
+  If your init file sets @code{debug-on-error}, the effect may
+not last past the end of loading the init file.  (This is an undesirable
+byproduct of the code that implements the @samp{--debug-init} command
+line option.)  The best way to make the init file set
+@code{debug-on-error} permanently is with @code{after-init-hook}, like
+this:
+
+@example
+(add-hook 'after-init-hook
+          (lambda () (setq debug-on-error t)))
+@end example
+
+@node Infinite Loops
+@subsection Debugging Infinite Loops
+@cindex infinite loops
+@cindex loops, infinite
+@cindex quitting from infinite loop
+@cindex stopping an infinite loop
+
+  When a program loops infinitely and fails to return, your first
+problem is to stop the loop.  On most operating systems, you can do this
+with @kbd{C-g}, which causes a @dfn{quit}.
+
+  Ordinary quitting gives no information about why the program was
+looping.  To get more information, you can set the variable
+@code{debug-on-quit} to non-@code{nil}.  Quitting with @kbd{C-g} is not
+considered an error, and @code{debug-on-error} has no effect on the
+handling of @kbd{C-g}.  Likewise, @code{debug-on-quit} has no effect on
+errors.
+
+  Once you have the debugger running in the middle of the infinite loop,
+you can proceed from the debugger using the stepping commands.  If you
+step through the entire loop, you will probably get enough information
+to solve the problem.
+
+@defopt debug-on-quit
+This variable determines whether the debugger is called when @code{quit}
+is signaled and not handled.  If @code{debug-on-quit} is non-@code{nil},
+then the debugger is called whenever you quit (that is, type @kbd{C-g}).
+If @code{debug-on-quit} is @code{nil}, then the debugger is not called
+when you quit.  @xref{Quitting}.
+@end defopt
+
+@node Function Debugging
+@subsection Entering the Debugger on a Function Call
+@cindex function call debugging
+@cindex debugging specific functions
+
+  To investigate a problem that happens in the middle of a program, one
+useful technique is to enter the debugger whenever a certain function is
+called.  You can do this to the function in which the problem occurs,
+and then step through the function, or you can do this to a function
+called shortly before the problem, step quickly over the call to that
+function, and then step through its caller.
+
+@deffn Command debug-on-entry function-name
+This function requests @var{function-name} to invoke the debugger each
+time it is called.  It works by inserting the form
+@code{(implement-debug-on-entry)} into the function definition as the
+first form.
+
+Any function or macro defined as Lisp code may be set to break on
+entry, regardless of whether it is interpreted code or compiled code.
+If the function is a command, it will enter the debugger when called
+from Lisp and when called interactively (after the reading of the
+arguments).  You can also set debug-on-entry for primitive functions
+(i.e., those written in C) this way, but it only takes effect when the
+primitive is called from Lisp code.  Debug-on-entry is not allowed for
+special forms.
+
+When @code{debug-on-entry} is called interactively, it prompts for
+@var{function-name} in the minibuffer.  If the function is already set
+up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
+@code{debug-on-entry} always returns @var{function-name}.
+
+@strong{Warning:} if you redefine a function after using
+@code{debug-on-entry} on it, the code to enter the debugger is
+discarded by the redefinition.  In effect, redefining the function
+cancels the break-on-entry feature for that function.
+
+Here's an example to illustrate use of this function:
+
+@example
+@group
+(defun fact (n)
+  (if (zerop n) 1
+      (* n (fact (1- n)))))
+     @result{} fact
+@end group
+@group
+(debug-on-entry 'fact)
+     @result{} fact
+@end group
+@group
+(fact 3)
+@end group
+
+@group
+------ Buffer: *Backtrace* ------
+Debugger entered--entering a function:
+* fact(3)
+  eval((fact 3))
+  eval-last-sexp-1(nil)
+  eval-last-sexp(nil)
+  call-interactively(eval-last-sexp)
+------ Buffer: *Backtrace* ------
+@end group
+
+@group
+(symbol-function 'fact)
+     @result{} (lambda (n)
+          (debug (quote debug))
+          (if (zerop n) 1 (* n (fact (1- n)))))
+@end group
+@end example
+@end deffn
+
+@deffn Command cancel-debug-on-entry &optional function-name
+This function undoes the effect of @code{debug-on-entry} on
+@var{function-name}.  When called interactively, it prompts for
+@var{function-name} in the minibuffer.  If @var{function-name} is
+omitted or @code{nil}, it cancels break-on-entry for all functions.
+Calling @code{cancel-debug-on-entry} does nothing to a function which is
+not currently set up to break on entry.
+@end deffn
+
+@node Explicit Debug
+@subsection Explicit Entry to the Debugger
+
+  You can cause the debugger to be called at a certain point in your
+program by writing the expression @code{(debug)} at that point.  To do
+this, visit the source file, insert the text @samp{(debug)} at the
+proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key
+binding).  @strong{Warning:} if you do this for temporary debugging
+purposes, be sure to undo this insertion before you save the file!
+
+  The place where you insert @samp{(debug)} must be a place where an
+additional form can be evaluated and its value ignored.  (If the value
+of @code{(debug)} isn't ignored, it will alter the execution of the
+program!)  The most common suitable places are inside a @code{progn} or
+an implicit @code{progn} (@pxref{Sequencing}).
+
+@node Using Debugger
+@subsection Using the Debugger
+
+  When the debugger is entered, it displays the previously selected
+buffer in one window and a buffer named @samp{*Backtrace*} in another
+window.  The backtrace buffer contains one line for each level of Lisp
+function execution currently going on.  At the beginning of this buffer
+is a message describing the reason that the debugger was invoked (such
+as the error message and associated data, if it was invoked due to an
+error).
+
+  The backtrace buffer is read-only and uses a special major mode,
+Debugger mode, in which letters are defined as debugger commands.  The
+usual Emacs editing commands are available; thus, you can switch windows
+to examine the buffer that was being edited at the time of the error,
+switch buffers, visit files, or do any other sort of editing.  However,
+the debugger is a recursive editing level (@pxref{Recursive Editing})
+and it is wise to go back to the backtrace buffer and exit the debugger
+(with the @kbd{q} command) when you are finished with it.  Exiting
+the debugger gets out of the recursive edit and kills the backtrace
+buffer.
+
+@cindex current stack frame
+  The backtrace buffer shows you the functions that are executing and
+their argument values.  It also allows you to specify a stack frame by
+moving point to the line describing that frame.  (A stack frame is the
+place where the Lisp interpreter records information about a particular
+invocation of a function.)  The frame whose line point is on is
+considered the @dfn{current frame}.  Some of the debugger commands
+operate on the current frame.  If a line starts with a star, that means
+that exiting that frame will call the debugger again.  This is useful
+for examining the return value of a function.
+
+  If a function name is underlined, that means the debugger knows
+where its source code is located.  You can click @kbd{Mouse-2} on that
+name, or move to it and type @key{RET}, to visit the source code.
+
+  The debugger itself must be run byte-compiled, since it makes
+assumptions about how many stack frames are used for the debugger
+itself.  These assumptions are false if the debugger is running
+interpreted.
+
+@node Debugger Commands
+@subsection Debugger Commands
+@cindex debugger command list
+
+  The debugger buffer (in Debugger mode) provides special commands in
+addition to the usual Emacs commands.  The most important use of
+debugger commands is for stepping through code, so that you can see
+how control flows.  The debugger can step through the control
+structures of an interpreted function, but cannot do so in a
+byte-compiled function.  If you would like to step through a
+byte-compiled function, replace it with an interpreted definition of
+the same function.  (To do this, visit the source for the function and
+type @kbd{C-M-x} on its definition.)  You cannot use the Lisp debugger
+to step through a primitive function.
+
+  Here is a list of Debugger mode commands:
+
+@table @kbd
+@item c
+Exit the debugger and continue execution.  When continuing is possible,
+it resumes execution of the program as if the debugger had never been
+entered (aside from any side-effects that you caused by changing
+variable values or data structures while inside the debugger).
+
+Continuing is possible after entry to the debugger due to function entry
+or exit, explicit invocation, or quitting.  You cannot continue if the
+debugger was entered because of an error.
+
+@item d
+Continue execution, but enter the debugger the next time any Lisp
+function is called.  This allows you to step through the
+subexpressions of an expression, seeing what values the subexpressions
+compute, and what else they do.
+
+The stack frame made for the function call which enters the debugger in
+this way will be flagged automatically so that the debugger will be
+called again when the frame is exited.  You can use the @kbd{u} command
+to cancel this flag.
+
+@item b
+Flag the current frame so that the debugger will be entered when the
+frame is exited.  Frames flagged in this way are marked with stars
+in the backtrace buffer.
+
+@item u
+Don't enter the debugger when the current frame is exited.  This
+cancels a @kbd{b} command on that frame.  The visible effect is to
+remove the star from the line in the backtrace buffer.
+
+@item j
+Flag the current frame like @kbd{b}.  Then continue execution like
+@kbd{c}, but temporarily disable break-on-entry for all functions that
+are set up to do so by @code{debug-on-entry}.
+
+@item e
+Read a Lisp expression in the minibuffer, evaluate it, and print the
+value in the echo area.  The debugger alters certain important
+variables, and the current buffer, as part of its operation; @kbd{e}
+temporarily restores their values from outside the debugger, so you can
+examine and change them.  This makes the debugger more transparent.  By
+contrast, @kbd{M-:} does nothing special in the debugger; it shows you
+the variable values within the debugger.
+
+@item R
+Like @kbd{e}, but also save the result of evaluation in the
+buffer @samp{*Debugger-record*}.
+
+@item q
+Terminate the program being debugged; return to top-level Emacs
+command execution.
+
+If the debugger was entered due to a @kbd{C-g} but you really want
+to quit, and not debug, use the @kbd{q} command.
+
+@item r
+Return a value from the debugger.  The value is computed by reading an
+expression with the minibuffer and evaluating it.
+
+The @kbd{r} command is useful when the debugger was invoked due to exit
+from a Lisp call frame (as requested with @kbd{b} or by entering the
+frame with @kbd{d}); then the value specified in the @kbd{r} command is
+used as the value of that frame.  It is also useful if you call
+@code{debug} and use its return value.  Otherwise, @kbd{r} has the same
+effect as @kbd{c}, and the specified return value does not matter.
+
+You can't use @kbd{r} when the debugger was entered due to an error.
+
+@item l
+Display a list of functions that will invoke the debugger when called.
+This is a list of functions that are set to break on entry by means of
+@code{debug-on-entry}.  @strong{Warning:} if you redefine such a
+function and thus cancel the effect of @code{debug-on-entry}, it may
+erroneously show up in this list.
+@end table
+
+@node Invoking the Debugger
+@subsection Invoking the Debugger
+
+  Here we describe in full detail the function @code{debug} that is used
+to invoke the debugger.
+
+@defun debug &rest debugger-args
+This function enters the debugger.  It switches buffers to a buffer
+named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
+recursive entry to the debugger, etc.), and fills it with information
+about the stack of Lisp function calls.  It then enters a recursive
+edit, showing the backtrace buffer in Debugger mode.
+
+The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit
+the recursive edit; then @code{debug} switches back to the previous
+buffer and returns to whatever called @code{debug}.  This is the only
+way the function @code{debug} can return to its caller.
+
+The use of the @var{debugger-args} is that @code{debug} displays the
+rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
+that the user can see them.  Except as described below, this is the
+@emph{only} way these arguments are used.
+
+However, certain values for first argument to @code{debug} have a
+special significance.  (Normally, these values are used only by the
+internals of Emacs, and not by programmers calling @code{debug}.)  Here
+is a table of these special values:
+
+@table @code
+@item lambda
+@cindex @code{lambda} in debug
+A first argument of @code{lambda} means @code{debug} was called
+because of entry to a function when @code{debug-on-next-call} was
+non-@code{nil}.  The debugger displays @samp{Debugger
+entered--entering a function:} as a line of text at the top of the
+buffer.
+
+@item debug
+@code{debug} as first argument means @code{debug} was called because
+of entry to a function that was set to debug on entry.  The debugger
+displays the string @samp{Debugger entered--entering a function:},
+just as in the @code{lambda} case.  It also marks the stack frame for
+that function so that it will invoke the debugger when exited.
+
+@item t
+When the first argument is @code{t}, this indicates a call to
+@code{debug} due to evaluation of a function call form when
+@code{debug-on-next-call} is non-@code{nil}.  The debugger displays
+@samp{Debugger entered--beginning evaluation of function call form:}
+as the top line in the buffer.
+
+@item exit
+When the first argument is @code{exit}, it indicates the exit of a
+stack frame previously marked to invoke the debugger on exit.  The
+second argument given to @code{debug} in this case is the value being
+returned from the frame.  The debugger displays @samp{Debugger
+entered--returning value:} in the top line of the buffer, followed by
+the value being returned.
+
+@item error
+@cindex @code{error} in debug
+When the first argument is @code{error}, the debugger indicates that
+it is being entered because an error or @code{quit} was signaled and
+not handled, by displaying @samp{Debugger entered--Lisp error:}
+followed by the error signaled and any arguments to @code{signal}.
+For example,
+
+@example
+@group
+(let ((debug-on-error t))
+  (/ 1 0))
+@end group
+
+@group
+------ Buffer: *Backtrace* ------
+Debugger entered--Lisp error: (arith-error)
+  /(1 0)
+...
+------ Buffer: *Backtrace* ------
+@end group
+@end example
+
+If an error was signaled, presumably the variable
+@code{debug-on-error} is non-@code{nil}.  If @code{quit} was signaled,
+then presumably the variable @code{debug-on-quit} is non-@code{nil}.
+
+@item nil
+Use @code{nil} as the first of the @var{debugger-args} when you want
+to enter the debugger explicitly.  The rest of the @var{debugger-args}
+are printed on the top line of the buffer.  You can use this feature to
+display messages---for example, to remind yourself of the conditions
+under which @code{debug} is called.
+@end table
+@end defun
+
+@node Internals of Debugger
+@subsection Internals of the Debugger
+
+  This section describes functions and variables used internally by the
+debugger.
+
+@defvar debugger
+The value of this variable is the function to call to invoke the
+debugger.  Its value must be a function of any number of arguments, or,
+more typically, the name of a function.  This function should invoke
+some kind of debugger.  The default value of the variable is
+@code{debug}.
+
+The first argument that Lisp hands to the function indicates why it
+was called.  The convention for arguments is detailed in the description
+of @code{debug} (@pxref{Invoking the Debugger}).
+@end defvar
+
+@deffn Command backtrace
+@cindex run time stack
+@cindex call stack
+This function prints a trace of Lisp function calls currently active.
+This is the function used by @code{debug} to fill up the
+@samp{*Backtrace*} buffer.  It is written in C, since it must have access
+to the stack to determine which function calls are active.  The return
+value is always @code{nil}.
+
+In the following example, a Lisp expression calls @code{backtrace}
+explicitly.  This prints the backtrace to the stream
+@code{standard-output}, which, in this case, is the buffer
+@samp{backtrace-output}.
+
+Each line of the backtrace represents one function call.  The line shows
+the values of the function's arguments if they are all known; if they
+are still being computed, the line says so.  The arguments of special
+forms are elided.
+
+@smallexample
+@group
+(with-output-to-temp-buffer "backtrace-output"
+  (let ((var 1))
+    (save-excursion
+      (setq var (eval '(progn
+                         (1+ var)
+                         (list 'testing (backtrace))))))))
+
+     @result{} (testing nil)
+@end group
+
+@group
+----------- Buffer: backtrace-output ------------
+  backtrace()
+  (list ...computing arguments...)
+@end group
+  (progn ...)
+  eval((progn (1+ var) (list (quote testing) (backtrace))))
+  (setq ...)
+  (save-excursion ...)
+  (let ...)
+  (with-output-to-temp-buffer ...)
+  eval((with-output-to-temp-buffer ...))
+  eval-last-sexp-1(nil)
+@group
+  eval-last-sexp(nil)
+  call-interactively(eval-last-sexp)
+----------- Buffer: backtrace-output ------------
+@end group
+@end smallexample
+@end deffn
+
+@ignore @c Not worth mentioning
+@defopt stack-trace-on-error
+@cindex stack trace
+This variable controls whether Lisp automatically displays a
+backtrace buffer after every error that is not handled.  A quit signal
+counts as an error for this variable.  If it is non-@code{nil} then a
+backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
+error.  If it is @code{nil}, then a backtrace is not shown.
+
+When a backtrace is shown, that buffer is not selected.  If either
+@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
+a backtrace is shown in one buffer, and the debugger is popped up in
+another buffer with its own backtrace.
+
+We consider this feature to be obsolete and superseded by the debugger
+itself.
+@end defopt
+@end ignore
+
+@defvar debug-on-next-call
+@cindex @code{eval}, and debugging
+@cindex @code{apply}, and debugging
+@cindex @code{funcall}, and debugging
+If this variable is non-@code{nil}, it says to call the debugger before
+the next @code{eval}, @code{apply} or @code{funcall}.  Entering the
+debugger sets @code{debug-on-next-call} to @code{nil}.
+
+The @kbd{d} command in the debugger works by setting this variable.
+@end defvar
+
+@defun backtrace-debug level flag
+This function sets the debug-on-exit flag of the stack frame @var{level}
+levels down the stack, giving it the value @var{flag}.  If @var{flag} is
+non-@code{nil}, this will cause the debugger to be entered when that
+frame later exits.  Even a nonlocal exit through that frame will enter
+the debugger.
+
+This function is used only by the debugger.
+@end defun
+
+@defvar command-debug-status
+This variable records the debugging status of the current interactive
+command.  Each time a command is called interactively, this variable is
+bound to @code{nil}.  The debugger can set this variable to leave
+information for future debugger invocations during the same command
+invocation.
+
+The advantage of using this variable rather than an ordinary global
+variable is that the data will never carry over to a subsequent command
+invocation.
+@end defvar
+
+@defun backtrace-frame frame-number
+The function @code{backtrace-frame} is intended for use in Lisp
+debuggers.  It returns information about what computation is happening
+in the stack frame @var{frame-number} levels down.
+
+If that frame has not evaluated the arguments yet, or is a special
+form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
+
+If that frame has evaluated its arguments and called its function
+already, the return value is @code{(t @var{function}
+@var{arg-values}@dots{})}.
+
+In the return value, @var{function} is whatever was supplied as the
+@sc{car} of the evaluated list, or a @code{lambda} expression in the
+case of a macro call.  If the function has a @code{&rest} argument, that
+is represented as the tail of the list @var{arg-values}.
+
+If @var{frame-number} is out of range, @code{backtrace-frame} returns
+@code{nil}.
+@end defun
+
+@include edebug.texi
+
+@node Syntax Errors
+@section Debugging Invalid Lisp Syntax
+@cindex debugging invalid Lisp syntax
+
+  The Lisp reader reports invalid syntax, but cannot say where the real
+problem is.  For example, the error ``End of file during parsing'' in
+evaluating an expression indicates an excess of open parentheses (or
+square brackets).  The reader detects this imbalance at the end of the
+file, but it cannot figure out where the close parenthesis should have
+been.  Likewise, ``Invalid read syntax: ")"'' indicates an excess close
+parenthesis or missing open parenthesis, but does not say where the
+missing parenthesis belongs.  How, then, to find what to change?
+
+  If the problem is not simply an imbalance of parentheses, a useful
+technique is to try @kbd{C-M-e} at the beginning of each defun, and see
+if it goes to the place where that defun appears to end.  If it does
+not, there is a problem in that defun.
+
+@cindex unbalanced parentheses
+@cindex parenthesis mismatch, debugging
+  However, unmatched parentheses are the most common syntax errors in
+Lisp, and we can give further advice for those cases.  (In addition,
+just moving point through the code with Show Paren mode enabled might
+find the mismatch.)
+
+@menu
+* Excess Open::     How to find a spurious open paren or missing close.
+* Excess Close::    How to find a spurious close paren or missing open.
+@end menu
+
+@node Excess Open
+@subsection Excess Open Parentheses
+
+  The first step is to find the defun that is unbalanced.  If there is
+an excess open parenthesis, the way to do this is to go to the end of
+the file and type @kbd{C-u C-M-u}.  This will move you to the
+beginning of the first defun that is unbalanced.
+
+  The next step is to determine precisely what is wrong.  There is no
+way to be sure of this except by studying the program, but often the
+existing indentation is a clue to where the parentheses should have
+been.  The easiest way to use this clue is to reindent with @kbd{C-M-q}
+and see what moves.  @strong{But don't do this yet!}  Keep reading,
+first.
+
+  Before you do this, make sure the defun has enough close parentheses.
+Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
+of the file until the end.  So move to the end of the defun and insert a
+close parenthesis there.  Don't use @kbd{C-M-e} to move there, since
+that too will fail to work until the defun is balanced.
+
+  Now you can go to the beginning of the defun and type @kbd{C-M-q}.
+Usually all the lines from a certain point to the end of the function
+will shift to the right.  There is probably a missing close parenthesis,
+or a superfluous open parenthesis, near that point.  (However, don't
+assume this is true; study the code to make sure.)  Once you have found
+the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old
+indentation is probably appropriate to the intended parentheses.
+
+  After you think you have fixed the problem, use @kbd{C-M-q} again.  If
+the old indentation actually fit the intended nesting of parentheses,
+and you have put back those parentheses, @kbd{C-M-q} should not change
+anything.
+
+@node Excess Close
+@subsection Excess Close Parentheses
+
+  To deal with an excess close parenthesis, first go to the beginning
+of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first
+unbalanced defun.
+
+  Then find the actual matching close parenthesis by typing @kbd{C-M-f}
+at the beginning of that defun.  This will leave you somewhere short of
+the place where the defun ought to end.  It is possible that you will
+find a spurious close parenthesis in that vicinity.
+
+  If you don't see a problem at that point, the next thing to do is to
+type @kbd{C-M-q} at the beginning of the defun.  A range of lines will
+probably shift left; if so, the missing open parenthesis or spurious
+close parenthesis is probably near the first of those lines.  (However,
+don't assume this is true; study the code to make sure.)  Once you have
+found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the
+old indentation is probably appropriate to the intended parentheses.
+
+  After you think you have fixed the problem, use @kbd{C-M-q} again.  If
+the old indentation actually fits the intended nesting of parentheses,
+and you have put back those parentheses, @kbd{C-M-q} should not change
+anything.
+
+@node Test Coverage
+@section Test Coverage
+@cindex coverage testing
+
+@findex testcover-start
+@findex testcover-mark-all
+@findex testcover-next-mark
+  You can do coverage testing for a file of Lisp code by loading the
+@code{testcover} library and using the command @kbd{M-x
+testcover-start @key{RET} @var{file} @key{RET}} to instrument the
+code.  Then test your code by calling it one or more times.  Then use
+the command @kbd{M-x testcover-mark-all} to display colored highlights
+on the code to show where coverage is insufficient.  The command
+@kbd{M-x testcover-next-mark} will move point forward to the next
+highlighted spot.
+
+  Normally, a red highlight indicates the form was never completely
+evaluated; a brown highlight means it always evaluated to the same
+value (meaning there has been little testing of what is done with the
+result).  However, the red highlight is skipped for forms that can't
+possibly complete their evaluation, such as @code{error}.  The brown
+highlight is skipped for forms that are expected to always evaluate to
+the same value, such as @code{(setq x 14)}.
+
+  For difficult cases, you can add do-nothing macros to your code to
+give advice to the test coverage tool.
+
+@defmac 1value form
+Evaluate @var{form} and return its value, but inform coverage testing
+that @var{form}'s value should always be the same.
+@end defmac
+
+@defmac noreturn form
+Evaluate @var{form}, informing coverage testing that @var{form} should
+never return.  If it ever does return, you get a run-time error.
+@end defmac
+
+  Edebug also has a coverage testing feature (@pxref{Coverage
+Testing}).  These features partly duplicate each other, and it would
+be cleaner to combine them.
+
+@node Compilation Errors
+@section Debugging Problems in Compilation
+@cindex debugging byte compilation problems
+
+  When an error happens during byte compilation, it is normally due to
+invalid syntax in the program you are compiling.  The compiler prints a
+suitable error message in the @samp{*Compile-Log*} buffer, and then
+stops.  The message may state a function name in which the error was
+found, or it may not.  Either way, here is how to find out where in the
+file the error occurred.
+
+  What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
+(Note that the buffer name starts with a space, so it does not show
+up in @kbd{M-x list-buffers}.)  This buffer contains the program being
+compiled, and point shows how far the byte compiler was able to read.
+
+  If the error was due to invalid Lisp syntax, point shows exactly where
+the invalid syntax was @emph{detected}.  The cause of the error is not
+necessarily near by!  Use the techniques in the previous section to find
+the error.
+
+  If the error was detected while compiling a form that had been read
+successfully, then point is located at the end of the form.  In this
+case, this technique can't localize the error precisely, but can still
+show you which function to check.
+
+@ignore
+   arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7
+@end ignore
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
new file mode 100644
index 00000000000..db630ba2c51
--- /dev/null
+++ b/doc/lispref/display.texi
@@ -0,0 +1,5442 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/display
+@node Display, System Interface, Processes, Top
+@chapter Emacs Display
+
+  This chapter describes a number of features related to the display
+that Emacs presents to the user.
+
+@menu
+* Refresh Screen::      Clearing the screen and redrawing everything on it.
+* Forcing Redisplay::   Forcing redisplay.
+* Truncation::          Folding or wrapping long text lines.
+* The Echo Area::       Displaying messages at the bottom of the screen.
+* Warnings::            Displaying warning messages for the user.
+* Invisible Text::      Hiding part of the buffer text.
+* Selective Display::   Hiding part of the buffer text (the old way).
+* Temporary Displays::  Displays that go away automatically.
+* Overlays::            Use overlays to highlight parts of the buffer.
+* Width::               How wide a character or string is on the screen.
+* Line Height::         Controlling the height of lines.
+* Faces::               A face defines a graphics style for text characters:
+                          font, colors, etc.
+* Fringes::             Controlling window fringes.
+* Scroll Bars::         Controlling vertical scroll bars.
+* Display Property::    Enabling special display features.
+* Images::              Displaying images in Emacs buffers.
+* Buttons::             Adding clickable buttons to Emacs buffers.
+* Abstract Display::    Emacs' Widget for Object Collections.
+* Blinking::            How Emacs shows the matching open parenthesis.
+* Usual Display::       The usual conventions for displaying nonprinting chars.
+* Display Tables::      How to specify other conventions.
+* Beeping::             Audible signal to the user.
+* Window Systems::      Which window system is being used.
+@end menu
+
+@node Refresh Screen
+@section Refreshing the Screen
+
+  The function @code{redraw-frame} clears and redisplays the entire
+contents of a given frame (@pxref{Frames}).  This is useful if the
+screen is corrupted.
+
+@c Emacs 19 feature
+@defun redraw-frame frame
+This function clears and redisplays frame @var{frame}.
+@end defun
+
+  Even more powerful is @code{redraw-display}:
+
+@deffn Command redraw-display
+This function clears and redisplays all visible frames.
+@end deffn
+
+  This function calls for redisplay of certain windows, the next time
+redisplay is done, but does not clear them first.
+
+@defun force-window-update &optional object
+This function forces some or all windows to be updated on next redisplay.
+If @var{object} is a window, it forces redisplay of that window.  If
+@var{object} is a buffer or buffer name, it forces redisplay of all
+windows displaying that buffer.  If @var{object} is @code{nil} (or
+omitted), it forces redisplay of all windows.
+@end defun
+
+  Processing user input takes absolute priority over redisplay.  If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually---after all the
+input has been processed.
+
+  Normally, suspending and resuming Emacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as Emacs and for ordinary sequential display.  If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption.
+
+@defvar no-redraw-on-reenter
+@cindex suspend (cf. @code{no-redraw-on-reenter})
+@cindex resume (cf. @code{no-redraw-on-reenter})
+This variable controls whether Emacs redraws the entire screen after it
+has been suspended and resumed.  Non-@code{nil} means there is no need
+to redraw, @code{nil} means redrawing is needed.  The default is @code{nil}.
+@end defvar
+
+@node Forcing Redisplay
+@section Forcing Redisplay
+@cindex forcing redisplay
+
+  Emacs redisplay normally stops if input arrives, and does not happen
+at all if input is available before it starts.  Most of the time, this
+is exactly what you want.  However, you can prevent preemption by
+binding @code{redisplay-dont-pause} to a non-@code{nil} value.
+
+@defvar redisplay-preemption-period
+This variable specifies how many seconds Emacs waits between checks
+for new input during redisplay.  (The default is 0.1 seconds.)  If
+input has arrived when Emacs checks, it pre-empts redisplay and
+processes the available input before trying again to redisplay.
+
+If this variable is @code{nil}, Emacs does not check for input during
+redisplay, and redisplay cannot be preempted by input.
+
+This variable is only obeyed on graphical terminals.  For
+text terminals, see @ref{Terminal Output}.
+@end defvar
+
+@defvar redisplay-dont-pause
+If this variable is non-@code{nil}, pending input does not
+prevent or halt redisplay; redisplay occurs, and finishes,
+regardless of whether input is available.
+@end defvar
+
+@defun redisplay &optional force
+This function performs an immediate redisplay provided there are no
+pending input events.  This is equivalent to @code{(sit-for 0)}.
+
+If the optional argument @var{force} is non-@code{nil}, it forces an
+immediate and complete redisplay even if input is available.
+
+Returns @code{t} if redisplay was performed, or @code{nil} otherwise.
+@end defun
+
+@node Truncation
+@section Truncation
+@cindex line wrapping
+@cindex line truncation
+@cindex continuation lines
+@cindex @samp{$} in display
+@cindex @samp{\} in display
+
+  When a line of text extends beyond the right edge of a window, Emacs
+can @dfn{continue} the line (make it ``wrap'' to the next screen
+line), or @dfn{truncate} the line (limit it to one screen line).  The
+additional screen lines used to display a long text line are called
+@dfn{continuation} lines.  Continuation is not the same as filling;
+continuation happens on the screen only, not in the buffer contents,
+and it breaks a line precisely at the right margin, not at a word
+boundary.  @xref{Filling}.
+
+   On a graphical display, tiny arrow images in the window fringes
+indicate truncated and continued lines (@pxref{Fringes}).  On a text
+terminal, a @samp{$} in the rightmost column of the window indicates
+truncation; a @samp{\} on the rightmost column indicates a line that
+``wraps.''  (The display table can specify alternate characters to use
+for this; @pxref{Display Tables}).
+
+@defopt truncate-lines
+This buffer-local variable controls how Emacs displays lines that extend
+beyond the right edge of the window.  The default is @code{nil}, which
+specifies continuation.  If the value is non-@code{nil}, then these
+lines are truncated.
+
+If the variable @code{truncate-partial-width-windows} is non-@code{nil},
+then truncation is always used for side-by-side windows (within one
+frame) regardless of the value of @code{truncate-lines}.
+@end defopt
+
+@defopt default-truncate-lines
+This variable is the default value for @code{truncate-lines}, for
+buffers that do not have buffer-local values for it.
+@end defopt
+
+@defopt truncate-partial-width-windows
+This variable controls display of lines that extend beyond the right
+edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
+If it is non-@code{nil}, these lines are truncated; otherwise,
+@code{truncate-lines} says what to do with them.
+@end defopt
+
+  When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
+a window, that forces truncation.
+
+  If your buffer contains @emph{very} long lines, and you use
+continuation to display them, just thinking about them can make Emacs
+redisplay slow.  The column computation and indentation functions also
+become slow.  Then you might find it advisable to set
+@code{cache-long-line-scans} to @code{t}.
+
+@defvar cache-long-line-scans
+If this variable is non-@code{nil}, various indentation and motion
+functions, and Emacs redisplay, cache the results of scanning the
+buffer, and consult the cache to avoid rescanning regions of the buffer
+unless they are modified.
+
+Turning on the cache slows down processing of short lines somewhat.
+
+This variable is automatically buffer-local in every buffer.
+@end defvar
+
+@node The Echo Area
+@section The Echo Area
+@cindex error display
+@cindex echo area
+
+  The @dfn{echo area} is used for displaying error messages
+(@pxref{Errors}), for messages made with the @code{message} primitive,
+and for echoing keystrokes.  It is not the same as the minibuffer,
+despite the fact that the minibuffer appears (when active) in the same
+place on the screen as the echo area.  The @cite{GNU Emacs Manual}
+specifies the rules for resolving conflicts between the echo area and
+the minibuffer for use of that screen space (@pxref{Minibuffer,, The
+Minibuffer, emacs, The GNU Emacs Manual}).
+
+  You can write output in the echo area by using the Lisp printing
+functions with @code{t} as the stream (@pxref{Output Functions}), or
+explicitly.
+
+@menu
+* Displaying Messages:: Explicitly displaying text in the echo area.
+* Progress::            Informing user about progress of a long operation.
+* Logging Messages::    Echo area messages are logged for the user.
+* Echo Area Customization:: Controlling the echo area.
+@end menu
+
+@node Displaying Messages
+@subsection Displaying Messages in the Echo Area
+@cindex display message in echo area
+
+  This section describes the functions for explicitly producing echo
+area messages.  Many other Emacs features display messages there, too.
+
+@defun message format-string &rest arguments
+This function displays a message in the echo area.  The argument
+@var{format-string} is similar to a C language @code{printf} format
+string.  See @code{format} in @ref{Formatting Strings}, for the details
+on the conversion specifications.  @code{message} returns the
+constructed string.
+
+In batch mode, @code{message} prints the message text on the standard
+error stream, followed by a newline.
+
+If @var{format-string}, or strings among the @var{arguments}, have
+@code{face} text properties, these affect the way the message is displayed.
+
+@c Emacs 19 feature
+If @var{format-string} is @code{nil} or the empty string,
+@code{message} clears the echo area; if the echo area has been
+expanded automatically, this brings it back to its normal size.
+If the minibuffer is active, this brings the minibuffer contents back
+onto the screen immediately.
+
+@example
+@group
+(message "Minibuffer depth is %d."
+         (minibuffer-depth))
+ @print{} Minibuffer depth is 0.
+@result{} "Minibuffer depth is 0."
+@end group
+
+@group
+---------- Echo Area ----------
+Minibuffer depth is 0.
+---------- Echo Area ----------
+@end group
+@end example
+
+To automatically display a message in the echo area or in a pop-buffer,
+depending on its size, use @code{display-message-or-buffer} (see below).
+@end defun
+
+@defmac with-temp-message message &rest body
+This construct displays a message in the echo area temporarily, during
+the execution of @var{body}.  It displays @var{message}, executes
+@var{body}, then returns the value of the last body form while restoring
+the previous echo area contents.
+@end defmac
+
+@defun message-or-box format-string &rest arguments
+This function displays a message like @code{message}, but may display it
+in a dialog box instead of the echo area.  If this function is called in
+a command that was invoked using the mouse---more precisely, if
+@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
+@code{nil} or a list---then it uses a dialog box or pop-up menu to
+display the message.  Otherwise, it uses the echo area.  (This is the
+same criterion that @code{y-or-n-p} uses to make a similar decision; see
+@ref{Yes-or-No Queries}.)
+
+You can force use of the mouse or of the echo area by binding
+@code{last-nonmenu-event} to a suitable value around the call.
+@end defun
+
+@defun message-box format-string &rest arguments
+@anchor{message-box}
+This function displays a message like @code{message}, but uses a dialog
+box (or a pop-up menu) whenever that is possible.  If it is impossible
+to use a dialog box or pop-up menu, because the terminal does not
+support them, then @code{message-box} uses the echo area, like
+@code{message}.
+@end defun
+
+@defun display-message-or-buffer message &optional buffer-name not-this-window frame
+This function displays the message @var{message}, which may be either a
+string or a buffer.  If it is shorter than the maximum height of the
+echo area, as defined by @code{max-mini-window-height}, it is displayed
+in the echo area, using @code{message}.  Otherwise,
+@code{display-buffer} is used to show it in a pop-up buffer.
+
+Returns either the string shown in the echo area, or when a pop-up
+buffer is used, the window used to display it.
+
+If @var{message} is a string, then the optional argument
+@var{buffer-name} is the name of the buffer used to display it when a
+pop-up buffer is used, defaulting to @samp{*Message*}.  In the case
+where @var{message} is a string and displayed in the echo area, it is
+not specified whether the contents are inserted into the buffer anyway.
+
+The optional arguments @var{not-this-window} and @var{frame} are as for
+@code{display-buffer}, and only used if a buffer is displayed.
+@end defun
+
+@defun current-message
+This function returns the message currently being displayed in the
+echo area, or @code{nil} if there is none.
+@end defun
+
+@node Progress
+@subsection Reporting Operation Progress
+@cindex progress reporting
+
+  When an operation can take a while to finish, you should inform the
+user about the progress it makes.  This way the user can estimate
+remaining time and clearly see that Emacs is busy working, not hung.
+
+  Functions listed in this section provide simple and efficient way of
+reporting operation progress.  Here is a working example that does
+nothing useful:
+
+@smallexample
+(let ((progress-reporter
+       (make-progress-reporter "Collecting mana for Emacs..."
+                               0  500)))
+  (dotimes (k 500)
+    (sit-for 0.01)
+    (progress-reporter-update progress-reporter k))
+  (progress-reporter-done progress-reporter))
+@end smallexample
+
+@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
+This function creates and returns a @dfn{progress reporter}---an
+object you will use as an argument for all other functions listed
+here.  The idea is to precompute as much data as possible to make
+progress reporting very fast.
+
+When this progress reporter is subsequently used, it will display
+@var{message} in the echo area, followed by progress percentage.
+@var{message} is treated as a simple string.  If you need it to depend
+on a filename, for instance, use @code{format} before calling this
+function.
+
+@var{min-value} and @var{max-value} arguments stand for starting and
+final states of your operation.  For instance, if you scan a buffer,
+they should be the results of @code{point-min} and @code{point-max}
+correspondingly.  It is required that @var{max-value} is greater than
+@var{min-value}.  If you create progress reporter when some part of
+the operation has already been completed, then specify
+@var{current-value} argument.  But normally you should omit it or set
+it to @code{nil}---it will default to @var{min-value} then.
+
+Remaining arguments control the rate of echo area updates.  Progress
+reporter will wait for at least @var{min-change} more percents of the
+operation to be completed before printing next message.
+@var{min-time} specifies the minimum time in seconds to pass between
+successive prints.  It can be fractional.  Depending on Emacs and
+system capabilities, progress reporter may or may not respect this
+last argument or do it with varying precision.  Default value for
+@var{min-change} is 1 (one percent), for @var{min-time}---0.2
+(seconds.)
+
+This function calls @code{progress-reporter-update}, so the first
+message is printed immediately.
+@end defun
+
+@defun progress-reporter-update reporter value
+This function does the main work of reporting progress of your
+operation.  It displays the message of @var{reporter}, followed by
+progress percentage determined by @var{value}.  If percentage is zero,
+or close enough according to the @var{min-change} and @var{min-time}
+arguments, then it is omitted from the output.
+
+@var{reporter} must be the result of a call to
+@code{make-progress-reporter}.  @var{value} specifies the current
+state of your operation and must be between @var{min-value} and
+@var{max-value} (inclusive) as passed to
+@code{make-progress-reporter}.  For instance, if you scan a buffer,
+then @var{value} should be the result of a call to @code{point}.
+
+This function respects @var{min-change} and @var{min-time} as passed
+to @code{make-progress-reporter} and so does not output new messages
+on every invocation.  It is thus very fast and normally you should not
+try to reduce the number of calls to it: resulting overhead will most
+likely negate your effort.
+@end defun
+
+@defun progress-reporter-force-update reporter value &optional new-message
+This function is similar to @code{progress-reporter-update} except
+that it prints a message in the echo area unconditionally.
+
+The first two arguments have the same meaning as for
+@code{progress-reporter-update}.  Optional @var{new-message} allows
+you to change the message of the @var{reporter}.  Since this functions
+always updates the echo area, such a change will be immediately
+presented to the user.
+@end defun
+
+@defun progress-reporter-done reporter
+This function should be called when the operation is finished.  It
+prints the message of @var{reporter} followed by word ``done'' in the
+echo area.
+
+You should always call this function and not hope for
+@code{progress-reporter-update} to print ``100%.''  Firstly, it may
+never print it, there are many good reasons for this not to happen.
+Secondly, ``done'' is more explicit.
+@end defun
+
+@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
+This is a convenience macro that works the same way as @code{dotimes}
+does, but also reports loop progress using the functions described
+above.  It allows you to save some typing.
+
+You can rewrite the example in the beginning of this node using
+this macro this way:
+
+@example
+(dotimes-with-progress-reporter
+    (k 500)
+    "Collecting some mana for Emacs..."
+  (sit-for 0.01))
+@end example
+@end defmac
+
+@node Logging Messages
+@subsection Logging Messages in @samp{*Messages*}
+@cindex logging echo-area messages
+
+  Almost all the messages displayed in the echo area are also recorded
+in the @samp{*Messages*} buffer so that the user can refer back to
+them.  This includes all the messages that are output with
+@code{message}.
+
+@defopt message-log-max
+This variable specifies how many lines to keep in the @samp{*Messages*}
+buffer.  The value @code{t} means there is no limit on how many lines to
+keep.  The value @code{nil} disables message logging entirely.  Here's
+how to display a message and prevent it from being logged:
+
+@example
+(let (message-log-max)
+  (message @dots{}))
+@end example
+@end defopt
+
+  To make @samp{*Messages*} more convenient for the user, the logging
+facility combines successive identical messages.  It also combines
+successive related messages for the sake of two cases: question
+followed by answer, and a series of progress messages.
+
+  A ``question followed by an answer'' means two messages like the
+ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
+and the second is @samp{@var{question}...@var{answer}}.  The first
+message conveys no additional information beyond what's in the second,
+so logging the second message discards the first from the log.
+
+  A ``series of progress messages'' means successive messages like
+those produced by @code{make-progress-reporter}.  They have the form
+@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
+time, while @var{how-far} varies.  Logging each message in the series
+discards the previous one, provided they are consecutive.
+
+  The functions @code{make-progress-reporter} and @code{y-or-n-p}
+don't have to do anything special to activate the message log
+combination feature.  It operates whenever two consecutive messages
+are logged that share a common prefix ending in @samp{...}.
+
+@node Echo Area Customization
+@subsection Echo Area Customization
+
+  These variables control details of how the echo area works.
+
+@defvar cursor-in-echo-area
+This variable controls where the cursor appears when a message is
+displayed in the echo area.  If it is non-@code{nil}, then the cursor
+appears at the end of the message.  Otherwise, the cursor appears at
+point---not in the echo area at all.
+
+The value is normally @code{nil}; Lisp programs bind it to @code{t}
+for brief periods of time.
+@end defvar
+
+@defvar echo-area-clear-hook
+This normal hook is run whenever the echo area is cleared---either by
+@code{(message nil)} or for any other reason.
+@end defvar
+
+@defvar echo-keystrokes
+This variable determines how much time should elapse before command
+characters echo.  Its value must be an integer or floating point number,
+which specifies the
+number of seconds to wait before echoing.  If the user types a prefix
+key (such as @kbd{C-x}) and then delays this many seconds before
+continuing, the prefix key is echoed in the echo area.  (Once echoing
+begins in a key sequence, all subsequent characters in the same key
+sequence are echoed immediately.)
+
+If the value is zero, then command input is not echoed.
+@end defvar
+
+@defvar message-truncate-lines
+Normally, displaying a long message resizes the echo area to display
+the entire message.  But if the variable @code{message-truncate-lines}
+is non-@code{nil}, the echo area does not resize, and the message is
+truncated to fit it, as in Emacs 20 and before.
+@end defvar
+
+  The variable @code{max-mini-window-height}, which specifies the
+maximum height for resizing minibuffer windows, also applies to the
+echo area (which is really a special use of the minibuffer window.
+@xref{Minibuffer Misc}.
+
+@node Warnings
+@section Reporting Warnings
+@cindex warnings
+
+  @dfn{Warnings} are a facility for a program to inform the user of a
+possible problem, but continue running.
+
+@menu
+* Warning Basics::      Warnings concepts and functions to report them.
+* Warning Variables::   Variables programs bind to customize their warnings.
+* Warning Options::     Variables users set to control display of warnings.
+@end menu
+
+@node Warning Basics
+@subsection Warning Basics
+@cindex severity level
+
+  Every warning has a textual message, which explains the problem for
+the user, and a @dfn{severity level} which is a symbol.  Here are the
+possible severity levels, in order of decreasing severity, and their
+meanings:
+
+@table @code
+@item :emergency
+A problem that will seriously impair Emacs operation soon
+if you do not attend to it promptly.
+@item :error
+A report of data or circumstances that are inherently wrong.
+@item :warning
+A report of data or circumstances that are not inherently wrong, but
+raise suspicion of a possible problem.
+@item :debug
+A report of information that may be useful if you are debugging.
+@end table
+
+  When your program encounters invalid input data, it can either
+signal a Lisp error by calling @code{error} or @code{signal} or report
+a warning with severity @code{:error}.  Signaling a Lisp error is the
+easiest thing to do, but it means the program cannot continue
+processing.  If you want to take the trouble to implement a way to
+continue processing despite the bad data, then reporting a warning of
+severity @code{:error} is the right way to inform the user of the
+problem.  For instance, the Emacs Lisp byte compiler can report an
+error that way and continue compiling other functions.  (If the
+program signals a Lisp error and then handles it with
+@code{condition-case}, the user won't see the error message; it could
+show the message to the user by reporting it as a warning.)
+
+@cindex warning type
+  Each warning has a @dfn{warning type} to classify it.  The type is a
+list of symbols.  The first symbol should be the custom group that you
+use for the program's user options.  For example, byte compiler
+warnings use the warning type @code{(bytecomp)}.  You can also
+subcategorize the warnings, if you wish, by using more symbols in the
+list.
+
+@defun display-warning type message &optional level buffer-name
+This function reports a warning, using @var{message} as the message
+and @var{type} as the warning type.  @var{level} should be the
+severity level, with @code{:warning} being the default.
+
+@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
+for logging the warning.  By default, it is @samp{*Warnings*}.
+@end defun
+
+@defun lwarn type level message &rest args
+This function reports a warning using the value of @code{(format
+@var{message} @var{args}...)} as the message.  In other respects it is
+equivalent to @code{display-warning}.
+@end defun
+
+@defun warn message &rest args
+This function reports a warning using the value of @code{(format
+@var{message} @var{args}...)} as the message, @code{(emacs)} as the
+type, and @code{:warning} as the severity level.  It exists for
+compatibility only; we recommend not using it, because you should
+specify a specific warning type.
+@end defun
+
+@node Warning Variables
+@subsection Warning Variables
+
+  Programs can customize how their warnings appear by binding
+the variables described in this section.
+
+@defvar warning-levels
+This list defines the meaning and severity order of the warning
+severity levels.  Each element defines one severity level,
+and they are arranged in order of decreasing severity.
+
+Each element has the form @code{(@var{level} @var{string}
+@var{function})}, where @var{level} is the severity level it defines.
+@var{string} specifies the textual description of this level.
+@var{string} should use @samp{%s} to specify where to put the warning
+type information, or it can omit the @samp{%s} so as not to include
+that information.
+
+The optional @var{function}, if non-@code{nil}, is a function to call
+with no arguments, to get the user's attention.
+
+Normally you should not change the value of this variable.
+@end defvar
+
+@defvar warning-prefix-function
+If non-@code{nil}, the value is a function to generate prefix text for
+warnings.  Programs can bind the variable to a suitable function.
+@code{display-warning} calls this function with the warnings buffer
+current, and the function can insert text in it.  That text becomes
+the beginning of the warning message.
+
+The function is called with two arguments, the severity level and its
+entry in @code{warning-levels}.  It should return a list to use as the
+entry (this value need not be an actual member of
+@code{warning-levels}).  By constructing this value, the function can
+change the severity of the warning, or specify different handling for
+a given severity level.
+
+If the variable's value is @code{nil} then there is no function
+to call.
+@end defvar
+
+@defvar warning-series
+Programs can bind this variable to @code{t} to say that the next
+warning should begin a series.  When several warnings form a series,
+that means to leave point on the first warning of the series, rather
+than keep moving it for each warning so that it appears on the last one.
+The series ends when the local binding is unbound and
+@code{warning-series} becomes @code{nil} again.
+
+The value can also be a symbol with a function definition.  That is
+equivalent to @code{t}, except that the next warning will also call
+the function with no arguments with the warnings buffer current.  The
+function can insert text which will serve as a header for the series
+of warnings.
+
+Once a series has begun, the value is a marker which points to the
+buffer position in the warnings buffer of the start of the series.
+
+The variable's normal value is @code{nil}, which means to handle
+each warning separately.
+@end defvar
+
+@defvar warning-fill-prefix
+When this variable is non-@code{nil}, it specifies a fill prefix to
+use for filling each warning's text.
+@end defvar
+
+@defvar warning-type-format
+This variable specifies the format for displaying the warning type
+in the warning message.  The result of formatting the type this way
+gets included in the message under the control of the string in the
+entry in @code{warning-levels}.  The default value is @code{" (%s)"}.
+If you bind it to @code{""} then the warning type won't appear at
+all.
+@end defvar
+
+@node Warning Options
+@subsection Warning Options
+
+  These variables are used by users to control what happens
+when a Lisp program reports a warning.
+
+@defopt warning-minimum-level
+This user option specifies the minimum severity level that should be
+shown immediately to the user.  The default is @code{:warning}, which
+means to immediately display all warnings except @code{:debug}
+warnings.
+@end defopt
+
+@defopt warning-minimum-log-level
+This user option specifies the minimum severity level that should be
+logged in the warnings buffer.  The default is @code{:warning}, which
+means to log all warnings except @code{:debug} warnings.
+@end defopt
+
+@defopt warning-suppress-types
+This list specifies which warning types should not be displayed
+immediately for the user.  Each element of the list should be a list
+of symbols.  If its elements match the first elements in a warning
+type, then that warning is not displayed immediately.
+@end defopt
+
+@defopt warning-suppress-log-types
+This list specifies which warning types should not be logged in the
+warnings buffer.  Each element of the list should be a list of
+symbols.  If it matches the first few elements in a warning type, then
+that warning is not logged.
+@end defopt
+
+@node Invisible Text
+@section Invisible Text
+
+@cindex invisible text
+You can make characters @dfn{invisible}, so that they do not appear on
+the screen, with the @code{invisible} property.  This can be either a
+text property (@pxref{Text Properties}) or a property of an overlay
+(@pxref{Overlays}).  Cursor motion also partly ignores these
+characters; if the command loop finds point within them, it moves
+point to the other side of them.
+
+In the simplest case, any non-@code{nil} @code{invisible} property makes
+a character invisible.  This is the default case---if you don't alter
+the default value of @code{buffer-invisibility-spec}, this is how the
+@code{invisible} property works.  You should normally use @code{t}
+as the value of the @code{invisible} property if you don't plan
+to set @code{buffer-invisibility-spec} yourself.
+
+More generally, you can use the variable @code{buffer-invisibility-spec}
+to control which values of the @code{invisible} property make text
+invisible.  This permits you to classify the text into different subsets
+in advance, by giving them different @code{invisible} values, and
+subsequently make various subsets visible or invisible by changing the
+value of @code{buffer-invisibility-spec}.
+
+Controlling visibility with @code{buffer-invisibility-spec} is
+especially useful in a program to display the list of entries in a
+database.  It permits the implementation of convenient filtering
+commands to view just a part of the entries in the database.  Setting
+this variable is very fast, much faster than scanning all the text in
+the buffer looking for properties to change.
+
+@defvar buffer-invisibility-spec
+This variable specifies which kinds of @code{invisible} properties
+actually make a character invisible.  Setting this variable makes it
+buffer-local.
+
+@table @asis
+@item @code{t}
+A character is invisible if its @code{invisible} property is
+non-@code{nil}.  This is the default.
+
+@item a list
+Each element of the list specifies a criterion for invisibility; if a
+character's @code{invisible} property fits any one of these criteria,
+the character is invisible.  The list can have two kinds of elements:
+
+@table @code
+@item @var{atom}
+A character is invisible if its @code{invisible} property value
+is @var{atom} or if it is a list with @var{atom} as a member.
+
+@item (@var{atom} . t)
+A character is invisible if its @code{invisible} property value is
+@var{atom} or if it is a list with @var{atom} as a member.  Moreover,
+a sequence of such characters displays as an ellipsis.
+@end table
+@end table
+@end defvar
+
+  Two functions are specifically provided for adding elements to
+@code{buffer-invisibility-spec} and removing elements from it.
+
+@defun add-to-invisibility-spec element
+This function adds the element @var{element} to
+@code{buffer-invisibility-spec}.  If @code{buffer-invisibility-spec}
+was @code{t}, it changes to a list, @code{(t)}, so that text whose
+@code{invisible} property is @code{t} remains invisible.
+@end defun
+
+@defun remove-from-invisibility-spec element
+This removes the element @var{element} from
+@code{buffer-invisibility-spec}.  This does nothing if @var{element}
+is not in the list.
+@end defun
+
+  A convention for use of @code{buffer-invisibility-spec} is that a
+major mode should use the mode's own name as an element of
+@code{buffer-invisibility-spec} and as the value of the
+@code{invisible} property:
+
+@example
+;; @r{If you want to display an ellipsis:}
+(add-to-invisibility-spec '(my-symbol . t))
+;; @r{If you don't want ellipsis:}
+(add-to-invisibility-spec 'my-symbol)
+
+(overlay-put (make-overlay beginning end)
+             'invisible 'my-symbol)
+
+;; @r{When done with the overlays:}
+(remove-from-invisibility-spec '(my-symbol . t))
+;; @r{Or respectively:}
+(remove-from-invisibility-spec 'my-symbol)
+@end example
+
+@vindex line-move-ignore-invisible
+  Ordinarily, functions that operate on text or move point do not care
+whether the text is invisible.  The user-level line motion commands
+explicitly ignore invisible newlines if
+@code{line-move-ignore-invisible} is non-@code{nil} (the default), but
+only because they are explicitly programmed to do so.
+
+  However, if a command ends with point inside or immediately before
+invisible text, the main editing loop moves point further forward or
+further backward (in the same direction that the command already moved
+it) until that condition is no longer true.  Thus, if the command
+moved point back into an invisible range, Emacs moves point back to
+the beginning of that range, and then back one more character.  If the
+command moved point forward into an invisible range, Emacs moves point
+forward up to the first visible character that follows the invisible
+text.
+
+  Incremental search can make invisible overlays visible temporarily
+and/or permanently when a match includes invisible text.  To enable
+this, the overlay should have a non-@code{nil}
+@code{isearch-open-invisible} property.  The property value should be a
+function to be called with the overlay as an argument.  This function
+should make the overlay visible permanently; it is used when the match
+overlaps the overlay on exit from the search.
+
+  During the search, such overlays are made temporarily visible by
+temporarily modifying their invisible and intangible properties.  If you
+want this to be done differently for a certain overlay, give it an
+@code{isearch-open-invisible-temporary} property which is a function.
+The function is called with two arguments: the first is the overlay, and
+the second is @code{nil} to make the overlay visible, or @code{t} to
+make it invisible again.
+
+@node Selective Display
+@section Selective Display
+@c @cindex selective display   Duplicates selective-display
+
+  @dfn{Selective display} refers to a pair of related features for
+hiding certain lines on the screen.
+
+  The first variant, explicit selective display, is designed for use
+in a Lisp program: it controls which lines are hidden by altering the
+text.  This kind of hiding in some ways resembles the effect of the
+@code{invisible} property (@pxref{Invisible Text}), but the two
+features are different and do not work the same way.
+
+  In the second variant, the choice of lines to hide is made
+automatically based on indentation.  This variant is designed to be a
+user-level feature.
+
+  The way you control explicit selective display is by replacing a
+newline (control-j) with a carriage return (control-m).  The text that
+was formerly a line following that newline is now hidden.  Strictly
+speaking, it is temporarily no longer a line at all, since only
+newlines can separate lines; it is now part of the previous line.
+
+  Selective display does not directly affect editing commands.  For
+example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
+into hidden text.  However, the replacement of newline characters with
+carriage return characters affects some editing commands.  For
+example, @code{next-line} skips hidden lines, since it searches only
+for newlines.  Modes that use selective display can also define
+commands that take account of the newlines, or that control which
+parts of the text are hidden.
+
+  When you write a selectively displayed buffer into a file, all the
+control-m's are output as newlines.  This means that when you next read
+in the file, it looks OK, with nothing hidden.  The selective display
+effect is seen only within Emacs.
+
+@defvar selective-display
+This buffer-local variable enables selective display.  This means that
+lines, or portions of lines, may be made hidden.
+
+@itemize @bullet
+@item
+If the value of @code{selective-display} is @code{t}, then the character
+control-m marks the start of hidden text; the control-m, and the rest
+of the line following it, are not displayed.  This is explicit selective
+display.
+
+@item
+If the value of @code{selective-display} is a positive integer, then
+lines that start with more than that many columns of indentation are not
+displayed.
+@end itemize
+
+When some portion of a buffer is hidden, the vertical movement
+commands operate as if that portion did not exist, allowing a single
+@code{next-line} command to skip any number of hidden lines.
+However, character movement commands (such as @code{forward-char}) do
+not skip the hidden portion, and it is possible (if tricky) to insert
+or delete text in an hidden portion.
+
+In the examples below, we show the @emph{display appearance} of the
+buffer @code{foo}, which changes with the value of
+@code{selective-display}.  The @emph{contents} of the buffer do not
+change.
+
+@example
+@group
+(setq selective-display nil)
+     @result{} nil
+
+---------- Buffer: foo ----------
+1 on this column
+ 2on this column
+  3n this column
+  3n this column
+ 2on this column
+1 on this column
+---------- Buffer: foo ----------
+@end group
+
+@group
+(setq selective-display 2)
+     @result{} 2
+
+---------- Buffer: foo ----------
+1 on this column
+ 2on this column
+ 2on this column
+1 on this column
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defvar
+
+@defvar selective-display-ellipses
+If this buffer-local variable is non-@code{nil}, then Emacs displays
+@samp{@dots{}} at the end of a line that is followed by hidden text.
+This example is a continuation of the previous one.
+
+@example
+@group
+(setq selective-display-ellipses t)
+     @result{} t
+
+---------- Buffer: foo ----------
+1 on this column
+ 2on this column ...
+ 2on this column
+1 on this column
+---------- Buffer: foo ----------
+@end group
+@end example
+
+You can use a display table to substitute other text for the ellipsis
+(@samp{@dots{}}).  @xref{Display Tables}.
+@end defvar
+
+@node Temporary Displays
+@section Temporary Displays
+
+  Temporary displays are used by Lisp programs to put output into a
+buffer and then present it to the user for perusal rather than for
+editing.  Many help commands use this feature.
+
+@defspec with-output-to-temp-buffer buffer-name forms@dots{}
+This function executes @var{forms} while arranging to insert any output
+they print into the buffer named @var{buffer-name}, which is first
+created if necessary, and put into Help mode.  Finally, the buffer is
+displayed in some window, but not selected.
+
+If the @var{forms} do not change the major mode in the output buffer,
+so that it is still Help mode at the end of their execution, then
+@code{with-output-to-temp-buffer} makes this buffer read-only at the
+end, and also scans it for function and variable names to make them
+into clickable cross-references.  @xref{Docstring hyperlinks, , Tips
+for Documentation Strings}, in particular the item on hyperlinks in
+documentation strings, for more details.
+
+The string @var{buffer-name} specifies the temporary buffer, which
+need not already exist.  The argument must be a string, not a buffer.
+The buffer is erased initially (with no questions asked), and it is
+marked as unmodified after @code{with-output-to-temp-buffer} exits.
+
+@code{with-output-to-temp-buffer} binds @code{standard-output} to the
+temporary buffer, then it evaluates the forms in @var{forms}.  Output
+using the Lisp output functions within @var{forms} goes by default to
+that buffer (but screen display and messages in the echo area, although
+they are ``output'' in the general sense of the word, are not affected).
+@xref{Output Functions}.
+
+Several hooks are available for customizing the behavior
+of this construct; they are listed below.
+
+The value of the last form in @var{forms} is returned.
+
+@example
+@group
+---------- Buffer: foo ----------
+ This is the contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(with-output-to-temp-buffer "foo"
+    (print 20)
+    (print standard-output))
+@result{} #<buffer foo>
+
+---------- Buffer: foo ----------
+20
+
+#<buffer foo>
+
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defspec
+
+@defvar temp-buffer-show-function
+If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
+calls it as a function to do the job of displaying a help buffer.  The
+function gets one argument, which is the buffer it should display.
+
+It is a good idea for this function to run @code{temp-buffer-show-hook}
+just as @code{with-output-to-temp-buffer} normally would, inside of
+@code{save-selected-window} and with the chosen window and buffer
+selected.
+@end defvar
+
+@defvar temp-buffer-setup-hook
+This normal hook is run by @code{with-output-to-temp-buffer} before
+evaluating @var{body}.  When the hook runs, the temporary buffer is
+current.  This hook is normally set up with a function to put the
+buffer in Help mode.
+@end defvar
+
+@defvar temp-buffer-show-hook
+This normal hook is run by @code{with-output-to-temp-buffer} after
+displaying the temporary buffer.  When the hook runs, the temporary buffer
+is current, and the window it was displayed in is selected.  This hook
+is normally set up with a function to make the buffer read only, and
+find function names and variable names in it, provided the major mode
+is Help mode.
+@end defvar
+
+@defun momentary-string-display string position &optional char message
+This function momentarily displays @var{string} in the current buffer at
+@var{position}.  It has no effect on the undo list or on the buffer's
+modification status.
+
+The momentary display remains until the next input event.  If the next
+input event is @var{char}, @code{momentary-string-display} ignores it
+and returns.  Otherwise, that event remains buffered for subsequent use
+as input.  Thus, typing @var{char} will simply remove the string from
+the display, while typing (say) @kbd{C-f} will remove the string from
+the display and later (presumably) move point forward.  The argument
+@var{char} is a space by default.
+
+The return value of @code{momentary-string-display} is not meaningful.
+
+If the string @var{string} does not contain control characters, you can
+do the same job in a more general way by creating (and then subsequently
+deleting) an overlay with a @code{before-string} property.
+@xref{Overlay Properties}.
+
+If @var{message} is non-@code{nil}, it is displayed in the echo area
+while @var{string} is displayed in the buffer.  If it is @code{nil}, a
+default message says to type @var{char} to continue.
+
+In this example, point is initially located at the beginning of the
+second line:
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the contents of foo.
+@point{}Second line.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(momentary-string-display
+  "**** Important Message! ****"
+  (point) ?\r
+  "Type RET when done reading")
+@result{} t
+@end group
+
+@group
+---------- Buffer: foo ----------
+This is the contents of foo.
+**** Important Message! ****Second line.
+---------- Buffer: foo ----------
+
+---------- Echo Area ----------
+Type RET when done reading
+---------- Echo Area ----------
+@end group
+@end example
+@end defun
+
+@node Overlays
+@section Overlays
+@cindex overlays
+
+You can use @dfn{overlays} to alter the appearance of a buffer's text on
+the screen, for the sake of presentation features.  An overlay is an
+object that belongs to a particular buffer, and has a specified
+beginning and end.  It also has properties that you can examine and set;
+these affect the display of the text within the overlay.
+
+An overlay uses markers to record its beginning and end; thus,
+editing the text of the buffer adjusts the beginning and end of each
+overlay so that it stays with the text.  When you create the overlay,
+you can specify whether text inserted at the beginning should be
+inside the overlay or outside, and likewise for the end of the overlay.
+
+@menu
+* Managing Overlays::   Creating and moving overlays.
+* Overlay Properties::  How to read and set properties.
+			What properties do to the screen display.
+* Finding Overlays::    Searching for overlays.
+@end menu
+
+@node Managing Overlays
+@subsection Managing Overlays
+
+  This section describes the functions to create, delete and move
+overlays, and to examine their contents.  Overlay changes are not
+recorded in the buffer's undo list, since the overlays are not
+part of the buffer's contents.
+
+@defun overlayp object
+This function returns @code{t} if @var{object} is an overlay.
+@end defun
+
+@defun make-overlay start end &optional buffer front-advance rear-advance
+This function creates and returns an overlay that belongs to
+@var{buffer} and ranges from @var{start} to @var{end}.  Both @var{start}
+and @var{end} must specify buffer positions; they may be integers or
+markers.  If @var{buffer} is omitted, the overlay is created in the
+current buffer.
+
+The arguments @var{front-advance} and @var{rear-advance} specify the
+marker insertion type for the start of the overlay and for the end of
+the overlay, respectively.  @xref{Marker Insertion Types}.  If they
+are both @code{nil}, the default, then the overlay extends to include
+any text inserted at the beginning, but not text inserted at the end.
+If @var{front-advance} is non-@code{nil}, text inserted at the
+beginning of the overlay is excluded from the overlay.  If
+@var{rear-advance} is non-@code{nil}, text inserted at the end of the
+overlay is included in the overlay.
+@end defun
+
+@defun overlay-start overlay
+This function returns the position at which @var{overlay} starts,
+as an integer.
+@end defun
+
+@defun overlay-end overlay
+This function returns the position at which @var{overlay} ends,
+as an integer.
+@end defun
+
+@defun overlay-buffer overlay
+This function returns the buffer that @var{overlay} belongs to.  It
+returns @code{nil} if @var{overlay} has been deleted.
+@end defun
+
+@defun delete-overlay overlay
+This function deletes @var{overlay}.  The overlay continues to exist as
+a Lisp object, and its property list is unchanged, but it ceases to be
+attached to the buffer it belonged to, and ceases to have any effect on
+display.
+
+A deleted overlay is not permanently disconnected.  You can give it a
+position in a buffer again by calling @code{move-overlay}.
+@end defun
+
+@defun move-overlay overlay start end &optional buffer
+This function moves @var{overlay} to @var{buffer}, and places its bounds
+at @var{start} and @var{end}.  Both arguments @var{start} and @var{end}
+must specify buffer positions; they may be integers or markers.
+
+If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
+was already associated with; if @var{overlay} was deleted, it goes into
+the current buffer.
+
+The return value is @var{overlay}.
+
+This is the only valid way to change the endpoints of an overlay.  Do
+not try modifying the markers in the overlay by hand, as that fails to
+update other vital data structures and can cause some overlays to be
+``lost.''
+@end defun
+
+@defun remove-overlays &optional start end name value
+This function removes all the overlays between @var{start} and
+@var{end} whose property @var{name} has the value @var{value}.  It can
+move the endpoints of the overlays in the region, or split them.
+
+If @var{name} is omitted or @code{nil}, it means to delete all overlays in
+the specified region.  If @var{start} and/or @var{end} are omitted or
+@code{nil}, that means the beginning and end of the buffer respectively.
+Therefore, @code{(remove-overlays)} removes all the overlays in the
+current buffer.
+@end defun
+
+  Here are some examples:
+
+@example
+;; @r{Create an overlay.}
+(setq foo (make-overlay 1 10))
+     @result{} #<overlay from 1 to 10 in display.texi>
+(overlay-start foo)
+     @result{} 1
+(overlay-end foo)
+     @result{} 10
+(overlay-buffer foo)
+     @result{} #<buffer display.texi>
+;; @r{Give it a property we can check later.}
+(overlay-put foo 'happy t)
+     @result{} t
+;; @r{Verify the property is present.}
+(overlay-get foo 'happy)
+     @result{} t
+;; @r{Move the overlay.}
+(move-overlay foo 5 20)
+     @result{} #<overlay from 5 to 20 in display.texi>
+(overlay-start foo)
+     @result{} 5
+(overlay-end foo)
+     @result{} 20
+;; @r{Delete the overlay.}
+(delete-overlay foo)
+     @result{} nil
+;; @r{Verify it is deleted.}
+foo
+     @result{} #<overlay in no buffer>
+;; @r{A deleted overlay has no position.}
+(overlay-start foo)
+     @result{} nil
+(overlay-end foo)
+     @result{} nil
+(overlay-buffer foo)
+     @result{} nil
+;; @r{Undelete the overlay.}
+(move-overlay foo 1 20)
+     @result{} #<overlay from 1 to 20 in display.texi>
+;; @r{Verify the results.}
+(overlay-start foo)
+     @result{} 1
+(overlay-end foo)
+     @result{} 20
+(overlay-buffer foo)
+     @result{} #<buffer display.texi>
+;; @r{Moving and deleting the overlay does not change its properties.}
+(overlay-get foo 'happy)
+     @result{} t
+@end example
+
+  Emacs stores the overlays of each buffer in two lists, divided
+around an arbitrary ``center position.''  One list extends backwards
+through the buffer from that center position, and the other extends
+forwards from that center position.  The center position can be anywhere
+in the buffer.
+
+@defun overlay-recenter pos
+This function recenters the overlays of the current buffer around
+position @var{pos}.  That makes overlay lookup faster for positions
+near @var{pos}, but slower for positions far away from @var{pos}.
+@end defun
+
+  A loop that scans the buffer forwards, creating overlays, can run
+faster if you do @code{(overlay-recenter (point-max))} first.
+
+@node Overlay Properties
+@subsection Overlay Properties
+
+  Overlay properties are like text properties in that the properties that
+alter how a character is displayed can come from either source.  But in
+most respects they are different.  @xref{Text Properties}, for comparison.
+
+  Text properties are considered a part of the text; overlays and
+their properties are specifically considered not to be part of the
+text.  Thus, copying text between various buffers and strings
+preserves text properties, but does not try to preserve overlays.
+Changing a buffer's text properties marks the buffer as modified,
+while moving an overlay or changing its properties does not.  Unlike
+text property changes, overlay property changes are not recorded in
+the buffer's undo list.
+
+  These functions read and set the properties of an overlay:
+
+@defun overlay-get overlay prop
+This function returns the value of property @var{prop} recorded in
+@var{overlay}, if any.  If @var{overlay} does not record any value for
+that property, but it does have a @code{category} property which is a
+symbol, that symbol's @var{prop} property is used.  Otherwise, the value
+is @code{nil}.
+@end defun
+
+@defun overlay-put overlay prop value
+This function sets the value of property @var{prop} recorded in
+@var{overlay} to @var{value}.  It returns @var{value}.
+@end defun
+
+@defun overlay-properties overlay
+This returns a copy of the property list of @var{overlay}.
+@end defun
+
+  See also the function @code{get-char-property} which checks both
+overlay properties and text properties for a given character.
+@xref{Examining Properties}.
+
+  Many overlay properties have special meanings; here is a table
+of them:
+
+@table @code
+@item priority
+@kindex priority @r{(overlay property)}
+This property's value (which should be a nonnegative integer number)
+determines the priority of the overlay.  The priority matters when two
+or more overlays cover the same character and both specify the same
+property; the one whose @code{priority} value is larger takes priority
+over the other.  For the @code{face} property, the higher priority
+value does not completely replace the other; instead, its face
+attributes override the face attributes of the lower priority
+@code{face} property.
+
+Currently, all overlays take priority over text properties.  Please
+avoid using negative priority values, as we have not yet decided just
+what they should mean.
+
+@item window
+@kindex window @r{(overlay property)}
+If the @code{window} property is non-@code{nil}, then the overlay
+applies only on that window.
+
+@item category
+@kindex category @r{(overlay property)}
+If an overlay has a @code{category} property, we call it the
+@dfn{category} of the overlay.  It should be a symbol.  The properties
+of the symbol serve as defaults for the properties of the overlay.
+
+@item face
+@kindex face @r{(overlay property)}
+This property controls the way text is displayed---for example, which
+font and which colors.  @xref{Faces}, for more information.
+
+In the simplest case, the value is a face name.  It can also be a list;
+then each element can be any of these possibilities:
+
+@itemize @bullet
+@item
+A face name (a symbol or string).
+
+@item
+A property list of face attributes.  This has the form (@var{keyword}
+@var{value} @dots{}), where each @var{keyword} is a face attribute
+name and @var{value} is a meaningful value for that attribute.  With
+this feature, you do not need to create a face each time you want to
+specify a particular attribute for certain text.  @xref{Face
+Attributes}.
+
+@item
+A cons cell, either of the form @code{(foreground-color . @var{color-name})} or
+@code{(background-color . @var{color-name})}.  These elements specify
+just the foreground color or just the background color.
+
+@code{(foreground-color . @var{color-name})} has the same effect as
+@code{(:foreground @var{color-name})}; likewise for the background.
+@end itemize
+
+@item mouse-face
+@kindex mouse-face @r{(overlay property)}
+This property is used instead of @code{face} when the mouse is within
+the range of the overlay.
+
+@item display
+@kindex display @r{(overlay property)}
+This property activates various features that change the
+way text is displayed.  For example, it can make text appear taller
+or shorter, higher or lower, wider or narrower, or replaced with an image.
+@xref{Display Property}.
+
+@item help-echo
+@kindex help-echo @r{(overlay property)}
+If an overlay has a @code{help-echo} property, then when you move the
+mouse onto the text in the overlay, Emacs displays a help string in the
+echo area, or in the tooltip window.  For details see @ref{Text
+help-echo}.
+
+@item modification-hooks
+@kindex modification-hooks @r{(overlay property)}
+This property's value is a list of functions to be called if any
+character within the overlay is changed or if text is inserted strictly
+within the overlay.
+
+The hook functions are called both before and after each change.
+If the functions save the information they receive, and compare notes
+between calls, they can determine exactly what change has been made
+in the buffer text.
+
+When called before a change, each function receives four arguments: the
+overlay, @code{nil}, and the beginning and end of the text range to be
+modified.
+
+When called after a change, each function receives five arguments: the
+overlay, @code{t}, the beginning and end of the text range just
+modified, and the length of the pre-change text replaced by that range.
+(For an insertion, the pre-change length is zero; for a deletion, that
+length is the number of characters deleted, and the post-change
+beginning and end are equal.)
+
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
+Text properties also support the @code{modification-hooks} property,
+but the details are somewhat different (@pxref{Special Properties}).
+
+@item insert-in-front-hooks
+@kindex insert-in-front-hooks @r{(overlay property)}
+This property's value is a list of functions to be called before and
+after inserting text right at the beginning of the overlay.  The calling
+conventions are the same as for the @code{modification-hooks} functions.
+
+@item insert-behind-hooks
+@kindex insert-behind-hooks @r{(overlay property)}
+This property's value is a list of functions to be called before and
+after inserting text right at the end of the overlay.  The calling
+conventions are the same as for the @code{modification-hooks} functions.
+
+@item invisible
+@kindex invisible @r{(overlay property)}
+The @code{invisible} property can make the text in the overlay
+invisible, which means that it does not appear on the screen.
+@xref{Invisible Text}, for details.
+
+@item intangible
+@kindex intangible @r{(overlay property)}
+The @code{intangible} property on an overlay works just like the
+@code{intangible} text property.  @xref{Special Properties}, for details.
+
+@item isearch-open-invisible
+This property tells incremental search how to make an invisible overlay
+visible, permanently, if the final match overlaps it.  @xref{Invisible
+Text}.
+
+@item isearch-open-invisible-temporary
+This property tells incremental search how to make an invisible overlay
+visible, temporarily, during the search.  @xref{Invisible Text}.
+
+@item before-string
+@kindex before-string @r{(overlay property)}
+This property's value is a string to add to the display at the beginning
+of the overlay.  The string does not appear in the buffer in any
+sense---only on the screen.
+
+@item after-string
+@kindex after-string @r{(overlay property)}
+This property's value is a string to add to the display at the end of
+the overlay.  The string does not appear in the buffer in any
+sense---only on the screen.
+
+@item evaporate
+@kindex evaporate @r{(overlay property)}
+If this property is non-@code{nil}, the overlay is deleted automatically
+if it becomes empty (i.e., if its length becomes zero).  If you give
+an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
+it immediately.
+
+@item local-map
+@cindex keymap of character (and overlays)
+@kindex local-map @r{(overlay property)}
+If this property is non-@code{nil}, it specifies a keymap for a portion
+of the text.  The property's value replaces the buffer's local map, when
+the character after point is within the overlay.  @xref{Active Keymaps}.
+
+@item keymap
+@kindex keymap @r{(overlay property)}
+The @code{keymap} property is similar to @code{local-map} but overrides the
+buffer's local map (and the map specified by the @code{local-map}
+property) rather than replacing it.
+@end table
+
+@node Finding Overlays
+@subsection Searching for Overlays
+
+@defun overlays-at pos
+This function returns a list of all the overlays that cover the
+character at position @var{pos} in the current buffer.  The list is in
+no particular order.  An overlay contains position @var{pos} if it
+begins at or before @var{pos}, and ends after @var{pos}.
+
+To illustrate usage, here is a Lisp function that returns a list of the
+overlays that specify property @var{prop} for the character at point:
+
+@smallexample
+(defun find-overlays-specifying (prop)
+  (let ((overlays (overlays-at (point)))
+        found)
+    (while overlays
+      (let ((overlay (car overlays)))
+        (if (overlay-get overlay prop)
+            (setq found (cons overlay found))))
+      (setq overlays (cdr overlays)))
+    found))
+@end smallexample
+@end defun
+
+@defun overlays-in beg end
+This function returns a list of the overlays that overlap the region
+@var{beg} through @var{end}.  ``Overlap'' means that at least one
+character is contained within the overlay and also contained within the
+specified region; however, empty overlays are included in the result if
+they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
+@end defun
+
+@defun next-overlay-change pos
+This function returns the buffer position of the next beginning or end
+of an overlay, after @var{pos}.  If there is none, it returns
+@code{(point-max)}.
+@end defun
+
+@defun previous-overlay-change pos
+This function returns the buffer position of the previous beginning or
+end of an overlay, before @var{pos}.  If there is none, it returns
+@code{(point-min)}.
+@end defun
+
+  As an example, here's a simplified (and inefficient) version of the
+primitive function @code{next-single-char-property-change}
+(@pxref{Property Search}).  It searches forward from position
+@var{pos} for the next position where the value of a given property
+@code{prop}, as obtained from either overlays or text properties,
+changes.
+
+@smallexample
+(defun next-single-char-property-change (position prop)
+  (save-excursion
+    (goto-char position)
+    (let ((propval (get-char-property (point) prop)))
+      (while (and (not (eobp))
+                  (eq (get-char-property (point) prop) propval))
+        (goto-char (min (next-overlay-change (point))
+                        (next-single-property-change (point) prop)))))
+    (point)))
+@end smallexample
+
+@node Width
+@section Width
+
+Since not all characters have the same width, these functions let you
+check the width of a character.  @xref{Primitive Indent}, and
+@ref{Screen Lines}, for related functions.
+
+@defun char-width char
+This function returns the width in columns of the character @var{char},
+if it were displayed in the current buffer and the selected window.
+@end defun
+
+@defun string-width string
+This function returns the width in columns of the string @var{string},
+if it were displayed in the current buffer and the selected window.
+@end defun
+
+@defun truncate-string-to-width string width &optional start-column padding ellipsis
+This function returns the part of @var{string} that fits within
+@var{width} columns, as a new string.
+
+If @var{string} does not reach @var{width}, then the result ends where
+@var{string} ends.  If one multi-column character in @var{string}
+extends across the column @var{width}, that character is not included in
+the result.  Thus, the result can fall short of @var{width} but cannot
+go beyond it.
+
+The optional argument @var{start-column} specifies the starting column.
+If this is non-@code{nil}, then the first @var{start-column} columns of
+the string are omitted from the value.  If one multi-column character in
+@var{string} extends across the column @var{start-column}, that
+character is not included.
+
+The optional argument @var{padding}, if non-@code{nil}, is a padding
+character added at the beginning and end of the result string, to extend
+it to exactly @var{width} columns.  The padding character is used at the
+end of the result if it falls short of @var{width}.  It is also used at
+the beginning of the result if one multi-column character in
+@var{string} extends across the column @var{start-column}.
+
+If @var{ellipsis} is non-@code{nil}, it should be a string which will
+replace the end of @var{str} (including any padding) if it extends
+beyond @var{end-column}, unless the display width of @var{str} is
+equal to or less than the display width of @var{ellipsis}.  If
+@var{ellipsis} is non-@code{nil} and not a string, it stands for
+@code{"..."}.
+
+@example
+(truncate-string-to-width "\tab\t" 12 4)
+     @result{} "ab"
+(truncate-string-to-width "\tab\t" 12 4 ?\s)
+     @result{} "    ab  "
+@end example
+@end defun
+
+@node Line Height
+@section Line Height
+@cindex line height
+
+  The total height of each display line consists of the height of the
+contents of the line, plus optional additional vertical line spacing
+above or below the display line.
+
+  The height of the line contents is the maximum height of any
+character or image on that display line, including the final newline
+if there is one.  (A display line that is continued doesn't include a
+final newline.)  That is the default line height, if you do nothing to
+specify a greater height.  (In the most common case, this equals the
+height of the default frame font.)
+
+  There are several ways to explicitly specify a larger line height,
+either by specifying an absolute height for the display line, or by
+specifying vertical space.  However, no matter what you specify, the
+actual line height can never be less than the default.
+
+@kindex line-height @r{(text property)}
+  A newline can have a @code{line-height} text or overlay property
+that controls the total height of the display line ending in that
+newline.
+
+  If the property value is @code{t}, the newline character has no
+effect on the displayed height of the line---the visible contents
+alone determine the height.  This is useful for tiling small images
+(or image slices) without adding blank areas between the images.
+
+  If the property value is a list of the form @code{(@var{height}
+@var{total})}, that adds extra space @emph{below} the display line.
+First Emacs uses @var{height} as a height spec to control extra space
+@emph{above} the line; then it adds enough space @emph{below} the line
+to bring the total line height up to @var{total}.  In this case, the
+other ways to specify the line spacing are ignored.
+
+  Any other kind of property value is a height spec, which translates
+into a number---the specified line height.  There are several ways to
+write a height spec; here's how each of them translates into a number:
+
+@table @code
+@item @var{integer}
+If the height spec is a positive integer, the height value is that integer.
+@item @var{float}
+If the height spec is a float, @var{float}, the numeric height value
+is @var{float} times the frame's default line height.
+@item (@var{face} . @var{ratio})
+If the height spec is a cons of the format shown, the numeric height
+is @var{ratio} times the height of face @var{face}.  @var{ratio} can
+be any type of number, or @code{nil} which means a ratio of 1.
+If @var{face} is @code{t}, it refers to the current face.
+@item (nil . @var{ratio})
+If the height spec is a cons of the format shown, the numeric height
+is @var{ratio} times the height of the contents of the line.
+@end table
+
+  Thus, any valid height spec determines the height in pixels, one way
+or another.  If the line contents' height is less than that, Emacs
+adds extra vertical space above the line to achieve the specified
+total height.
+
+  If you don't specify the @code{line-height} property, the line's
+height consists of the contents' height plus the line spacing.
+There are several ways to specify the line spacing for different
+parts of Emacs text.
+
+@vindex default-line-spacing
+  You can specify the line spacing for all lines in a frame with the
+@code{line-spacing} frame parameter (@pxref{Layout Parameters}).
+However, if the variable @code{default-line-spacing} is
+non-@code{nil}, it overrides the frame's @code{line-spacing}
+parameter.  An integer value specifies the number of pixels put below
+lines on graphical displays.  A floating point number specifies the
+spacing relative to the frame's default line height.
+
+@vindex line-spacing
+  You can specify the line spacing for all lines in a buffer via the
+buffer-local @code{line-spacing} variable.  An integer value specifies
+the number of pixels put below lines on graphical displays.  A floating
+point number specifies the spacing relative to the default frame line
+height.  This overrides line spacings specified for the frame.
+
+@kindex line-spacing @r{(text property)}
+  Finally, a newline can have a @code{line-spacing} text or overlay
+property that overrides the default frame line spacing and the buffer
+local @code{line-spacing} variable, for the display line ending in
+that newline.
+
+  One way or another, these mechanisms specify a Lisp value for the
+spacing of each line.  The value is a height spec, and it translates
+into a Lisp value as described above.  However, in this case the
+numeric height value specifies the line spacing, rather than the line
+height.
+
+@node Faces
+@section Faces
+@cindex faces
+
+  A @dfn{face} is a named collection of graphical attributes: font
+family, foreground color, background color, optional underlining, and
+many others.  Faces are used in Emacs to control the style of display of
+particular parts of the text or the frame.  @xref{Standard Faces,,,
+emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
+comes with.
+
+@cindex face id
+Each face has its own @dfn{face number}, which distinguishes faces at
+low levels within Emacs.  However, for most purposes, you refer to
+faces in Lisp programs by the symbols that name them.
+
+@defun facep object
+This function returns @code{t} if @var{object} is a face name string
+or symbol (or if it is a vector of the kind used internally to record
+face data).  It returns @code{nil} otherwise.
+@end defun
+
+Each face name is meaningful for all frames, and by default it has the
+same meaning in all frames.  But you can arrange to give a particular
+face name a special meaning in one frame if you wish.
+
+@menu
+* Defining Faces::      How to define a face with @code{defface}.
+* Face Attributes::     What is in a face?
+* Attribute Functions::  Functions to examine and set face attributes.
+* Displaying Faces::     How Emacs combines the faces specified for a character.
+* Font Selection::      Finding the best available font for a face.
+* Face Functions::      How to define and examine faces.
+* Auto Faces::          Hook for automatic face assignment.
+* Font Lookup::         Looking up the names of available fonts
+                          and information about them.
+* Fontsets::            A fontset is a collection of fonts
+                          that handle a range of character sets.
+@end menu
+
+@node Defining Faces
+@subsection Defining Faces
+
+  The way to define a new face is with @code{defface}.  This creates a
+kind of customization item (@pxref{Customization}) which the user can
+customize using the Customization buffer (@pxref{Easy Customization,,,
+emacs, The GNU Emacs Manual}).
+
+@defmac defface face spec doc [keyword value]@dots{}
+This declares @var{face} as a customizable face that defaults
+according to @var{spec}.  You should not quote the symbol @var{face},
+and it should not end in @samp{-face} (that would be redundant).  The
+argument @var{doc} specifies the face documentation.  The keywords you
+can use in @code{defface} are the same as in @code{defgroup} and
+@code{defcustom} (@pxref{Common Keywords}).
+
+When @code{defface} executes, it defines the face according to
+@var{spec}, then uses any customizations that were read from the
+init file (@pxref{Init File}) to override that specification.
+
+When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
+Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
+overrides any customizations of the face.  This way, the face reflects
+exactly what the @code{defface} says.
+
+The purpose of @var{spec} is to specify how the face should appear on
+different kinds of terminals.  It should be an alist whose elements
+have the form @code{(@var{display} @var{atts})}.  Each element's
+@sc{car}, @var{display}, specifies a class of terminals.  (The first
+element, if its @sc{car} is @code{default}, is special---it specifies
+defaults for the remaining elements).  The element's @sc{cadr},
+@var{atts}, is a list of face attributes and their values; it
+specifies what the face should look like on that kind of terminal.
+The possible attributes are defined in the value of
+@code{custom-face-attributes}.
+
+The @var{display} part of an element of @var{spec} determines which
+frames the element matches.  If more than one element of @var{spec}
+matches a given frame, the first element that matches is the one used
+for that frame.  There are three possibilities for @var{display}:
+
+@table @asis
+@item @code{default}
+This element of @var{spec} doesn't match any frames; instead, it
+specifies defaults that apply to all frames.  This kind of element, if
+used, must be the first element of @var{spec}.  Each of the following
+elements can override any or all of these defaults.
+
+@item @code{t}
+This element of @var{spec} matches all frames.  Therefore, any
+subsequent elements of @var{spec} are never used.  Normally
+@code{t} is used in the last (or only) element of @var{spec}.
+
+@item a list
+If @var{display} is a list, each element should have the form
+@code{(@var{characteristic} @var{value}@dots{})}.  Here
+@var{characteristic} specifies a way of classifying frames, and the
+@var{value}s are possible classifications which @var{display} should
+apply to.  Here are the possible values of @var{characteristic}:
+
+@table @code
+@item type
+The kind of window system the frame uses---either @code{graphic} (any
+graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
+@code{w32} (for MS Windows 9X/NT/2K/XP), @code{mac} (for the Macintosh
+display), or @code{tty} (a non-graphics-capable display).
+@xref{Window Systems, window-system}.
+
+@item class
+What kinds of colors the frame supports---either @code{color},
+@code{grayscale}, or @code{mono}.
+
+@item background
+The kind of background---either @code{light} or @code{dark}.
+
+@item min-colors
+An integer that represents the minimum number of colors the frame
+should support.  This matches a frame if its
+@code{display-color-cells} value is at least the specified integer.
+
+@item supports
+Whether or not the frame can display the face attributes given in
+@var{value}@dots{} (@pxref{Face Attributes}).  See the documentation
+for the function @code{display-supports-face-attributes-p} for more
+information on exactly how this testing is done.  @xref{Display Face
+Attribute Testing}.
+@end table
+
+If an element of @var{display} specifies more than one @var{value} for a
+given @var{characteristic}, any of those values is acceptable.  If
+@var{display} has more than one element, each element should specify a
+different @var{characteristic}; then @emph{each} characteristic of the
+frame must match one of the @var{value}s specified for it in
+@var{display}.
+@end table
+@end defmac
+
+  Here's how the standard face @code{region} is defined:
+
+@example
+@group
+(defface region
+  '((((class color) (min-colors 88) (background dark))
+     :background "blue3")
+@end group
+    (((class color) (min-colors 88) (background light))
+     :background "lightgoldenrod2")
+    (((class color) (min-colors 16) (background dark))
+     :background "blue3")
+    (((class color) (min-colors 16) (background light))
+     :background "lightgoldenrod2")
+    (((class color) (min-colors 8))
+     :background "blue" :foreground "white")
+    (((type tty) (class mono))
+     :inverse-video t)
+    (t :background "gray"))
+@group
+  "Basic face for highlighting the region."
+  :group 'basic-faces)
+@end group
+@end example
+
+  Internally, @code{defface} uses the symbol property
+@code{face-defface-spec} to record the face attributes specified in
+@code{defface}, @code{saved-face} for the attributes saved by the user
+with the customization buffer, @code{customized-face} for the
+attributes customized by the user for the current session, but not
+saved, and @code{face-documentation} for the documentation string.
+
+@defopt frame-background-mode
+This option, if non-@code{nil}, specifies the background type to use for
+interpreting face definitions.  If it is @code{dark}, then Emacs treats
+all frames as if they had a dark background, regardless of their actual
+background colors.  If it is @code{light}, then Emacs treats all frames
+as if they had a light background.
+@end defopt
+
+@node Face Attributes
+@subsection Face Attributes
+@cindex face attributes
+
+  The effect of using a face is determined by a fixed set of @dfn{face
+attributes}.  This table lists all the face attributes, and what they
+mean.  You can specify more than one face for a given piece of text;
+Emacs merges the attributes of all the faces to determine how to
+display the text.  @xref{Displaying Faces}.
+
+  Any attribute in a face can have the value @code{unspecified}.  This
+means the face doesn't specify that attribute.  In face merging, when
+the first face fails to specify a particular attribute, that means the
+next face gets a chance.  However, the @code{default} face must
+specify all attributes.
+
+  Some of these font attributes are meaningful only on certain kinds of
+displays---if your display cannot handle a certain attribute, the
+attribute is ignored.  (The attributes @code{:family}, @code{:width},
+@code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
+an X Logical Font Descriptor.)
+
+@table @code
+@item :family
+Font family name, or fontset name (@pxref{Fontsets}).  If you specify a
+font family name, the wild-card characters @samp{*} and @samp{?} are
+allowed.
+
+@item :width
+Relative proportionate width, also known as the character set width or
+set width.  This should be one of the symbols @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}.
+
+@item :height
+Either the font height, an integer in units of 1/10 point, a floating
+point number specifying the amount by which to scale the height of any
+underlying face, or a function, which is called with the old height
+(from the underlying face), and should return the new height.
+
+@item :weight
+Font weight---a symbol from this series (from most dense to most faint):
+@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
+@code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
+or @code{ultra-light}.
+
+On a text-only terminal, any weight greater than normal is displayed as
+extra bright, and any weight less than normal is displayed as
+half-bright (provided the terminal supports the feature).
+
+@item :slant
+Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
+@code{reverse-italic}, or @code{reverse-oblique}.
+
+On a text-only terminal, slanted text is displayed as half-bright, if
+the terminal supports the feature.
+
+@item :foreground
+Foreground color, a string.  The value can be a system-defined color
+name, 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.)
+
+@item :background
+Background color, a string, like the foreground color.
+
+@item :inverse-video
+Whether or not characters should be displayed in inverse video.  The
+value should be @code{t} (yes) or @code{nil} (no).
+
+@item :stipple
+The background stipple, a bitmap.
+
+The value can be a string; that should be the name of a file containing
+external-format X bitmap data.  The file is found in the directories
+listed in the variable @code{x-bitmap-file-path}.
+
+Alternatively, the value can specify the bitmap directly, with a list
+of the form @code{(@var{width} @var{height} @var{data})}.  Here,
+@var{width} and @var{height} specify the size in pixels, and
+@var{data} is a string containing the raw bits of the bitmap, row by
+row.  Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
+in the string (which should be a unibyte string for best results).
+This means that each row always occupies at least one whole byte.
+
+If the value is @code{nil}, that means use no stipple pattern.
+
+Normally you do not need to set the stipple attribute, because it is
+used automatically to handle certain shades of gray.
+
+@item :underline
+Whether or not characters should be underlined, and in what color.  If
+the value is @code{t}, underlining uses the foreground color of the
+face.  If the value is a string, underlining uses that color.  The
+value @code{nil} means do not underline.
+
+@item :overline
+Whether or not characters should be overlined, and in what color.
+The value is used like that of @code{:underline}.
+
+@item :strike-through
+Whether or not characters should be strike-through, and in what
+color.  The value is used like that of @code{:underline}.
+
+@item :inherit
+The name of a face from which to inherit attributes, or a list of face
+names.  Attributes from inherited faces are merged into the face like an
+underlying face would be, with higher priority than underlying faces.
+If a list of faces is used, attributes from faces earlier in the list
+override those from later faces.
+
+@item :box
+Whether or not a box should be drawn around characters, its color, the
+width of the box lines, and 3D appearance.
+@end table
+
+  Here are the possible values of the @code{:box} attribute, and what
+they mean:
+
+@table @asis
+@item @code{nil}
+Don't draw a box.
+
+@item @code{t}
+Draw a box with lines of width 1, in the foreground color.
+
+@item @var{color}
+Draw a box with lines of width 1, in color @var{color}.
+
+@item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
+This way you can explicitly specify all aspects of the box.  The value
+@var{width} specifies the width of the lines to draw; it defaults to 1.
+
+The value @var{color} specifies the color to draw with.  The default is
+the foreground color of the face for simple boxes, and the background
+color of the face for 3D boxes.
+
+The value @var{style} specifies whether to draw a 3D box.  If it is
+@code{released-button}, the box looks like a 3D button that is not being
+pressed.  If it is @code{pressed-button}, the box looks like a 3D button
+that is being pressed.  If it is @code{nil} or omitted, a plain 2D box
+is used.
+@end table
+
+  In older versions of Emacs, before @code{:family}, @code{:height},
+@code{:width}, @code{:weight}, and @code{:slant} existed, these
+attributes were used to specify the type face.  They are now
+semi-obsolete, but they still work:
+
+@table @code
+@item :font
+This attribute specifies the font name.
+
+@item :bold
+A non-@code{nil} value specifies a bold font.
+
+@item :italic
+A non-@code{nil} value specifies an italic font.
+@end table
+
+  For compatibility, you can still set these ``attributes,'' even
+though they are not real face attributes.  Here is what that does:
+
+@table @code
+@item :font
+You can specify an X font name as the ``value'' of this ``attribute'';
+that sets the @code{:family}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} attributes according to the font name.
+
+If the value is a pattern with wildcards, the first font that matches
+the pattern is used to set these attributes.
+
+@item :bold
+A non-@code{nil} makes the face bold; @code{nil} makes it normal.
+This actually works by setting the @code{:weight} attribute.
+
+@item :italic
+A non-@code{nil} makes the face italic; @code{nil} makes it normal.
+This actually works by setting the @code{:slant} attribute.
+@end table
+
+@defvar x-bitmap-file-path
+This variable specifies a list of directories for searching
+for bitmap files, for the @code{:stipple} attribute.
+@end defvar
+
+@defun bitmap-spec-p object
+This returns @code{t} if @var{object} is a valid bitmap specification,
+suitable for use with @code{:stipple} (see above).  It returns
+@code{nil} otherwise.
+@end defun
+
+@node Attribute Functions
+@subsection Face Attribute Functions
+
+  This section describes the functions for accessing and modifying the
+attributes of an existing face.
+
+@defun set-face-attribute face frame &rest arguments
+This function sets one or more attributes of face @var{face} for frame
+@var{frame}.  The attributes you specify this way override whatever
+the @code{defface} says.
+
+The extra arguments @var{arguments} specify the attributes to set, and
+the values for them.  They should consist of alternating attribute names
+(such as @code{:family} or @code{:underline}) and corresponding values.
+Thus,
+
+@example
+(set-face-attribute 'foo nil
+                    :width 'extended
+                    :weight 'bold
+                    :underline "red")
+@end example
+
+@noindent
+sets the attributes @code{:width}, @code{:weight} and @code{:underline}
+to the corresponding values.
+
+If @var{frame} is @code{t}, this function sets the default attributes
+for new frames.  Default attribute values specified this way override
+the @code{defface} for newly created frames.
+
+If @var{frame} is @code{nil}, this function sets the attributes for
+all existing frames, and the default for new frames.
+@end defun
+
+@defun face-attribute face attribute &optional frame inherit
+This returns the value of the @var{attribute} attribute of face
+@var{face} on @var{frame}.  If @var{frame} is @code{nil},
+that means the selected frame (@pxref{Input Focus}).
+
+If @var{frame} is @code{t}, this returns whatever new-frames default
+value you previously specified with @code{set-face-attribute} for the
+@var{attribute} attribute of @var{face}.  If you have not specified
+one, it returns @code{nil}.
+
+If @var{inherit} is @code{nil}, only attributes directly defined by
+@var{face} are considered, so the return value may be
+@code{unspecified}, or a relative value.  If @var{inherit} is
+non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
+with the faces specified by its @code{:inherit} attribute; however the
+return value may still be @code{unspecified} or relative.  If
+@var{inherit} is a face or a list of faces, then the result is further
+merged with that face (or faces), until it becomes specified and
+absolute.
+
+To ensure that the return value is always specified and absolute, use
+a value of @code{default} for @var{inherit}; this will resolve any
+unspecified or relative values by merging with the @code{default} face
+(which is always completely specified).
+
+For example,
+
+@example
+(face-attribute 'bold :weight)
+     @result{} bold
+@end example
+@end defun
+
+@defun face-attribute-relative-p attribute value
+This function returns non-@code{nil} if @var{value}, when used as the
+value of the face attribute @var{attribute}, is relative.  This means
+it would modify, rather than completely override, any value that comes
+from a subsequent face in the face list or that is inherited from
+another face.
+
+@code{unspecified} is a relative value for all attributes.
+For @code{:height}, floating point values are also relative.
+
+For example:
+
+@example
+(face-attribute-relative-p :height 2.0)
+     @result{} t
+@end example
+@end defun
+
+@defun merge-face-attribute attribute value1 value2
+If @var{value1} is a relative value for the face attribute
+@var{attribute}, returns it merged with the underlying value
+@var{value2}; otherwise, if @var{value1} is an absolute value for the
+face attribute @var{attribute}, returns @var{value1} unchanged.
+@end defun
+
+  The functions above did not exist before Emacs 21.  For compatibility
+with older Emacs versions, you can use the following functions to set
+and examine the face attributes which existed in those versions.
+They use values of @code{t} and @code{nil} for @var{frame}
+just like @code{set-face-attribute} and @code{face-attribute}.
+
+@defun set-face-foreground face color &optional frame
+@defunx set-face-background face color &optional frame
+These functions set the foreground (or background, respectively) color
+of face @var{face} to @var{color}.  The argument @var{color} should be a
+string, the name of a color.
+
+Certain shades of gray are implemented by stipple patterns on
+black-and-white screens.
+@end defun
+
+@defun set-face-stipple face pattern &optional frame
+This function sets the background stipple pattern of face @var{face}
+to @var{pattern}.  The argument @var{pattern} should be the name of a
+stipple pattern defined by the X server, or actual bitmap data
+(@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
+
+Normally there is no need to pay attention to stipple patterns, because
+they are used automatically to handle certain shades of gray.
+@end defun
+
+@defun set-face-font face font &optional frame
+This function sets the font of face @var{face}.  This actually sets
+the attributes @code{:family}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} according to the font name
+@var{font}.
+@end defun
+
+@defun set-face-bold-p face bold-p &optional frame
+This function specifies whether @var{face} should be bold.  If
+@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
+This actually sets the @code{:weight} attribute.
+@end defun
+
+@defun set-face-italic-p face italic-p &optional frame
+This function specifies whether @var{face} should be italic.  If
+@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
+This actually sets the @code{:slant} attribute.
+@end defun
+
+@defun set-face-underline-p face underline &optional frame
+This function sets the underline attribute of face @var{face}.
+Non-@code{nil} means do underline; @code{nil} means don't.
+If @var{underline} is a string, underline with that color.
+@end defun
+
+@defun set-face-inverse-video-p face inverse-video-p &optional frame
+This function sets the @code{:inverse-video} attribute of face
+@var{face}.
+@end defun
+
+@defun invert-face face &optional frame
+This function swaps the foreground and background colors of face
+@var{face}.
+@end defun
+
+  These functions examine the attributes of a face.  If you don't
+specify @var{frame}, they refer to the selected frame; @code{t} refers
+to the default data for new frames.  They return the symbol
+@code{unspecified} if the face doesn't define any value for that
+attribute.
+
+@defun face-foreground face &optional frame inherit
+@defunx face-background face &optional frame inherit
+These functions return the foreground color (or background color,
+respectively) of face @var{face}, as a string.
+
+If @var{inherit} is @code{nil}, only a color directly defined by the face is
+returned.  If @var{inherit} is non-@code{nil}, any faces specified by its
+@code{:inherit} attribute are considered as well, and if @var{inherit}
+is a face or a list of faces, then they are also considered, until a
+specified color is found.  To ensure that the return value is always
+specified, use a value of @code{default} for @var{inherit}.
+@end defun
+
+@defun face-stipple face &optional frame inherit
+This function returns the name of the background stipple pattern of face
+@var{face}, or @code{nil} if it doesn't have one.
+
+If @var{inherit} is @code{nil}, only a stipple directly defined by the
+face is returned.  If @var{inherit} is non-@code{nil}, any faces
+specified by its @code{:inherit} attribute are considered as well, and
+if @var{inherit} is a face or a list of faces, then they are also
+considered, until a specified stipple is found.  To ensure that the
+return value is always specified, use a value of @code{default} for
+@var{inherit}.
+@end defun
+
+@defun face-font face &optional frame
+This function returns the name of the font of face @var{face}.
+@end defun
+
+@defun face-bold-p face &optional frame
+This function returns @code{t} if @var{face} is bold---that is, if it is
+bolder than normal.  It returns @code{nil} otherwise.
+@end defun
+
+@defun face-italic-p face &optional frame
+This function returns @code{t} if @var{face} is italic or oblique,
+@code{nil} otherwise.
+@end defun
+
+@defun face-underline-p face &optional frame
+This function returns the @code{:underline} attribute of face @var{face}.
+@end defun
+
+@defun face-inverse-video-p face &optional frame
+This function returns the @code{:inverse-video} attribute of face @var{face}.
+@end defun
+
+@node Displaying Faces
+@subsection Displaying Faces
+
+  Here are the ways to specify which faces to use for display of text:
+
+@itemize @bullet
+@item
+With defaults.  The @code{default} face is used as the ultimate
+default for all text.  (In Emacs 19 and 20, the @code{default}
+face is used only when no other face is specified.)
+
+@item
+For a mode line or header line, the face @code{mode-line} or
+@code{mode-line-inactive}, or @code{header-line}, is merged in just
+before @code{default}.
+
+@item
+With text properties.  A character can have a @code{face} property; if
+so, the faces and face attributes specified there apply.  @xref{Special
+Properties}.
+
+If the character has a @code{mouse-face} property, that is used instead
+of the @code{face} property when the mouse is ``near enough'' to the
+character.
+
+@item
+With overlays.  An overlay can have @code{face} and @code{mouse-face}
+properties too; they apply to all the text covered by the overlay.
+
+@item
+With a region that is active.  In Transient Mark mode, the region is
+highlighted with the face @code{region} (@pxref{Standard Faces,,,
+emacs, The GNU Emacs Manual}).
+
+@item
+With special glyphs.  Each glyph can specify a particular face
+number.  @xref{Glyphs}.
+@end itemize
+
+  If these various sources together specify more than one face for a
+particular character, Emacs merges the attributes of the various faces
+specified.  For each attribute, Emacs tries first the face of any
+special glyph; then the face for region highlighting, if appropriate;
+then the faces specified by overlays, followed by those specified by
+text properties, then the @code{mode-line} or
+@code{mode-line-inactive} or @code{header-line} face (if in a mode
+line or a header line), and last the @code{default} face.
+
+  When multiple overlays cover one character, an overlay with higher
+priority overrides those with lower priority.  @xref{Overlays}.
+
+@node Font Selection
+@subsection Font Selection
+
+  @dfn{Selecting a font} means mapping the specified face attributes for
+a character to a font that is available on a particular display.  The
+face attributes, as determined by face merging, specify most of the
+font choice, but not all.  Part of the choice depends on what character
+it is.
+
+  If the face specifies a fontset name, that fontset determines a
+pattern for fonts of the given charset.  If the face specifies a font
+family, a font pattern is constructed.
+
+  Emacs tries to find an available font for the given face attributes
+and character's registry and encoding.  If there is a font that matches
+exactly, it is used, of course.  The hard case is when no available font
+exactly fits the specification.  Then Emacs looks for one that is
+``close''---one attribute at a time.  You can specify the order to
+consider the attributes.  In the case where a specified font family is
+not available, you can specify a set of mappings for alternatives to
+try.
+
+@defvar face-font-selection-order
+This variable specifies the order of importance of the face attributes
+@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}.  The
+value should be a list containing those four symbols, in order of
+decreasing importance.
+
+Font selection first finds the best available matches for the first
+attribute listed; then, among the fonts which are best in that way, it
+searches for the best matches in the second attribute, and so on.
+
+The attributes @code{:weight} and @code{:width} have symbolic values in
+a range centered around @code{normal}.  Matches that are more extreme
+(farther from @code{normal}) are somewhat preferred to matches that are
+less extreme (closer to @code{normal}); this is designed to ensure that
+non-normal faces contrast with normal ones, whenever possible.
+
+The default is @code{(:width :height :weight :slant)}, which means first
+find the fonts closest to the specified @code{:width}, then---among the
+fonts with that width---find a best match for the specified font height,
+and so on.
+
+One example of a case where this variable makes a difference is when the
+default font has no italic equivalent.  With the default ordering, the
+@code{italic} face will use a non-italic font that is similar to the
+default one.  But if you put @code{:slant} before @code{:height}, the
+@code{italic} face will use an italic font, even if its height is not
+quite right.
+@end defvar
+
+@defvar face-font-family-alternatives
+This variable lets you specify alternative font families to try, if a
+given family is specified and doesn't exist.  Each element should have
+this form:
+
+@example
+(@var{family} @var{alternate-families}@dots{})
+@end example
+
+If @var{family} is specified but not available, Emacs will try the other
+families given in @var{alternate-families}, one by one, until it finds a
+family that does exist.
+@end defvar
+
+@defvar face-font-registry-alternatives
+This variable lets you specify alternative font registries to try, if a
+given registry is specified and doesn't exist.  Each element should have
+this form:
+
+@example
+(@var{registry} @var{alternate-registries}@dots{})
+@end example
+
+If @var{registry} is specified but not available, Emacs will try the
+other registries given in @var{alternate-registries}, one by one,
+until it finds a registry that does exist.
+@end defvar
+
+  Emacs can make use of scalable fonts, but by default it does not use
+them, since the use of too many or too big scalable fonts can crash
+XFree86 servers.
+
+@defvar scalable-fonts-allowed
+This variable controls which scalable fonts to use.  A value of
+@code{nil}, the default, means do not use scalable fonts.  @code{t}
+means to use any scalable font that seems appropriate for the text.
+
+Otherwise, the value must be a list of regular expressions.  Then a
+scalable font is enabled for use if its name matches any regular
+expression in the list.  For example,
+
+@example
+(setq scalable-fonts-allowed '("muleindian-2$"))
+@end example
+
+@noindent
+allows the use of scalable fonts with registry @code{muleindian-2}.
+@end defvar
+
+@defvar face-font-rescale-alist
+This variable specifies scaling for certain faces.  Its value should
+be a list of elements of the form
+
+@example
+(@var{fontname-regexp} . @var{scale-factor})
+@end example
+
+If @var{fontname-regexp} matches the font name that is about to be
+used, this says to choose a larger similar font according to the
+factor @var{scale-factor}.  You would use this feature to normalize
+the font size if certain fonts are bigger or smaller than their
+nominal heights and widths would suggest.
+@end defvar
+
+@node Face Functions
+@subsection Functions for Working with Faces
+
+  Here are additional functions for creating and working with faces.
+
+@defun make-face name
+This function defines a new face named @var{name}, initially with all
+attributes @code{nil}.  It does nothing if there is already a face named
+@var{name}.
+@end defun
+
+@defun face-list
+This function returns a list of all defined face names.
+@end defun
+
+@defun copy-face old-face new-name &optional frame new-frame
+This function defines a face named @var{new-name} as a copy of the existing
+face named @var{old-face}.  It creates the face @var{new-name} if that
+doesn't already exist.
+
+If the optional argument @var{frame} is given, this function applies
+only to that frame.  Otherwise it applies to each frame individually,
+copying attributes from @var{old-face} in each frame to @var{new-face}
+in the same frame.
+
+If the optional argument @var{new-frame} is given, then @code{copy-face}
+copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
+in @var{new-frame}.
+@end defun
+
+@defun face-id face
+This function returns the face number of face @var{face}.
+@end defun
+
+@defun face-documentation face
+This function returns the documentation string of face @var{face}, or
+@code{nil} if none was specified for it.
+@end defun
+
+@defun face-equal face1 face2 &optional frame
+This returns @code{t} if the faces @var{face1} and @var{face2} have the
+same attributes for display.
+@end defun
+
+@defun face-differs-from-default-p face &optional frame
+This returns non-@code{nil} if the face @var{face} displays
+differently from the default face.
+@end defun
+
+@cindex face alias
+A @dfn{face alias} provides an equivalent name for a face.  You can
+define a face alias by giving the alias symbol the @code{face-alias}
+property, with a value of the target face name.  The following example
+makes @code{modeline} an alias for the @code{mode-line} face.
+
+@example
+(put 'modeline 'face-alias 'mode-line)
+@end example
+
+
+@node Auto Faces
+@subsection Automatic Face Assignment
+@cindex automatic face assignment
+@cindex faces, automatic choice
+
+  This hook is used for automatically assigning facesto text in the
+buffer.  It is part of the implementation of Jit-Lock mode, used by
+Font-Lock.
+
+@defvar fontification-functions
+This variable holds a list of functions that are called by Emacs
+redisplay as needed to assign faces automatically to text in the buffer.
+
+The functions are called in the order listed, with one argument, a
+buffer position @var{pos}.  Each function should attempt to assign faces
+to the text in the current buffer starting at @var{pos}.
+
+Each function should record the faces they assign by setting the
+@code{face} property.  It should also add a non-@code{nil}
+@code{fontified} property for all the text it has assigned faces to.
+That property tells redisplay that faces have been assigned to that text
+already.
+
+It is probably a good idea for each function to do nothing if the
+character after @var{pos} already has a non-@code{nil} @code{fontified}
+property, but this is not required.  If one function overrides the
+assignments made by a previous one, the properties as they are
+after the last function finishes are the ones that really matter.
+
+For efficiency, we recommend writing these functions so that they
+usually assign faces to around 400 to 600 characters at each call.
+@end defvar
+
+@node Font Lookup
+@subsection Looking Up Fonts
+
+@defun x-list-fonts pattern &optional face frame maximum
+This function returns a list of available font names that match
+@var{pattern}.  If the optional arguments @var{face} and @var{frame} are
+specified, then the list is limited to fonts that are the same size as
+@var{face} currently is on @var{frame}.
+
+The argument @var{pattern} should be a string, perhaps with wildcard
+characters: the @samp{*} character matches any substring, and the
+@samp{?} character matches any single character.  Pattern matching
+of font names ignores case.
+
+If you specify @var{face} and @var{frame}, @var{face} should be a face name
+(a symbol) and @var{frame} should be a frame.
+
+The optional argument @var{maximum} sets a limit on how many fonts to
+return.  If this is non-@code{nil}, then the return value is truncated
+after the first @var{maximum} matching fonts.  Specifying a small value
+for @var{maximum} can make this function much faster, in cases where
+many fonts match the pattern.
+@end defun
+
+@defun x-family-fonts &optional family frame
+This function returns a list describing the available fonts for family
+@var{family} on @var{frame}.  If @var{family} is omitted or @code{nil},
+this list applies to all families, and therefore, it contains all
+available fonts.  Otherwise, @var{family} must be a string; it may
+contain the wildcards @samp{?} and @samp{*}.
+
+The list describes the display that @var{frame} is on; if @var{frame} is
+omitted or @code{nil}, it applies to the selected frame's display
+(@pxref{Input Focus}).
+
+The list contains a vector of the following form for each font:
+
+@example
+[@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
+ @var{fixed-p} @var{full} @var{registry-and-encoding}]
+@end example
+
+The first five elements correspond to face attributes; if you
+specify these attributes for a face, it will use this font.
+
+The last three elements give additional information about the font.
+@var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
+@var{full} is the full name of the font, and
+@var{registry-and-encoding} is a string giving the registry and
+encoding of the font.
+
+The result list is sorted according to the current face font sort order.
+@end defun
+
+@defun x-font-family-list &optional frame
+This function returns a list of the font families available for
+@var{frame}'s display.  If @var{frame} is omitted or @code{nil}, it
+describes the selected frame's display (@pxref{Input Focus}).
+
+The value is a list of elements of this form:
+
+@example
+(@var{family} . @var{fixed-p})
+@end example
+
+@noindent
+Here @var{family} is a font family, and @var{fixed-p} is
+non-@code{nil} if fonts of that family are fixed-pitch.
+@end defun
+
+@defvar font-list-limit
+This variable specifies maximum number of fonts to consider in font
+matching.  The function @code{x-family-fonts} will not return more than
+that many fonts, and font selection will consider only that many fonts
+when searching a matching font for face attributes.  The default is
+currently 100.
+@end defvar
+
+@node Fontsets
+@subsection Fontsets
+
+  A @dfn{fontset} is a list of fonts, each assigned to a range of
+character codes.  An individual font cannot display the whole range of
+characters that Emacs supports, but a fontset can.  Fontsets have names,
+just as fonts do, and you can use a fontset name in place of a font name
+when you specify the ``font'' for a frame or a face.  Here is
+information about defining a fontset under Lisp program control.
+
+@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
+This function defines a new fontset according to the specification
+string @var{fontset-spec}.  The string should have this format:
+
+@smallexample
+@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
+@end smallexample
+
+@noindent
+Whitespace characters before and after the commas are ignored.
+
+The first part of the string, @var{fontpattern}, should have the form of
+a standard X font name, except that the last two fields should be
+@samp{fontset-@var{alias}}.
+
+The new fontset has two names, one long and one short.  The long name is
+@var{fontpattern} in its entirety.  The short name is
+@samp{fontset-@var{alias}}.  You can refer to the fontset by either
+name.  If a fontset with the same name already exists, an error is
+signaled, unless @var{noerror} is non-@code{nil}, in which case this
+function does nothing.
+
+If optional argument @var{style-variant-p} is non-@code{nil}, that says
+to create bold, italic and bold-italic variants of the fontset as well.
+These variant fontsets do not have a short name, only a long one, which
+is made by altering @var{fontpattern} to indicate the bold or italic
+status.
+
+The specification string also says which fonts to use in the fontset.
+See below for the details.
+@end defun
+
+  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 the specification string.
+
+  For the remaining character sets, those that you don't specify
+explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
+@samp{fontset-@var{alias}} with a value that names one character set.
+For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
+with @samp{ISO8859-1}.
+
+  In addition, when several consecutive fields are wildcards, Emacs
+collapses them into a single wildcard.  This is to prevent use of
+auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
+for editing, and scaling a smaller font is not useful because it is
+better to use the smaller font in its own size, which Emacs does.
+
+  Thus if @var{fontpattern} is this,
+
+@example
+-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
+@end example
+
+@noindent
+the font specification for @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 the @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.
+
+@defun set-fontset-font name character fontname &optional frame
+This function modifies the existing fontset @var{name} to
+use the font name @var{fontname} for the character @var{character}.
+
+If @var{name} is @code{nil}, this function modifies the default
+fontset, whose short name is @samp{fontset-default}.
+
+@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
+@var{from} and @var{to} are non-generic characters.  In that case, use
+@var{fontname} for all characters in the range @var{from} and @var{to}
+(inclusive).
+
+@var{character} may be a charset.  In that case, use
+@var{fontname} for all character in the charsets.
+
+@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
+where @var{family} is a family name of a font (possibly including a
+foundry name at the head), @var{registry} is a registry name of a font
+(possibly including an encoding name at the tail).
+
+For instance, this changes the default fontset to use a font of which
+registry name is @samp{JISX0208.1983} for all characters belonging to
+the charset @code{japanese-jisx0208}.
+
+@smallexample
+(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
+@end smallexample
+@end defun
+
+@defun char-displayable-p char
+This function returns @code{t} if Emacs ought to be able to display
+@var{char}.  More precisely, if the selected frame's fontset has a
+font to display the character set that @var{char} belongs to.
+
+Fontsets can specify a font on a per-character basis; when the fontset
+does that, this function's value may not be accurate.
+@end defun
+
+@node Fringes
+@section Fringes
+@cindex fringes
+
+  The @dfn{fringes} of a window are thin vertical strips down the
+sides that are used for displaying bitmaps that indicate truncation,
+continuation, horizontal scrolling, and the overlay arrow.
+
+@menu
+* Fringe Size/Pos::     Specifying where to put the window fringes.
+* Fringe Indicators::   Displaying indicator icons in the window fringes.
+* Fringe Cursors::      Displaying cursors in the right fringe.
+* Fringe Bitmaps::      Specifying bitmaps for fringe indicators.
+* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
+* Overlay Arrow::       Display of an arrow to indicate position.
+@end menu
+
+@node Fringe Size/Pos
+@subsection Fringe Size and Position
+
+  The following buffer-local variables control the position and width
+of the window fringes.
+
+@defvar fringes-outside-margins
+The fringes normally appear between the display margins and the window
+text.  If the value is non-@code{nil}, they appear outside the display
+margins.  @xref{Display Margins}.
+@end defvar
+
+@defvar left-fringe-width
+This variable, if non-@code{nil}, specifies the width of the left
+fringe in pixels.  A value of @code{nil} means to use the left fringe
+width from the window's frame.
+@end defvar
+
+@defvar right-fringe-width
+This variable, if non-@code{nil}, specifies the width of the right
+fringe in pixels.  A value of @code{nil} means to use the right fringe
+width from the window's frame.
+@end defvar
+
+  The values of these variables take effect when you display the
+buffer in a window.  If you change them while the buffer is visible,
+you can call @code{set-window-buffer} to display it once again in the
+same window, to make the changes take effect.
+
+@defun set-window-fringes window left &optional right outside-margins
+This function sets the fringe widths of window @var{window}.
+If @var{window} is @code{nil}, the selected window is used.
+
+The argument @var{left} specifies the width in pixels of the left
+fringe, and likewise @var{right} for the right fringe.  A value of
+@code{nil} for either one stands for the default width.  If
+@var{outside-margins} is non-@code{nil}, that specifies that fringes
+should appear outside of the display margins.
+@end defun
+
+@defun window-fringes &optional window
+This function returns information about the fringes of a window
+@var{window}.  If @var{window} is omitted or @code{nil}, the selected
+window is used.  The value has the form @code{(@var{left-width}
+@var{right-width} @var{outside-margins})}.
+@end defun
+
+
+@node Fringe Indicators
+@subsection Fringe Indicators
+@cindex fringe indicators
+@cindex indicators, fringe
+
+  The @dfn{fringe indicators} are tiny icons Emacs displays in the
+window fringe (on a graphic display) to indicate truncated or
+continued lines, buffer boundaries, overlay arrow, etc.
+
+@defopt indicate-empty-lines
+@cindex fringes, and empty line indication
+When this is non-@code{nil}, Emacs displays a special glyph in the
+fringe of each empty line at the end of the buffer, on graphical
+displays.  @xref{Fringes}.  This variable is automatically
+buffer-local in every buffer.
+@end defopt
+
+@defvar indicate-buffer-boundaries
+This buffer-local variable controls how the buffer boundaries and
+window scrolling are indicated in the window fringes.
+
+Emacs can indicate the buffer boundaries---that is, the first and last
+line in the buffer---with angle icons when they appear on the screen.
+In addition, Emacs can display an up-arrow in the fringe to show
+that there is text above the screen, and a down-arrow to show
+there is text below the screen.
+
+There are three kinds of basic values:
+
+@table @asis
+@item @code{nil}
+Don't display any of these fringe icons.
+@item @code{left}
+Display the angle icons and arrows in the left fringe.
+@item @code{right}
+Display the angle icons and arrows in the right fringe.
+@item any non-alist
+Display the angle icons in the left fringe
+and don't display the arrows.
+@end table
+
+Otherwise the value should be an alist that specifies which fringe
+indicators to display and where.  Each element of the alist should
+have the form @code{(@var{indicator} . @var{position})}.  Here,
+@var{indicator} is one of @code{top}, @code{bottom}, @code{up},
+@code{down}, and @code{t} (which covers all the icons not yet
+specified), while @var{position} is one of @code{left}, @code{right}
+and @code{nil}.
+
+For example, @code{((top . left) (t . right))} places the top angle
+bitmap in left fringe, and the bottom angle bitmap as well as both
+arrow bitmaps in right fringe.  To show the angle bitmaps in the left
+fringe, and no arrow bitmaps, use @code{((top .  left) (bottom . left))}.
+@end defvar
+
+@defvar default-indicate-buffer-boundaries
+The value of this variable is the default value for
+@code{indicate-buffer-boundaries} in buffers that do not override it.
+@end defvar
+
+@defvar fringe-indicator-alist
+This buffer-local variable specifies the mapping from logical fringe
+indicators to the actual bitmaps displayed in the window fringes.
+
+These symbols identify the logical fringe indicators:
+
+@table @asis
+@item Truncation and continuation line indicators:
+@code{truncation}, @code{continuation}.
+
+@item Buffer position indicators:
+@code{up}, @code{down},
+@code{top}, @code{bottom},
+@code{top-bottom}.
+
+@item Empty line indicator:
+@code{empty-line}.
+
+@item Overlay arrow indicator:
+@code{overlay-arrow}.
+
+@item Unknown bitmap indicator:
+@code{unknown}.
+@end table
+
+  The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})}
+specifies the fringe bitmaps used to display a specific logical
+fringe indicator.
+
+Here, @var{indicator} specifies the logical indicator type, and
+@var{bitmaps} is list of symbols @code{(@var{left} @var{right}
+[@var{left1} @var{right1}])} which specifies the actual bitmap shown
+in the left or right fringe for the logical indicator.
+
+The @var{left} and @var{right} symbols specify the bitmaps shown in
+the left and/or right fringe for the specific indicator.  The
+@var{left1} or @var{right1} bitmaps are used only for the `bottom' and
+`top-bottom indicators when the last (only) line in has no final
+newline.  Alternatively, @var{bitmaps} may be a single symbol which is
+used in both left and right fringes.
+
+When @code{fringe-indicator-alist} has a buffer-local value, and there
+is no bitmap defined for a logical indicator, or the bitmap is
+@code{t}, the corresponding value from the (non-local)
+@code{default-fringe-indicator-alist} is used.
+
+To completely hide a specific indicator, set the bitmap to @code{nil}.
+@end defvar
+
+@defvar default-fringe-indicator-alist
+The value of this variable is the default value for
+@code{fringe-indicator-alist} in buffers that do not override it.
+@end defvar
+
+Standard fringe bitmaps for indicators:
+@example
+left-arrow right-arrow up-arrow down-arrow
+left-curly-arrow right-curly-arrow
+left-triangle right-triangle
+top-left-angle top-right-angle
+bottom-left-angle bottom-right-angle
+left-bracket right-bracket
+filled-rectangle hollow-rectangle
+filled-square hollow-square
+vertical-bar horizontal-bar
+empty-line question-mark
+@end example
+
+@node Fringe Cursors
+@subsection Fringe Cursors
+@cindex fringe cursors
+@cindex cursor, fringe
+
+  When a line is exactly as wide as the window, Emacs displays the
+cursor in the right fringe instead of using two lines.  Different
+bitmaps are used to represent the cursor in the fringe depending on
+the current buffer's cursor type.
+
+@table @asis
+@item Logical cursor types:
+@code{box} , @code{hollow}, @code{bar},
+@code{hbar}, @code{hollow-small}.
+@end table
+
+The @code{hollow-small} type is used instead of @code{hollow} when the
+normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
+display line.
+
+@defvar overflow-newline-into-fringe
+If this is non-@code{nil}, lines exactly as wide as the window (not
+counting the final newline character) are not continued.  Instead,
+when point is at the end of the line, the cursor appears in the right
+fringe.
+@end defvar
+
+@defvar fringe-cursor-alist
+This variable specifies the mapping from logical cursor type to the
+actual fringe bitmaps displayed in the right fringe.  The value is an
+alist where each element @code{(@var{cursor} . @var{bitmap})} specifies
+the fringe bitmaps used to display a specific logical cursor type in
+the fringe.  Here, @var{cursor} specifies the logical cursor type and
+@var{bitmap} is a symbol specifying the fringe bitmap to be displayed
+for that logical cursor type.
+
+When @code{fringe-cursor-alist} has a buffer-local value, and there is
+no bitmap defined for a cursor type, the corresponding value from the
+(non-local) @code{default-fringes-indicator-alist} is used.
+@end defvar
+
+@defvar default-fringes-cursor-alist
+The value of this variable is the default value for
+@code{fringe-cursor-alist} in buffers that do not override it.
+@end defvar
+
+Standard bitmaps for displaying the cursor in right fringe:
+@example
+filled-rectangle hollow-rectangle filled-square hollow-square
+vertical-bar horizontal-bar
+@end example
+
+
+@node Fringe Bitmaps
+@subsection Fringe Bitmaps
+@cindex fringe bitmaps
+@cindex bitmaps, fringe
+
+  The @dfn{fringe bitmaps} are the actual bitmaps which represent the
+logical fringe indicators for truncated or continued lines, buffer
+boundaries, overlay arrow, etc.  Fringe bitmap symbols have their own
+name space.  The fringe bitmaps are shared by all frames and windows.
+You can redefine the built-in fringe bitmaps, and you can define new
+fringe bitmaps.
+
+  The way to display a bitmap in the left or right fringes for a given
+line in a window is by specifying the @code{display} property for one
+of the characters that appears in it.  Use a display specification of
+the form @code{(left-fringe @var{bitmap} [@var{face}])} or
+@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
+Property}).  Here, @var{bitmap} is a symbol identifying the bitmap you
+want, and @var{face} (which is optional) is the name of the face whose
+colors should be used for displaying the bitmap, instead of the
+default @code{fringe} face.  @var{face} is automatically merged with
+the @code{fringe} face, so normally @var{face} need only specify the
+foreground color for the bitmap.
+
+@defun fringe-bitmaps-at-pos &optional pos window
+This function returns the fringe bitmaps of the display line
+containing position @var{pos} in window @var{window}.  The return
+value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
+is the symbol for the fringe bitmap in the left fringe (or @code{nil}
+if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
+is non-@code{nil} if there is an overlay arrow in the left fringe.
+
+The value is @code{nil} if @var{pos} is not visible in @var{window}.
+If @var{window} is @code{nil}, that stands for the selected window.
+If @var{pos} is @code{nil}, that stands for the value of point in
+@var{window}.
+@end defun
+
+@node Customizing Bitmaps
+@subsection Customizing Fringe Bitmaps
+
+@defun define-fringe-bitmap bitmap bits &optional height width align
+This function defines the symbol @var{bitmap} as a new fringe bitmap,
+or replaces an existing bitmap with that name.
+
+The argument @var{bits} specifies the image to use.  It should be
+either a string or a vector of integers, where each element (an
+integer) corresponds to one row of the bitmap.  Each bit of an integer
+corresponds to one pixel of the bitmap, where the low bit corresponds
+to the rightmost pixel of the bitmap.
+
+The height is normally the length of @var{bits}.  However, you
+can specify a different height with non-@code{nil} @var{height}.  The width
+is normally 8, but you can specify a different width with non-@code{nil}
+@var{width}.  The width must be an integer between 1 and 16.
+
+The argument @var{align} specifies the positioning of the bitmap
+relative to the range of rows where it is used; the default is to
+center the bitmap.  The allowed values are @code{top}, @code{center},
+or @code{bottom}.
+
+The @var{align} argument may also be a list @code{(@var{align}
+@var{periodic})} where @var{align} is interpreted as described above.
+If @var{periodic} is non-@code{nil}, it specifies that the rows in
+@code{bits} should be repeated enough times to reach the specified
+height.
+@end defun
+
+@defun destroy-fringe-bitmap bitmap
+This function destroy the fringe bitmap identified by @var{bitmap}.
+If @var{bitmap} identifies a standard fringe bitmap, it actually
+restores the standard definition of that bitmap, instead of
+eliminating it entirely.
+@end defun
+
+@defun set-fringe-bitmap-face bitmap &optional face
+This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
+If @var{face} is @code{nil}, it selects the @code{fringe} face.  The
+bitmap's face controls the color to draw it in.
+
+@var{face} is merged with the @code{fringe} face, so normally
+@var{face} should specify only the foreground color.
+@end defun
+
+@node Overlay Arrow
+@subsection The Overlay Arrow
+@c @cindex overlay arrow  Duplicates variable names
+
+  The @dfn{overlay arrow} is useful for directing the user's attention
+to a particular line in a buffer.  For example, in the modes used for
+interface to debuggers, the overlay arrow indicates the line of code
+about to be executed.  This feature has nothing to do with
+@dfn{overlays} (@pxref{Overlays}).
+
+@defvar overlay-arrow-string
+This variable holds the string to display to call attention to a
+particular line, or @code{nil} if the arrow feature is not in use.
+On a graphical display the contents of the string are ignored; instead a
+glyph is displayed in the fringe area to the left of the display area.
+@end defvar
+
+@defvar overlay-arrow-position
+This variable holds a marker that indicates where to display the overlay
+arrow.  It should point at the beginning of a line.  On a non-graphical
+display the arrow text
+appears at the beginning of that line, overlaying any text that would
+otherwise appear.  Since the arrow is usually short, and the line
+usually begins with indentation, normally nothing significant is
+overwritten.
+
+The overlay-arrow string is displayed in any given buffer if the value
+of @code{overlay-arrow-position} in that buffer points into that
+buffer.  Thus, it is possible to display multiple overlay arrow strings
+by creating buffer-local bindings of @code{overlay-arrow-position}.
+However, it is usually cleaner to use
+@code{overlay-arrow-variable-list} to achieve this result.
+@c !!! overlay-arrow-position: but the overlay string may remain in the display
+@c of some other buffer until an update is required.  This should be fixed
+@c now.  Is it?
+@end defvar
+
+  You can do a similar job by creating an overlay with a
+@code{before-string} property.  @xref{Overlay Properties}.
+
+  You can define multiple overlay arrows via the variable
+@code{overlay-arrow-variable-list}.
+
+@defvar overlay-arrow-variable-list
+This variable's value is a list of variables, each of which specifies
+the position of an overlay arrow.  The variable
+@code{overlay-arrow-position} has its normal meaning because it is on
+this list.
+@end defvar
+
+Each variable on this list can have properties
+@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
+specify an overlay arrow string (for text-only terminals) or fringe
+bitmap (for graphical terminals) to display at the corresponding
+overlay arrow position.  If either property is not set, the default
+@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
+is used.
+
+@node Scroll Bars
+@section Scroll Bars
+@cindex scroll bars
+
+Normally the frame parameter @code{vertical-scroll-bars} controls
+whether the windows in the frame have vertical scroll bars, and
+whether they are on the left or right.  The frame parameter
+@code{scroll-bar-width} specifies how wide they are (@code{nil}
+meaning the default).  @xref{Layout Parameters}.
+
+@defun frame-current-scroll-bars &optional frame
+This function reports the scroll bar type settings for frame
+@var{frame}.  The value is a cons cell
+@code{(@var{vertical-type} .@: @var{horizontal-type})}, where
+@var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
+(which means no scroll bar.)  @var{horizontal-type} is meant to
+specify the horizontal scroll bar type, but since they are not
+implemented, it is always @code{nil}.
+@end defun
+
+@vindex vertical-scroll-bar
+  You can enable or disable scroll bars for a particular buffer,
+by setting the variable @code{vertical-scroll-bar}.  This variable
+automatically becomes buffer-local when set.  The possible values are
+@code{left}, @code{right}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+
+  You can also control this for individual windows.  Call the function
+@code{set-window-scroll-bars} to specify what to do for a specific window:
+
+@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
+This function sets the width and type of scroll bars for window
+@var{window}.
+
+@var{width} specifies the scroll bar width in pixels (@code{nil} means
+use the width specified for the frame).  @var{vertical-type} specifies
+whether to have a vertical scroll bar and, if so, where.  The possible
+values are @code{left}, @code{right} and @code{nil}, just like the
+values of the @code{vertical-scroll-bars} frame parameter.
+
+The argument @var{horizontal-type} is meant to specify whether and
+where to have horizontal scroll bars, but since they are not
+implemented, it has no effect.  If @var{window} is @code{nil}, the
+selected window is used.
+@end defun
+
+@defun window-scroll-bars &optional window
+Report the width and type of scroll bars specified for @var{window}.
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a list of the form @code{(@var{width}
+@var{cols} @var{vertical-type} @var{horizontal-type})}.  The value
+@var{width} is the value that was specified for the width (which may
+be @code{nil}); @var{cols} is the number of columns that the scroll
+bar actually occupies.
+
+@var{horizontal-type} is not actually meaningful.
+@end defun
+
+If you don't specify these values for a window with
+@code{set-window-scroll-bars}, the buffer-local variables
+@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
+displayed control the window's vertical scroll bars.  The function
+@code{set-window-buffer} examines these variables.  If you change them
+in a buffer that is already visible in a window, you can make the
+window take note of the new values by calling @code{set-window-buffer}
+specifying the same buffer that is already displayed.
+
+@defvar scroll-bar-mode
+This variable, always local in all buffers, controls whether and where
+to put scroll bars in windows displaying the buffer.  The possible values
+are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
+the left, and @code{right} to put a scroll bar on the right.
+@end defvar
+
+@defun window-current-scroll-bars &optional window
+This function reports the scroll bar type for window @var{window}.
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a cons cell
+@code{(@var{vertical-type} .@: @var{horizontal-type})}.  Unlike
+@code{window-scroll-bars}, this reports the scroll bar type actually
+used, once frame defaults and @code{scroll-bar-mode} are taken into
+account.
+@end defun
+
+@defvar scroll-bar-width
+This variable, always local in all buffers, specifies the width of the
+buffer's scroll bars, measured in pixels.  A value of @code{nil} means
+to use the value specified by the frame.
+@end defvar
+
+@node Display Property
+@section The @code{display} Property
+@cindex display specification
+@kindex display @r{(text property)}
+
+  The @code{display} text property (or overlay property) is used to
+insert images into text, and also control other aspects of how text
+displays.  The value of the @code{display} property should be a
+display specification, or a list or vector containing several display
+specifications.
+
+  Some kinds of @code{display} properties specify something to display
+instead of the text that has the property.  In this case, ``the text''
+means all the consecutive characters that have the same Lisp object as
+their @code{display} property; these characters are replaced as a
+single unit.  By contrast, characters that have similar but distinct
+Lisp objects as their @code{display} properties are handled
+separately.  Here's a function that illustrates this point:
+
+@smallexample
+(defun foo ()
+  (goto-char (point-min))
+  (dotimes (i 5)
+    (let ((string (concat "A")))
+      (put-text-property (point) (1+ (point)) 'display string)
+      (forward-char 1)
+      (put-text-property (point) (1+ (point)) 'display string)
+      (forward-char 1))))
+@end smallexample
+
+@noindent
+It gives each of the first ten characters in the buffer string
+@code{"A"} as the @code{display} property, but they don't all get the
+same string.  The first two characters get the same string, so they
+together are replaced with one @samp{A}.  The next two characters get
+a second string, so they together are replaced with one @samp{A}.
+Likewise for each following pair of characters.  Thus, the ten
+characters appear as five A's.  This function would have the same
+results:
+
+@smallexample
+(defun foo ()
+  (goto-char (point-min))
+  (dotimes (i 5)
+    (let ((string (concat "A")))
+      (put-text-property (point) (2+ (point)) 'display string)
+      (put-text-property (point) (1+ (point)) 'display string)
+      (forward-char 2))))
+@end smallexample
+
+@noindent
+This illustrates that what matters is the property value for
+each character.  If two consecutive characters have the same
+object as the @code{display} property value, it's irrelevant
+whether they got this property from a single call to
+@code{put-text-property} or from two different calls.
+
+  The rest of this section describes several kinds of
+display specifications and what they mean.
+
+@menu
+* Specified Space::      Displaying one space with a specified width.
+* Pixel Specification::  Specifying space width or height in pixels.
+* Other Display Specs::  Displaying an image; magnifying text; moving it
+                          up or down on the page; adjusting the width
+                          of spaces within text.
+* Display Margins::     Displaying text or images to the side of the main text.
+@end menu
+
+@node Specified Space
+@subsection Specified Spaces
+@cindex spaces, specified height or width
+@cindex variable-width spaces
+
+  To display a space of specified width and/or height, use a display
+specification of the form @code{(space . @var{props})}, where
+@var{props} is a property list (a list of alternating properties and
+values).  You can put this property on one or more consecutive
+characters; a space of the specified height and width is displayed in
+place of @emph{all} of those characters.  These are the properties you
+can use in @var{props} to specify the weight of the space:
+
+@table @code
+@item :width @var{width}
+If @var{width} is an integer or floating point number, it specifies
+that the space width should be @var{width} times the normal character
+width.  @var{width} can also be a @dfn{pixel width} specification
+(@pxref{Pixel Specification}).
+
+@item :relative-width @var{factor}
+Specifies that the width of the stretch should be computed from the
+first character in the group of consecutive characters that have the
+same @code{display} property.  The space width is the width of that
+character, multiplied by @var{factor}.
+
+@item :align-to @var{hpos}
+Specifies that the space should be wide enough to reach @var{hpos}.
+If @var{hpos} is a number, it is measured in units of the normal
+character width.  @var{hpos} can also be a @dfn{pixel width}
+specification (@pxref{Pixel Specification}).
+@end table
+
+  You should use one and only one of the above properties.  You can
+also specify the height of the space, with these properties:
+
+@table @code
+@item :height @var{height}
+Specifies the height of the space.
+If @var{height} is an integer or floating point number, it specifies
+that the space height should be @var{height} times the normal character
+height.  The @var{height} may also be a @dfn{pixel height} specification
+(@pxref{Pixel Specification}).
+
+@item :relative-height @var{factor}
+Specifies the height of the space, multiplying the ordinary height
+of the text having this display specification by @var{factor}.
+
+@item :ascent @var{ascent}
+If the value of @var{ascent} is a non-negative number no greater than
+100, it specifies that @var{ascent} percent of the height of the space
+should be considered as the ascent of the space---that is, the part
+above the baseline.  The ascent may also be specified in pixel units
+with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
+
+@end table
+
+  Don't use both @code{:height} and @code{:relative-height} together.
+
+  The @code{:width} and @code{:align-to} properties are supported on
+non-graphic terminals, but the other space properties in this section
+are not.
+
+@node Pixel Specification
+@subsection Pixel Specification for Spaces
+@cindex spaces, pixel specification
+
+  The value of the @code{:width}, @code{:align-to}, @code{:height},
+and @code{:ascent} properties can be a special kind of expression that
+is evaluated during redisplay.  The result of the evaluation is used
+as an absolute number of pixels.
+
+  The following expressions are supported:
+
+@smallexample
+@group
+  @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
+  @var{num}  ::= @var{integer} | @var{float} | @var{symbol}
+  @var{unit} ::= in | mm | cm | width | height
+@end group
+@group
+  @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
+        |  scroll-bar | text
+  @var{pos}  ::= left | center | right
+  @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
+  @var{op}   ::= + | -
+@end group
+@end smallexample
+
+  The form @var{num} specifies a fraction of the default frame font
+height or width.  The form @code{(@var{num})} specifies an absolute
+number of pixels.  If @var{num} is a symbol, @var{symbol}, its
+buffer-local variable binding is used.
+
+  The @code{in}, @code{mm}, and @code{cm} units specify the number of
+pixels per inch, millimeter, and centimeter, respectively.  The
+@code{width} and @code{height} units correspond to the default width
+and height of the current face.  An image specification @code{image}
+corresponds to the width or height of the image.
+
+  The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
+@code{right-margin}, @code{scroll-bar}, and @code{text} elements
+specify to the width of the corresponding area of the window.
+
+  The @code{left}, @code{center}, and @code{right} positions can be
+used with @code{:align-to} to specify a position relative to the left
+edge, center, or right edge of the text area.
+
+  Any of the above window elements (except @code{text}) can also be
+used with @code{:align-to} to specify that the position is relative to
+the left edge of the given area.  Once the base offset for a relative
+position has been set (by the first occurrence of one of these
+symbols), further occurrences of these symbols are interpreted as the
+width of the specified area.  For example, to align to the center of
+the left-margin, use
+
+@example
+:align-to (+ left-margin (0.5 . left-margin))
+@end example
+
+  If no specific base offset is set for alignment, it is always relative
+to the left edge of the text area.  For example, @samp{:align-to 0} in a
+header-line aligns with the first text column in the text area.
+
+  A value of the form @code{(@var{num} . @var{expr})} stands for the
+product of the values of @var{num} and @var{expr}.  For example,
+@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
+@var{image})} specifies half the width (or height) of the specified
+image.
+
+  The form @code{(+ @var{expr} ...)} adds up the value of the
+expressions.  The form @code{(- @var{expr} ...)} negates or subtracts
+the value of the expressions.
+
+@node Other Display Specs
+@subsection Other Display Specifications
+
+  Here are the other sorts of display specifications that you can use
+in the @code{display} text property.
+
+@table @code
+@item @var{string}
+Display @var{string} instead of the text that has this property.
+
+Recursive display specifications are not supported---@var{string}'s
+@code{display} properties, if any, are not used.
+
+@item (image . @var{image-props})
+This kind of display specification is an image descriptor (@pxref{Images}).
+When used as a display specification, it means to display the image
+instead of the text that has the display specification.
+
+@item (slice @var{x} @var{y} @var{width} @var{height})
+This specification together with @code{image} specifies a @dfn{slice}
+(a partial area) of the image to display.  The elements @var{y} and
+@var{x} specify the top left corner of the slice, within the image;
+@var{width} and @var{height} specify the width and height of the
+slice.  Integer values are numbers of pixels.  A floating point number
+in the range 0.0--1.0 stands for that fraction of the width or height
+of the entire image.
+
+@item ((margin nil) @var{string})
+A display specification of this form means to display @var{string}
+instead of the text that has the display specification, at the same
+position as that text.  It is equivalent to using just @var{string},
+but it is done as a special case of marginal display (@pxref{Display
+Margins}).
+
+@item (space-width @var{factor})
+This display specification affects all the space characters within the
+text that has the specification.  It displays all of these spaces
+@var{factor} times as wide as normal.  The element @var{factor} should
+be an integer or float.  Characters other than spaces are not affected
+at all; in particular, this has no effect on tab characters.
+
+@item (height @var{height})
+This display specification makes the text taller or shorter.
+Here are the possibilities for @var{height}:
+
+@table @asis
+@item @code{(+ @var{n})}
+This means to use a font that is @var{n} steps larger.  A ``step'' is
+defined by the set of available fonts---specifically, those that match
+what was otherwise specified for this text, in all attributes except
+height.  Each size for which a suitable font is available counts as
+another step.  @var{n} should be an integer.
+
+@item @code{(- @var{n})}
+This means to use a font that is @var{n} steps smaller.
+
+@item a number, @var{factor}
+A number, @var{factor}, means to use a font that is @var{factor} times
+as tall as the default font.
+
+@item a symbol, @var{function}
+A symbol is a function to compute the height.  It is called with the
+current height as argument, and should return the new height to use.
+
+@item anything else, @var{form}
+If the @var{height} value doesn't fit the previous possibilities, it is
+a form.  Emacs evaluates it to get the new height, with the symbol
+@code{height} bound to the current specified font height.
+@end table
+
+@item (raise @var{factor})
+This kind of display specification raises or lowers the text
+it applies to, relative to the baseline of the line.
+
+@var{factor} must be a number, which is interpreted as a multiple of the
+height of the affected text.  If it is positive, that means to display
+the characters raised.  If it is negative, that means to display them
+lower down.
+
+If the text also has a @code{height} display specification, that does
+not affect the amount of raising or lowering, which is based on the
+faces used for the text.
+@end table
+
+@c We put all the `@code{(when ...)}' on one line to encourage
+@c makeinfo's end-of-sentence heuristics to DTRT.  Previously, the dot
+@c was at eol; the info file ended up w/ two spaces rendered after it.
+  You can make any display specification conditional.  To do that,
+package it in another list of the form
+@code{(when @var{condition} . @var{spec})}.
+Then the specification @var{spec} applies only when
+@var{condition} evaluates to a non-@code{nil} value.  During the
+evaluation, @code{object} is bound to the string or buffer having the
+conditional @code{display} property.  @code{position} and
+@code{buffer-position} are bound to the position within @code{object}
+and the buffer position where the @code{display} property was found,
+respectively.  Both positions can be different when @code{object} is a
+string.
+
+@node Display Margins
+@subsection Displaying in the Margins
+@cindex display margins
+@cindex margins, display
+
+  A buffer can have blank areas called @dfn{display margins} on the left
+and on the right.  Ordinary text never appears in these areas, but you
+can put things into the display margins using the @code{display}
+property.
+
+  To put text in the left or right display margin of the window, use a
+display specification of the form @code{(margin right-margin)} or
+@code{(margin left-margin)} on it.  To put an image in a display margin,
+use that display specification along with the display specification for
+the image.  Unfortunately, there is currently no way to make
+text or images in the margin mouse-sensitive.
+
+  If you put such a display specification directly on text in the
+buffer, the specified margin display appears @emph{instead of} that
+buffer text itself.  To put something in the margin @emph{in
+association with} certain buffer text without preventing or altering
+the display of that text, put a @code{before-string} property on the
+text and put the display specification on the contents of the
+before-string.
+
+  Before the display margins can display anything, you must give
+them a nonzero width.  The usual way to do that is to set these
+variables:
+
+@defvar left-margin-width
+This variable specifies the width of the left margin.
+It is buffer-local in all buffers.
+@end defvar
+
+@defvar right-margin-width
+This variable specifies the width of the right margin.
+It is buffer-local in all buffers.
+@end defvar
+
+  Setting these variables does not immediately affect the window.  These
+variables are checked when a new buffer is displayed in the window.
+Thus, you can make changes take effect by calling
+@code{set-window-buffer}.
+
+  You can also set the margin widths immediately.
+
+@defun set-window-margins window left &optional right
+This function specifies the margin widths for window @var{window}.
+The argument @var{left} controls the left margin and
+@var{right} controls the right margin (default @code{0}).
+@end defun
+
+@defun window-margins &optional window
+This function returns the left and right margins of @var{window}
+as a cons cell of the form @code{(@var{left} . @var{right})}.
+If @var{window} is @code{nil}, the selected window is used.
+@end defun
+
+@node Images
+@section Images
+@cindex images in buffers
+
+  To display an image in an Emacs buffer, you must first create an image
+descriptor, then use it as a display specifier in the @code{display}
+property of text that is displayed (@pxref{Display Property}).
+
+  Emacs is usually able to display images when it is run on a
+graphical terminal.  Images cannot be displayed in a text terminal, on
+certain graphical terminals that lack the support for this, or if
+Emacs is compiled without image support.  You can use the function
+@code{display-images-p} to determine if images can in principle be
+displayed (@pxref{Display Feature Testing}).
+
+@menu
+* Image Formats::       Supported image formats.
+* Image Descriptors::   How to specify an image for use in @code{:display}.
+* XBM Images::          Special features for XBM format.
+* XPM Images::          Special features for XPM format.
+* GIF Images::          Special features for GIF format.
+* PostScript Images::   Special features for PostScript format.
+* Other Image Types::   Various other formats are supported.
+* Defining Images::     Convenient ways to define an image for later use.
+* Showing Images::      Convenient ways to display an image once it is defined.
+* Image Cache::         Internal mechanisms of image display.
+@end menu
+
+@node Image Formats
+@subsection Image Formats
+@cindex image formats
+@cindex image types
+
+  Emacs can display a number of different image formats; some of them
+are supported only if particular support libraries are installed on
+your machine.  In some environments, Emacs can load image
+libraries on demand; if so, the variable @code{image-library-alist}
+can be used to modify the set of known names for these dynamic
+libraries (though it is not possible to add new image formats).
+
+  The supported image formats include XBM, XPM (this requires the
+libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
+@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the
+@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
+v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring
+@code{librsvg} 2.0.0).
+
+  You specify one of these formats with an image type symbol.  The image
+type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
+@code{pbm}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}.
+
+@defvar image-types
+This variable contains a list of those image type symbols that are
+potentially supported in the current configuration.
+@emph{Potentially} here means that Emacs knows about the image types,
+not necessarily that they can be loaded (they could depend on
+unavailable dynamic libraries, for example).
+
+To know which image types are really available, use
+@code{image-type-available-p}.
+@end defvar
+
+@defvar image-library-alist
+This in an alist of image types vs external libraries needed to
+display them.
+
+Each element is a list @code{(@var{image-type} @var{library}...)},
+where the car is a supported image format from @code{image-types}, and
+the rest are strings giving alternate filenames for the corresponding
+external libraries to load.
+
+Emacs tries to load the libraries in the order they appear on the
+list; if none is loaded, the running session of Emacs won't support
+the image type.  @code{pbm} and @code{xbm} don't need to be listed;
+they're always supported.
+
+This variable is ignored if the image libraries are statically linked
+into Emacs.
+@end defvar
+
+@defun image-type-available-p type
+This function returns non-@code{nil} if image type @var{type} is
+available, i.e., if images of this type can be loaded and displayed in
+Emacs.  @var{type} should be one of the types contained in
+@code{image-types}.
+
+For image types whose support libraries are statically linked, this
+function always returns @code{t}; for other image types, it returns
+@code{t} if the dynamic library could be loaded, @code{nil} otherwise.
+@end defun
+
+@node Image Descriptors
+@subsection Image Descriptors
+@cindex image descriptor
+
+  An image description is a list of the form @code{(image . @var{props})},
+where @var{props} is a property list containing alternating keyword
+symbols (symbols whose names start with a colon) and their values.
+You can use any Lisp object as a property, but the only properties
+that have any special meaning are certain symbols, all of them keywords.
+
+  Every image descriptor must contain the property @code{:type
+@var{type}} to specify the format of the image.  The value of @var{type}
+should be an image type symbol; for example, @code{xpm} for an image in
+XPM format.
+
+  Here is a list of other properties that are meaningful for all image
+types:
+
+@table @code
+@item :file @var{file}
+The @code{:file} property says to load the image from file
+@var{file}.  If @var{file} is not an absolute file name, it is expanded
+in @code{data-directory}.
+
+@item :data @var{data}
+The @code{:data} property says the actual contents of the image.
+Each image must use either @code{:data} or @code{:file}, but not both.
+For most image types, the value of the @code{:data} property should be a
+string containing the image data; we recommend using a unibyte string.
+
+Before using @code{:data}, look for further information in the section
+below describing the specific image format.  For some image types,
+@code{:data} may not be supported; for some, it allows other data types;
+for some, @code{:data} alone is not enough, so you need to use other
+image properties along with @code{:data}.
+
+@item :margin @var{margin}
+The @code{:margin} property specifies how many pixels to add as an
+extra margin around the image.  The value, @var{margin}, must be a
+non-negative number, or a pair @code{(@var{x} . @var{y})} of such
+numbers.  If it is a pair, @var{x} specifies how many pixels to add
+horizontally, and @var{y} specifies how many pixels to add vertically.
+If @code{:margin} is not specified, the default is zero.
+
+@item :ascent @var{ascent}
+The @code{:ascent} property specifies the amount of the image's
+height to use for its ascent---that is, the part above the baseline.
+The value, @var{ascent}, must be a number in the range 0 to 100, or
+the symbol @code{center}.
+
+If @var{ascent} is a number, that percentage of the image's height is
+used for its ascent.
+
+If @var{ascent} is @code{center}, the image is vertically centered
+around a centerline which would be the vertical centerline of text drawn
+at the position of the image, in the manner specified by the text
+properties and overlays that apply to the image.
+
+If this property is omitted, it defaults to 50.
+
+@item :relief @var{relief}
+The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
+around the image.  The value, @var{relief}, specifies the width of the
+shadow lines, in pixels.  If @var{relief} is negative, shadows are drawn
+so that the image appears as a pressed button; otherwise, it appears as
+an unpressed button.
+
+@item :conversion @var{algorithm}
+The @code{:conversion} property, if non-@code{nil}, specifies a
+conversion algorithm that should be applied to the image before it is
+displayed; the value, @var{algorithm}, specifies which algorithm.
+
+@table @code
+@item laplace
+@itemx emboss
+Specifies the Laplace edge detection algorithm, which blurs out small
+differences in color while highlighting larger differences.  People
+sometimes consider this useful for displaying the image for a
+``disabled'' button.
+
+@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
+Specifies a general edge-detection algorithm.  @var{matrix} must be
+either a nine-element list or a nine-element vector of numbers.  A pixel
+at position @math{x/y} in the transformed image is computed from
+original pixels around that position.  @var{matrix} specifies, for each
+pixel in the neighborhood of @math{x/y}, a factor with which that pixel
+will influence the transformed pixel; element @math{0} specifies the
+factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
+the pixel at @math{x/y-1} etc., as shown below:
+@iftex
+@tex
+$$\pmatrix{x-1/y-1 & x/y-1  & x+1/y-1 \cr
+   x-1/y  &   x/y &    x+1/y \cr
+   x-1/y+1&   x/y+1 &  x+1/y+1 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+  (x-1/y-1  x/y-1  x+1/y-1
+   x-1/y    x/y    x+1/y
+   x-1/y+1  x/y+1  x+1/y+1)
+@end display
+@end ifnottex
+
+The resulting pixel is computed from the color intensity of the color
+resulting from summing up the RGB values of surrounding pixels,
+multiplied by the specified factors, and dividing that sum by the sum
+of the factors' absolute values.
+
+Laplace edge-detection currently uses a matrix of
+@iftex
+@tex
+$$\pmatrix{1 & 0 & 0 \cr
+   0&  0 &  0 \cr
+   9 & 9 & -1 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+  (1  0  0
+   0  0  0
+   9  9 -1)
+@end display
+@end ifnottex
+
+Emboss edge-detection uses a matrix of
+@iftex
+@tex
+$$\pmatrix{ 2 & -1 &  0 \cr
+   -1 &  0 &  1 \cr
+    0  & 1 & -2 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+  ( 2 -1  0
+   -1  0  1
+    0  1 -2)
+@end display
+@end ifnottex
+
+@item disabled
+Specifies transforming the image so that it looks ``disabled.''
+@end table
+
+@item :mask @var{mask}
+If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
+a clipping mask for the image, so that the background of a frame is
+visible behind the image.  If @var{bg} is not specified, or if @var{bg}
+is @code{t}, determine the background color of the image by looking at
+the four corners of the image, assuming the most frequently occurring
+color from the corners is the background color of the image.  Otherwise,
+@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
+specifying the color to assume for the background of the image.
+
+If @var{mask} is @code{nil}, remove a mask from the image, if it has
+one.  Images in some formats include a mask which can be removed by
+specifying @code{:mask nil}.
+
+@item :pointer @var{shape}
+This specifies the pointer shape when the mouse pointer is over this
+image.  @xref{Pointer Shape}, for available pointer shapes.
+
+@item :map @var{map}
+This associates an image map of @dfn{hot spots} with this image.
+
+An image map is an alist where each element has the format
+@code{(@var{area} @var{id} @var{plist})}.  An @var{area} is specified
+as either a rectangle, a circle, or a polygon.
+
+A rectangle is a cons
+@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
+which specifies the pixel coordinates of the upper left and bottom right
+corners of the rectangle area.
+
+A circle is a cons
+@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
+which specifies the center and the radius of the circle; @var{r} may
+be a float or integer.
+
+A polygon is a cons
+@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
+where each pair in the vector describes one corner in the polygon.
+
+When the mouse pointer lies on a hot-spot area of an image, the
+@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
+property, that defines a tool-tip for the hot-spot, and if it contains
+a @code{pointer} property, that defines the shape of the mouse cursor when
+it is on the hot-spot.
+@xref{Pointer Shape}, for available pointer shapes.
+
+When you click the mouse when the mouse pointer is over a hot-spot, an
+event is composed by combining the @var{id} of the hot-spot with the
+mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
+@var{id} is @code{area4}.
+@end table
+
+@defun image-mask-p spec &optional frame
+This function returns @code{t} if image @var{spec} has a mask bitmap.
+@var{frame} is the frame on which the image will be displayed.
+@var{frame} @code{nil} or omitted means to use the selected frame
+(@pxref{Input Focus}).
+@end defun
+
+@node XBM Images
+@subsection XBM Images
+@cindex XBM
+
+  To use XBM format, specify @code{xbm} as the image type.  This image
+format doesn't require an external library, so images of this type are
+always supported.
+
+  Additional image properties supported for the @code{xbm} image type are:
+
+@table @code
+@item :foreground @var{foreground}
+The value, @var{foreground}, should be a string specifying the image
+foreground color, or @code{nil} for the default color.  This color is
+used for each pixel in the XBM that is 1.  The default is the frame's
+foreground color.
+
+@item :background @var{background}
+The value, @var{background}, should be a string specifying the image
+background color, or @code{nil} for the default color.  This color is
+used for each pixel in the XBM that is 0.  The default is the frame's
+background color.
+@end table
+
+  If you specify an XBM image using data within Emacs instead of an
+external file, use the following three properties:
+
+@table @code
+@item :data @var{data}
+The value, @var{data}, specifies the contents of the image.
+There are three formats you can use for @var{data}:
+
+@itemize @bullet
+@item
+A vector of strings or bool-vectors, each specifying one line of the
+image.  Do specify @code{:height} and @code{:width}.
+
+@item
+A string containing the same byte sequence as an XBM file would contain.
+You must not specify @code{:height} and @code{:width} in this case,
+because omitting them is what indicates the data has the format of an
+XBM file.  The file contents specify the height and width of the image.
+
+@item
+A string or a bool-vector containing the bits of the image (plus perhaps
+some extra bits at the end that will not be used).  It should contain at
+least @var{width} * @code{height} bits.  In this case, you must specify
+@code{:height} and @code{:width}, both to indicate that the string
+contains just the bits rather than a whole XBM file, and to specify the
+size of the image.
+@end itemize
+
+@item :width @var{width}
+The value, @var{width}, specifies the width of the image, in pixels.
+
+@item :height @var{height}
+The value, @var{height}, specifies the height of the image, in pixels.
+@end table
+
+@node XPM Images
+@subsection XPM Images
+@cindex XPM
+
+  To use XPM format, specify @code{xpm} as the image type.  The
+additional image property @code{:color-symbols} is also meaningful with
+the @code{xpm} image type:
+
+@table @code
+@item :color-symbols @var{symbols}
+The value, @var{symbols}, should be an alist whose elements have the
+form @code{(@var{name} . @var{color})}.  In each element, @var{name} is
+the name of a color as it appears in the image file, and @var{color}
+specifies the actual color to use for displaying that name.
+@end table
+
+@node GIF Images
+@subsection GIF Images
+@cindex GIF
+
+  For GIF images, specify image type @code{gif}.
+
+@table @code
+@item :index @var{index}
+You can use @code{:index} to specify one image from a GIF file that
+contains more than one image.  This property specifies use of image
+number @var{index} from the file.  If the GIF file doesn't contain an
+image with index @var{index}, the image displays as a hollow box.
+@end table
+
+@ignore
+This could be used to implement limited support for animated GIFs.
+For example, the following function displays a multi-image GIF file
+at point-min in the current buffer, switching between sub-images
+every 0.1 seconds.
+
+(defun show-anim (file max)
+  "Display multi-image GIF file FILE which contains MAX subimages."
+  (display-anim (current-buffer) file 0 max t))
+
+(defun display-anim (buffer file idx max first-time)
+  (when (= idx max)
+    (setq idx 0))
+  (let ((img (create-image file nil :image idx)))
+    (save-excursion
+      (set-buffer buffer)
+      (goto-char (point-min))
+      (unless first-time (delete-char 1))
+      (insert-image img))
+    (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
+@end ignore
+
+@node PostScript Images
+@subsection PostScript Images
+@cindex postscript images
+
+  To use PostScript for an image, specify image type @code{postscript}.
+This works only if you have Ghostscript installed.  You must always use
+these three properties:
+
+@table @code
+@item :pt-width @var{width}
+The value, @var{width}, specifies the width of the image measured in
+points (1/72 inch).  @var{width} must be an integer.
+
+@item :pt-height @var{height}
+The value, @var{height}, specifies the height of the image in points
+(1/72 inch).  @var{height} must be an integer.
+
+@item :bounding-box @var{box}
+The value, @var{box}, must be a list or vector of four integers, which
+specifying the bounding box of the PostScript image, analogous to the
+@samp{BoundingBox} comment found in PostScript files.
+
+@example
+%%BoundingBox: 22 171 567 738
+@end example
+@end table
+
+  Displaying PostScript images from Lisp data is not currently
+implemented, but it may be implemented by the time you read this.
+See the @file{etc/NEWS} file to make sure.
+
+@node Other Image Types
+@subsection Other Image Types
+@cindex PBM
+
+  For PBM images, specify image type @code{pbm}.  Color, gray-scale and
+monochromatic images are supported.   For mono PBM images, two additional
+image properties are supported.
+
+@table @code
+@item :foreground @var{foreground}
+The value, @var{foreground}, should be a string specifying the image
+foreground color, or @code{nil} for the default color.  This color is
+used for each pixel in the XBM that is 1.  The default is the frame's
+foreground color.
+
+@item :background @var{background}
+The value, @var{background}, should be a string specifying the image
+background color, or @code{nil} for the default color.  This color is
+used for each pixel in the XBM that is 0.  The default is the frame's
+background color.
+@end table
+
+  For JPEG images, specify image type @code{jpeg}.
+
+  For TIFF images, specify image type @code{tiff}.
+
+  For PNG images, specify image type @code{png}.
+
+  For SVG images, specify image type @code{svg}.
+
+@node Defining Images
+@subsection Defining Images
+
+  The functions @code{create-image}, @code{defimage} and
+@code{find-image} provide convenient ways to create image descriptors.
+
+@defun create-image file-or-data &optional type data-p &rest props
+This function creates and returns an image descriptor which uses the
+data in @var{file-or-data}.  @var{file-or-data} can be a file name or
+a string containing the image data; @var{data-p} should be @code{nil}
+for the former case, non-@code{nil} for the latter case.
+
+The optional argument @var{type} is a symbol specifying the image type.
+If @var{type} is omitted or @code{nil}, @code{create-image} tries to
+determine the image type from the file's first few bytes, or else
+from the file's name.
+
+The remaining arguments, @var{props}, specify additional image
+properties---for example,
+
+@example
+(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
+@end example
+
+The function returns @code{nil} if images of this type are not
+supported.  Otherwise it returns an image descriptor.
+@end defun
+
+@defmac defimage symbol specs &optional doc
+This macro defines @var{symbol} as an image name.  The arguments
+@var{specs} is a list which specifies how to display the image.
+The third argument, @var{doc}, is an optional documentation string.
+
+Each argument in @var{specs} has the form of a property list, and each
+one should specify at least the @code{:type} property and either the
+@code{:file} or the @code{:data} property.  The value of @code{:type}
+should be a symbol specifying the image type, the value of
+@code{:file} is the file to load the image from, and the value of
+@code{:data} is a string containing the actual image data.  Here is an
+example:
+
+@example
+(defimage test-image
+  ((:type xpm :file "~/test1.xpm")
+   (:type xbm :file "~/test1.xbm")))
+@end example
+
+@code{defimage} tests each argument, one by one, to see if it is
+usable---that is, if the type is supported and the file exists.  The
+first usable argument is used to make an image descriptor which is
+stored in @var{symbol}.
+
+If none of the alternatives will work, then @var{symbol} is defined
+as @code{nil}.
+@end defmac
+
+@defun find-image specs
+This function provides a convenient way to find an image satisfying one
+of a list of image specifications @var{specs}.
+
+Each specification in @var{specs} is a property list with contents
+depending on image type.  All specifications must at least contain the
+properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
+or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
+the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
+image from, and @var{data} is a string containing the actual image data.
+The first specification in the list whose @var{type} is supported, and
+@var{file} exists, is used to construct the image specification to be
+returned.  If no specification is satisfied, @code{nil} is returned.
+
+The image is looked for in @code{image-load-path}.
+@end defun
+
+@defvar image-load-path
+This variable's value is a list of locations in which to search for
+image files.  If an element is a string or a variable symbol whose
+value is a string, the string is taken to be the name of a directory
+to search.  If an element is a variable symbol whose value is a list,
+that is taken to be a list of directory names to search.
+
+The default is to search in the @file{images} subdirectory of the
+directory specified by @code{data-directory}, then the directory
+specified by @code{data-directory}, and finally in the directories in
+@code{load-path}.  Subdirectories are not automatically included in
+the search, so if you put an image file in a subdirectory, you have to
+supply the subdirectory name explicitly.  For example, to find the
+image @file{images/foo/bar.xpm} within @code{data-directory}, you
+should specify the image as follows:
+
+@example
+(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
+@end example
+@end defvar
+
+@defun image-load-path-for-library library image &optional path no-error
+This function returns a suitable search path for images used by the
+Lisp package @var{library}.
+
+The function searches for @var{image} first using @code{image-load-path},
+excluding @file{@code{data-directory}/images}, and then in
+@code{load-path}, followed by a path suitable for @var{library}, which
+includes @file{../../etc/images} and @file{../etc/images} relative to
+the library file itself, and finally in
+@file{@code{data-directory}/images}.
+
+Then this function returns a list of directories which contains first
+the directory in which @var{image} was found, followed by the value of
+@code{load-path}.  If @var{path} is given, it is used instead of
+@code{load-path}.
+
+If @var{no-error} is non-@code{nil} and a suitable path can't be
+found, don't signal an error.  Instead, return a list of directories as
+before, except that @code{nil} appears in place of the image directory.
+
+Here is an example that uses a common idiom to provide compatibility
+with versions of Emacs that lack the variable @code{image-load-path}:
+
+@example
+(defvar image-load-path) ; shush compiler
+(let* ((load-path (image-load-path-for-library
+                        "mh-e" "mh-logo.xpm"))
+       (image-load-path (cons (car load-path)
+                              (when (boundp 'image-load-path)
+                                image-load-path))))
+  (mh-tool-bar-folder-buttons-init))
+@end example
+@end defun
+
+@node Showing Images
+@subsection Showing Images
+
+  You can use an image descriptor by setting up the @code{display}
+property yourself, but it is easier to use the functions in this
+section.
+
+@defun insert-image image &optional string area slice
+This function inserts @var{image} in the current buffer at point.  The
+value @var{image} should be an image descriptor; it could be a value
+returned by @code{create-image}, or the value of a symbol defined with
+@code{defimage}.  The argument @var{string} specifies the text to put
+in the buffer to hold the image.  If it is omitted or @code{nil},
+@code{insert-image} uses @code{" "} by default.
+
+The argument @var{area} specifies whether to put the image in a margin.
+If it is @code{left-margin}, the image appears in the left margin;
+@code{right-margin} specifies the right margin.  If @var{area} is
+@code{nil} or omitted, the image is displayed at point within the
+buffer's text.
+
+The argument @var{slice} specifies a slice of the image to insert.  If
+@var{slice} is @code{nil} or omitted the whole image is inserted.
+Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
+@var{height})} which specifies the @var{x} and @var{y} positions and
+@var{width} and @var{height} of the image area to insert.  Integer
+values are in units of pixels.  A floating point number in the range
+0.0--1.0 stands for that fraction of the width or height of the entire
+image.
+
+Internally, this function inserts @var{string} in the buffer, and gives
+it a @code{display} property which specifies @var{image}.  @xref{Display
+Property}.
+@end defun
+
+@defun insert-sliced-image image &optional string area rows cols
+This function inserts @var{image} in the current buffer at point, like
+@code{insert-image}, but splits the image into @var{rows}x@var{cols}
+equally sized slices.
+@end defun
+
+@defun put-image image pos &optional string area
+This function puts image @var{image} in front of @var{pos} in the
+current buffer.  The argument @var{pos} should be an integer or a
+marker.  It specifies the buffer position where the image should appear.
+The argument @var{string} specifies the text that should hold the image
+as an alternative to the default.
+
+The argument @var{image} must be an image descriptor, perhaps returned
+by @code{create-image} or stored by @code{defimage}.
+
+The argument @var{area} specifies whether to put the image in a margin.
+If it is @code{left-margin}, the image appears in the left margin;
+@code{right-margin} specifies the right margin.  If @var{area} is
+@code{nil} or omitted, the image is displayed at point within the
+buffer's text.
+
+Internally, this function creates an overlay, and gives it a
+@code{before-string} property containing text that has a @code{display}
+property whose value is the image.  (Whew!)
+@end defun
+
+@defun remove-images start end &optional buffer
+This function removes images in @var{buffer} between positions
+@var{start} and @var{end}.  If @var{buffer} is omitted or @code{nil},
+images are removed from the current buffer.
+
+This removes only images that were put into @var{buffer} the way
+@code{put-image} does it, not images that were inserted with
+@code{insert-image} or in other ways.
+@end defun
+
+@defun image-size spec &optional pixels frame
+This function returns the size of an image as a pair
+@w{@code{(@var{width} . @var{height})}}.  @var{spec} is an image
+specification.  @var{pixels} non-@code{nil} means return sizes
+measured in pixels, otherwise return sizes measured in canonical
+character units (fractions of the width/height of the frame's default
+font).  @var{frame} is the frame on which the image will be displayed.
+@var{frame} null or omitted means use the selected frame (@pxref{Input
+Focus}).
+@end defun
+
+@defvar max-image-size
+This variable is used to define the maximum size of image that Emacs
+will load.  Emacs will refuse to load (and display) any image that is
+larger than this limit.
+
+If the value is an integer, it directly specifies the maximum
+image height and width, measured in pixels.  If it is a floating
+point number, it specifies the maximum image height and width
+as a ratio to the frame height and width.  If the value is
+non-numeric, there is no explicit limit on the size of images.
+
+The purpose of this variable is to prevent unreasonably large images
+from accidentally being loaded into Emacs.  It only takes effect the
+first time an image is loaded.  Once an image is placed in the image
+cache, it can always be displayed, even if the value of
+@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
+@end defvar
+
+@node Image Cache
+@subsection Image Cache
+@cindex image cache
+
+  Emacs stores images in an image cache so that it can display them
+again more efficiently.  When Emacs displays an image, it searches the
+image cache for an existing image specification @code{equal} to the
+desired specification.  If a match is found, the image is displayed
+from the cache; otherwise, Emacs loads the image normally.
+
+  Occasionally, you may need to tell Emacs to refresh the images
+associated with a given image specification.  For example, suppose you
+display an image using a specification that contains a @code{:file}
+property.  The image is loaded from the given file and stored in the
+image cache.  If you later display the image again, using the same
+image specification, the image is displayed from the image cache.
+Normally, this is not a problem.  However, if the image file has
+changed in the meantime, Emacs would be displaying the old version of
+the image.  In such a situation, it is necessary to ``refresh'' the
+image using @code{image-refresh}.
+
+@defun image-refresh spec &optional frame
+This function refreshes any images having image specifications
+@code{equal} to @var{spec} on frame @var{frame}.  If @var{frame} is
+@code{nil}, the selected frame is used.  If @var{frame} is @code{t},
+the refresh is applied to all existing frames.
+
+This works by removing all image with image specifications matching
+@var{spec} from the image cache.  Thus, the next time the image is
+displayed, Emacs will load the image again.
+@end defun
+
+@defun clear-image-cache &optional frame
+This function clears the entire image cache.  If @var{frame} is
+non-@code{nil}, only the cache for that frame is cleared.  Otherwise,
+all frames' caches are cleared.
+@end defun
+
+If an image in the image cache has not been displayed for a specified
+period of time, Emacs removes it from the cache and frees the
+associated memory.
+
+@defvar image-cache-eviction-delay
+This variable specifies the number of seconds an image can remain in the
+cache without being displayed.  When an image is not displayed for this
+length of time, Emacs removes it from the image cache.
+
+If the value is @code{nil}, Emacs does not remove images from the cache
+except when you explicitly clear it.  This mode can be useful for
+debugging.
+@end defvar
+
+@node Buttons
+@section Buttons
+@cindex buttons in buffers
+@cindex clickable buttons in buffers
+
+  The @emph{button} package defines functions for inserting and
+manipulating clickable (with the mouse, or via keyboard commands)
+buttons in Emacs buffers, such as might be used for help hyper-links,
+etc.  Emacs uses buttons for the hyper-links in help text and the like.
+
+  A button is essentially a set of properties attached (via text
+properties or overlays) to a region of text in an Emacs buffer.  These
+properties are called @dfn{button properties}.
+
+  One of these properties (@code{action}) is a function, which will
+be called when the user invokes it using the keyboard or the mouse.
+The invoked function may then examine the button and use its other
+properties as desired.
+
+  In some ways the Emacs button package duplicates functionality offered
+by the widget package (@pxref{Top, , Introduction, widget, The Emacs
+Widget Library}), but the button package has the advantage that it is
+much faster, much smaller, and much simpler to use (for elisp
+programmers---for users, the result is about the same).  The extra
+speed and space savings are useful mainly if you need to create many
+buttons in a buffer (for instance an @code{*Apropos*} buffer uses
+buttons to make entries clickable, and may contain many thousands of
+entries).
+
+@menu
+* Button Properties::      Button properties with special meanings.
+* Button Types::           Defining common properties for classes of buttons.
+* Making Buttons::         Adding buttons to Emacs buffers.
+* Manipulating Buttons::   Getting and setting properties of buttons.
+* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
+@end menu
+
+@node Button Properties
+@subsection Button Properties
+@cindex button properties
+
+  Buttons have an associated list of properties defining their
+appearance and behavior, and other arbitrary properties may be used
+for application specific purposes.  Some properties that have special
+meaning to the button package include:
+
+@table @code
+@item action
+@kindex action @r{(button property)}
+The function to call when the user invokes the button, which is passed
+the single argument @var{button}.  By default this is @code{ignore},
+which does nothing.
+
+@item mouse-action
+@kindex mouse-action @r{(button property)}
+This is similar to @code{action}, and when present, will be used
+instead of @code{action} for button invocations resulting from
+mouse-clicks (instead of the user hitting @key{RET}).  If not
+present, mouse-clicks use @code{action} instead.
+
+@item face
+@kindex face @r{(button property)}
+This is an Emacs face controlling how buttons of this type are
+displayed; by default this is the @code{button} face.
+
+@item mouse-face
+@kindex mouse-face @r{(button property)}
+This is an additional face which controls appearance during
+mouse-overs (merged with the usual button face); by default this is
+the usual Emacs @code{highlight} face.
+
+@item keymap
+@kindex keymap @r{(button property)}
+The button's keymap, defining bindings active within the button
+region.  By default this is the usual button region keymap, stored
+in the variable @code{button-map}, which defines @key{RET} and
+@key{mouse-2} to invoke the button.
+
+@item type
+@kindex type @r{(button property)}
+The button-type of the button.  When creating a button, this is
+usually specified using the @code{:type} keyword argument.
+@xref{Button Types}.
+
+@item help-echo
+@kindex help-index @r{(button property)}
+A string displayed by the Emacs tool-tip help system; by default,
+@code{"mouse-2, RET: Push this button"}.
+
+@item follow-link
+@kindex follow-link @r{(button property)}
+The follow-link property, defining how a @key{Mouse-1} click behaves
+on this button, @xref{Links and Mouse-1}.
+
+@item button
+@kindex button @r{(button property)}
+All buttons have a non-@code{nil} @code{button} property, which may be useful
+in finding regions of text that comprise buttons (which is what the
+standard button functions do).
+@end table
+
+  There are other properties defined for the regions of text in a
+button, but these are not generally interesting for typical uses.
+
+@node Button Types
+@subsection Button Types
+@cindex button types
+
+  Every button has a button @emph{type}, which defines default values
+for the button's properties.  Button types are arranged in a
+hierarchy, with specialized types inheriting from more general types,
+so that it's easy to define special-purpose types of buttons for
+specific tasks.
+
+@defun define-button-type name &rest properties
+Define a `button type' called @var{name}.  The remaining arguments
+form a sequence of @var{property value} pairs, specifying default
+property values for buttons with this type (a button's type may be set
+by giving it a @code{type} property when creating the button, using
+the @code{:type} keyword argument).
+
+In addition, the keyword argument @code{:supertype} may be used to
+specify a button-type from which @var{name} inherits its default
+property values.  Note that this inheritance happens only when
+@var{name} is defined; subsequent changes to a supertype are not
+reflected in its subtypes.
+@end defun
+
+  Using @code{define-button-type} to define default properties for
+buttons is not necessary---buttons without any specified type use the
+built-in button-type @code{button}---but it is encouraged, since
+doing so usually makes the resulting code clearer and more efficient.
+
+@node Making Buttons
+@subsection Making Buttons
+@cindex making buttons
+
+  Buttons are associated with a region of text, using an overlay or
+text properties to hold button-specific information, all of which are
+initialized from the button's type (which defaults to the built-in
+button type @code{button}).  Like all Emacs text, the appearance of
+the button is governed by the @code{face} property; by default (via
+the @code{face} property inherited from the @code{button} button-type)
+this is a simple underline, like a typical web-page link.
+
+  For convenience, there are two sorts of button-creation functions,
+those that add button properties to an existing region of a buffer,
+called @code{make-...button}, and those that also insert the button
+text, called @code{insert-...button}.
+
+  The button-creation functions all take the @code{&rest} argument
+@var{properties}, which should be a sequence of @var{property value}
+pairs, specifying properties to add to the button; see @ref{Button
+Properties}.  In addition, the keyword argument @code{:type} may be
+used to specify a button-type from which to inherit other properties;
+see @ref{Button Types}.  Any properties not explicitly specified
+during creation will be inherited from the button's type (if the type
+defines such a property).
+
+  The following functions add a button using an overlay
+(@pxref{Overlays}) to hold the button properties:
+
+@defun make-button beg end &rest properties
+This makes a button from @var{beg} to @var{end} in the
+current buffer, and returns it.
+@end defun
+
+@defun insert-button label &rest properties
+This insert a button with the label @var{label} at point,
+and returns it.
+@end defun
+
+  The following functions are similar, but use Emacs text properties
+(@pxref{Text Properties}) to hold the button properties, making the
+button actually part of the text instead of being a property of the
+buffer.  Buttons using text properties do not create markers into the
+buffer, which is important for speed when you use extremely large
+numbers of buttons.  Both functions return the position of the start
+of the new button:
+
+@defun make-text-button beg end &rest properties
+This makes a button from @var{beg} to @var{end} in the current buffer, using
+text properties.
+@end defun
+
+@defun insert-text-button label &rest properties
+This inserts a button with the label @var{label} at point, using text
+properties.
+@end defun
+
+@node Manipulating Buttons
+@subsection Manipulating Buttons
+@cindex manipulating buttons
+
+These are functions for getting and setting properties of buttons.
+Often these are used by a button's invocation function to determine
+what to do.
+
+Where a @var{button} parameter is specified, it means an object
+referring to a specific button, either an overlay (for overlay
+buttons), or a buffer-position or marker (for text property buttons).
+Such an object is passed as the first argument to a button's
+invocation function when it is invoked.
+
+@defun button-start button
+Return the position at which @var{button} starts.
+@end defun
+
+@defun button-end button
+Return the position at which @var{button} ends.
+@end defun
+
+@defun button-get button prop
+Get the property of button @var{button} named @var{prop}.
+@end defun
+
+@defun button-put button prop val
+Set @var{button}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-activate button &optional use-mouse-action
+Call @var{button}'s @code{action} property (i.e., invoke it).  If
+@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@end defun
+
+@defun button-label button
+Return @var{button}'s text label.
+@end defun
+
+@defun button-type button
+Return @var{button}'s button-type.
+@end defun
+
+@defun button-has-type-p button type
+Return @code{t} if @var{button} has button-type @var{type}, or one of
+@var{type}'s subtypes.
+@end defun
+
+@defun button-at pos
+Return the button at position @var{pos} in the current buffer, or @code{nil}.
+@end defun
+
+@defun button-type-put type prop val
+Set the button-type @var{type}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-type-get type prop
+Get the property of button-type @var{type} named @var{prop}.
+@end defun
+
+@defun button-type-subtype-p type supertype
+Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
+@end defun
+
+@node Button Buffer Commands
+@subsection Button Buffer Commands
+@cindex button buffer commands
+
+These are commands and functions for locating and operating on
+buttons in an Emacs buffer.
+
+@code{push-button} is the command that a user uses to actually `push'
+a button, and is bound by default in the button itself to @key{RET}
+and to @key{mouse-2} using a region-specific keymap.  Commands
+that are useful outside the buttons itself, such as
+@code{forward-button} and @code{backward-button} are additionally
+available in the keymap stored in @code{button-buffer-map}; a mode
+which uses buttons may want to use @code{button-buffer-map} as a
+parent keymap for its keymap.
+
+If the button has a non-@code{nil} @code{follow-link} property, and
+@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
+will also activate the @code{push-button} command.
+@xref{Links and Mouse-1}.
+
+@deffn Command push-button &optional pos use-mouse-action
+Perform the action specified by a button at location @var{pos}.
+@var{pos} may be either a buffer position or a mouse-event.  If
+@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
+mouse-event (@pxref{Mouse Events}), try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@var{pos} defaults to point, except when @code{push-button} is invoked
+interactively as the result of a mouse-event, in which case, the mouse
+event's position is used.  If there's no button at @var{pos}, do
+nothing and return @code{nil}, otherwise return @code{t}.
+@end deffn
+
+@deffn Command forward-button n &optional wrap display-message
+Move to the @var{n}th next button, or @var{n}th previous button if
+@var{n} is negative.  If @var{n} is zero, move to the start of any
+button at point.  If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end.  If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed.  Any button with a non-@code{nil} @code{skip} property
+is skipped over.  Returns the button found.
+@end deffn
+
+@deffn Command backward-button n &optional wrap display-message
+Move to the @var{n}th previous button, or @var{n}th next button if
+@var{n} is negative.  If @var{n} is zero, move to the start of any
+button at point.  If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end.  If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed.  Any button with a non-@code{nil} @code{skip} property
+is skipped over.  Returns the button found.
+@end deffn
+
+@defun next-button pos &optional count-current
+@defunx previous-button pos &optional count-current
+Return the next button after (for @code{next-button} or before (for
+@code{previous-button}) position @var{pos} in the current buffer.  If
+@var{count-current} is non-@code{nil}, count any button at @var{pos}
+in the search, instead of starting at the next button.
+@end defun
+
+@node Abstract Display
+@section Abstract Display
+@cindex ewoc
+@cindex display, abstract
+@cindex display, arbitrary objects
+@cindex model/view/controller
+@cindex view part, model/view/controller
+
+  The Ewoc package constructs buffer text that represents a structure
+of Lisp objects, and updates the text to follow changes in that
+structure.  This is like the ``view'' component in the
+``model/view/controller'' design paradigm.
+
+  An @dfn{ewoc} is a structure that organizes information required to
+construct buffer text that represents certain Lisp data.  The buffer
+text of the ewoc has three parts, in order: first, fixed @dfn{header}
+text; next, textual descriptions of a series of data elements (Lisp
+objects that you specify); and last, fixed @dfn{footer} text.
+Specifically, an ewoc contains information on:
+
+@itemize @bullet
+@item
+The buffer which its text is generated in.
+
+@item
+The text's start position in the buffer.
+
+@item
+The header and footer strings.
+
+@item
+A doubly-linked chain of @dfn{nodes}, each of which contains:
+
+@itemize
+@item
+A @dfn{data element}, a single Lisp object.
+
+@item
+Links to the preceding and following nodes in the chain.
+@end itemize
+
+@item
+A @dfn{pretty-printer} function which is responsible for
+inserting the textual representation of a data
+element value into the current buffer.
+@end itemize
+
+  Typically, you define an ewoc with @code{ewoc-create}, and then pass
+the resulting ewoc structure to other functions in the Ewoc package to
+build nodes within it, and display it in the buffer.  Once it is
+displayed in the buffer, other functions determine the correspondance
+between buffer positions and nodes, move point from one node's textual
+representation to another, and so forth.  @xref{Abstract Display
+Functions}.
+
+  A node @dfn{encapsulates} a data element much the way a variable
+holds a value.  Normally, encapsulation occurs as a part of adding a
+node to the ewoc.  You can retrieve the data element value and place a
+new value in its place, like so:
+
+@lisp
+(ewoc-data @var{node})
+@result{} value
+
+(ewoc-set-data @var{node} @var{new-value})
+@result{} @var{new-value}
+@end lisp
+
+@noindent
+You can also use, as the data element value, a Lisp object (list or
+vector) that is a container for the ``real'' value, or an index into
+some other structure.  The example (@pxref{Abstract Display Example})
+uses the latter approach.
+
+  When the data changes, you will want to update the text in the
+buffer.  You can update all nodes by calling @code{ewoc-refresh}, or
+just specific nodes using @code{ewoc-invalidate}, or all nodes
+satisfying a predicate using @code{ewoc-map}.  Alternatively, you can
+delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
+and add new nodes in their place.  Deleting a node from an ewoc deletes
+its associated textual description from buffer, as well.
+
+@menu
+* Abstract Display Functions::
+* Abstract Display Example::
+@end menu
+
+@node Abstract Display Functions
+@subsection Abstract Display Functions
+
+  In this subsection, @var{ewoc} and @var{node} stand for the
+structures described above (@pxref{Abstract Display}), while
+@var{data} stands for an arbitrary Lisp object used as a data element.
+
+@defun ewoc-create pretty-printer &optional header footer nosep
+This constructs and returns a new ewoc, with no nodes (and thus no data
+elements).  @var{pretty-printer} should be a function that takes one
+argument, a data element of the sort you plan to use in this ewoc, and
+inserts its textual description at point using @code{insert} (and never
+@code{insert-before-markers}, because that would interfere with the
+Ewoc package's internal mechanisms).
+
+Normally, a newline is automatically inserted after the header,
+the footer and every node's textual description.  If @var{nosep}
+is non-@code{nil}, no newline is inserted.  This may be useful for
+displaying an entire ewoc on a single line, for example, or for
+making nodes ``invisible'' by arranging for @var{pretty-printer}
+to do nothing for those nodes.
+
+An ewoc maintains its text in the buffer that is current when
+you create it, so switch to the intended buffer before calling
+@code{ewoc-create}.
+@end defun
+
+@defun ewoc-buffer ewoc
+This returns the buffer where @var{ewoc} maintains its text.
+@end defun
+
+@defun ewoc-get-hf ewoc
+This returns a cons cell @code{(@var{header} . @var{footer})}
+made from @var{ewoc}'s header and footer.
+@end defun
+
+@defun ewoc-set-hf ewoc header footer
+This sets the header and footer of @var{ewoc} to the strings
+@var{header} and @var{footer}, respectively.
+@end defun
+
+@defun ewoc-enter-first ewoc data
+@defunx ewoc-enter-last ewoc data
+These add a new node encapsulating @var{data}, putting it, respectively,
+at the beginning or end of @var{ewoc}'s chain of nodes.
+@end defun
+
+@defun ewoc-enter-before ewoc node data
+@defunx ewoc-enter-after ewoc node data
+These add a new node encapsulating @var{data}, adding it to
+@var{ewoc} before or after @var{node}, respectively.
+@end defun
+
+@defun ewoc-prev ewoc node
+@defunx ewoc-next ewoc node
+These return, respectively, the previous node and the next node of @var{node}
+in @var{ewoc}.
+@end defun
+
+@defun ewoc-nth ewoc n
+This returns the node in @var{ewoc} found at zero-based index @var{n}.
+A negative @var{n} means count from the end.  @code{ewoc-nth} returns
+@code{nil} if @var{n} is out of range.
+@end defun
+
+@defun ewoc-data node
+This extracts the data encapsulated by @var{node} and returns it.
+@end defun
+
+@defun ewoc-set-data node data
+This sets the data encapsulated by @var{node} to @var{data}.
+@end defun
+
+@defun ewoc-locate ewoc &optional pos guess
+This determines the node in @var{ewoc} which contains point (or
+@var{pos} if specified), and returns that node.  If @var{ewoc} has no
+nodes, it returns @code{nil}.  If @var{pos} is before the first node,
+it returns the first node; if @var{pos} is after the last node, it returns
+the last node.  The optional third arg @var{guess}
+should be a node that is likely to be near @var{pos}; this doesn't
+alter the result, but makes the function run faster.
+@end defun
+
+@defun ewoc-location node
+This returns the start position of @var{node}.
+@end defun
+
+@defun ewoc-goto-prev ewoc arg
+@defunx ewoc-goto-next ewoc arg
+These move point to the previous or next, respectively, @var{arg}th node
+in @var{ewoc}.  @code{ewoc-goto-prev} does not move if it is already at
+the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
+moves past the last node, returning @code{nil}.  Excepting this special
+case, these functions return the node moved to.
+@end defun
+
+@defun ewoc-goto-node ewoc node
+This moves point to the start of @var{node} in @var{ewoc}.
+@end defun
+
+@defun ewoc-refresh ewoc
+This function regenerates the text of @var{ewoc}.  It works by
+deleting the text between the header and the footer, i.e., all the
+data elements' representations, and then calling the pretty-printer
+function for each node, one by one, in order.
+@end defun
+
+@defun ewoc-invalidate ewoc &rest nodes
+This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
+@var{ewoc} are updated instead of the entire set.
+@end defun
+
+@defun ewoc-delete ewoc &rest nodes
+This deletes each node in @var{nodes} from @var{ewoc}.
+@end defun
+
+@defun ewoc-filter ewoc predicate &rest args
+This calls @var{predicate} for each data element in @var{ewoc} and
+deletes those nodes for which @var{predicate} returns @code{nil}.
+Any @var{args} are passed to @var{predicate}.
+@end defun
+
+@defun ewoc-collect ewoc predicate &rest args
+This calls @var{predicate} for each data element in @var{ewoc}
+and returns a list of those elements for which @var{predicate}
+returns non-@code{nil}.  The elements in the list are ordered
+as in the buffer.  Any @var{args} are passed to @var{predicate}.
+@end defun
+
+@defun ewoc-map map-function ewoc &rest args
+This calls @var{map-function} for each data element in @var{ewoc} and
+updates those nodes for which @var{map-function} returns non-@code{nil}.
+Any @var{args} are passed to @var{map-function}.
+@end defun
+
+@node Abstract Display Example
+@subsection Abstract Display Example
+
+  Here is a simple example using functions of the ewoc package to
+implement a ``color components display,'' an area in a buffer that
+represents a vector of three integers (itself representing a 24-bit RGB
+value) in various ways.
+
+@example
+(setq colorcomp-ewoc nil
+      colorcomp-data nil
+      colorcomp-mode-map nil
+      colorcomp-labels ["Red" "Green" "Blue"])
+
+(defun colorcomp-pp (data)
+  (if data
+      (let ((comp (aref colorcomp-data data)))
+        (insert (aref colorcomp-labels data) "\t: #x"
+                (format "%02X" comp) " "
+                (make-string (ash comp -2) ?#) "\n"))
+    (let ((cstr (format "#%02X%02X%02X"
+                        (aref colorcomp-data 0)
+                        (aref colorcomp-data 1)
+                        (aref colorcomp-data 2)))
+          (samp " (sample text) "))
+      (insert "Color\t: "
+              (propertize samp 'face `(foreground-color . ,cstr))
+              (propertize samp 'face `(background-color . ,cstr))
+              "\n"))))
+
+(defun colorcomp (color)
+  "Allow fiddling with COLOR in a new buffer.
+The buffer is in Color Components mode."
+  (interactive "sColor (name or #RGB or #RRGGBB): ")
+  (when (string= "" color)
+    (setq color "green"))
+  (unless (color-values color)
+    (error "No such color: %S" color))
+  (switch-to-buffer
+   (generate-new-buffer (format "originally: %s" color)))
+  (kill-all-local-variables)
+  (setq major-mode 'colorcomp-mode
+        mode-name "Color Components")
+  (use-local-map colorcomp-mode-map)
+  (erase-buffer)
+  (buffer-disable-undo)
+  (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
+                                     (color-values color))))
+        (ewoc (ewoc-create 'colorcomp-pp
+                           "\nColor Components\n\n"
+                           (substitute-command-keys
+                            "\n\\@{colorcomp-mode-map@}"))))
+    (set (make-local-variable 'colorcomp-data) data)
+    (set (make-local-variable 'colorcomp-ewoc) ewoc)
+    (ewoc-enter-last ewoc 0)
+    (ewoc-enter-last ewoc 1)
+    (ewoc-enter-last ewoc 2)
+    (ewoc-enter-last ewoc nil)))
+@end example
+
+@cindex controller part, model/view/controller
+  This example can be extended to be a ``color selection widget'' (in
+other words, the controller part of the ``model/view/controller''
+design paradigm) by defining commands to modify @code{colorcomp-data}
+and to ``finish'' the selection process, and a keymap to tie it all
+together conveniently.
+
+@smallexample
+(defun colorcomp-mod (index limit delta)
+  (let ((cur (aref colorcomp-data index)))
+    (unless (= limit cur)
+      (aset colorcomp-data index (+ cur delta)))
+    (ewoc-invalidate
+     colorcomp-ewoc
+     (ewoc-nth colorcomp-ewoc index)
+     (ewoc-nth colorcomp-ewoc -1))))
+
+(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
+(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
+(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
+(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
+(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
+(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
+
+(defun colorcomp-copy-as-kill-and-exit ()
+  "Copy the color components into the kill ring and kill the buffer.
+The string is formatted #RRGGBB (hash followed by six hex digits)."
+  (interactive)
+  (kill-new (format "#%02X%02X%02X"
+                    (aref colorcomp-data 0)
+                    (aref colorcomp-data 1)
+                    (aref colorcomp-data 2)))
+  (kill-buffer nil))
+
+(setq colorcomp-mode-map
+      (let ((m (make-sparse-keymap)))
+        (suppress-keymap m)
+        (define-key m "i" 'colorcomp-R-less)
+        (define-key m "o" 'colorcomp-R-more)
+        (define-key m "k" 'colorcomp-G-less)
+        (define-key m "l" 'colorcomp-G-more)
+        (define-key m "," 'colorcomp-B-less)
+        (define-key m "." 'colorcomp-B-more)
+        (define-key m " " 'colorcomp-copy-as-kill-and-exit)
+        m))
+@end smallexample
+
+Note that we never modify the data in each node, which is fixed when the
+ewoc is created to be either @code{nil} or an index into the vector
+@code{colorcomp-data}, the actual color components.
+
+@node Blinking
+@section Blinking Parentheses
+@cindex parenthesis matching
+@cindex blinking parentheses
+@cindex balancing parentheses
+
+  This section describes the mechanism by which Emacs shows a matching
+open parenthesis when the user inserts a close parenthesis.
+
+@defvar blink-paren-function
+The value of this variable should be a function (of no arguments) to
+be called whenever a character with close parenthesis syntax is inserted.
+The value of @code{blink-paren-function} may be @code{nil}, in which
+case nothing is done.
+@end defvar
+
+@defopt blink-matching-paren
+If this variable is @code{nil}, then @code{blink-matching-open} does
+nothing.
+@end defopt
+
+@defopt blink-matching-paren-distance
+This variable specifies the maximum distance to scan for a matching
+parenthesis before giving up.
+@end defopt
+
+@defopt blink-matching-delay
+This variable specifies the number of seconds for the cursor to remain
+at the matching parenthesis.  A fraction of a second often gives
+good results, but the default is 1, which works on all systems.
+@end defopt
+
+@deffn Command blink-matching-open
+This function is the default value of @code{blink-paren-function}.  It
+assumes that point follows a character with close parenthesis syntax and
+moves the cursor momentarily to the matching opening character.  If that
+character is not already on the screen, it displays the character's
+context in the echo area.  To avoid long delays, this function does not
+search farther than @code{blink-matching-paren-distance} characters.
+
+Here is an example of calling this function explicitly.
+
+@smallexample
+@group
+(defun interactive-blink-matching-open ()
+@c Do not break this line! -- rms.
+@c The first line of a doc string
+@c must stand alone.
+  "Indicate momentarily the start of sexp before point."
+  (interactive)
+@end group
+@group
+  (let ((blink-matching-paren-distance
+         (buffer-size))
+        (blink-matching-paren t))
+    (blink-matching-open)))
+@end group
+@end smallexample
+@end deffn
+
+@node Usual Display
+@section Usual Display Conventions
+
+  The usual display conventions define how to display each character
+code.  You can override these conventions by setting up a display table
+(@pxref{Display Tables}).  Here are the usual display conventions:
+
+@itemize @bullet
+@item
+Character codes 32 through 126 map to glyph codes 32 through 126.
+Normally this means they display as themselves.
+
+@item
+Character code 9 is a horizontal tab.  It displays as whitespace
+up to a position determined by @code{tab-width}.
+
+@item
+Character code 10 is a newline.
+
+@item
+All other codes in the range 0 through 31, and code 127, display in one
+of two ways according to the value of @code{ctl-arrow}.  If it is
+non-@code{nil}, these codes map to sequences of two glyphs, where the
+first glyph is the @acronym{ASCII} code for @samp{^}.  (A display table can
+specify a glyph to use instead of @samp{^}.)  Otherwise, these codes map
+just like the codes in the range 128 to 255.
+
+On MS-DOS terminals, Emacs arranges by default for the character code
+127 to be mapped to the glyph code 127, which normally displays as an
+empty polygon.  This glyph is used to display non-@acronym{ASCII} characters
+that the MS-DOS terminal doesn't support.  @xref{MS-DOS and MULE,,,
+emacs, The GNU Emacs Manual}.
+
+@item
+Character codes 128 through 255 map to sequences of four glyphs, where
+the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
+digit characters representing the character code in octal.  (A display
+table can specify a glyph to use instead of @samp{\}.)
+
+@item
+Multibyte character codes above 256 are displayed as themselves, or as a
+question mark or empty box if the terminal cannot display that
+character.
+@end itemize
+
+  The usual display conventions apply even when there is a display
+table, for any character whose entry in the active display table is
+@code{nil}.  Thus, when you set up a display table, you need only
+specify the characters for which you want special behavior.
+
+  These display rules apply to carriage return (character code 13), when
+it appears in the buffer.  But that character may not appear in the
+buffer where you expect it, if it was eliminated as part of end-of-line
+conversion (@pxref{Coding System Basics}).
+
+  These variables affect the way certain characters are displayed on the
+screen.  Since they change the number of columns the characters occupy,
+they also affect the indentation functions.  These variables also affect
+how the mode line is displayed; if you want to force redisplay of the
+mode line using the new values, call the function
+@code{force-mode-line-update} (@pxref{Mode Line Format}).
+
+@defopt ctl-arrow
+@cindex control characters in display
+This buffer-local variable controls how control characters are
+displayed.  If it is non-@code{nil}, they are displayed as a caret
+followed by the character: @samp{^A}.  If it is @code{nil}, they are
+displayed as a backslash followed by three octal digits: @samp{\001}.
+@end defopt
+
+@c Following may have overfull hbox.
+@defvar default-ctl-arrow
+The value of this variable is the default value for @code{ctl-arrow} in
+buffers that do not override it.  @xref{Default Value}.
+@end defvar
+
+@defopt tab-width
+The value of this buffer-local variable is the spacing between tab
+stops used for displaying tab characters in Emacs buffers.  The value
+is in units of columns, and the default is 8.  Note that this feature
+is completely independent of the user-settable tab stops used by the
+command @code{tab-to-tab-stop}.  @xref{Indent Tabs}.
+@end defopt
+
+@node Display Tables
+@section Display Tables
+
+@cindex display table
+You can use the @dfn{display table} feature to control how all possible
+character codes display on the screen.  This is useful for displaying
+European languages that have letters not in the @acronym{ASCII} character
+set.
+
+The display table maps each character code into a sequence of
+@dfn{glyphs}, each glyph being a graphic that takes up one character
+position on the screen.  You can also define how to display each glyph
+on your terminal, using the @dfn{glyph table}.
+
+Display tables affect how the mode line is displayed; if you want to
+force redisplay of the mode line using a new display table, call
+@code{force-mode-line-update} (@pxref{Mode Line Format}).
+
+@menu
+* Display Table Format::  What a display table consists of.
+* Active Display Table::  How Emacs selects a display table to use.
+* Glyphs::              How to define a glyph, and what glyphs mean.
+@end menu
+
+@node Display Table Format
+@subsection Display Table Format
+
+  A display table is actually a char-table (@pxref{Char-Tables}) with
+@code{display-table} as its subtype.
+
+@defun make-display-table
+This creates and returns a display table.  The table initially has
+@code{nil} in all elements.
+@end defun
+
+  The ordinary elements of the display table are indexed by character
+codes; the element at index @var{c} says how to display the character
+code @var{c}.  The value should be @code{nil} or a vector of the
+glyphs to be output (@pxref{Glyphs}).  @code{nil} says to display the
+character @var{c} according to the usual display conventions
+(@pxref{Usual Display}).
+
+  @strong{Warning:} if you use the display table to change the display
+of newline characters, the whole buffer will be displayed as one long
+``line.''
+
+  The display table also has six ``extra slots'' which serve special
+purposes.  Here is a table of their meanings; @code{nil} in any slot
+means to use the default for that slot, as stated below.
+
+@table @asis
+@item 0
+The glyph for the end of a truncated screen line (the default for this
+is @samp{$}).  @xref{Glyphs}.  On graphical terminals, Emacs uses
+arrows in the fringes to indicate truncation, so the display table has
+no effect.
+
+@item 1
+The glyph for the end of a continued line (the default is @samp{\}).
+On graphical terminals, Emacs uses curved arrows in the fringes to
+indicate continuation, so the display table has no effect.
+
+@item 2
+The glyph for indicating a character displayed as an octal character
+code (the default is @samp{\}).
+
+@item 3
+The glyph for indicating a control character (the default is @samp{^}).
+
+@item 4
+A vector of glyphs for indicating the presence of invisible lines (the
+default is @samp{...}).  @xref{Selective Display}.
+
+@item 5
+The glyph used to draw the border between side-by-side windows (the
+default is @samp{|}).  @xref{Splitting Windows}.  This takes effect only
+when there are no scroll bars; if scroll bars are supported and in use,
+a scroll bar separates the two windows.
+@end table
+
+  For example, here is how to construct a display table that mimics the
+effect of setting @code{ctl-arrow} to a non-@code{nil} value:
+
+@example
+(setq disptab (make-display-table))
+(let ((i 0))
+  (while (< i 32)
+    (or (= i ?\t) (= i ?\n)
+        (aset disptab i (vector ?^ (+ i 64))))
+    (setq i (1+ i)))
+  (aset disptab 127 (vector ?^ ??)))
+@end example
+
+@defun display-table-slot display-table slot
+This function returns the value of the extra slot @var{slot} of
+@var{display-table}.  The argument @var{slot} may be a number from 0 to
+5 inclusive, or a slot name (symbol).  Valid symbols are
+@code{truncation}, @code{wrap}, @code{escape}, @code{control},
+@code{selective-display}, and @code{vertical-border}.
+@end defun
+
+@defun set-display-table-slot display-table slot value
+This function stores @var{value} in the extra slot @var{slot} of
+@var{display-table}.  The argument @var{slot} may be a number from 0 to
+5 inclusive, or a slot name (symbol).  Valid symbols are
+@code{truncation}, @code{wrap}, @code{escape}, @code{control},
+@code{selective-display}, and @code{vertical-border}.
+@end defun
+
+@defun describe-display-table display-table
+This function displays a description of the display table
+@var{display-table} in a help buffer.
+@end defun
+
+@deffn Command describe-current-display-table
+This command displays a description of the current display table in a
+help buffer.
+@end deffn
+
+@node Active Display Table
+@subsection Active Display Table
+@cindex active display table
+
+  Each window can specify a display table, and so can each buffer.  When
+a buffer @var{b} is displayed in window @var{w}, display uses the
+display table for window @var{w} if it has one; otherwise, the display
+table for buffer @var{b} if it has one; otherwise, the standard display
+table if any.  The display table chosen is called the @dfn{active}
+display table.
+
+@defun window-display-table &optional window
+This function returns @var{window}'s display table, or @code{nil}
+if @var{window} does not have an assigned display table.  The default
+for @var{window} is the selected window.
+@end defun
+
+@defun set-window-display-table window table
+This function sets the display table of @var{window} to @var{table}.
+The argument @var{table} should be either a display table or
+@code{nil}.
+@end defun
+
+@defvar buffer-display-table
+This variable is automatically buffer-local in all buffers; its value in
+a particular buffer specifies the display table for that buffer.  If it
+is @code{nil}, that means the buffer does not have an assigned display
+table.
+@end defvar
+
+@defvar standard-display-table
+This variable's value is the default display table, used whenever a
+window has no display table and neither does the buffer displayed in
+that window.  This variable is @code{nil} by default.
+@end defvar
+
+  If there is no display table to use for a particular window---that is,
+if the window specifies none, its buffer specifies none, and
+@code{standard-display-table} is @code{nil}---then Emacs uses the usual
+display conventions for all character codes in that window.  @xref{Usual
+Display}.
+
+A number of functions for changing the standard display table
+are defined in the library @file{disp-table}.
+
+@node Glyphs
+@subsection Glyphs
+
+@cindex glyph
+  A @dfn{glyph} is a generalization of a character; it stands for an
+image that takes up a single character position on the screen.  Normally
+glyphs come from vectors in the display table (@pxref{Display Tables}).
+
+  A glyph is represented in Lisp as a @dfn{glyph code}.  A glyph code
+can be @dfn{simple} or it can be defined by the @dfn{glyph table}.  A
+simple glyph code is just a way of specifying a character and a face
+to output it in.  @xref{Faces}.
+
+  The following functions are used to manipulate simple glyph codes:
+
+@defun make-glyph-code char &optional face
+This function returns a simple glyph code representing char @var{char}
+with face @var{face}.
+@end defun
+
+@defun glyph-char glyph
+This function returns the character of simple glyph code @var{glyph}.
+@end defun
+
+@defun glyph-face glyph
+This function returns face of simple glyph code @var{glyph}, or
+@code{nil} if @var{glyph} has the default face (face-id 0).
+@end defun
+
+  On character terminals, you can set up a @dfn{glyph table} to define
+the meaning of glyph codes (represented as small integers).
+
+@defvar glyph-table
+The value of this variable is the current glyph table.  It should be
+@code{nil} or a vector whose @var{g}th element defines glyph code
+@var{g}.
+
+If a glyph code is greater than or equal to the length of the glyph
+table, that code is automatically simple.  If @code{glyph-table} is
+@code{nil} then all glyph codes are simple.
+
+The glyph table is used only on character terminals.  On graphical
+displays, all glyph codes are simple.
+@end defvar
+
+  Here are the meaningful types of elements in the glyph table:
+
+@table @asis
+@item @var{string}
+Send the characters in @var{string} to the terminal to output
+this glyph code.
+
+@item @var{code}
+Define this glyph code as an alias for glyph code @var{code} created
+by @code{make-glyph-code}.  You can use such an alias to define a
+small-numbered glyph code which specifies a character with a face.
+
+@item @code{nil}
+This glyph code is simple.
+@end table
+
+@defun create-glyph string
+This function returns a newly-allocated glyph code which is set up to
+display by sending @var{string} to the terminal.
+@end defun
+
+@node Beeping
+@section Beeping
+@c  @cindex beeping   "beep" is adjacent
+@cindex bell
+
+  This section describes how to make Emacs ring the bell (or blink the
+screen) to attract the user's attention.  Be conservative about how
+often you do this; frequent bells can become irritating.  Also be
+careful not to use just beeping when signaling an error is more
+appropriate.  (@xref{Errors}.)
+
+@defun ding &optional do-not-terminate
+@cindex keyboard macro termination
+This function beeps, or flashes the screen (see @code{visible-bell} below).
+It also terminates any keyboard macro currently executing unless
+@var{do-not-terminate} is non-@code{nil}.
+@end defun
+
+@defun beep &optional do-not-terminate
+This is a synonym for @code{ding}.
+@end defun
+
+@defopt visible-bell
+This variable determines whether Emacs should flash the screen to
+represent a bell.  Non-@code{nil} means yes, @code{nil} means no.  This
+is effective on graphical displays, and on text-only terminals
+provided the terminal's Termcap entry defines the visible bell
+capability (@samp{vb}).
+@end defopt
+
+@defvar ring-bell-function
+If this is non-@code{nil}, it specifies how Emacs should ``ring the
+bell.''  Its value should be a function of no arguments.  If this is
+non-@code{nil}, it takes precedence over the @code{visible-bell}
+variable.
+@end defvar
+
+@node Window Systems
+@section Window Systems
+
+  Emacs works with several window systems, most notably the X Window
+System.  Both Emacs and X use the term ``window,'' but use it
+differently.  An Emacs frame is a single window as far as X is
+concerned; the individual Emacs windows are not known to X at all.
+
+@defvar window-system
+This variable tells Lisp programs what window system Emacs is running
+under.  The possible values are
+
+@table @code
+@item x
+@cindex X Window System
+Emacs is displaying using X.
+@item pc
+Emacs is displaying using MS-DOS.
+@item w32
+Emacs is displaying using Windows.
+@item mac
+Emacs is displaying using a Macintosh.
+@item nil
+Emacs is using a character-based terminal.
+@end table
+@end defvar
+
+@defvar window-setup-hook
+This variable is a normal hook which Emacs runs after handling the
+initialization files.  Emacs runs this hook after it has completed
+loading your init file, the default initialization file (if
+any), and the terminal-specific Lisp code, and running the hook
+@code{term-setup-hook}.
+
+This hook is used for internal purposes: setting up communication with
+the window system, and creating the initial window.  Users should not
+interfere with it.
+@end defvar
+
+@ignore
+   arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6
+@end ignore
diff --git a/doc/lispref/doclicense.texi b/doc/lispref/doclicense.texi
new file mode 100644
index 00000000000..f2f32aaa968
--- /dev/null
+++ b/doc/lispref/doclicense.texi
@@ -0,0 +1,419 @@
+@c -*-texinfo-*-
+@node GNU Free Documentation License, GPL, Antinews, 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.
+
+@ignore
+   arch-tag: 9014cf6e-f3c4-401d-b8da-4fe52723984c
+@end ignore
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
new file mode 100644
index 00000000000..4be030896c5
--- /dev/null
+++ b/doc/lispref/edebug.texi
@@ -0,0 +1,1582 @@
+@comment -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+
+@c This file can also be used by an independent Edebug User
+@c Manual in which case the Edebug node below should be used
+@c with the following links to the Bugs section and to the top level:
+
+@c , Bugs and Todo List, Top, Top
+
+@node Edebug, Syntax Errors, Debugger, Debugging
+@section Edebug
+@cindex Edebug debugging facility
+
+  Edebug is a source-level debugger for Emacs Lisp programs with which
+you can:
+
+@itemize @bullet
+@item
+Step through evaluation, stopping before and after each expression.
+
+@item
+Set conditional or unconditional breakpoints.
+
+@item
+Stop when a specified condition is true (the global break event).
+
+@item
+Trace slow or fast, stopping briefly at each stop point, or
+at each breakpoint.
+
+@item
+Display expression results and evaluate expressions as if outside of
+Edebug.
+
+@item
+Automatically re-evaluate a list of expressions and
+display their results each time Edebug updates the display.
+
+@item
+Output trace info on function enter and exit.
+
+@item
+Stop when an error occurs.
+
+@item
+Display a backtrace, omitting Edebug's own frames.
+
+@item
+Specify argument evaluation for macros and defining forms.
+
+@item
+Obtain rudimentary coverage testing and frequency counts.
+@end itemize
+
+The first three sections below should tell you enough about Edebug to
+enable you to use it.
+
+@menu
+* Using Edebug::		Introduction to use of Edebug.
+* Instrumenting::		You must instrument your code
+				  in order to debug it with Edebug.
+* Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
+* Jumping::			Commands to jump to a specified place.
+* Misc: Edebug Misc.		Miscellaneous commands.
+* Breaks::                      Setting breakpoints to make the program stop.
+* Trapping Errors::		Trapping errors with Edebug.
+* Views: Edebug Views.		Views inside and outside of Edebug.
+* Eval: Edebug Eval.		Evaluating expressions within Edebug.
+* Eval List::			Expressions whose values are displayed
+				  each time you enter Edebug.
+* Printing in Edebug::		Customization of printing.
+* Trace Buffer::		How to produce trace output in a buffer.
+* Coverage Testing::		How to test evaluation coverage.
+* The Outside Context::		Data that Edebug saves and restores.
+* Edebug and Macros::	        Specifying how to handle macro calls.
+* Options: Edebug Options.	Option variables for customizing Edebug.
+@end menu
+
+@node Using Edebug
+@subsection Using Edebug
+
+  To debug a Lisp program with Edebug, you must first @dfn{instrument}
+the Lisp code that you want to debug.  A simple way to do this is to
+first move point into the definition of a function or macro and then do
+@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument).  See
+@ref{Instrumenting}, for alternative ways to instrument code.
+
+  Once a function is instrumented, any call to the function activates
+Edebug.  Depending on which Edebug execution mode you have selected,
+activating Edebug may stop execution and let you step through the
+function, or it may update the display and continue execution while
+checking for debugging commands.  The default execution mode is step,
+which stops execution.  @xref{Edebug Execution Modes}.
+
+  Within Edebug, you normally view an Emacs buffer showing the source of
+the Lisp code you are debugging.  This is referred to as the @dfn{source
+code buffer}, and it is temporarily read-only.
+
+  An arrow in the left fringe indicates the line where the function is
+executing.  Point initially shows where within the line the function is
+executing, but this ceases to be true if you move point yourself.
+
+  If you instrument the definition of @code{fac} (shown below) and then
+execute @code{(fac 3)}, here is what you would normally see.  Point is
+at the open-parenthesis before @code{if}.
+
+@example
+(defun fac (n)
+=>@point{}(if (< 0 n)
+      (* n (fac (1- n)))
+    1))
+@end example
+
+@cindex stop points
+The places within a function where Edebug can stop execution are called
+@dfn{stop points}.  These occur both before and after each subexpression
+that is a list, and also after each variable reference.
+Here we use periods to show the stop points in the function
+@code{fac}:
+
+@example
+(defun fac (n)
+  .(if .(< 0 n.).
+      .(* n. .(fac .(1- n.).).).
+    1).)
+@end example
+
+The special commands of Edebug are available in the source code buffer
+in addition to the commands of Emacs Lisp mode.  For example, you can
+type the Edebug command @key{SPC} to execute until the next stop point.
+If you type @key{SPC} once after entry to @code{fac}, here is the
+display you will see:
+
+@example
+(defun fac (n)
+=>(if @point{}(< 0 n)
+      (* n (fac (1- n)))
+    1))
+@end example
+
+When Edebug stops execution after an expression, it displays the
+expression's value in the echo area.
+
+Other frequently used commands are @kbd{b} to set a breakpoint at a stop
+point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
+exit Edebug and return to the top-level command loop.  Type @kbd{?} to
+display a list of all Edebug commands.
+
+@node Instrumenting
+@subsection Instrumenting for Edebug
+
+  In order to use Edebug to debug Lisp code, you must first
+@dfn{instrument} the code.  Instrumenting code inserts additional code
+into it, to invoke Edebug at the proper places.
+
+@kindex C-M-x
+@findex eval-defun (Edebug)
+  When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a
+prefix argument on a function definition, it instruments the
+definition before evaluating it.  (This does not modify the source
+code itself.)  If the variable @code{edebug-all-defs} is
+non-@code{nil}, that inverts the meaning of the prefix argument: in
+this case, @kbd{C-M-x} instruments the definition @emph{unless} it has
+a prefix argument.  The default value of @code{edebug-all-defs} is
+@code{nil}.  The command @kbd{M-x edebug-all-defs} toggles the value
+of the variable @code{edebug-all-defs}.
+
+@findex eval-region @r{(Edebug)}
+@findex eval-buffer @r{(Edebug)}
+@findex eval-current-buffer @r{(Edebug)}
+  If @code{edebug-all-defs} is non-@code{nil}, then the commands
+@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
+also instrument any definitions they evaluate.  Similarly,
+@code{edebug-all-forms} controls whether @code{eval-region} should
+instrument @emph{any} form, even non-defining forms.  This doesn't apply
+to loading or evaluations in the minibuffer.  The command @kbd{M-x
+edebug-all-forms} toggles this option.
+
+@findex edebug-eval-top-level-form
+  Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
+instrument any top-level form regardless of the values of
+@code{edebug-all-defs} and @code{edebug-all-forms}.
+
+  While Edebug is active, the command @kbd{I}
+(@code{edebug-instrument-callee}) instruments the definition of the
+function or macro called by the list form after point, if is not already
+instrumented.  This is possible only if Edebug knows where to find the
+source for that function; for this reading, after loading Edebug,
+@code{eval-region} records the position of every definition it
+evaluates, even if not instrumenting it.  See also the @kbd{i} command
+(@pxref{Jumping}), which steps into the call after instrumenting the
+function.
+
+  Edebug knows how to instrument all the standard special forms,
+@code{interactive} forms with an expression argument, anonymous lambda
+expressions, and other defining forms.  However, Edebug cannot determine
+on its own what a user-defined macro will do with the arguments of a
+macro call, so you must provide that information using Edebug
+specifications; see @ref{Edebug and Macros}, for details.
+
+  When Edebug is about to instrument code for the first time in a
+session, it runs the hook @code{edebug-setup-hook}, then sets it to
+@code{nil}.  You can use this to load Edebug specifications
+associated with a package you are using, but only when you use Edebug.
+
+@findex eval-expression @r{(Edebug)}
+  To remove instrumentation from a definition, simply re-evaluate its
+definition in a way that does not instrument.  There are two ways of
+evaluating forms that never instrument them: from a file with
+@code{load}, and from the minibuffer with @code{eval-expression}
+(@kbd{M-:}).
+
+  If Edebug detects a syntax error while instrumenting, it leaves point
+at the erroneous code and signals an @code{invalid-read-syntax} error.
+
+  @xref{Edebug Eval}, for other evaluation functions available
+inside of Edebug.
+
+@node Edebug Execution Modes
+@subsection Edebug Execution Modes
+
+@cindex Edebug execution modes
+Edebug supports several execution modes for running the program you are
+debugging.  We call these alternatives @dfn{Edebug execution modes}; do
+not confuse them with major or minor modes.  The current Edebug execution mode
+determines how far Edebug continues execution before stopping---whether
+it stops at each stop point, or continues to the next breakpoint, for
+example---and how much Edebug displays the progress of the evaluation
+before it stops.
+
+Normally, you specify the Edebug execution mode by typing a command to
+continue the program in a certain mode.  Here is a table of these
+commands; all except for @kbd{S} resume execution of the program, at
+least for a certain distance.
+
+@table @kbd
+@item S
+Stop: don't execute any more of the program, but wait for more
+Edebug commands (@code{edebug-stop}).
+
+@item @key{SPC}
+Step: stop at the next stop point encountered (@code{edebug-step-mode}).
+
+@item n
+Next: stop at the next stop point encountered after an expression
+(@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
+@ref{Jumping}.
+
+@item t
+Trace: pause (normally one second) at each Edebug stop point
+(@code{edebug-trace-mode}).
+
+@item T
+Rapid trace: update the display at each stop point, but don't actually
+pause (@code{edebug-Trace-fast-mode}).
+
+@item g
+Go: run until the next breakpoint (@code{edebug-go-mode}).  @xref{Breakpoints}.
+
+@item c
+Continue: pause one second at each breakpoint, and then continue
+(@code{edebug-continue-mode}).
+
+@item C
+Rapid continue: move point to each breakpoint, but don't pause
+(@code{edebug-Continue-fast-mode}).
+
+@item G
+Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}).  You
+can still stop the program by typing @kbd{S}, or any editing command.
+@end table
+
+In general, the execution modes earlier in the above list run the
+program more slowly or stop sooner than the modes later in the list.
+
+While executing or tracing, you can interrupt the execution by typing
+any Edebug command.  Edebug stops the program at the next stop point and
+then executes the command you typed.  For example, typing @kbd{t} during
+execution switches to trace mode at the next stop point.  You can use
+@kbd{S} to stop execution without doing anything else.
+
+If your function happens to read input, a character you type intending
+to interrupt execution may be read by the function instead.  You can
+avoid such unintended results by paying attention to when your program
+wants input.
+
+@cindex keyboard macros (Edebug)
+Keyboard macros containing the commands in this section do not
+completely work: exiting from Edebug, to resume the program, loses track
+of the keyboard macro.  This is not easy to fix.  Also, defining or
+executing a keyboard macro outside of Edebug does not affect commands
+inside Edebug.  This is usually an advantage.  See also the
+@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
+
+When you enter a new Edebug level, the initial execution mode comes
+from the value of the variable @code{edebug-initial-mode}.
+(@xref{Edebug Options}.)  By default, this specifies step mode.  Note
+that you may reenter the same Edebug level several times if, for
+example, an instrumented function is called several times from one
+command.
+
+@defopt edebug-sit-for-seconds
+This option specifies how many seconds to wait between execution steps
+in trace mode.  The default is 1 second.
+@end defopt
+
+@node Jumping
+@subsection Jumping
+
+  The commands described in this section execute until they reach a
+specified location.  All except @kbd{i} make a temporary breakpoint to
+establish the place to stop, then switch to go mode.  Any other
+breakpoint reached before the intended stop point will also stop
+execution.  @xref{Breakpoints}, for the details on breakpoints.
+
+  These commands may fail to work as expected in case of nonlocal exit,
+as that can bypass the temporary breakpoint where you expected the
+program to stop.
+
+@table @kbd
+@item h
+Proceed to the stop point near where point is (@code{edebug-goto-here}).
+
+@item f
+Run the program for one expression
+(@code{edebug-forward-sexp}).
+
+@item o
+Run the program until the end of the containing sexp.
+
+@item i
+Step into the function or macro called by the form after point.
+@end table
+
+The @kbd{h} command proceeds to the stop point at or after the current
+location of point, using a temporary breakpoint.
+
+The @kbd{f} command runs the program forward over one expression.  More
+precisely, it sets a temporary breakpoint at the position that
+@kbd{C-M-f} would reach, then executes in go mode so that the program
+will stop at breakpoints.
+
+With a prefix argument @var{n}, the temporary breakpoint is placed
+@var{n} sexps beyond point.  If the containing list ends before @var{n}
+more elements, then the place to stop is after the containing
+expression.
+
+You must check that the position @kbd{C-M-f} finds is a place that the
+program will really get to.  In @code{cond}, for example, this may not
+be true.
+
+For flexibility, the @kbd{f} command does @code{forward-sexp} starting
+at point, rather than at the stop point.  If you want to execute one
+expression @emph{from the current stop point}, first type @kbd{w}, to
+move point there, and then type @kbd{f}.
+
+The @kbd{o} command continues ``out of'' an expression.  It places a
+temporary breakpoint at the end of the sexp containing point.  If the
+containing sexp is a function definition itself, @kbd{o} continues until
+just before the last sexp in the definition.  If that is where you are
+now, it returns from the function and then stops.  In other words, this
+command does not exit the currently executing function unless you are
+positioned after the last sexp.
+
+The @kbd{i} command steps into the function or macro called by the list
+form after point, and stops at its first stop point.  Note that the form
+need not be the one about to be evaluated.  But if the form is a
+function call about to be evaluated, remember to use this command before
+any of the arguments are evaluated, since otherwise it will be too late.
+
+The @kbd{i} command instruments the function or macro it's supposed to
+step into, if it isn't instrumented already.  This is convenient, but keep
+in mind that the function or macro remains instrumented unless you explicitly
+arrange to deinstrument it.
+
+@node Edebug Misc
+@subsection Miscellaneous Edebug Commands
+
+  Some miscellaneous Edebug commands are described here.
+
+@table @kbd
+@item ?
+Display the help message for Edebug (@code{edebug-help}).
+
+@item C-]
+Abort one level back to the previous command level
+(@code{abort-recursive-edit}).
+
+@item q
+Return to the top level editor command loop (@code{top-level}).  This
+exits all recursive editing levels, including all levels of Edebug
+activity.  However, instrumented code protected with
+@code{unwind-protect} or @code{condition-case} forms may resume
+debugging.
+
+@item Q
+Like @kbd{q}, but don't stop even for protected code
+(@code{top-level-nonstop}).
+
+@item r
+Redisplay the most recently known expression result in the echo area
+(@code{edebug-previous-result}).
+
+@item d
+Display a backtrace, excluding Edebug's own functions for clarity
+(@code{edebug-backtrace}).
+
+You cannot use debugger commands in the backtrace buffer in Edebug as
+you would in the standard debugger.
+
+The backtrace buffer is killed automatically when you continue
+execution.
+@end table
+
+You can invoke commands from Edebug that activate Edebug again
+recursively.  Whenever Edebug is active, you can quit to the top level
+with @kbd{q} or abort one recursive edit level with @kbd{C-]}.  You can
+display a backtrace of all the pending evaluations with @kbd{d}.
+
+@node Breaks
+@subsection Breaks
+
+Edebug's step mode stops execution when the next stop point is reached.
+There are three other ways to stop Edebug execution once it has started:
+breakpoints, the global break condition, and source breakpoints.
+
+@menu
+* Breakpoints::                 Breakpoints at stop points.
+* Global Break Condition::	Breaking on an event.
+* Source Breakpoints::  	Embedding breakpoints in source code.
+@end menu
+
+@node Breakpoints
+@subsubsection Edebug Breakpoints
+
+@cindex breakpoints (Edebug)
+While using Edebug, you can specify @dfn{breakpoints} in the program you
+are testing: these are places where execution should stop.  You can set a
+breakpoint at any stop point, as defined in @ref{Using Edebug}.  For
+setting and unsetting breakpoints, the stop point that is affected is
+the first one at or after point in the source code buffer.  Here are the
+Edebug commands for breakpoints:
+
+@table @kbd
+@item b
+Set a breakpoint at the stop point at or after point
+(@code{edebug-set-breakpoint}).  If you use a prefix argument, the
+breakpoint is temporary---it turns off the first time it stops the
+program.
+
+@item u
+Unset the breakpoint (if any) at the stop point at or after
+point (@code{edebug-unset-breakpoint}).
+
+@item x @var{condition} @key{RET}
+Set a conditional breakpoint which stops the program only if
+evaluating @var{condition} produces a non-@code{nil} value
+(@code{edebug-set-conditional-breakpoint}).  With a prefix argument,
+the breakpoint is temporary.
+
+@item B
+Move point to the next breakpoint in the current definition
+(@code{edebug-next-breakpoint}).
+@end table
+
+While in Edebug, you can set a breakpoint with @kbd{b} and unset one
+with @kbd{u}.  First move point to the Edebug stop point of your choice,
+then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
+Unsetting a breakpoint where none has been set has no effect.
+
+Re-evaluating or reinstrumenting a definition removes all of its
+previous breakpoints.
+
+A @dfn{conditional breakpoint} tests a condition each time the program
+gets there.  Any errors that occur as a result of evaluating the
+condition are ignored, as if the result were @code{nil}.  To set a
+conditional breakpoint, use @kbd{x}, and specify the condition
+expression in the minibuffer.  Setting a conditional breakpoint at a
+stop point that has a previously established conditional breakpoint puts
+the previous condition expression in the minibuffer so you can edit it.
+
+You can make a conditional or unconditional breakpoint
+@dfn{temporary} by using a prefix argument with the command to set the
+breakpoint.  When a temporary breakpoint stops the program, it is
+automatically unset.
+
+Edebug always stops or pauses at a breakpoint, except when the Edebug
+mode is Go-nonstop.  In that mode, it ignores breakpoints entirely.
+
+To find out where your breakpoints are, use the @kbd{B} command, which
+moves point to the next breakpoint following point, within the same
+function, or to the first breakpoint if there are no following
+breakpoints.  This command does not continue execution---it just moves
+point in the buffer.
+
+@node Global Break Condition
+@subsubsection Global Break Condition
+
+@cindex stopping on events
+@cindex global break condition
+  A @dfn{global break condition} stops execution when a specified
+condition is satisfied, no matter where that may occur.  Edebug
+evaluates the global break condition at every stop point; if it
+evaluates to a non-@code{nil} value, then execution stops or pauses
+depending on the execution mode, as if a breakpoint had been hit.  If
+evaluating the condition gets an error, execution does not stop.
+
+@findex edebug-set-global-break-condition
+  The condition expression is stored in
+@code{edebug-global-break-condition}.  You can specify a new expression
+using the @kbd{X} command from the source code buffer while Edebug is
+active, or using @kbd{C-x X X} from any buffer at any time, as long as
+Edebug is loaded (@code{edebug-set-global-break-condition}).
+
+  The global break condition is the simplest way to find where in your
+code some event occurs, but it makes code run much more slowly.  So you
+should reset the condition to @code{nil} when not using it.
+
+@node Source Breakpoints
+@subsubsection Source Breakpoints
+
+@findex edebug
+@cindex source breakpoints
+  All breakpoints in a definition are forgotten each time you
+reinstrument it.  If you wish to make a breakpoint that won't be
+forgotten, you can write a @dfn{source breakpoint}, which is simply a
+call to the function @code{edebug} in your source code.  You can, of
+course, make such a call conditional.  For example, in the @code{fac}
+function, you can insert the first line as shown below, to stop when the
+argument reaches zero:
+
+@example
+(defun fac (n)
+  (if (= n 0) (edebug))
+  (if (< 0 n)
+      (* n (fac (1- n)))
+    1))
+@end example
+
+  When the @code{fac} definition is instrumented and the function is
+called, the call to @code{edebug} acts as a breakpoint.  Depending on
+the execution mode, Edebug stops or pauses there.
+
+  If no instrumented code is being executed when @code{edebug} is called,
+that function calls @code{debug}.
+@c This may not be a good idea anymore.
+
+@node Trapping Errors
+@subsection Trapping Errors
+
+  Emacs normally displays an error message when an error is signaled and
+not handled with @code{condition-case}.  While Edebug is active and
+executing instrumented code, it normally responds to all unhandled
+errors.  You can customize this with the options @code{edebug-on-error}
+and @code{edebug-on-quit}; see @ref{Edebug Options}.
+
+  When Edebug responds to an error, it shows the last stop point
+encountered before the error.  This may be the location of a call to a
+function which was not instrumented, and within which the error actually
+occurred.  For an unbound variable error, the last known stop point
+might be quite distant from the offending variable reference.  In that
+case, you might want to display a full backtrace (@pxref{Edebug Misc}).
+
+@c Edebug should be changed for the following: -- dan
+  If you change @code{debug-on-error} or @code{debug-on-quit} while
+Edebug is active, these changes will be forgotten when Edebug becomes
+inactive.  Furthermore, during Edebug's recursive edit, these variables
+are bound to the values they had outside of Edebug.
+
+@node Edebug Views
+@subsection Edebug Views
+
+  These Edebug commands let you view aspects of the buffer and window
+status as they were before entry to Edebug.  The outside window
+configuration is the collection of windows and contents that were in
+effect outside of Edebug.
+
+@table @kbd
+@item v
+Switch to viewing the outside window configuration
+(@code{edebug-view-outside}).  Type @kbd{C-x X w} to return to Edebug.
+
+@item p
+Temporarily display the outside current buffer with point at its
+outside position (@code{edebug-bounce-point}), pausing for one second
+before returning to Edebug.  With a prefix argument @var{n}, pause for
+@var{n} seconds instead.
+
+@item w
+Move point back to the current stop point in the source code buffer
+(@code{edebug-where}).
+
+If you use this command in a different window displaying the same
+buffer, that window will be used instead to display the current
+definition in the future.
+
+@item W
+@c Its function is not simply to forget the saved configuration -- dan
+Toggle whether Edebug saves and restores the outside window
+configuration (@code{edebug-toggle-save-windows}).
+
+With a prefix argument, @code{W} only toggles saving and restoring of
+the selected window.  To specify a window that is not displaying the
+source code buffer, you must use @kbd{C-x X W} from the global keymap.
+@end table
+
+  You can view the outside window configuration with @kbd{v} or just
+bounce to the point in the current buffer with @kbd{p}, even if
+it is not normally displayed.
+
+  After moving point, you may wish to jump back to the stop point.
+You can do that with @kbd{w} from a source code buffer.  You can jump
+back to the stop point in the source code buffer from any buffer using
+@kbd{C-x X w}.
+
+  Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
+saved outside window configuration---so that even if you turn saving
+back @emph{on}, the current window configuration remains unchanged when
+you next exit Edebug (by continuing the program).  However, the
+automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
+conflict with the buffers you wish to see unless you have enough windows
+open.
+
+@node Edebug Eval
+@subsection Evaluation
+
+  While within Edebug, you can evaluate expressions ``as if'' Edebug
+were not running.  Edebug tries to be invisible to the expression's
+evaluation and printing.  Evaluation of expressions that cause side
+effects will work as expected, except for changes to data that Edebug
+explicitly saves and restores.  @xref{The Outside Context}, for details
+on this process.
+
+@table @kbd
+@item e @var{exp} @key{RET}
+Evaluate expression @var{exp} in the context outside of Edebug
+(@code{edebug-eval-expression}).  That is, Edebug tries to minimize its
+interference with the evaluation.
+
+@item M-: @var{exp} @key{RET}
+Evaluate expression @var{exp} in the context of Edebug itself.
+
+@item C-x C-e
+Evaluate the expression before point, in the context outside of Edebug
+(@code{edebug-eval-last-sexp}).
+@end table
+
+@cindex lexical binding (Edebug)
+  Edebug supports evaluation of expressions containing references to
+lexically bound symbols created by the following constructs in
+@file{cl.el} (version 2.03 or later): @code{lexical-let},
+@code{macrolet}, and @code{symbol-macrolet}.
+
+@node Eval List
+@subsection Evaluation List Buffer
+
+  You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
+evaluate expressions interactively.  You can also set up the
+@dfn{evaluation list} of expressions to be evaluated automatically each
+time Edebug updates the display.
+
+@table @kbd
+@item E
+Switch to the evaluation list buffer @samp{*edebug*}
+(@code{edebug-visit-eval-list}).
+@end table
+
+  In the @samp{*edebug*} buffer you can use the commands of Lisp
+Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
+Manual}) as well as these special commands:
+
+@table @kbd
+@item C-j
+Evaluate the expression before point, in the outside context, and insert
+the value in the buffer (@code{edebug-eval-print-last-sexp}).
+
+@item C-x C-e
+Evaluate the expression before point, in the context outside of Edebug
+(@code{edebug-eval-last-sexp}).
+
+@item C-c C-u
+Build a new evaluation list from the contents of the buffer
+(@code{edebug-update-eval-list}).
+
+@item C-c C-d
+Delete the evaluation list group that point is in
+(@code{edebug-delete-eval-item}).
+
+@item C-c C-w
+Switch back to the source code buffer at the current stop point
+(@code{edebug-where}).
+@end table
+
+  You can evaluate expressions in the evaluation list window with
+@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
+but they are evaluated in the context outside of Edebug.
+
+  The expressions you enter interactively (and their results) are lost
+when you continue execution; but you can set up an @dfn{evaluation list}
+consisting of expressions to be evaluated each time execution stops.
+
+@cindex evaluation list group
+  To do this, write one or more @dfn{evaluation list groups} in the
+evaluation list buffer.  An evaluation list group consists of one or
+more Lisp expressions.  Groups are separated by comment lines.
+
+  The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
+evaluation list, scanning the buffer and using the first expression of
+each group.  (The idea is that the second expression of the group is the
+value previously computed and displayed.)
+
+  Each entry to Edebug redisplays the evaluation list by inserting each
+expression in the buffer, followed by its current value.  It also
+inserts comment lines so that each expression becomes its own group.
+Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
+the evaluation list is effectively unchanged.
+
+  If an error occurs during an evaluation from the evaluation list, the
+error message is displayed in a string as if it were the result.
+Therefore, expressions that use variables not currently valid do not
+interrupt your debugging.
+
+  Here is an example of what the evaluation list window looks like after
+several expressions have been added to it:
+
+@smallexample
+(current-buffer)
+#<buffer *scratch*>
+;---------------------------------------------------------------
+(selected-window)
+#<window 16 on *scratch*>
+;---------------------------------------------------------------
+(point)
+196
+;---------------------------------------------------------------
+bad-var
+"Symbol's value as variable is void: bad-var"
+;---------------------------------------------------------------
+(recursion-depth)
+0
+;---------------------------------------------------------------
+this-command
+eval-last-sexp
+;---------------------------------------------------------------
+@end smallexample
+
+To delete a group, move point into it and type @kbd{C-c C-d}, or simply
+delete the text for the group and update the evaluation list with
+@kbd{C-c C-u}.  To add a new expression to the evaluation list, insert
+the expression at a suitable place, insert a new comment line, then type
+@kbd{C-c C-u}.  You need not insert dashes in the comment line---its
+contents don't matter.
+
+After selecting @samp{*edebug*}, you can return to the source code
+buffer with @kbd{C-c C-w}.  The @samp{*edebug*} buffer is killed when
+you continue execution, and recreated next time it is needed.
+
+@node Printing in Edebug
+@subsection Printing in Edebug
+
+@cindex printing (Edebug)
+@cindex printing circular structures
+@pindex cust-print
+  If an expression in your program produces a value containing circular
+list structure, you may get an error when Edebug attempts to print it.
+
+  One way to cope with circular structure is to set @code{print-length}
+or @code{print-level} to truncate the printing.  Edebug does this for
+you; it binds @code{print-length} and @code{print-level} to 50 if they
+were @code{nil}.  (Actually, the variables @code{edebug-print-length}
+and @code{edebug-print-level} specify the values to use within Edebug.)
+@xref{Output Variables}.
+
+@defopt edebug-print-length
+If non-@code{nil}, Edebug binds @code{print-length} to this value while
+printing results.  The default value is @code{50}.
+@end defopt
+
+@defopt edebug-print-level
+If non-@code{nil}, Edebug binds @code{print-level} to this value while
+printing results.  The default value is @code{50}.
+@end defopt
+
+  You can also print circular structures and structures that share
+elements more informatively by binding @code{print-circle}
+to a non-@code{nil} value.
+
+  Here is an example of code that creates a circular structure:
+
+@example
+(setq a '(x y))
+(setcar a a)
+@end example
+
+@noindent
+Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
+@samp{#1=} notation labels the structure that follows it with the label
+@samp{1}, and the @samp{#1#} notation references the previously labeled
+structure.  This notation is used for any shared elements of lists or
+vectors.
+
+@defopt edebug-print-circle
+If non-@code{nil}, Edebug binds @code{print-circle} to this value while
+printing results.  The default value is @code{t}.
+@end defopt
+
+  Other programs can also use custom printing; see @file{cust-print.el}
+for details.
+
+@node Trace Buffer
+@subsection Trace Buffer
+@cindex trace buffer
+
+  Edebug can record an execution trace, storing it in a buffer named
+@samp{*edebug-trace*}.  This is a log of function calls and returns,
+showing the function names and their arguments and values.  To enable
+trace recording, set @code{edebug-trace} to a non-@code{nil} value.
+
+  Making a trace buffer is not the same thing as using trace execution
+mode (@pxref{Edebug Execution Modes}).
+
+  When trace recording is enabled, each function entry and exit adds
+lines to the trace buffer.  A function entry record consists of
+@samp{::::@{}, followed by the function name and argument values.  A
+function exit record consists of @samp{::::@}}, followed by the function
+name and result of the function.
+
+  The number of @samp{:}s in an entry shows its recursion depth.  You
+can use the braces in the trace buffer to find the matching beginning or
+end of function calls.
+
+@findex edebug-print-trace-before
+@findex edebug-print-trace-after
+  You can customize trace recording for function entry and exit by
+redefining the functions @code{edebug-print-trace-before} and
+@code{edebug-print-trace-after}.
+
+@defmac edebug-tracing string body@dots{}
+This macro requests additional trace information around the execution
+of the @var{body} forms.  The argument @var{string} specifies text
+to put in the trace buffer, after the @samp{@{} or @samp{@}}.  All
+the arguments are evaluated, and @code{edebug-tracing} returns the
+value of the last form in @var{body}.
+@end defmac
+
+@defun edebug-trace format-string &rest format-args
+This function inserts text in the trace buffer.  It computes the text
+with @code{(apply 'format @var{format-string} @var{format-args})}.
+It also appends a newline to separate entries.
+@end defun
+
+  @code{edebug-tracing} and @code{edebug-trace} insert lines in the
+trace buffer whenever they are called, even if Edebug is not active.
+Adding text to the trace buffer also scrolls its window to show the last
+lines inserted.
+
+@node Coverage Testing
+@subsection Coverage Testing
+
+@cindex coverage testing (Edebug)
+@cindex frequency counts
+@cindex performance analysis
+  Edebug provides rudimentary coverage testing and display of execution
+frequency.
+
+  Coverage testing works by comparing the result of each expression with
+the previous result; each form in the program is considered ``covered''
+if it has returned two different values since you began testing coverage
+in the current Emacs session.  Thus, to do coverage testing on your
+program, execute it under various conditions and note whether it behaves
+correctly; Edebug will tell you when you have tried enough different
+conditions that each form has returned two different values.
+
+  Coverage testing makes execution slower, so it is only done if
+@code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
+performed for all execution of an instrumented function, even if the
+execution mode is Go-nonstop, and regardless of whether coverage testing
+is enabled.
+
+@kindex C-x X =
+@findex edebug-temp-display-freq-count
+  Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
+the coverage information and the frequency counts for a definition.
+Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
+information temporarily, only until you type another key.
+
+@deffn Command edebug-display-freq-count
+This command displays the frequency count data for each line of the
+current definition.
+
+The frequency counts appear as comment lines after each line of code,
+and you can undo all insertions with one @code{undo} command.  The
+counts appear under the @samp{(} before an expression or the @samp{)}
+after an expression, or on the last character of a variable.  To
+simplify the display, a count is not shown if it is equal to the
+count of an earlier expression on the same line.
+
+The character @samp{=} following the count for an expression says that
+the expression has returned the same value each time it was evaluated.
+In other words, it is not yet ``covered'' for coverage testing purposes.
+
+To clear the frequency count and coverage data for a definition,
+simply reinstrument it with @code{eval-defun}.
+@end deffn
+
+For example, after evaluating @code{(fac 5)} with a source
+breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
+the breakpoint is reached, the frequency data looks like this:
+
+@example
+(defun fac (n)
+  (if (= n 0) (edebug))
+;#6           1      = =5
+  (if (< 0 n)
+;#5         =
+      (* n (fac (1- n)))
+;#    5               0
+    1))
+;#   0
+@end example
+
+The comment lines show that @code{fac} was called 6 times.  The
+first @code{if} statement returned 5 times with the same result each
+time; the same is true of the condition on the second @code{if}.
+The recursive call of @code{fac} did not return at all.
+
+
+@node The Outside Context
+@subsection The Outside Context
+
+Edebug tries to be transparent to the program you are debugging, but it
+does not succeed completely.  Edebug also tries to be transparent when
+you evaluate expressions with @kbd{e} or with the evaluation list
+buffer, by temporarily restoring the outside context.  This section
+explains precisely what context Edebug restores, and how Edebug fails to
+be completely transparent.
+
+@menu
+* Checking Whether to Stop::	When Edebug decides what to do.
+* Edebug Display Update::	When Edebug updates the display.
+* Edebug Recursive Edit::	When Edebug stops execution.
+@end menu
+
+@node Checking Whether to Stop
+@subsubsection Checking Whether to Stop
+
+Whenever Edebug is entered, it needs to save and restore certain data
+before even deciding whether to make trace information or stop the
+program.
+
+@itemize @bullet
+@item
+@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
+incremented once to reduce Edebug's impact on the stack.  You could,
+however, still run out of stack space when using Edebug.
+
+@item
+The state of keyboard macro execution is saved and restored.  While
+Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
+unless @code{edebug-continue-kbd-macro} is non-@code{nil}.
+@end itemize
+
+
+@node Edebug Display Update
+@subsubsection Edebug Display Update
+
+@c This paragraph is not filled, because LaLiberte's conversion script
+@c needs an xref to be on just one line.
+When Edebug needs to display something (e.g., in trace mode), it saves
+the current window configuration from ``outside'' Edebug
+(@pxref{Window Configurations}).  When you exit Edebug (by continuing
+the program), it restores the previous window configuration.
+
+Emacs redisplays only when it pauses.  Usually, when you continue
+execution, the program re-enters Edebug at a breakpoint or after
+stepping, without pausing or reading input in between.  In such cases,
+Emacs never gets a chance to redisplay the ``outside'' configuration.
+Consequently, what you see is the same window configuration as the last
+time Edebug was active, with no interruption.
+
+Entry to Edebug for displaying something also saves and restores the
+following data (though some of them are deliberately not restored if an
+error or quit signal occurs).
+
+@itemize @bullet
+@item
+@cindex current buffer point and mark (Edebug)
+Which buffer is current, and the positions of point and the mark in the
+current buffer, are saved and restored.
+
+@item
+@cindex window configuration (Edebug)
+The outside window configuration is saved and restored if
+@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}).
+
+The window configuration is not restored on error or quit, but the
+outside selected window @emph{is} reselected even on error or quit in
+case a @code{save-excursion} is active.  If the value of
+@code{edebug-save-windows} is a list, only the listed windows are saved
+and restored.
+
+The window start and horizontal scrolling of the source code buffer are
+not restored, however, so that the display remains coherent within Edebug.
+
+@item
+The value of point in each displayed buffer is saved and restored if
+@code{edebug-save-displayed-buffer-points} is non-@code{nil}.
+
+@item
+The variables @code{overlay-arrow-position} and
+@code{overlay-arrow-string} are saved and restored.  So you can safely
+invoke Edebug from the recursive edit elsewhere in the same buffer.
+
+@item
+@code{cursor-in-echo-area} is locally bound to @code{nil} so that
+the cursor shows up in the window.
+@end itemize
+
+@node Edebug Recursive Edit
+@subsubsection Edebug Recursive Edit
+
+When Edebug is entered and actually reads commands from the user, it
+saves (and later restores) these additional data:
+
+@itemize @bullet
+@item
+The current match data.  @xref{Match Data}.
+
+@item
+The variables @code{last-command}, @code{this-command},
+@code{last-command-char}, @code{last-input-char},
+@code{last-input-event}, @code{last-command-event},
+@code{last-event-frame}, @code{last-nonmenu-event}, and
+@code{track-mouse}.  Commands used within Edebug do not affect these
+variables outside of Edebug.
+
+Executing commands within Edebug can change the key sequence that
+would be returned by @code{this-command-keys}, and there is no way to
+reset the key sequence from Lisp.
+
+Edebug cannot save and restore the value of
+@code{unread-command-events}.  Entering Edebug while this variable has a
+nontrivial value can interfere with execution of the program you are
+debugging.
+
+@item
+Complex commands executed while in Edebug are added to the variable
+@code{command-history}.  In rare cases this can alter execution.
+
+@item
+Within Edebug, the recursion depth appears one deeper than the recursion
+depth outside Edebug.  This is not true of the automatically updated
+evaluation list window.
+
+@item
+@code{standard-output} and @code{standard-input} are bound to @code{nil}
+by the @code{recursive-edit}, but Edebug temporarily restores them during
+evaluations.
+
+@item
+The state of keyboard macro definition is saved and restored.  While
+Edebug is active, @code{defining-kbd-macro} is bound to
+@code{edebug-continue-kbd-macro}.
+@end itemize
+
+@node Edebug and Macros
+@subsection Edebug and Macros
+
+To make Edebug properly instrument expressions that call macros, some
+extra care is needed.  This subsection explains the details.
+
+@menu
+* Instrumenting Macro Calls::   The basic problem.
+* Specification List::		How to specify complex patterns of evaluation.
+* Backtracking::		What Edebug does when matching fails.
+* Specification Examples::	To help understand specifications.
+@end menu
+
+@node Instrumenting Macro Calls
+@subsubsection Instrumenting Macro Calls
+
+  When Edebug instruments an expression that calls a Lisp macro, it needs
+additional information about the macro to do the job properly.  This is
+because there is no a-priori way to tell which subexpressions of the
+macro call are forms to be evaluated.  (Evaluation may occur explicitly
+in the macro body, or when the resulting expansion is evaluated, or any
+time later.)
+
+  Therefore, you must define an Edebug specification for each macro
+that Edebug will encounter, to explain the format of calls to that
+macro.  To do this, add a @code{debug} declaration to the macro
+definition.  Here is a simple example that shows the specification for
+the @code{for} example macro (@pxref{Argument Evaluation}).
+
+@smallexample
+(defmacro for (var from init to final do &rest body)
+  "Execute a simple \"for\" loop.
+For example, (for i from 1 to 10 do (print i))."
+  (declare (debug (symbolp "from" form "to" form "do" &rest form)))
+  ...)
+@end smallexample
+
+  The Edebug specification says which parts of a call to the macro are
+forms to be evaluated.  For simple macros, the @var{specification}
+often looks very similar to the formal argument list of the macro
+definition, but specifications are much more general than macro
+arguments.  @xref{Defining Macros}, for more explanation of
+the @code{declare} form.
+
+  You can also define an edebug specification for a macro separately
+from the macro definition with @code{def-edebug-spec}.  Adding
+@code{debug} declarations is preferred, and more convenient, for macro
+definitions in Lisp, but @code{def-edebug-spec} makes it possible to
+define Edebug specifications for special forms implemented in C.
+
+@deffn Macro def-edebug-spec macro specification
+Specify which expressions of a call to macro @var{macro} are forms to be
+evaluated.  @var{specification} should be the edebug specification.
+Neither argument is evaluated.
+
+The @var{macro} argument can actually be any symbol, not just a macro
+name.
+@end deffn
+
+Here is a table of the possibilities for @var{specification} and how each
+directs processing of arguments.
+
+@table @asis
+@item @code{t}
+All arguments are instrumented for evaluation.
+
+@item @code{0}
+None of the arguments is instrumented.
+
+@item a symbol
+The symbol must have an Edebug specification which is used instead.
+This indirection is repeated until another kind of specification is
+found.  This allows you to inherit the specification from another macro.
+
+@item a list
+The elements of the list describe the types of the arguments of a
+calling form.  The possible elements of a specification list are
+described in the following sections.
+@end table
+
+@vindex edebug-eval-macro-args
+If a macro has no Edebug specification, neither through a @code{debug}
+declaration nor through a @code{def-edebug-spec} call, the variable
+@code{edebug-eval-macro-args} comes into play.  If it is @code{nil},
+the default, none of the arguments is instrumented for evaluation.
+If it is non-@code{nil}, all arguments are instrumented.
+
+@node Specification List
+@subsubsection Specification List
+
+@cindex Edebug specification list
+A @dfn{specification list} is required for an Edebug specification if
+some arguments of a macro call are evaluated while others are not.  Some
+elements in a specification list match one or more arguments, but others
+modify the processing of all following elements.  The latter, called
+@dfn{specification keywords}, are symbols beginning with @samp{&} (such
+as @code{&optional}).
+
+A specification list may contain sublists which match arguments that are
+themselves lists, or it may contain vectors used for grouping.  Sublists
+and groups thus subdivide the specification list into a hierarchy of
+levels.  Specification keywords apply only to the remainder of the
+sublist or group they are contained in.
+
+When a specification list involves alternatives or repetition, matching
+it against an actual macro call may require backtracking.
+@xref{Backtracking}, for more details.
+
+Edebug specifications provide the power of regular expression matching,
+plus some context-free grammar constructs: the matching of sublists with
+balanced parentheses, recursive processing of forms, and recursion via
+indirect specifications.
+
+Here's a table of the possible elements of a specification list, with
+their meanings (see @ref{Specification Examples}, for the referenced
+examples):
+
+@table @code
+@item sexp
+A single unevaluated Lisp object, which is not instrumented.
+@c an "expression" is not necessarily intended for evaluation.
+
+@item form
+A single evaluated expression, which is instrumented.
+
+@item place
+@findex edebug-unwrap
+A place to store a value, as in the Common Lisp @code{setf} construct.
+
+@item body
+Short for @code{&rest form}.  See @code{&rest} below.
+
+@item function-form
+A function form: either a quoted function symbol, a quoted lambda
+expression, or a form (that should evaluate to a function symbol or
+lambda expression).  This is useful when an argument that's a lambda
+expression might be quoted with @code{quote} rather than
+@code{function}, since it instruments the body of the lambda expression
+either way.
+
+@item lambda-expr
+A lambda expression with no quoting.
+
+@item &optional
+@c @kindex &optional @r{(Edebug)}
+All following elements in the specification list are optional; as soon
+as one does not match, Edebug stops matching at this level.
+
+To make just a few elements optional followed by non-optional elements,
+use @code{[&optional @var{specs}@dots{}]}.  To specify that several
+elements must all match or none, use @code{&optional
+[@var{specs}@dots{}]}.  See the @code{defun} example.
+
+@item &rest
+@c @kindex &rest @r{(Edebug)}
+All following elements in the specification list are repeated zero or
+more times.  In the last repetition, however, it is not a problem if the
+expression runs out before matching all of the elements of the
+specification list.
+
+To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
+To specify several elements that must all match on every repetition, use
+@code{&rest [@var{specs}@dots{}]}.
+
+@item &or
+@c @kindex &or @r{(Edebug)}
+Each of the following elements in the specification list is an
+alternative.  One of the alternatives must match, or the @code{&or}
+specification fails.
+
+Each list element following @code{&or} is a single alternative.  To
+group two or more list elements as a single alternative, enclose them in
+@code{[@dots{}]}.
+
+@item &not
+@c @kindex &not @r{(Edebug)}
+Each of the following elements is matched as alternatives as if by using
+@code{&or}, but if any of them match, the specification fails.  If none
+of them match, nothing is matched, but the @code{&not} specification
+succeeds.
+
+@item &define
+@c @kindex &define @r{(Edebug)}
+Indicates that the specification is for a defining form.  The defining
+form itself is not instrumented (that is, Edebug does not stop before and
+after the defining form), but forms inside it typically will be
+instrumented.  The @code{&define} keyword should be the first element in
+a list specification.
+
+@item nil
+This is successful when there are no more arguments to match at the
+current argument list level; otherwise it fails.  See sublist
+specifications and the backquote example.
+
+@item gate
+@cindex preventing backtracking
+No argument is matched but backtracking through the gate is disabled
+while matching the remainder of the specifications at this level.  This
+is primarily used to generate more specific syntax error messages.  See
+@ref{Backtracking}, for more details.  Also see the @code{let} example.
+
+@item @var{other-symbol}
+@cindex indirect specifications
+Any other symbol in a specification list may be a predicate or an
+indirect specification.
+
+If the symbol has an Edebug specification, this @dfn{indirect
+specification} should be either a list specification that is used in
+place of the symbol, or a function that is called to process the
+arguments.  The specification may be defined with @code{def-edebug-spec}
+just as for macros. See the @code{defun} example.
+
+Otherwise, the symbol should be a predicate.  The predicate is called
+with the argument and the specification fails if the predicate returns
+@code{nil}.  In either case, that argument is not instrumented.
+
+Some suitable predicates include @code{symbolp}, @code{integerp},
+@code{stringp}, @code{vectorp}, and @code{atom}.
+
+@item [@var{elements}@dots{}]
+@cindex [@dots{}] (Edebug)
+A vector of elements groups the elements into a single @dfn{group
+specification}.  Its meaning has nothing to do with vectors.
+
+@item "@var{string}"
+The argument should be a symbol named @var{string}.  This specification
+is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
+of @var{symbol} is the @var{string}, but the string form is preferred.
+
+@item (vector @var{elements}@dots{})
+The argument should be a vector whose elements must match the
+@var{elements} in the specification.  See the backquote example.
+
+@item (@var{elements}@dots{})
+Any other list is a @dfn{sublist specification} and the argument must be
+a list whose elements match the specification @var{elements}.
+
+@cindex dotted lists (Edebug)
+A sublist specification may be a dotted list and the corresponding list
+argument may then be a dotted list.  Alternatively, the last @sc{cdr} of a
+dotted list specification may be another sublist specification (via a
+grouping or an indirect specification, e.g., @code{(spec .  [(more
+specs@dots{})])}) whose elements match the non-dotted list arguments.
+This is useful in recursive specifications such as in the backquote
+example.  Also see the description of a @code{nil} specification
+above for terminating such recursion.
+
+Note that a sublist specification written as @code{(specs .  nil)}
+is equivalent to @code{(specs)}, and @code{(specs .
+(sublist-elements@dots{}))} is equivalent to @code{(specs
+sublist-elements@dots{})}.
+@end table
+
+@c Need to document extensions with &symbol and :symbol
+
+Here is a list of additional specifications that may appear only after
+@code{&define}.  See the @code{defun} example.
+
+@table @code
+@item name
+The argument, a symbol, is the name of the defining form.
+
+A defining form is not required to have a name field; and it may have
+multiple name fields.
+
+@item :name
+This construct does not actually match an argument.  The element
+following @code{:name} should be a symbol; it is used as an additional
+name component for the definition.  You can use this to add a unique,
+static component to the name of the definition.  It may be used more
+than once.
+
+@item arg
+The argument, a symbol, is the name of an argument of the defining form.
+However, lambda-list keywords (symbols starting with @samp{&})
+are not allowed.
+
+@item lambda-list
+@cindex lambda-list (Edebug)
+This matches a lambda list---the argument list of a lambda expression.
+
+@item def-body
+The argument is the body of code in a definition.  This is like
+@code{body}, described above, but a definition body must be instrumented
+with a different Edebug call that looks up information associated with
+the definition.  Use @code{def-body} for the highest level list of forms
+within the definition.
+
+@item def-form
+The argument is a single, highest-level form in a definition.  This is
+like @code{def-body}, except use this to match a single form rather than
+a list of forms.  As a special case, @code{def-form} also means that
+tracing information is not output when the form is executed.  See the
+@code{interactive} example.
+@end table
+
+@node Backtracking
+@subsubsection Backtracking in Specifications
+
+@cindex backtracking
+@cindex syntax error (Edebug)
+If a specification fails to match at some point, this does not
+necessarily mean a syntax error will be signaled; instead,
+@dfn{backtracking} will take place until all alternatives have been
+exhausted.  Eventually every element of the argument list must be
+matched by some element in the specification, and every required element
+in the specification must match some argument.
+
+When a syntax error is detected, it might not be reported until much
+later after higher-level alternatives have been exhausted, and with the
+point positioned further from the real error.  But if backtracking is
+disabled when an error occurs, it can be reported immediately.  Note
+that backtracking is also reenabled automatically in several situations;
+it is reenabled when a new alternative is established by
+@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
+processing a sublist, group, or indirect specification.  The effect of
+enabling or disabling backtracking is limited to the remainder of the
+level currently being processed and lower levels.
+
+Backtracking is disabled while matching any of the
+form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
+@code{def-body}).  These specifications will match any form so any error
+must be in the form itself rather than at a higher level.
+
+Backtracking is also disabled after successfully matching a quoted
+symbol or string specification, since this usually indicates a
+recognized construct.  But if you have a set of alternative constructs that
+all begin with the same symbol, you can usually work around this
+constraint by factoring the symbol out of the alternatives, e.g.,
+@code{["foo" &or [first case] [second case] ...]}.
+
+Most needs are satisfied by these two ways that backtracking is
+automatically disabled, but occasionally it is useful to explicitly
+disable backtracking by using the @code{gate} specification.  This is
+useful when you know that no higher alternatives could apply.  See the
+example of the @code{let} specification.
+
+@node Specification Examples
+@subsubsection Specification Examples
+
+It may be easier to understand Edebug specifications by studying
+the examples provided here.
+
+A @code{let} special form has a sequence of bindings and a body.  Each
+of the bindings is either a symbol or a sublist with a symbol and
+optional expression.  In the specification below, notice the @code{gate}
+inside of the sublist to prevent backtracking once a sublist is found.
+
+@example
+(def-edebug-spec let
+  ((&rest
+    &or symbolp (gate symbolp &optional form))
+   body))
+@end example
+
+Edebug uses the following specifications for @code{defun} and
+@code{defmacro} and the associated argument list and @code{interactive}
+specifications.  It is necessary to handle interactive forms specially
+since an expression argument is actually evaluated outside of the
+function body.
+
+@smallexample
+(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
+(def-edebug-spec defun
+  (&define name lambda-list
+           [&optional stringp]   ; @r{Match the doc string, if present.}
+           [&optional ("interactive" interactive)]
+           def-body))
+
+(def-edebug-spec lambda-list
+  (([&rest arg]
+    [&optional ["&optional" arg &rest arg]]
+    &optional ["&rest" arg]
+    )))
+
+(def-edebug-spec interactive
+  (&optional &or stringp def-form))    ; @r{Notice: @code{def-form}}
+@end smallexample
+
+The specification for backquote below illustrates how to match
+dotted lists and use @code{nil} to terminate recursion.  It also
+illustrates how components of a vector may be matched.  (The actual
+specification defined by Edebug does not support dotted lists because
+doing so causes very deep recursion that could fail.)
+
+@smallexample
+(def-edebug-spec ` (backquote-form))   ; @r{Alias just for clarity.}
+
+(def-edebug-spec backquote-form
+  (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
+       (backquote-form . [&or nil backquote-form])
+       (vector &rest backquote-form)
+       sexp))
+@end smallexample
+
+
+@node Edebug Options
+@subsection Edebug Options
+
+  These options affect the behavior of Edebug:
+
+@defopt edebug-setup-hook
+Functions to call before Edebug is used.  Each time it is set to a new
+value, Edebug will call those functions once and then
+@code{edebug-setup-hook} is reset to @code{nil}.  You could use this to
+load up Edebug specifications associated with a package you are using
+but only when you also use Edebug.
+@xref{Instrumenting}.
+@end defopt
+
+@defopt edebug-all-defs
+If this is non-@code{nil}, normal evaluation of defining forms such as
+@code{defun} and @code{defmacro} instruments them for Edebug.  This
+applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
+and @code{eval-current-buffer}.
+
+Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
+option.  @xref{Instrumenting}.
+@end defopt
+
+@defopt edebug-all-forms
+If this is non-@code{nil}, the commands @code{eval-defun},
+@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
+instrument all forms, even those that don't define anything.
+This doesn't apply to loading or evaluations in the minibuffer.
+
+Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
+option.  @xref{Instrumenting}.
+@end defopt
+
+@defopt edebug-save-windows
+If this is non-@code{nil}, Edebug saves and restores the window
+configuration.  That takes some time, so if your program does not care
+what happens to the window configurations, it is better to set this
+variable to @code{nil}.
+
+If the value is a list, only the listed windows are saved and
+restored.
+
+You can use the @kbd{W} command in Edebug to change this variable
+interactively.  @xref{Edebug Display Update}.
+@end defopt
+
+@defopt edebug-save-displayed-buffer-points
+If this is non-@code{nil}, Edebug saves and restores point in all
+displayed buffers.
+
+Saving and restoring point in other buffers is necessary if you are
+debugging code that changes the point of a buffer which is displayed in
+a non-selected window.  If Edebug or the user then selects the window,
+point in that buffer will move to the window's value of point.
+
+Saving and restoring point in all buffers is expensive, since it
+requires selecting each window twice, so enable this only if you need
+it.  @xref{Edebug Display Update}.
+@end defopt
+
+@defopt edebug-initial-mode
+If this variable is non-@code{nil}, it specifies the initial execution
+mode for Edebug when it is first activated.  Possible values are
+@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
+@code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
+
+The default value is @code{step}.
+@xref{Edebug Execution Modes}.
+@end defopt
+
+@defopt edebug-trace
+If this is non-@code{nil}, trace each function entry and exit.
+Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
+function entry or exit per line, indented by the recursion level.
+
+Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
+@end defopt
+
+@defopt edebug-test-coverage
+If non-@code{nil}, Edebug tests coverage of all expressions debugged.
+@xref{Coverage Testing}.
+@end defopt
+
+@defopt edebug-continue-kbd-macro
+If non-@code{nil}, continue defining or executing any keyboard macro
+that is executing outside of Edebug.   Use this with caution since it is not
+debugged.
+@xref{Edebug Execution Modes}.
+@end defopt
+
+@defopt edebug-on-error
+Edebug binds @code{debug-on-error} to this value, if
+@code{debug-on-error} was previously @code{nil}.  @xref{Trapping
+Errors}.
+@end defopt
+
+@defopt edebug-on-quit
+Edebug binds @code{debug-on-quit} to this value, if
+@code{debug-on-quit} was previously @code{nil}.  @xref{Trapping
+Errors}.
+@end defopt
+
+  If you change the values of @code{edebug-on-error} or
+@code{edebug-on-quit} while Edebug is active, their values won't be used
+until the @emph{next} time Edebug is invoked via a new command.
+@c Not necessarily a deeper command level.
+@c A new command is not precisely true, but that is close enough -- dan
+
+@defopt edebug-global-break-condition
+If non-@code{nil}, an expression to test for at every stop point.  If
+the result is non-@code{nil}, then break.  Errors are ignored.
+@xref{Global Break Condition}.
+@end defopt
+
+@ignore
+   arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
+@end ignore
diff --git a/doc/lispref/elisp-covers.texi b/doc/lispref/elisp-covers.texi
new file mode 100644
index 00000000000..4b9693dece7
--- /dev/null
+++ b/doc/lispref/elisp-covers.texi
@@ -0,0 +1,257 @@
+\input texinfo    @c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
+@c   Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@c
+@comment %**start of header
+@setfilename covers.info
+@settitle GNU Emacs Lisp Reference Manual
+@comment %**end of header
+
+@titlepage
+@c ================ Volume 1 ================
+@w{ }
+@sp 2
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@sp 2
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 2
+@center @titlefont{Volume 1}
+@sp 2
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+
+@page
+@c ================ Volume 2 ================
+@w{ }
+@sp 5
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@sp 2
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 2
+@center @titlefont{Volume 2}
+@sp 2
+@center by Bil Lewis,
+@center Dan LaLiberte, and
+@center the GNU Manual Group
+
+@page
+@c ================ Volume 1 with baseline skip 16pt ================
+
+@tex
+\global\baselineskip = 16pt
+@end tex
+
+16 pts baseline skip:
+
+@w{ }
+@sp 2
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@sp 2
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 2
+@center @titlefont{Volume 1}
+@sp 2
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+
+@page
+@c ================ Volume 1 with baseline skip 18pt ================
+
+@tex
+\global\baselineskip = 18pt
+@end tex
+
+18 pts baseline skip, with 15pts  between sections
+
+@w{ }
+@sp 2
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@tex
+\global\baselineskip = 15pt
+@end tex
+
+@sp 2
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 2
+@center @titlefont{Volume 1}
+@sp 2
+@center by Bil Lewis,
+@center Dan LaLiberte, and
+@center the GNU Manual Group
+
+@page
+@c ================ Volume 1 with more baseline skip 24 pts ================
+
+@tex
+\global\baselineskip = 24pt
+@end tex
+
+24 pts baseline skip:
+
+@w{ }
+@sp 2
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@sp 2
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 2
+@center @titlefont{Volume 1}
+@sp 2
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+
+@page
+@c ================ Volume 2 with more baseline skip 18 pts ================
+
+@tex
+\global\baselineskip = 18pt
+@end tex
+
+18 pts baseline skip:
+
+@w{ }
+@sp 5
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@sp 2
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 2
+@center @titlefont{Volume 2}
+@sp 2
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+
+@page
+@c ================ Volume 2 with more baseline skip 24 pts ================
+
+@tex
+\global\baselineskip = 24pt
+@end tex
+
+24 pts baseline skip:
+
+@w{ }
+@sp 5
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@sp 2
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 2
+@center @titlefont{Volume 2}
+@sp 2
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+
+
+@page
+@c ================  Spine 1 ================
+
+@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 1}}
+@sp 4
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 4
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+
+@sp 4
+@author The GNU Emacs Lisp Reference Manual --- Vol. 1
+@sp 3
+@author FSF
+
+@author
+
+@page
+@c ================  Spine 2 ================
+
+@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 2}}
+@sp 4
+@center GNU Emacs Version 19
+@center for Unix Users
+@center Edition 2.3, June 1994
+@sp 4
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+
+
+@sp 4
+@author The GNU Emacs Lisp Reference Manual --- Vol. 2
+@sp 3
+@author FSF
+
+@end titlepage
+@bye
+
+@ignore
+   arch-tag: 02d65d63-3b64-49bc-a5c0-bfd5eabb6c98
+@end ignore
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
new file mode 100644
index 00000000000..613bdbace38
--- /dev/null
+++ b/doc/lispref/elisp.texi
@@ -0,0 +1,1483 @@
+\input texinfo  @c -*-texinfo-*-
+@c %**start of header
+@setfilename elisp
+@settitle GNU Emacs Lisp Reference Manual
+@c %**end of header
+
+@c Version of the manual and of Emacs.
+@c Please remember to update the edition number in README as well.
+@set VERSION  2.9
+@set EMACSVER 23.0.50
+
+@dircategory Emacs
+@direntry
+* Elisp: (elisp).       The Emacs Lisp Reference Manual.
+@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.1
+\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
+
+@c Combine indices.
+@synindex cp fn
+@syncodeindex vr fn
+@syncodeindex ky fn
+@syncodeindex pg fn
+@c We use the "type index" to index new functions and variables.
+@c @syncodeindex tp fn
+
+@copying
+This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@*
+corresponding to Emacs version @value{EMACSVER}.
+
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 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 ``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
+
+@titlepage
+@title GNU Emacs Lisp Reference Manual
+@subtitle For Emacs Version @value{EMACSVER}
+@subtitle Revision @value{VERSION}, April 2007
+
+@author by Bil Lewis, Dan LaLiberte, Richard Stallman
+@author and the GNU Manual Group
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+
+@sp 2
+Published by the Free Software Foundation @*
+51 Franklin St, Fifth Floor @*
+Boston, MA 02110-1301 @*
+USA @*
+ISBN 1-882114-74-4
+
+@sp 2
+Cover art by Etienne Suvasa.
+@end titlepage
+
+
+@c Print the tables of contents
+@summarycontents
+@contents
+
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Emacs Lisp
+
+This Info file contains edition @value{VERSION} of the GNU Emacs Lisp
+Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
+@end ifnottex
+
+@menu
+* Introduction::            Introduction and conventions used.
+
+* Lisp Data Types::         Data types of objects in Emacs Lisp.
+* Numbers::                 Numbers and arithmetic functions.
+* Strings and Characters::  Strings, and functions that work on them.
+* Lists::                   Lists, cons cells, and related functions.
+* Sequences Arrays Vectors::  Lists, strings and vectors are called sequences.
+                                Certain functions act on any kind of sequence.
+                                The description of vectors is here as well.
+* Hash Tables::             Very fast lookup-tables.
+* Symbols::                 Symbols represent names, uniquely.
+
+* Evaluation::              How Lisp expressions are evaluated.
+* Control Structures::      Conditionals, loops, nonlocal exits.
+* Variables::               Using symbols in programs to stand for values.
+* Functions::               A function is a Lisp program
+                              that can be invoked from other functions.
+* Macros::                  Macros are a way to extend the Lisp language.
+* Customization::           Writing customization declarations.
+
+* Loading::                 Reading files of Lisp code into Lisp.
+* Byte Compilation::        Compilation makes programs run faster.
+* Advising Functions::      Adding to the definition of a function.
+* Debugging::               Tools and tips for debugging Lisp programs.
+
+* Read and Print::          Converting Lisp objects to text and back.
+* Minibuffers::             Using the minibuffer to read input.
+* Command Loop::            How the editor command loop works,
+                              and how you can call its subroutines.
+* Keymaps::                 Defining the bindings from keys to commands.
+* Modes::                   Defining major and minor modes.
+* Documentation::           Writing and using documentation strings.
+
+* Files::                   Accessing files.
+* Backups and Auto-Saving:: Controlling how backups and auto-save
+                              files are made.
+* Buffers::                 Creating and using buffer objects.
+* Windows::                 Manipulating windows and displaying buffers.
+* Frames::		    Making multiple system-level windows.
+* Positions::               Buffer positions and motion functions.
+* Markers::                 Markers represent positions and update
+                              automatically when the text is changed.
+
+* Text::                    Examining and changing text in buffers.
+* Non-ASCII Characters::    Non-ASCII text in buffers and strings.
+* Searching and Matching::  Searching buffers for strings or regexps.
+* Syntax Tables::           The syntax table controls word and list parsing.
+* Abbrevs::                 How Abbrev mode works, and its data structures.
+
+* Processes::               Running and communicating with subprocesses.
+* Display::	            Features for controlling the screen display.
+* System Interface::        Getting the user id, system type, environment
+                              variables, and other such things.
+
+Appendices
+
+* Antinews::                Info for users downgrading to Emacs 21.
+* GNU Free Documentation License:: The license for this documentation
+* GPL::                     Conditions for copying and changing GNU Emacs.
+* Tips::                    Advice and coding conventions for Emacs Lisp.
+* GNU Emacs Internals::     Building and dumping Emacs;
+                              internal data structures.
+* Standard Errors::         List of all error symbols.
+* Standard Buffer-Local Variables::
+                            List of variables buffer-local in all buffers.
+* Standard Keymaps::        List of standard keymaps.
+* Standard Hooks::          List of standard hook variables.
+
+* Index::                   Index including concepts, functions, variables,
+                              and other terms.
+
+@ignore
+* New Symbols::             New functions and variables in Emacs @value{EMACSVER}.
+@end ignore
+
+@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 other nodes that are inferiors of those already listed,
+mentioned here so you can get to them in one step:
+
+Introduction
+
+* Caveats::                 Flaws and a request for help.
+* Lisp History::            Emacs Lisp is descended from Maclisp.
+* Conventions::             How the manual is formatted.
+* Version Info::            Which Emacs version is running?
+* Acknowledgements::        The authors, editors, and sponsors of this manual.
+
+Conventions
+
+* Some Terms::              Explanation of terms we use in this manual.
+* nil and t::               How the symbols @code{nil} and @code{t} are used.
+* Evaluation Notation::     The format we use for examples of evaluation.
+* Printing Notation::       The format we use for examples that print output.
+* Error Messages::          The format we use for examples of errors.
+* Buffer Text Notation::    The format we use for buffer contents in examples.
+* Format of Descriptions::  Notation for describing functions, variables, etc.
+
+Format of Descriptions
+
+* A Sample Function Description::  A description of an imaginary
+                                     function, @code{foo}.
+* A Sample Variable Description::  A description of an imaginary
+                                     variable, @code{electric-future-map}.
+
+Lisp Data Types
+
+* Printed Representation::  How Lisp objects are represented as text.
+* Comments::                Comments and their formatting conventions.
+* Programming Types::       Types found in all Lisp systems.
+* Editing Types::           Types specific to Emacs.
+* Circular Objects::            Read syntax for circular structure.
+* Type Predicates::         Tests related to types.
+* Equality Predicates::     Tests of equality between any two objects.
+
+Programming Types
+
+* Integer Type::        Numbers without fractional parts.
+* Floating Point Type:: Numbers with fractional parts and with a large range.
+* Character Type::      The representation of letters, numbers and
+                          control characters.
+* Symbol Type::         A multi-use object that refers to a function,
+                        variable, property list, or itself.
+* Sequence Type::       Both lists and arrays are classified as sequences.
+* Cons Cell Type::      Cons cells, and lists (which are made from cons cells).
+* Array Type::          Arrays include strings and vectors.
+* String Type::         An (efficient) array of characters.
+* Vector Type::         One-dimensional arrays.
+* Char-Table Type::     One-dimensional sparse arrays indexed by characters.
+* Bool-Vector Type::    One-dimensional arrays of @code{t} or @code{nil}.
+* Hash Table Type::     Super-fast lookup tables.
+* Function Type::       A piece of executable code you can call from elsewhere.
+* Macro Type::          A method of expanding an expression into another
+                          expression, more fundamental but less pretty.
+* Primitive Function Type::     A function written in C, callable from Lisp.
+* Byte-Code Type::      A function written in Lisp, then compiled.
+* Autoload Type::       A type used for automatically loading seldom-used
+                          functions.
+
+Character Type
+
+* Basic Char Syntax::       Syntax for regular characters.
+* General Escape Syntax::   How to specify characters by their codes.
+* Ctl-Char Syntax::         Syntax for control characters.
+* Meta-Char Syntax::        Syntax for meta-characters.
+* Other Char Bits::         Syntax for hyper-, super-, and alt-characters.
+
+Cons Cell and List Types
+
+* Box Diagrams::            Drawing pictures of lists.
+* Dotted Pair Notation::    An alternative syntax for lists.
+* Association List Type::   A specially constructed list.
+
+String Type
+
+* Syntax for Strings::      How to specify Lisp strings.
+* Non-ASCII in Strings::    International characters in strings.
+* Nonprinting Characters::  Literal unprintable characters in strings.
+* Text Props and Strings::  Strings with text properties.
+
+Editing Types
+
+* Buffer Type::             The basic object of editing.
+* Marker Type::             A position in a buffer.
+* Window Type::             What makes buffers visible.
+* Frame Type::		    Windows subdivide frames.
+* Window Configuration Type::  Recording the way a frame is subdivided.
+* Frame Configuration Type::   Recording the status of all frames.
+* Process Type::            A process running on the underlying OS.
+* Stream Type::             Receive or send characters.
+* Keymap Type::             What function a keystroke invokes.
+* Overlay Type::            How an overlay is represented.
+
+Numbers
+
+* Integer Basics::          Representation and range of integers.
+* Float Basics::	    Representation and range of floating point.
+* Predicates on Numbers::   Testing for numbers.
+* Comparison of Numbers::   Equality and inequality predicates.
+* Numeric Conversions::	    Converting float to integer and vice versa.
+* Arithmetic Operations::   How to add, subtract, multiply and divide.
+* Rounding Operations::     Explicitly rounding floating point numbers.
+* Bitwise Operations::      Logical and, or, not, shifting.
+* Math Functions::          Trig, exponential and logarithmic functions.
+* Random Numbers::          Obtaining random integers, predictable or not.
+
+Strings and Characters
+
+* String Basics::           Basic properties of strings and characters.
+* Predicates for Strings::  Testing whether an object is a string or char.
+* Creating Strings::        Functions to allocate new strings.
+* Modifying Strings::         Altering the contents of an existing string.
+* Text Comparison::         Comparing characters or strings.
+* String Conversion::       Converting characters to strings and vice versa.
+* Formatting Strings::      @code{format}: Emacs's analogue of @code{printf}.
+* Case Conversion::         Case conversion functions.
+* Case Tables::		    Customizing case conversion.
+
+Lists
+
+* Cons Cells::              How lists are made out of cons cells.
+* List-related Predicates:: Is this object a list?  Comparing two lists.
+* List Elements::           Extracting the pieces of a list.
+* Building Lists::          Creating list structure.
+* List Variables::          Modifying lists stored in variables.
+* Modifying Lists::         Storing new pieces into an existing list.
+* Sets And Lists::          A list can represent a finite mathematical set.
+* Association Lists::       A list can represent a finite relation or mapping.
+* Rings::                   Managing a fixed-size ring of objects.
+
+Modifying Existing List Structure
+
+* Setcar::                  Replacing an element in a list.
+* Setcdr::                  Replacing part of the list backbone.
+                              This can be used to remove or add elements.
+* Rearrangement::           Reordering the elements in a list; combining lists.
+
+Sequences, Arrays, and Vectors
+
+* Sequence Functions::      Functions that accept any kind of sequence.
+* Arrays::                  Characteristics of arrays in Emacs Lisp.
+* Array Functions::         Functions specifically for arrays.
+* Vectors::                 Special characteristics of Emacs Lisp vectors.
+* Vector Functions::        Functions specifically for vectors.
+* Char-Tables::             How to work with char-tables.
+* Bool-Vectors::            How to work with bool-vectors.
+
+Hash Tables
+
+* Creating Hash::           Functions to create hash tables.
+* Hash Access::             Reading and writing the hash table contents.
+* Defining Hash::           Defining new comparison methods
+* Other Hash::              Miscellaneous.
+
+Symbols
+
+* Symbol Components::       Symbols have names, values, function definitions
+                              and property lists.
+* Definitions::             A definition says how a symbol will be used.
+* Creating Symbols::        How symbols are kept unique.
+* Property Lists::          Each symbol has a property list
+                              for recording miscellaneous information.
+
+Property Lists
+
+* Plists and Alists::       Comparison of the advantages of property
+                              lists and association lists.
+* Symbol Plists::           Functions to access symbols' property lists.
+* Other Plists::            Accessing property lists stored elsewhere.
+
+Evaluation
+
+* Intro Eval::              Evaluation in the scheme of things.
+* Forms::                   How various sorts of objects are evaluated.
+* Quoting::                 Avoiding evaluation (to put constants in
+                              the program).
+* Eval::                    How to invoke the Lisp interpreter explicitly.
+
+Kinds of Forms
+
+* Self-Evaluating Forms::   Forms that evaluate to themselves.
+* Symbol Forms::            Symbols evaluate as variables.
+* Classifying Lists::       How to distinguish various sorts of list forms.
+* Function Indirection::    When a symbol appears as the car of a list,
+			      we find the real function via the symbol.
+* Function Forms::          Forms that call functions.
+* Macro Forms::             Forms that call macros.
+* Special Forms::           "Special forms" are idiosyncratic primitives,
+                              most of them extremely important.
+* Autoloading::             Functions set up to load files
+                              containing their real definitions.
+
+Control Structures
+
+* Sequencing::              Evaluation in textual order.
+* Conditionals::            @code{if}, @code{cond}, @code{when}, @code{unless}.
+* Combining Conditions::    @code{and}, @code{or}, @code{not}.
+* Iteration::               @code{while} loops.
+* Nonlocal Exits::          Jumping out of a sequence.
+
+Nonlocal Exits
+
+* Catch and Throw::         Nonlocal exits for the program's own purposes.
+* Examples of Catch::       Showing how such nonlocal exits can be written.
+* Errors::                  How errors are signaled and handled.
+* Cleanups::                Arranging to run a cleanup form if an
+                              error happens.
+
+Errors
+
+* Signaling Errors::        How to report an error.
+* Processing of Errors::    What Emacs does when you report an error.
+* Handling Errors::         How you can trap errors and continue execution.
+* Error Symbols::           How errors are classified for trapping them.
+* Standard Errors::         List of all error symbols.
+
+Variables
+
+* Global Variables::        Variable values that exist permanently, everywhere.
+* Constant Variables::      Certain "variables" have values that never change.
+* Local Variables::         Variable values that exist only temporarily.
+* Void Variables::          Symbols that lack values.
+* Defining Variables::      A definition says a symbol is used as a variable.
+* Tips for Defining::       Things you should think about when you
+                              define a variable.
+* Accessing Variables::     Examining values of variables whose names
+                              are known only at run time.
+* Setting Variables::       Storing new values in variables.
+* Variable Scoping::        How Lisp chooses among local and global values.
+* Buffer-Local Variables::  Variable values in effect only in one buffer.
+* Frame-Local Variables::   Variable values in effect only in one frame.
+* Future Local Variables::  New kinds of local values we might add some day.
+* File Local Variables::    Handling local variable lists in files.
+* Variable Aliases::        Variables that are aliases for other variables.
+* Variables with Restricted Values::  Non-constant variables whose value can
+                                        @emph{not} be an arbitrary Lisp object.
+* Standard Buffer-Local Variables::
+                            List of variables buffer-local in all buffers.
+
+Scoping Rules for Variable Bindings
+
+* Scope::                   Scope means where in the program a value
+                              is visible.  Comparison with other languages.
+* Extent::                  Extent means how long in time a value exists.
+* Impl of Scope::           Two ways to implement dynamic scoping.
+* Using Scoping::           How to use dynamic scoping carefully and
+                              avoid problems.
+
+Buffer-Local Variables
+
+* Intro to Buffer-Local::   Introduction and concepts.
+* Creating Buffer-Local::   Creating and destroying buffer-local bindings.
+* Default Value::           The default value is seen in buffers
+                              that don't have their own buffer-local values.
+
+Functions
+
+* What Is a Function::      Lisp functions vs primitives; terminology.
+* Lambda Expressions::      How functions are expressed as Lisp objects.
+* Function Names::          A symbol can serve as the name of a function.
+* Defining Functions::      Lisp expressions for defining functions.
+* Calling Functions::       How to use an existing function.
+* Mapping Functions::       Applying a function to each element of a list, etc.
+* Anonymous Functions::     Lambda-expressions are functions with no names.
+* Function Cells::          Accessing or setting the function definition
+                              of a symbol.
+* Obsolete Functions::      Declaring functions obsolete.
+* Inline Functions::	    Defining functions that the compiler will open code.
+* Function Safety::         Determining whether a function is safe to call.
+* Related Topics::          Cross-references to specific Lisp primitives
+                              that have a special bearing on how
+                              functions work.
+
+Lambda Expressions
+
+* Lambda Components::       The parts of a lambda expression.
+* Simple Lambda::           A simple example.
+* Argument List::           Details and special features of argument lists.
+* Function Documentation::  How to put documentation in a function.
+
+Macros
+
+* Simple Macro::            A basic example.
+* Expansion::               How, when and why macros are expanded.
+* Compiling Macros::        How macros are expanded by the compiler.
+* Defining Macros::         How to write a macro definition.
+* Backquote::               Easier construction of list structure.
+* Problems with Macros::    Don't evaluate the macro arguments too many times.
+                              Don't hide the user's variables.
+* Indenting Macros::        Specifying how to indent macro calls.
+
+Common Problems Using Macros
+
+* Wrong Time::             Do the work in the expansion, not in the macro.
+* Argument Evaluation::    The expansion should evaluate each macro arg once.
+* Surprising Local Vars::  Local variable bindings in the expansion
+                              require special care.
+* Eval During Expansion::  Don't evaluate them; put them in the expansion.
+* Repeated Expansion::     Avoid depending on how many times expansion is done.
+
+Writing Customization Definitions
+
+* Common Keywords::         Common keyword arguments for all kinds of
+                              customization declarations.
+* Group Definitions::       Writing customization group definitions.
+* Variable Definitions::    Declaring user options.
+* Customization Types::     Specifying the type of a user option.
+
+Customization Types
+
+* Simple Types::            Simple customization types: sexp, integer, number,
+                              string, file, directory, alist.
+* Composite Types::         Build new types from other types or data.
+* Splicing into Lists::     Splice elements into list with @code{:inline}.
+* Type Keywords::           Keyword-argument pairs in a customization type.
+* Defining New Types::      Give your type a name.
+
+Loading
+
+* How Programs Do Loading:: The @code{load} function and others.
+* Load Suffixes::           Details about the suffixes that @code{load} tries.
+* Library Search::          Finding a library to load.
+* Loading Non-ASCII::       Non-@acronym{ASCII} characters in Emacs Lisp files.
+* Autoload::                Setting up a function to autoload.
+* Repeated Loading::        Precautions about loading a file twice.
+* Named Features::          Loading a library if it isn't already loaded.
+* Where Defined::           Finding which file defined a certain symbol.
+* Unloading::		    How to "unload" a library that was loaded.
+* Hooks for Loading::	    Providing code to be run when
+			      particular libraries are loaded.
+
+Byte Compilation
+
+* Speed of Byte-Code::      An example of speedup from byte compilation.
+* Compilation Functions::   Byte compilation functions.
+* Docs and Compilation::    Dynamic loading of documentation strings.
+* Dynamic Loading::         Dynamic loading of individual functions.
+* Eval During Compile::     Code to be evaluated when you compile.
+* Compiler Errors::         Handling compiler error messages.
+* Byte-Code Objects::	    The data type used for byte-compiled functions.
+* Disassembly::             Disassembling byte-code; how to read byte-code.
+
+Advising Emacs Lisp Functions
+
+* Simple Advice::           A simple example to explain the basics of advice.
+* Defining Advice::         Detailed description of @code{defadvice}.
+* Around-Advice::           Wrapping advice around a function's definition.
+* Computed Advice::         ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice::    Advice doesn't do anything until you activate it.
+* Enabling Advice::         You can enable or disable each piece of advice.
+* Preactivation::           Preactivation is a way of speeding up the
+                              loading of compiled advice.
+* Argument Access in Advice:: How advice can access the function's arguments.
+* Advising Primitives::     Accessing arguments when advising a primitive.
+* Combined Definition::     How advice is implemented.
+
+Debugging Lisp Programs
+
+* Debugger::                How the Emacs Lisp debugger is implemented.
+* Edebug::                  A source-level Emacs Lisp debugger.
+* Syntax Errors::           How to find syntax errors.
+* Test Coverage::           Ensuring you have tested all branches in your code.
+* Compilation Errors::      How to find errors that show up in
+                              byte compilation.
+
+The Lisp Debugger
+
+* Error Debugging::         Entering the debugger when an error happens.
+* Infinite Loops::	    Stopping and debugging a program that doesn't exit.
+* Function Debugging::      Entering it when a certain function is called.
+* Explicit Debug::          Entering it at a certain point in the program.
+* Using Debugger::          What the debugger does; what you see while in it.
+* Debugger Commands::       Commands used while in the debugger.
+* Invoking the Debugger::   How to call the function @code{debug}.
+* Internals of Debugger::   Subroutines of the debugger, and global variables.
+
+Edebug
+
+* Using Edebug::	    Introduction to use of Edebug.
+* Instrumenting::	    You must instrument your code
+			      in order to debug it with Edebug.
+* Edebug Execution Modes::  Execution modes, stopping more or less often.
+* Jumping::		    Commands to jump to a specified place.
+* Edebug Misc::		    Miscellaneous commands.
+* Breaks::		    Setting breakpoints to make the program stop.
+* Trapping Errors::	    Trapping errors with Edebug.
+* Edebug Views::	    Views inside and outside of Edebug.
+* Edebug Eval::		    Evaluating expressions within Edebug.
+* Eval List::		    Expressions whose values are displayed
+			      each time you enter Edebug.
+* Printing in Edebug::	    Customization of printing.
+* Trace Buffer::	    How to produce trace output in a buffer.
+* Coverage Testing::	    How to test evaluation coverage.
+* The Outside Context::	    Data that Edebug saves and restores.
+* Edebug and Macros::       Specifying how to handle macro calls.
+* Edebug Options::	    Option variables for customizing Edebug.
+
+Debugging Invalid Lisp Syntax
+
+* Excess Open::             How to find a spurious open paren or missing close.
+* Excess Close::            How to find a spurious close paren or missing open.
+
+Reading and Printing Lisp Objects
+
+* Streams Intro::           Overview of streams, reading and printing.
+* Input Streams::           Various data types that can be used as
+                              input streams.
+* Input Functions::         Functions to read Lisp objects from text.
+* Output Streams::          Various data types that can be used as
+                              output streams.
+* Output Functions::        Functions to print Lisp objects as text.
+* Output Variables::        Variables that control what the printing
+                              functions do.
+
+Minibuffers
+
+* Intro to Minibuffers::    Basic information about minibuffers.
+* Text from Minibuffer::    How to read a straight text string.
+* Object from Minibuffer::  How to read a Lisp object or expression.
+* Minibuffer History::	    Recording previous minibuffer inputs
+			      so the user can reuse them.
+* Initial Input::           Specifying initial contents for the minibuffer.
+* Completion::              How to invoke and customize completion.
+* Yes-or-No Queries::       Asking a question with a simple answer.
+* Multiple Queries::	    Asking a series of similar questions.
+* Reading a Password::	    Reading a password from the terminal.
+* Minibuffer Commands::     Commands used as key bindings in minibuffers.
+* Minibuffer Contents::     How such commands access the minibuffer text.
+* Minibuffer Windows::      Operating on the special minibuffer windows.
+* Recursive Mini::          Whether recursive entry to minibuffer is allowed.
+* Minibuffer Misc::         Various customization hooks and variables.
+
+Completion
+
+* Basic Completion::        Low-level functions for completing strings.
+                              (These are too low level to use the minibuffer.)
+* Minibuffer Completion::   Invoking the minibuffer with completion.
+* Completion Commands::     Minibuffer commands that do completion.
+* High-Level Completion::   Convenient special cases of completion
+                              (reading buffer name, file name, etc.)
+* Reading File Names::      Using completion to read file names.
+* Programmed Completion::   Finding the completions for a given file name.
+
+Command Loop
+
+* Command Overview::    How the command loop reads commands.
+* Defining Commands::   Specifying how a function should read arguments.
+* Interactive Call::    Calling a command, so that it will read arguments.
+* Command Loop Info::   Variables set by the command loop for you to examine.
+* Adjusting Point::     Adjustment of point after a command.
+* Input Events::	What input looks like when you read it.
+* Reading Input::       How to read input events from the keyboard or mouse.
+* Special Events::      Events processed immediately and individually.
+* Waiting::             Waiting for user input or elapsed time.
+* Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
+* Prefix Command Arguments::    How the commands to set prefix args work.
+* Recursive Editing::   Entering a recursive edit,
+                          and why you usually shouldn't.
+* Disabling Commands::  How the command loop handles disabled commands.
+* Command History::     How the command history is set up, and how accessed.
+* Keyboard Macros::     How keyboard macros are implemented.
+
+Defining Commands
+
+* Using Interactive::       General rules for @code{interactive}.
+* Interactive Codes::       The standard letter-codes for reading arguments
+                              in various ways.
+* Interactive Examples::    Examples of how to read interactive arguments.
+
+Input Events
+
+* Keyboard Events::         Ordinary characters--keys with symbols on them.
+* Function Keys::           Function keys--keys with names, not symbols.
+* Mouse Events::            Overview of mouse events.
+* Click Events::            Pushing and releasing a mouse button.
+* Drag Events::             Moving the mouse before releasing the button.
+* Button-Down Events::      A button was pushed and not yet released.
+* Repeat Events::           Double and triple click (or drag, or down).
+* Motion Events::           Just moving the mouse, not pushing a button.
+* Focus Events::            Moving the mouse between frames.
+* Misc Events::             Other events the system can generate.
+* Event Examples::          Examples of the lists for mouse events.
+* Classifying Events::      Finding the modifier keys in an event symbol.
+* Accessing Events::        Functions to extract info from events.
+* Strings of Events::       Special considerations for putting
+                              keyboard character events in a string.
+
+Reading Input
+
+* Key Sequence Input::      How to read one key sequence.
+* Reading One Event::       How to read just one event.
+* Event Mod::               How Emacs modifies events as they are read.
+* Invoking the Input Method::   How reading an event uses the input method.
+* Quoted Character Input::  Asking the user to specify a character.
+* Event Input Misc::        How to reread or throw away input events.
+
+Keymaps
+
+* Key Sequences::           Key sequences as Lisp objects.
+* Keymap Basics::           Basic concepts of keymaps.
+* Format of Keymaps::       What a keymap looks like as a Lisp object.
+* Creating Keymaps::        Functions to create and copy keymaps.
+* Inheritance and Keymaps:: How one keymap can inherit the bindings
+                              of another keymap.
+* Prefix Keys::             Defining a key with a keymap as its definition.
+* Active Keymaps::          How Emacs searches the active keymaps
+                              for a key binding.
+* Searching Keymaps::       A pseudo-Lisp summary of searching active maps.
+* Controlling Active Maps:: Each buffer has a local keymap
+                               to override the standard (global) bindings.
+                               A minor mode can also override them.
+* Key Lookup::              How extracting elements from keymaps works.
+* Functions for Key Lookup::    How to request key lookup.
+* Changing Key Bindings::   Redefining a key in a keymap.
+* Remapping Commands::      A keymap can translate one command to another.
+* Translation Keymaps::     Keymaps for translating sequences of events.
+* Key Binding Commands::    Interactive interfaces for redefining keys.
+* Scanning Keymaps::        Looking through all keymaps, for printing help.
+* Menu Keymaps::            A keymap can define a menu for X
+                              or for use from the terminal.
+* Standard Keymaps::        List of standard keymaps.
+
+Major and Minor Modes
+
+* Hooks::                   How to use hooks; how to write code that
+                              provides hooks.
+* Major Modes::             Defining major modes.
+* Minor Modes::             Defining minor modes.
+* Mode Line Format::        Customizing the text that appears in the mode line.
+* Imenu::                   How a mode can provide a menu
+                              of definitions in the buffer.
+* Font Lock Mode::          How modes can highlight text according to syntax.
+* Desktop Save Mode::       How modes can have buffer state saved between
+                              Emacs sessions.
+
+Menu Keymaps
+
+* Defining Menus::          How to make a keymap that defines a menu.
+* Mouse Menus::             How users actuate the menu with the mouse.
+* Keyboard Menus::          How users actuate the menu with the keyboard.
+* Menu Example::            Making a simple menu.
+* Menu Bar::                How to customize the menu bar.
+* Tool Bar::                A tool bar is a row of images.
+* Modifying Menus::         How to add new items to a menu.
+
+Defining Menus
+
+* Simple Menu Items::       A simple kind of menu key binding,
+                              limited in capabilities.
+* Extended Menu Items::     More powerful menu item definitions
+                              let you specify keywords to enable
+                              various features.
+* Menu Separators::         Drawing a horizontal line through a menu.
+* Alias Menu Items::        Using command aliases in menu items.
+
+Major and Minor Modes
+
+* Hooks::              How to use hooks; how to write code that provides hooks.
+* Major Modes::        Defining major modes.
+* Minor Modes::        Defining minor modes.
+* Mode Line Format::   Customizing the text that appears in the mode line.
+* Imenu::              How a mode can provide a menu
+                         of definitions in the buffer.
+* Font Lock Mode::     How modes can highlight text according to syntax.
+* Desktop Save Mode::  How modes can have buffer state saved between
+                         Emacs sessions.
+
+Major Modes
+
+* Major Mode Basics::
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* Example Major Modes::     Text mode and Lisp modes.
+* Auto Major Mode::         How Emacs chooses the major mode automatically.
+* Mode Help::               Finding out how to use a mode.
+* Derived Modes::           Defining a new major mode based on another major
+                              mode.
+* Generic Modes::           Defining a simple major mode that supports
+                              comment syntax and Font Lock mode.
+* Mode Hooks::              Hooks run at the end of major mode functions.
+
+Minor Modes
+
+* Minor Mode Conventions::  Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+* Defining Minor Modes::    A convenient facility for defining minor modes.
+
+Mode Line Format
+
+* Mode Line Basics::
+* Mode Line Data::          The data structure that controls the mode line.
+* Mode Line Variables::     Variables used in that data structure.
+* %-Constructs::            Putting information into a mode line.
+* Properties in Mode::      Using text properties in the mode line.
+* Header Lines::            Like a mode line, but at the top.
+* Emulating Mode Line::     Formatting text as the mode line would.
+
+Font Lock Mode
+
+* Font Lock Basics::        Overview of customizing Font Lock.
+* Search-based Fontification::  Fontification based on regexps.
+* Customizing Keywords::    Customizing search-based fontification.
+* Other Font Lock Variables::   Additional customization facilities.
+* Levels of Font Lock::     Each mode can define alternative levels
+                              so that the user can select more or less.
+* Precalculated Fontification:: How Lisp programs that produce the buffer
+                                  contents can also specify how to fontify it.
+* Faces for Font Lock::     Special faces specifically for Font Lock.
+* Syntactic Font Lock::     Fontification based on syntax tables.
+* Setting Syntax Properties::   Defining character syntax based on context
+                                  using the Font Lock mechanism.
+* Multiline Font Lock::     How to coerce Font Lock into properly
+                              highlighting multiline constructs.
+
+Multiline Font Lock Constructs
+
+* Font Lock Multiline::     Marking multiline chunks with a text property
+* Region to Fontify::       Controlling which region gets refontified
+                              after a buffer change.
+
+Documentation
+
+* Documentation Basics::    Good style for doc strings.
+                              Where to put them.  How Emacs stores them.
+* Accessing Documentation:: How Lisp programs can access doc strings.
+* Keys in Documentation::   Substituting current key bindings.
+* Describing Characters::   Making printable descriptions of
+                              non-printing characters and key sequences.
+* Help Functions::          Subroutines used by Emacs help facilities.
+
+Files
+
+* Visiting Files::          Reading files into Emacs buffers for editing.
+* Saving Buffers::          Writing changed buffers back into files.
+* Reading from Files::      Reading files into other buffers.
+* Writing to Files::        Writing new files from parts of buffers.
+* File Locks::              Locking and unlocking files, to prevent
+                              simultaneous editing by two people.
+* Information about Files:: Testing existence, accessibility, size of files.
+* Changing Files::          Renaming files, changing protection, etc.
+* File Names::              Decomposing and expanding file names.
+* Contents of Directories:: Getting a list of the files in a directory.
+* Create/Delete Dirs::	    Creating and Deleting Directories.
+* Magic File Names::	    Defining "magic" special handling
+			      for certain file names.
+* Format Conversion::       Conversion to and from various file formats.
+
+Visiting Files
+
+* Visiting Functions::      The usual interface functions for visiting.
+* Subroutines of Visiting:: Lower-level subroutines that they use.
+
+Information about Files
+
+* Testing Accessibility::   Is a given file readable?  Writable?
+* Kinds of Files::          Is it a directory?  A symbolic link?
+* Truenames::		    Eliminating symbolic links from a file name.
+* File Attributes::         How large is it?  Any other names?  Etc.
+* Locating Files::          How to find a file in standard places.
+
+File Names
+
+* File Name Components::    The directory part of a file name, and the rest.
+* Relative File Names::     Some file names are relative to a
+                              current directory.
+* Directory Names::         A directory's name as a directory
+                              is different from its name as a file.
+* File Name Expansion::     Converting relative file names to absolute ones.
+* Unique File Names::       Generating names for temporary files.
+* File Name Completion::    Finding the completions for a given file name.
+* Standard File Names::     If your package uses a fixed file name,
+                              how to handle various operating systems simply.
+
+Backups and Auto-Saving
+
+* Backup Files::            How backup files are made; how their names
+                              are chosen.
+* Auto-Saving::             How auto-save files are made; how their
+                              names are chosen.
+* Reverting::               @code{revert-buffer}, and how to customize
+                              what it does.
+
+Backup Files
+
+* Making Backups::          How Emacs makes backup files, and when.
+* Rename or Copy::          Two alternatives: renaming the old file
+                              or copying it.
+* Numbered Backups::        Keeping multiple backups for each source file.
+* Backup Names::            How backup file names are computed; customization.
+
+Buffers
+
+* Buffer Basics::           What is a buffer?
+* Current Buffer::          Designating a buffer as current
+                              so primitives will access its contents.
+* Buffer Names::            Accessing and changing buffer names.
+* Buffer File Name::        The buffer file name indicates which file
+                              is visited.
+* Buffer Modification::     A buffer is @dfn{modified} if it needs to be saved.
+* Modification Time::       Determining whether the visited file was changed
+                              ``behind Emacs's back''.
+* Read Only Buffers::       Modifying text is not allowed in a
+                              read-only buffer.
+* The Buffer List::         How to look at all the existing buffers.
+* Creating Buffers::        Functions that create buffers.
+* Killing Buffers::         Buffers exist until explicitly killed.
+* Indirect Buffers::        An indirect buffer shares text with some
+                              other buffer.
+* Buffer Gap::              The gap in the buffer.
+
+Windows
+
+* Basic Windows::           Basic information on using windows.
+* Splitting Windows::       Splitting one window into two windows.
+* Deleting Windows::        Deleting a window gives its space to other windows.
+* Selecting Windows::       The selected window is the one that you edit in.
+* Cyclic Window Ordering::  Moving around the existing windows.
+* Buffers and Windows::     Each window displays the contents of a buffer.
+* Displaying Buffers::      Higher-level functions for displaying a buffer
+                              and choosing a window for it.
+* Choosing Window::	    How to choose a window for displaying a buffer.
+* Window Point::            Each window has its own location of point.
+* Window Start::            The display-start position controls which text
+                              is on-screen in the window.
+* Textual Scrolling::       Moving text up and down through the window.
+* Vertical Scrolling::      Moving the contents up and down on the window.
+* Horizontal Scrolling::    Moving the contents sideways on the window.
+* Size of Window::          Accessing the size of a window.
+* Resizing Windows::        Changing the size of a window.
+* Coordinates and Windows:: Converting coordinates to windows.
+* Window Tree::             The layout and sizes of all windows in a frame.
+* Window Configurations::   Saving and restoring the state of the screen.
+* Window Hooks::            Hooks for scrolling, window size changes,
+                              redisplay going past a certain point,
+                              or window configuration changes.
+
+Frames
+
+* Creating Frames::	    Creating additional frames.
+* Multiple Displays::       Creating frames on other displays.
+* Frame Parameters::	    Controlling frame size, position, font, etc.
+* Frame Titles::            Automatic updating of frame titles.
+* Deleting Frames::	    Frames last until explicitly deleted.
+* Finding All Frames::	    How to examine all existing frames.
+* Frames and Windows::	    A frame contains windows;
+			      display of text always works through windows.
+* Minibuffers and Frames::  How a frame finds the minibuffer to use.
+* Input Focus::		    Specifying the selected frame.
+* Visibility of Frames::    Frames may be visible or invisible, or icons.
+* Raising and Lowering::    Raising a frame makes it hide other windows;
+			      lowering it puts it underneath the others.
+* Frame Configurations::    Saving the state of all frames.
+* Mouse Tracking::	    Getting events that say when the mouse moves.
+* Mouse Position::	    Asking where the mouse is, or moving it.
+* Pop-Up Menus::	    Displaying a menu for the user to select from.
+* Dialog Boxes::            Displaying a box to ask yes or no.
+* Pointer Shape::           Specifying the shape of the mouse pointer.
+* Window System Selections::Transferring text to and from other windows.
+* Drag and Drop::               Internals of Drag-and-Drop implementation.
+* Color Names::	            Getting the definitions of color names.
+* Text Terminal Colors::    Defining colors for text-only terminals.
+* Resources::		    Getting resource values from the server.
+* Display Feature Testing:: Determining the features of a terminal.
+
+Frame Parameters
+
+* Parameter Access::        How to change a frame's parameters.
+* Initial Parameters::	    Specifying frame parameters when you make a frame.
+* Window Frame Parameters:: List of frame parameters for window systems.
+* Size and Position::       Changing the size and position of a frame.
+* Geometry::                Parsing geometry specifications.
+
+Window Frame Parameters
+
+* Basic Parameters::        Parameters that are fundamental.
+* Position Parameters::     The position of the frame on the screen.
+* Size Parameters::         Frame's size.
+* Layout Parameters::       Size of parts of the frame, and
+                              enabling or disabling some parts.
+* Buffer Parameters::       Which buffers have been or should be shown.
+* Management Parameters::   Communicating with the window manager.
+* Cursor Parameters::       Controlling the cursor appearance.
+* Color Parameters::        Colors of various parts of the frame.
+
+Positions
+
+* Point::                   The special position where editing takes place.
+* Motion::                  Changing point.
+* Excursions::              Temporary motion and buffer changes.
+* Narrowing::               Restricting editing to a portion of the buffer.
+
+Motion
+
+* Character Motion::        Moving in terms of characters.
+* Word Motion::             Moving in terms of words.
+* Buffer End Motion::       Moving to the beginning or end of the buffer.
+* Text Lines::              Moving in terms of lines of text.
+* Screen Lines::            Moving in terms of lines as displayed.
+* List Motion::             Moving by parsing lists and sexps.
+* Skipping Characters::     Skipping characters belonging to a certain set.
+
+Markers
+
+* Overview of Markers::     The components of a marker, and how it relocates.
+* Predicates on Markers::   Testing whether an object is a marker.
+* Creating Markers::        Making empty markers or markers at certain places.
+* Information from Markers::Finding the marker's buffer or character
+                              position.
+* Marker Insertion Types::  Two ways a marker can relocate when you
+                              insert where it points.
+* Moving Markers::          Moving the marker to a new buffer or position.
+* The Mark::                How "the mark" is implemented with a marker.
+* The Region::              How to access "the region".
+
+Text
+
+* Near Point::              Examining text in the vicinity of point.
+* Buffer Contents::         Examining text in a general fashion.
+* Comparing Text::          Comparing substrings of buffers.
+* Insertion::               Adding new text to a buffer.
+* Commands for Insertion::  User-level commands to insert text.
+* Deletion::                Removing text from a buffer.
+* User-Level Deletion::     User-level commands to delete text.
+* The Kill Ring::           Where removed text sometimes is saved for
+                              later use.
+* Undo::                    Undoing changes to the text of a buffer.
+* Maintaining Undo::        How to enable and disable undo information.
+			      How to control how much information is kept.
+* Filling::                 Functions for explicit filling.
+* Margins::                 How to specify margins for filling commands.
+* Adaptive Fill::           Adaptive Fill mode chooses a fill prefix
+                              from context.
+* Auto Filling::            How auto-fill mode is implemented to break lines.
+* Sorting::                 Functions for sorting parts of the buffer.
+* Columns::                 Computing horizontal positions, and using them.
+* Indentation::             Functions to insert or adjust indentation.
+* Case Changes::            Case conversion of parts of the buffer.
+* Text Properties::         Assigning Lisp property lists to text characters.
+* Substitution::            Replacing a given character wherever it appears.
+* Transposition::           Swapping two portions of a buffer.
+* Registers::               How registers are implemented.  Accessing
+                              the text or position stored in a register.
+* Base 64::                 Conversion to or from base 64 encoding.
+* MD5 Checksum::            Compute the MD5 "message digest"/"checksum".
+* Atomic Changes::          Installing several buffer changes "atomically".
+* Change Hooks::            Supplying functions to be run when text is changed.
+
+The Kill Ring
+
+* Kill Ring Concepts::      What text looks like in the kill ring.
+* Kill Functions::          Functions that kill text.
+* Yanking::                 How yanking is done.
+* Yank Commands::           Commands that access the kill ring.
+* Low-Level Kill Ring::	    Functions and variables for kill ring access.
+* Internals of Kill Ring::  Variables that hold kill-ring data.
+
+Indentation
+
+* Primitive Indent::        Functions used to count and insert indentation.
+* Mode-Specific Indent::    Customize indentation for different modes.
+* Region Indent::           Indent all the lines in a region.
+* Relative Indent::         Indent the current line based on previous lines.
+* Indent Tabs::             Adjustable, typewriter-like tab stops.
+* Motion by Indent::        Move to first non-blank character.
+
+Text Properties
+
+* Examining Properties::    Looking at the properties of one character.
+* Changing Properties::	    Setting the properties of a range of text.
+* Property Search::	    Searching for where a property changes value.
+* Special Properties::	    Particular properties with special meanings.
+* Format Properties::       Properties for representing formatting of text.
+* Sticky Properties::       How inserted text gets properties from
+                              neighboring text.
+* Lazy Properties::         Computing text properties in a lazy fashion
+                              only when text is examined.
+* Clickable Text::          Using text properties to make regions of text
+                              do something when you click on them.
+* Links and Mouse-1::       How to make @key{Mouse-1} follow a link.
+* Fields::                  The @code{field} property defines
+                              fields within the buffer.
+* Not Intervals::	    Why text properties do not use
+			      Lisp-visible text intervals.
+
+Non-ASCII Characters
+
+* Text Representations::    Unibyte and multibyte representations
+* Converting Representations::  Converting unibyte to multibyte and vice versa.
+* Selecting a Representation::  Treating a byte sequence as unibyte or multi.
+* Character Codes::         How unibyte and multibyte relate to
+                                codes of individual characters.
+* Character Sets::          The space of possible character codes
+                                is divided into various character sets.
+* Chars and Bytes::         More information about multibyte encodings.
+* Splitting Characters::    Converting a character to its byte sequence.
+* Scanning Charsets::       Which character sets are used in a buffer?
+* Translation of Characters::   Translation tables are used for conversion.
+* Coding Systems::          Coding systems are conversions for saving files.
+* Input Methods::           Input methods allow users to enter various
+                                non-ASCII characters without special keyboards.
+* Locales::                 Interacting with the POSIX locale.
+
+Coding Systems
+
+* Coding System Basics::    Basic concepts.
+* Encoding and I/O::        How file I/O functions handle coding systems.
+* Lisp and Coding Systems:: Functions to operate on coding system names.
+* User-Chosen Coding Systems::  Asking the user to choose a coding system.
+* Default Coding Systems::  Controlling the default choices.
+* Specifying Coding Systems::   Requesting a particular coding system
+                                    for a single file operation.
+* Explicit Encoding::       Encoding or decoding text without doing I/O.
+* Terminal I/O Encoding::   Use of encoding for terminal I/O.
+* MS-DOS File Types::       How DOS "text" and "binary" files
+                                relate to coding systems.
+
+Searching and Matching
+
+* String Search::           Search for an exact match.
+* Searching and Case::      Case-independent or case-significant searching.
+* Regular Expressions::     Describing classes of strings.
+* Regexp Search::           Searching for a match for a regexp.
+* POSIX Regexps::           Searching POSIX-style for the longest match.
+* Match Data::              Finding out which part of the text matched,
+                              after a string or regexp search.
+* Search and Replace::	    Commands that loop, searching and replacing.
+* Standard Regexps::        Useful regexps for finding sentences, pages,...
+
+Regular Expressions
+
+* Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Example::          Illustrates regular expression syntax.
+* Regexp Functions::        Functions for operating on regular expressions.
+
+Syntax of Regular Expressions
+
+* Regexp Special::          Special characters in regular expressions.
+* Char Classes::            Character classes used in regular expressions.
+* Regexp Backslash::        Backslash-sequences in regular expressions.
+
+The Match Data
+
+* Replacing Match::	    Replacing a substring that was matched.
+* Simple Match Data::       Accessing single items of match data,
+			      such as where a particular subexpression started.
+* Entire Match Data::       Accessing the entire match data at once, as a list.
+* Saving Match Data::       Saving and restoring the match data.
+
+Syntax Tables
+
+* Syntax Basics::           Basic concepts of syntax tables.
+* Syntax Descriptors::      How characters are classified.
+* Syntax Table Functions::  How to create, examine and alter syntax tables.
+* Syntax Properties::       Overriding syntax with text properties.
+* Motion and Syntax::	    Moving over characters with certain syntaxes.
+* Parsing Expressions::     Parsing balanced expressions
+                              using the syntax table.
+* Standard Syntax Tables::  Syntax tables used by various major modes.
+* Syntax Table Internals::  How syntax table information is stored.
+* Categories::              Another way of classifying character syntax.
+
+Syntax Descriptors
+
+* Syntax Class Table::      Table of syntax classes.
+* Syntax Flags::            Additional flags each character can have.
+
+Parsing Expressions
+
+* Motion via Parsing::      Motion functions that work by parsing.
+* Position Parse::          Determining the syntactic state of a position.
+* Parser State::            How Emacs represents a syntactic state.
+* Low-Level Parsing::       Parsing across a specified region.
+* Control Parsing::         Parameters that affect parsing.
+
+Abbrevs And Abbrev Expansion
+
+* Abbrev Mode::             Setting up Emacs for abbreviation.
+* Abbrev Tables::           Creating and working with abbrev tables.
+* Defining Abbrevs::        Specifying abbreviations and their expansions.
+* Abbrev Files::            Saving abbrevs in files.
+* Abbrev Expansion::        Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables::  Abbrev tables used by various major modes.
+
+Processes
+
+* Subprocess Creation::     Functions that start subprocesses.
+* Shell Arguments::         Quoting an argument to pass it to a shell.
+* Synchronous Processes::   Details of using synchronous subprocesses.
+* Asynchronous Processes::  Starting up an asynchronous subprocess.
+* Deleting Processes::      Eliminating an asynchronous subprocess.
+* Process Information::     Accessing run-status and other attributes.
+* Input to Processes::      Sending input to an asynchronous subprocess.
+* Signals to Processes::    Stopping, continuing or interrupting
+                              an asynchronous subprocess.
+* Output from Processes::   Collecting output from an asynchronous subprocess.
+* Sentinels::               Sentinels run when process run-status changes.
+* Query Before Exit::       Whether to query if exiting will kill a process.
+* Transaction Queues::      Transaction-based communication with subprocesses.
+* Network::                 Opening network connections.
+* Network Servers::         Network servers let Emacs accept net connections.
+* Datagrams::               UDP network connections.
+* Low-Level Network::       Lower-level but more general function
+                              to create connections and servers.
+* Misc Network::            Additional relevant functions for network connections.
+* Byte Packing::            Using bindat to pack and unpack binary data.
+
+Receiving Output from Processes
+
+* Process Buffers::         If no filter, output is put in a buffer.
+* Filter Functions::        Filter functions accept output from the process.
+* Decoding Output::         Filters can get unibyte or multibyte strings.
+* Accepting Output::        How to wait until process output arrives.
+
+Low-Level Network Access
+
+* Proc: Network Processes.  Using @code{make-network-process}.
+* Options: Network Options.  Further control over network connections.
+* Features: Network Feature Testing.
+                            Determining which network features work on
+                              the machine you are using.
+
+Packing and Unpacking Byte Arrays
+
+* Bindat Spec::             Describing data layout.
+* Bindat Functions::        Doing the unpacking and packing.
+* Bindat Examples::         Samples of what bindat.el can do for you!
+
+Emacs Display
+
+* Refresh Screen::          Clearing the screen and redrawing everything on it.
+* Forcing Redisplay::       Forcing redisplay.
+* Truncation::              Folding or wrapping long text lines.
+* The Echo Area::           Displaying messages at the bottom of the screen.
+* Warnings::                Displaying warning messages for the user.
+* Invisible Text::          Hiding part of the buffer text.
+* Selective Display::       Hiding part of the buffer text (the old way).
+* Temporary Displays::      Displays that go away automatically.
+* Overlays::		    Use overlays to highlight parts of the buffer.
+* Width::                   How wide a character or string is on the screen.
+* Line Height::             Controlling the height of lines.
+* Faces::		    A face defines a graphics style
+                              for text characters: font, colors, etc.
+* Fringes::                 Controlling window fringes.
+* Scroll Bars::             Controlling vertical scroll bars.
+* Display Property::        Enabling special display features.
+* Images::                  Displaying images in Emacs buffers.
+* Buttons::                 Adding clickable buttons to Emacs buffers.
+* Abstract Display::        Emacs' Widget for Object Collections.
+* Blinking::                How Emacs shows the matching open parenthesis.
+* Usual Display::	    The usual conventions for displaying nonprinting chars.
+* Display Tables::	    How to specify other conventions.
+* Beeping::                 Audible signal to the user.
+* Window Systems::          Which window system is being used.
+
+The Echo Area
+
+* Displaying Messages::     Explicitly displaying text in the echo area.
+* Progress::                Informing user about progress of a long operation.
+* Logging Messages::        Echo area messages are logged for the user.
+* Echo Area Customization:: Controlling the echo area.
+
+Reporting Warnings
+
+* Warning Basics::          Warnings concepts and functions to report them.
+* Warning Variables::       Variables programs bind to customize their warnings.
+* Warning Options::         Variables users set to control display of warnings.
+
+Overlays
+
+* Managing Overlays::       Creating and moving overlays.
+* Overlay Properties::      How to read and set properties.
+			    What properties do to the screen display.
+* Finding Overlays::        Searching for overlays.
+
+Faces
+
+* Defining Faces::          How to define a face with @code{defface}.
+* Face Attributes::         What is in a face?
+* Attribute Functions::     Functions to examine and set face attributes.
+* Displaying Faces::        How Emacs combines the faces specified for
+                              a character.
+* Font Selection::          Finding the best available font for a face.
+* Face Functions::          How to define and examine faces.
+* Auto Faces::              Hook for automatic face assignment.
+* Font Lookup::             Looking up the names of available fonts
+                              and information about them.
+* Fontsets::                A fontset is a collection of fonts
+                              that handle a range of character sets.
+
+Fringes
+
+* Fringe Size/Pos::         Specifying where to put the window fringes.
+* Fringe Indicators::       Displaying indicator icons in the window fringes.
+* Fringe Cursors::          Displaying cursors in the right fringe.
+* Fringe Bitmaps::          Specifying bitmaps for fringe indicators.
+* Customizing Bitmaps::     Specifying your own bitmaps to use in the fringes.
+* Overlay Arrow::           Display of an arrow to indicate position.
+
+The @code{display} Property
+
+* Specified Space::         Displaying one space with a specified width.
+* Pixel Specification::     Specifying space width or height in pixels.
+* Other Display Specs::     Displaying an image; magnifying text; moving it
+                              up or down on the page; adjusting the width
+                              of spaces within text.
+* Display Margins::         Displaying text or images to the side of
+                              the main text.
+
+Images
+
+* Image Descriptors::       How to specify an image for use in @code{:display}.
+* XBM Images::              Special features for XBM format.
+* XPM Images::              Special features for XPM format.
+* GIF Images::              Special features for GIF format.
+* PostScript Images::       Special features for PostScript format.
+* Other Image Types::       Various other formats are supported.
+* Defining Images::         Convenient ways to define an image for later use.
+* Showing Images::          Convenient ways to display an image once
+                              it is defined.
+* Image Cache::             Internal mechanisms of image display.
+
+Buttons
+
+* Button Properties::       Button properties with special meanings.
+* Button Types::            Defining common properties for classes of buttons.
+* Making Buttons::          Adding buttons to Emacs buffers.
+* Manipulating Buttons::    Getting and setting properties of buttons.
+* Button Buffer Commands::  Buffer-wide commands and bindings for buttons.
+
+Abstract Display
+
+* Abstract Display Functions::  Functions in the Ewoc package.
+* Abstract Display Example::    Example of using Ewoc.
+
+Display Tables
+
+* Display Table Format::    What a display table consists of.
+* Active Display Table::    How Emacs selects a display table to use.
+* Glyphs::                  How to define a glyph, and what glyphs mean.
+
+Operating System Interface
+
+* Starting Up::             Customizing Emacs start-up processing.
+* Getting Out::             How exiting works (permanent or temporary).
+* System Environment::      Distinguish the name and kind of system.
+* User Identification::     Finding the name and user id of the user.
+* Time of Day::		    Getting the current time.
+* Time Conversion::         Converting a time from numeric form to a string, or
+                              to calendrical data (or vice versa).
+* Time Parsing::            Converting a time from numeric form to text
+                              and vice versa.
+* Processor Run Time::      Getting the run time used by Emacs.
+* Time Calculations::       Adding, subtracting, comparing times, etc.
+* Timers::		    Setting a timer to call a function at a certain time.
+* Idle Timers::             Setting a timer to call a function when Emacs has
+                              been idle for a certain length of time.
+* Terminal Input::          Accessing and recording terminal input.
+* Terminal Output::         Controlling and recording terminal output.
+* Sound Output::            Playing sounds on the computer's speaker.
+* X11 Keysyms::             Operating on key symbols for X Windows
+* Batch Mode::              Running Emacs without terminal interaction.
+* Session Management::      Saving and restoring state with X Session Management.
+
+Starting Up Emacs
+
+* Startup Summary::         Sequence of actions Emacs performs at start-up.
+* Init File::               Details on reading the init file (@file{.emacs}).
+* Terminal-Specific::       How the terminal-specific Lisp file is read.
+* Command-Line Arguments::  How command-line arguments are processed,
+                              and how you can customize them.
+
+Getting Out of Emacs
+
+* Killing Emacs::           Exiting Emacs irreversibly.
+* Suspending Emacs::        Exiting Emacs reversibly.
+
+Terminal Input
+
+* Input Modes::		    Options for how input is processed.
+* Recording Input::	    Saving histories of recent or all input events.
+
+Tips and Conventions
+
+* Coding Conventions::      Conventions for clean and robust programs.
+* Key Binding Conventions:: Which keys should be bound by which programs.
+* Programming Tips::        Making Emacs code fit smoothly in Emacs.
+* Compilation Tips::        Making compiled code run fast.
+* Warning Tips::            Turning off compiler warnings.
+* Documentation Tips::      Writing readable documentation strings.
+* Comment Tips::	    Conventions for writing comments.
+* Library Headers::         Standard headers for library packages.
+
+GNU Emacs Internals
+
+* Building Emacs::          How the dumped Emacs is made.
+* Pure Storage::            A kludge to make preloaded Lisp functions sharable.
+* Garbage Collection::      Reclaiming space for Lisp objects no longer used.
+* Memory Usage::            Info about total size of Lisp objects made so far.
+* Writing Emacs Primitives::  Writing C code for Emacs.
+* Object Internals::        Data formats of buffers, windows, processes.
+
+Object Internals
+
+* Buffer Internals::        Components of a buffer structure.
+* Window Internals::        Components of a window structure.
+* Process Internals::       Components of a process structure.
+@end detailmenu
+@end menu
+
+@include intro.texi
+@include objects.texi
+@include numbers.texi
+@include strings.texi
+
+@include lists.texi
+@include sequences.texi
+@include hash.texi
+@include symbols.texi
+@include eval.texi
+
+@include control.texi
+@include variables.texi
+@include functions.texi
+@include macros.texi
+
+@include customize.texi
+@include loading.texi
+@include compile.texi
+@include advice.texi
+
+@include debugging.texi
+@include streams.texi
+@include minibuf.texi
+@include commands.texi
+
+@include keymaps.texi
+@include modes.texi
+@include help.texi
+@include files.texi
+
+@include backups.texi
+@include buffers.texi
+@include windows.texi
+@include frames.texi
+
+@include positions.texi
+@include markers.texi
+@include text.texi
+@include nonascii.texi
+
+@include searching.texi
+@include syntax.texi
+@include abbrevs.texi
+@include processes.texi
+
+@include display.texi
+@include os.texi
+
+@c MOVE to Emacs Manual:  include misc-modes.texi
+
+@c appendices
+
+@c  REMOVE this:  include non-hacker.texi
+
+@include anti.texi
+@include doclicense.texi
+@include gpl.texi
+@include tips.texi
+@include internals.texi
+@include errors.texi
+@include locals.texi
+@include maps.texi
+@include hooks.texi
+
+@include index.texi
+
+@ignore
+@node New Symbols, , Index, Top
+@unnumbered New Symbols Since the Previous Edition
+
+@printindex tp
+@end ignore
+
+@bye
+
+
+These words prevent "local variables" above from confusing Emacs.
+
+@ignore
+   arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34
+@end ignore
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
new file mode 100644
index 00000000000..af2df791c39
--- /dev/null
+++ b/doc/lispref/errors.texi
@@ -0,0 +1,209 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/errors
+@node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top
+@appendix Standard Errors
+@cindex standard errors
+
+  Here is the complete list of the error symbols in standard Emacs,
+grouped by concept.  The list includes each symbol's message (on the
+@code{error-message} property of the symbol) and a cross reference to a
+description of how the error can occur.
+
+  Each error symbol has an @code{error-conditions} property that is a
+list of symbols.  Normally this list includes the error symbol itself
+and the symbol @code{error}.  Occasionally it includes additional
+symbols, which are intermediate classifications, narrower than
+@code{error} but broader than a single error symbol.  For example, all
+the errors in accessing files have the condition @code{file-error}.  If
+we do not say here that a certain error symbol has additional error
+conditions, that means it has none.
+
+  As a special exception, the error symbol @code{quit} does not have the
+condition @code{error}, because quitting is not considered an error.
+
+  @xref{Errors}, for an explanation of how errors are generated and
+handled.
+
+@table @code
+@item @var{symbol}
+@var{string}; @var{reference}.
+
+@item error
+@code{"error"}@*
+@xref{Errors}.
+
+@item quit
+@code{"Quit"}@*
+@xref{Quitting}.
+
+@item args-out-of-range
+@code{"Args out of range"}@*
+This happens when trying to access an element beyond the range of a
+sequence or buffer.@*
+@xref{Sequences Arrays Vectors}, @xref{Text}.
+
+@item arith-error
+@code{"Arithmetic error"}@*
+@xref{Arithmetic Operations}.
+
+@item beginning-of-buffer
+@code{"Beginning of buffer"}@*
+@xref{Character Motion}.
+
+@item buffer-read-only
+@code{"Buffer is read-only"}@*
+@xref{Read Only Buffers}.
+
+@item coding-system-error
+@code{"Invalid coding system"}@*
+@xref{Lisp and Coding Systems}.
+
+@item cyclic-function-indirection
+@code{"Symbol's chain of function indirections\@* contains a loop"}@*
+@xref{Function Indirection}.
+
+@item cyclic-variable-indirection
+@code{"Symbol's chain of variable indirections\@* contains a loop"}@*
+@xref{Variable Aliases}.
+
+@item end-of-buffer
+@code{"End of buffer"}@*
+@xref{Character Motion}.
+
+@item end-of-file
+@code{"End of file during parsing"}@*
+Note that this is not a subcategory of @code{file-error},
+because it pertains to the Lisp reader, not to file I/O.@*
+@xref{Input Functions}.
+
+@item file-already-exists
+This is a subcategory of @code{file-error}.@*
+@xref{Writing to Files}.
+
+@item file-date-error
+This is a subcategory of @code{file-error}.  It occurs when
+@code{copy-file} tries and fails to set the last-modification time of
+the output file.@*
+@xref{Changing Files}.
+
+@item file-error
+We do not list the error-strings of this error and its subcategories,
+because the error message is normally constructed from the data items
+alone when the error condition @code{file-error} is present.  Thus,
+the error-strings are not very relevant.  However, these error symbols
+do have @code{error-message} properties, and if no data is provided,
+the @code{error-message} property @emph{is} used.@*
+@xref{Files}.
+
+@item file-locked
+This is a subcategory of @code{file-error}.@*
+@xref{File Locks}.
+
+@item file-supersession
+This is a subcategory of @code{file-error}.@*
+@xref{Modification Time}.
+
+@item ftp-error
+This is a subcategory of @code{file-error}, which results from problems
+in accessing a remote file using ftp.@*
+@xref{Remote Files,,, emacs, The GNU Emacs Manual}.
+
+@item invalid-function
+@code{"Invalid function"}@*
+@xref{Function Indirection}.
+
+@item invalid-read-syntax
+@code{"Invalid read syntax"}@*
+@xref{Printed Representation}.
+
+@item invalid-regexp
+@code{"Invalid regexp"}@*
+@xref{Regular Expressions}.
+
+@item mark-inactive
+@code{"The mark is not active now"}@*
+@xref{The Mark}.
+
+@item no-catch
+@code{"No catch for tag"}@*
+@xref{Catch and Throw}.
+
+@item scan-error
+@code{"Scan error"}@*
+This happens when certain syntax-parsing functions
+find invalid syntax or mismatched parentheses.@*
+@xref{List Motion}, and @ref{Parsing Expressions}.
+
+@item search-failed
+@code{"Search failed"}@*
+@xref{Searching and Matching}.
+
+@item setting-constant
+@code{"Attempt to set a constant symbol"}@*
+The values of the symbols @code{nil} and @code{t},
+and any symbols that start with @samp{:},
+may not be changed.@*
+@xref{Constant Variables, , Variables that Never Change}.
+
+@item text-read-only
+@code{"Text is read-only"}@*
+This is a subcategory of @code{buffer-read-only}.@*
+@xref{Special Properties}.
+
+@item undefined-color
+@code{"Undefined color"}@*
+@xref{Color Names}.
+
+@item void-function
+@code{"Symbol's function definition is void"}@*
+@xref{Function Cells}.
+
+@item void-variable
+@code{"Symbol's value as variable is void"}@*
+@xref{Accessing Variables}.
+
+@item wrong-number-of-arguments
+@code{"Wrong number of arguments"}@*
+@xref{Classifying Lists}.
+
+@item wrong-type-argument
+@code{"Wrong type argument"}@*
+@xref{Type Predicates}.
+@end table
+
+  These kinds of error, which are classified as special cases of
+@code{arith-error}, can occur on certain systems for invalid use of
+mathematical functions.
+
+@table @code
+@item domain-error
+@code{"Arithmetic domain error"}@*
+@xref{Math Functions}.
+
+@item overflow-error
+@code{"Arithmetic overflow error"}@*
+This is a subcategory of @code{domain-error}.@*
+@xref{Math Functions}.
+
+@item range-error
+@code{"Arithmetic range error"}@*
+@xref{Math Functions}.
+
+@item singularity-error
+@code{"Arithmetic singularity error"}@*
+This is a subcategory of @code{domain-error}.@*
+@xref{Math Functions}.
+
+@item underflow-error
+@code{"Arithmetic underflow error"}@*
+This is a subcategory of @code{domain-error}.@*
+@xref{Math Functions}.
+@end table
+
+@ignore
+   arch-tag: 717c6048-5d9d-4c7d-9a62-df57390b6f19
+@end ignore
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
new file mode 100644
index 00000000000..772f502553c
--- /dev/null
+++ b/doc/lispref/eval.texi
@@ -0,0 +1,758 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003,
+@c   2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/eval
+@node Evaluation, Control Structures, Symbols, Top
+@chapter Evaluation
+@cindex evaluation
+@cindex  interpreter
+@cindex interpreter
+@cindex value of expression
+
+  The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
+@dfn{Lisp interpreter}---a program that receives a Lisp object as input
+and computes its @dfn{value as an expression}.  How it does this depends
+on the data type of the object, according to rules described in this
+chapter.  The interpreter runs automatically to evaluate portions of
+your program, but can also be called explicitly via the Lisp primitive
+function @code{eval}.
+
+@ifnottex
+@menu
+* Intro Eval::  Evaluation in the scheme of things.
+* Forms::       How various sorts of objects are evaluated.
+* Quoting::     Avoiding evaluation (to put constants in the program).
+* Eval::        How to invoke the Lisp interpreter explicitly.
+@end menu
+
+@node Intro Eval
+@section Introduction to Evaluation
+
+  The Lisp interpreter, or evaluator, is the program that computes
+the value of an expression that is given to it.  When a function
+written in Lisp is called, the evaluator computes the value of the
+function by evaluating the expressions in the function body.  Thus,
+running any Lisp program really means running the Lisp interpreter.
+
+  How the evaluator handles an object depends primarily on the data
+type of the object.
+@end ifnottex
+
+@cindex forms
+@cindex expression
+  A Lisp object that is intended for evaluation is called an
+@dfn{expression} or a @dfn{form}.  The fact that expressions are data
+objects and not merely text is one of the fundamental differences
+between Lisp-like languages and typical programming languages.  Any
+object can be evaluated, but in practice only numbers, symbols, lists
+and strings are evaluated very often.
+
+  It is very common to read a Lisp expression and then evaluate the
+expression, but reading and evaluation are separate activities, and
+either can be performed alone.  Reading per se does not evaluate
+anything; it converts the printed representation of a Lisp object to the
+object itself.  It is up to the caller of @code{read} whether this
+object is a form to be evaluated, or serves some entirely different
+purpose.  @xref{Input Functions}.
+
+  Do not confuse evaluation with command key interpretation.  The
+editor command loop translates keyboard input into a command (an
+interactively callable function) using the active keymaps, and then
+uses @code{call-interactively} to invoke the command.  The execution of
+the command itself involves evaluation if the command is written in
+Lisp, but that is not a part of command key interpretation itself.
+@xref{Command Loop}.
+
+@cindex recursive evaluation
+  Evaluation is a recursive process.  That is, evaluation of a form may
+call @code{eval} to evaluate parts of the form.  For example, evaluation
+of a function call first evaluates each argument of the function call,
+and then evaluates each form in the function body.  Consider evaluation
+of the form @code{(car x)}: the subform @code{x} must first be evaluated
+recursively, so that its value can be passed as an argument to the
+function @code{car}.
+
+  Evaluation of a function call ultimately calls the function specified
+in it.  @xref{Functions}.  The execution of the function may itself work
+by evaluating the function definition; or the function may be a Lisp
+primitive implemented in C, or it may be a byte-compiled function
+(@pxref{Byte Compilation}).
+
+@cindex environment
+  The evaluation of forms takes place in a context called the
+@dfn{environment}, which consists of the current values and bindings of
+all Lisp variables.@footnote{This definition of ``environment'' is
+specifically not intended to include all the data that can affect the
+result of a program.}  Whenever a form refers to a variable without
+creating a new binding for it, the value of the variable's binding in
+the current environment is used.  @xref{Variables}.
+
+@cindex side effect
+  Evaluation of a form may create new environments for recursive
+evaluation by binding variables (@pxref{Local Variables}).  These
+environments are temporary and vanish by the time evaluation of the form
+is complete.  The form may also make changes that persist; these changes
+are called @dfn{side effects}.  An example of a form that produces side
+effects is @code{(setq foo 1)}.
+
+  The details of what evaluation means for each kind of form are
+described below (@pxref{Forms}).
+
+@node Forms
+@section Kinds of Forms
+
+  A Lisp object that is intended to be evaluated is called a @dfn{form}.
+How Emacs evaluates a form depends on its data type.  Emacs has three
+different kinds of form that are evaluated differently: symbols, lists,
+and ``all other types.''  This section describes all three kinds, one by
+one, starting with the ``all other types'' which are self-evaluating
+forms.
+
+@menu
+* Self-Evaluating Forms::   Forms that evaluate to themselves.
+* Symbol Forms::            Symbols evaluate as variables.
+* Classifying Lists::       How to distinguish various sorts of list forms.
+* Function Indirection::    When a symbol appears as the car of a list,
+			      we find the real function via the symbol.
+* Function Forms::          Forms that call functions.
+* Macro Forms::             Forms that call macros.
+* Special Forms::           "Special forms" are idiosyncratic primitives,
+                              most of them extremely important.
+* Autoloading::             Functions set up to load files
+                              containing their real definitions.
+@end menu
+
+@node Self-Evaluating Forms
+@subsection Self-Evaluating Forms
+@cindex vector evaluation
+@cindex literal evaluation
+@cindex self-evaluating form
+
+  A @dfn{self-evaluating form} is any form that is not a list or symbol.
+Self-evaluating forms evaluate to themselves: the result of evaluation
+is the same object that was evaluated.  Thus, the number 25 evaluates to
+25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
+Likewise, evaluation of a vector does not cause evaluation of the
+elements of the vector---it returns the same vector with its contents
+unchanged.
+
+@example
+@group
+'123               ; @r{A number, shown without evaluation.}
+     @result{} 123
+@end group
+@group
+123                ; @r{Evaluated as usual---result is the same.}
+     @result{} 123
+@end group
+@group
+(eval '123)        ; @r{Evaluated ``by hand''---result is the same.}
+     @result{} 123
+@end group
+@group
+(eval (eval '123)) ; @r{Evaluating twice changes nothing.}
+     @result{} 123
+@end group
+@end example
+
+  It is common to write numbers, characters, strings, and even vectors
+in Lisp code, taking advantage of the fact that they self-evaluate.
+However, it is quite unusual to do this for types that lack a read
+syntax, because there's no way to write them textually.  It is possible
+to construct Lisp expressions containing these types by means of a Lisp
+program.  Here is an example:
+
+@example
+@group
+;; @r{Build an expression containing a buffer object.}
+(setq print-exp (list 'print (current-buffer)))
+     @result{} (print #<buffer eval.texi>)
+@end group
+@group
+;; @r{Evaluate it.}
+(eval print-exp)
+     @print{} #<buffer eval.texi>
+     @result{} #<buffer eval.texi>
+@end group
+@end example
+
+@node Symbol Forms
+@subsection Symbol Forms
+@cindex symbol evaluation
+
+  When a symbol is evaluated, it is treated as a variable.  The result
+is the variable's value, if it has one.  If it has none (if its value
+cell is void), an error is signaled.  For more information on the use of
+variables, see @ref{Variables}.
+
+  In the following example, we set the value of a symbol with
+@code{setq}.  Then we evaluate the symbol, and get back the value that
+@code{setq} stored.
+
+@example
+@group
+(setq a 123)
+     @result{} 123
+@end group
+@group
+(eval 'a)
+     @result{} 123
+@end group
+@group
+a
+     @result{} 123
+@end group
+@end example
+
+  The symbols @code{nil} and @code{t} are treated specially, so that the
+value of @code{nil} is always @code{nil}, and the value of @code{t} is
+always @code{t}; you cannot set or bind them to any other values.  Thus,
+these two symbols act like self-evaluating forms, even though
+@code{eval} treats them like any other symbol.  A symbol whose name
+starts with @samp{:} also self-evaluates in the same way; likewise,
+its value ordinarily cannot be changed.  @xref{Constant Variables}.
+
+@node Classifying Lists
+@subsection Classification of List Forms
+@cindex list form evaluation
+
+  A form that is a nonempty list is either a function call, a macro
+call, or a special form, according to its first element.  These three
+kinds of forms are evaluated in different ways, described below.  The
+remaining list elements constitute the @dfn{arguments} for the function,
+macro, or special form.
+
+  The first step in evaluating a nonempty list is to examine its first
+element.  This element alone determines what kind of form the list is
+and how the rest of the list is to be processed.  The first element is
+@emph{not} evaluated, as it would be in some Lisp dialects such as
+Scheme.
+
+@node Function Indirection
+@subsection Symbol Function Indirection
+@cindex symbol function indirection
+@cindex indirection for functions
+@cindex void function
+
+  If the first element of the list is a symbol then evaluation examines
+the symbol's function cell, and uses its contents instead of the
+original symbol.  If the contents are another symbol, this process,
+called @dfn{symbol function indirection}, is repeated until it obtains a
+non-symbol.  @xref{Function Names}, for more information about using a
+symbol as a name for a function stored in the function cell of the
+symbol.
+
+  One possible consequence of this process is an infinite loop, in the
+event that a symbol's function cell refers to the same symbol.  Or a
+symbol may have a void function cell, in which case the subroutine
+@code{symbol-function} signals a @code{void-function} error.  But if
+neither of these things happens, we eventually obtain a non-symbol,
+which ought to be a function or other suitable object.
+
+@kindex invalid-function
+  More precisely, we should now have a Lisp function (a lambda
+expression), a byte-code function, a primitive function, a Lisp macro, a
+special form, or an autoload object.  Each of these types is a case
+described in one of the following sections.  If the object is not one of
+these types, the error @code{invalid-function} is signaled.
+
+  The following example illustrates the symbol indirection process.  We
+use @code{fset} to set the function cell of a symbol and
+@code{symbol-function} to get the function cell contents
+(@pxref{Function Cells}).  Specifically, we store the symbol @code{car}
+into the function cell of @code{first}, and the symbol @code{first} into
+the function cell of @code{erste}.
+
+@smallexample
+@group
+;; @r{Build this function cell linkage:}
+;;   -------------       -----        -------        -------
+;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
+;;   -------------       -----        -------        -------
+@end group
+@end smallexample
+
+@smallexample
+@group
+(symbol-function 'car)
+     @result{} #<subr car>
+@end group
+@group
+(fset 'first 'car)
+     @result{} car
+@end group
+@group
+(fset 'erste 'first)
+     @result{} first
+@end group
+@group
+(erste '(1 2 3))   ; @r{Call the function referenced by @code{erste}.}
+     @result{} 1
+@end group
+@end smallexample
+
+  By contrast, the following example calls a function without any symbol
+function indirection, because the first element is an anonymous Lisp
+function, not a symbol.
+
+@smallexample
+@group
+((lambda (arg) (erste arg))
+ '(1 2 3))
+     @result{} 1
+@end group
+@end smallexample
+
+@noindent
+Executing the function itself evaluates its body; this does involve
+symbol function indirection when calling @code{erste}.
+
+  The built-in function @code{indirect-function} provides an easy way to
+perform symbol function indirection explicitly.
+
+@c Emacs 19 feature
+@defun indirect-function function &optional noerror
+@anchor{Definition of indirect-function}
+This function returns the meaning of @var{function} as a function.  If
+@var{function} is a symbol, then it finds @var{function}'s function
+definition and starts over with that value.  If @var{function} is not a
+symbol, then it returns @var{function} itself.
+
+This function signals a @code{void-function} error if the final symbol
+is unbound and optional argument @var{noerror} is @code{nil} or
+omitted.  Otherwise, if @var{noerror} is non-@code{nil}, it returns
+@code{nil} if the final symbol is unbound.
+
+It signals a @code{cyclic-function-indirection} error if there is a
+loop in the chain of symbols.
+
+Here is how you could define @code{indirect-function} in Lisp:
+
+@smallexample
+(defun indirect-function (function)
+  (if (symbolp function)
+      (indirect-function (symbol-function function))
+    function))
+@end smallexample
+@end defun
+
+@node Function Forms
+@subsection Evaluation of Function Forms
+@cindex function form evaluation
+@cindex function call
+
+  If the first element of a list being evaluated is a Lisp function
+object, byte-code object or primitive function object, then that list is
+a @dfn{function call}.  For example, here is a call to the function
+@code{+}:
+
+@example
+(+ 1 x)
+@end example
+
+  The first step in evaluating a function call is to evaluate the
+remaining elements of the list from left to right.  The results are the
+actual argument values, one value for each list element.  The next step
+is to call the function with this list of arguments, effectively using
+the function @code{apply} (@pxref{Calling Functions}).  If the function
+is written in Lisp, the arguments are used to bind the argument
+variables of the function (@pxref{Lambda Expressions}); then the forms
+in the function body are evaluated in order, and the value of the last
+body form becomes the value of the function call.
+
+@node Macro Forms
+@subsection Lisp Macro Evaluation
+@cindex macro call evaluation
+
+  If the first element of a list being evaluated is a macro object, then
+the list is a @dfn{macro call}.  When a macro call is evaluated, the
+elements of the rest of the list are @emph{not} initially evaluated.
+Instead, these elements themselves are used as the arguments of the
+macro.  The macro definition computes a replacement form, called the
+@dfn{expansion} of the macro, to be evaluated in place of the original
+form.  The expansion may be any sort of form: a self-evaluating
+constant, a symbol, or a list.  If the expansion is itself a macro call,
+this process of expansion repeats until some other sort of form results.
+
+  Ordinary evaluation of a macro call finishes by evaluating the
+expansion.  However, the macro expansion is not necessarily evaluated
+right away, or at all, because other programs also expand macro calls,
+and they may or may not evaluate the expansions.
+
+  Normally, the argument expressions are not evaluated as part of
+computing the macro expansion, but instead appear as part of the
+expansion, so they are computed when the expansion is evaluated.
+
+  For example, given a macro defined as follows:
+
+@example
+@group
+(defmacro cadr (x)
+  (list 'car (list 'cdr x)))
+@end group
+@end example
+
+@noindent
+an expression such as @code{(cadr (assq 'handler list))} is a macro
+call, and its expansion is:
+
+@example
+(car (cdr (assq 'handler list)))
+@end example
+
+@noindent
+Note that the argument @code{(assq 'handler list)} appears in the
+expansion.
+
+@xref{Macros}, for a complete description of Emacs Lisp macros.
+
+@node Special Forms
+@subsection Special Forms
+@cindex special form evaluation
+
+  A @dfn{special form} is a primitive function specially marked so that
+its arguments are not all evaluated.  Most special forms define control
+structures or perform variable bindings---things which functions cannot
+do.
+
+  Each special form has its own rules for which arguments are evaluated
+and which are used without evaluation.  Whether a particular argument is
+evaluated may depend on the results of evaluating other arguments.
+
+  Here is a list, in alphabetical order, of all of the special forms in
+Emacs Lisp with a reference to where each is described.
+
+@table @code
+@item and
+@pxref{Combining Conditions}
+
+@item catch
+@pxref{Catch and Throw}
+
+@item cond
+@pxref{Conditionals}
+
+@item condition-case
+@pxref{Handling Errors}
+
+@item defconst
+@pxref{Defining Variables}
+
+@item defmacro
+@pxref{Defining Macros}
+
+@item defun
+@pxref{Defining Functions}
+
+@item defvar
+@pxref{Defining Variables}
+
+@item function
+@pxref{Anonymous Functions}
+
+@item if
+@pxref{Conditionals}
+
+@item interactive
+@pxref{Interactive Call}
+
+@item let
+@itemx let*
+@pxref{Local Variables}
+
+@item or
+@pxref{Combining Conditions}
+
+@item prog1
+@itemx prog2
+@itemx progn
+@pxref{Sequencing}
+
+@item quote
+@pxref{Quoting}
+
+@item save-current-buffer
+@pxref{Current Buffer}
+
+@item save-excursion
+@pxref{Excursions}
+
+@item save-restriction
+@pxref{Narrowing}
+
+@item save-window-excursion
+@pxref{Window Configurations}
+
+@item setq
+@pxref{Setting Variables}
+
+@item setq-default
+@pxref{Creating Buffer-Local}
+
+@item track-mouse
+@pxref{Mouse Tracking}
+
+@item unwind-protect
+@pxref{Nonlocal Exits}
+
+@item while
+@pxref{Iteration}
+
+@item with-output-to-temp-buffer
+@pxref{Temporary Displays}
+@end table
+
+@cindex CL note---special forms compared
+@quotation
+@b{Common Lisp note:} Here are some comparisons of special forms in
+GNU Emacs Lisp and Common Lisp.  @code{setq}, @code{if}, and
+@code{catch} are special forms in both Emacs Lisp and Common Lisp.
+@code{defun} is a special form in Emacs Lisp, but a macro in Common
+Lisp.  @code{save-excursion} is a special form in Emacs Lisp, but
+doesn't exist in Common Lisp.  @code{throw} is a special form in
+Common Lisp (because it must be able to throw multiple values), but it
+is a function in Emacs Lisp (which doesn't have multiple
+values).@refill
+@end quotation
+
+@node Autoloading
+@subsection Autoloading
+
+  The @dfn{autoload} feature allows you to call a function or macro
+whose function definition has not yet been loaded into Emacs.  It
+specifies which file contains the definition.  When an autoload object
+appears as a symbol's function definition, calling that symbol as a
+function automatically loads the specified file; then it calls the real
+definition loaded from that file.  @xref{Autoload}.
+
+@node Quoting
+@section Quoting
+
+  The special form @code{quote} returns its single argument, as written,
+without evaluating it.  This provides a way to include constant symbols
+and lists, which are not self-evaluating objects, in a program.  (It is
+not necessary to quote self-evaluating objects such as numbers, strings,
+and vectors.)
+
+@defspec quote object
+This special form returns @var{object}, without evaluating it.
+@end defspec
+
+@cindex @samp{'} for quoting
+@cindex quoting using apostrophe
+@cindex apostrophe for quoting
+Because @code{quote} is used so often in programs, Lisp provides a
+convenient read syntax for it.  An apostrophe character (@samp{'})
+followed by a Lisp object (in read syntax) expands to a list whose first
+element is @code{quote}, and whose second element is the object.  Thus,
+the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
+
+Here are some examples of expressions that use @code{quote}:
+
+@example
+@group
+(quote (+ 1 2))
+     @result{} (+ 1 2)
+@end group
+@group
+(quote foo)
+     @result{} foo
+@end group
+@group
+'foo
+     @result{} foo
+@end group
+@group
+''foo
+     @result{} (quote foo)
+@end group
+@group
+'(quote foo)
+     @result{} (quote foo)
+@end group
+@group
+['foo]
+     @result{} [(quote foo)]
+@end group
+@end example
+
+  Other quoting constructs include @code{function} (@pxref{Anonymous
+Functions}), which causes an anonymous lambda expression written in Lisp
+to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
+only part of a list, while computing and substituting other parts.
+
+@node Eval
+@section Eval
+
+  Most often, forms are evaluated automatically, by virtue of their
+occurrence in a program being run.  On rare occasions, you may need to
+write code that evaluates a form that is computed at run time, such as
+after reading a form from text being edited or getting one from a
+property list.  On these occasions, use the @code{eval} function.
+
+  The functions and variables described in this section evaluate forms,
+specify limits to the evaluation process, or record recently returned
+values.  Loading a file also does evaluation (@pxref{Loading}).
+
+  It is generally cleaner and more flexible to store a function in a
+data structure, and call it with @code{funcall} or @code{apply}, than
+to store an expression in the data structure and evaluate it.  Using
+functions provides the ability to pass information to them as
+arguments.
+
+@defun eval form
+This is the basic function evaluating an expression.  It evaluates
+@var{form} in the current environment and returns the result.  How the
+evaluation proceeds depends on the type of the object (@pxref{Forms}).
+
+Since @code{eval} is a function, the argument expression that appears
+in a call to @code{eval} is evaluated twice: once as preparation before
+@code{eval} is called, and again by the @code{eval} function itself.
+Here is an example:
+
+@example
+@group
+(setq foo 'bar)
+     @result{} bar
+@end group
+@group
+(setq bar 'baz)
+     @result{} baz
+;; @r{Here @code{eval} receives argument @code{foo}}
+(eval 'foo)
+     @result{} bar
+;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
+(eval foo)
+     @result{} baz
+@end group
+@end example
+
+The number of currently active calls to @code{eval} is limited to
+@code{max-lisp-eval-depth} (see below).
+@end defun
+
+@deffn Command eval-region start end &optional stream read-function
+@anchor{Definition of eval-region}
+This function evaluates the forms in the current buffer in the region
+defined by the positions @var{start} and @var{end}.  It reads forms from
+the region and calls @code{eval} on them until the end of the region is
+reached, or until an error is signaled and not handled.
+
+By default, @code{eval-region} does not produce any output.  However,
+if @var{stream} is non-@code{nil}, any output produced by output
+functions (@pxref{Output Functions}), as well as the values that
+result from evaluating the expressions in the region are printed using
+@var{stream}.  @xref{Output Streams}.
+
+If @var{read-function} is non-@code{nil}, it should be a function,
+which is used instead of @code{read} to read expressions one by one.
+This function is called with one argument, the stream for reading
+input.  You can also use the variable @code{load-read-function}
+(@pxref{Definition of load-read-function,, How Programs Do Loading})
+to specify this function, but it is more robust to use the
+@var{read-function} argument.
+
+@code{eval-region} does not move point.  It always returns @code{nil}.
+@end deffn
+
+@cindex evaluation of buffer contents
+@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
+This is similar to @code{eval-region}, but the arguments provide
+different optional features.  @code{eval-buffer} operates on the
+entire accessible portion of buffer @var{buffer-or-name}.
+@var{buffer-or-name} can be a buffer, a buffer name (a string), or
+@code{nil} (or omitted), which means to use the current buffer.
+@var{stream} is used as in @code{eval-region}, unless @var{stream} is
+@code{nil} and @var{print} non-@code{nil}.  In that case, values that
+result from evaluating the expressions are still discarded, but the
+output of the output functions is printed in the echo area.
+@var{filename} is the file name to use for @code{load-history}
+(@pxref{Unloading}), and defaults to @code{buffer-file-name}
+(@pxref{Buffer File Name}).  If @var{unibyte} is non-@code{nil},
+@code{read} converts strings to unibyte whenever possible.
+
+@findex eval-current-buffer
+@code{eval-current-buffer} is an alias for this command.
+@end deffn
+
+@defvar max-lisp-eval-depth
+@anchor{Definition of max-lisp-eval-depth}
+This variable defines the maximum depth allowed in calls to @code{eval},
+@code{apply}, and @code{funcall} before an error is signaled (with error
+message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).
+
+This limit, with the associated error when it is exceeded, is one way
+Emacs Lisp avoids infinite recursion on an ill-defined function.  If
+you increase the value of @code{max-lisp-eval-depth} too much, such
+code can cause stack overflow instead.
+@cindex Lisp nesting error
+
+The depth limit counts internal uses of @code{eval}, @code{apply}, and
+@code{funcall}, such as for calling the functions mentioned in Lisp
+expressions, and recursive evaluation of function call arguments and
+function body forms, as well as explicit calls in Lisp code.
+
+The default value of this variable is 300.  If you set it to a value
+less than 100, Lisp will reset it to 100 if the given value is reached.
+Entry to the Lisp debugger increases the value, if there is little room
+left, to make sure the debugger itself has room to execute.
+
+@code{max-specpdl-size} provides another limit on nesting.
+@xref{Definition of max-specpdl-size,, Local Variables}.
+@end defvar
+
+@defvar values
+The value of this variable is a list of the values returned by all the
+expressions that were read, evaluated, and printed from buffers
+(including the minibuffer) by the standard Emacs commands which do
+this.  (Note that this does @emph{not} include evaluation in
+@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
+@code{lisp-interaction-mode}.)  The elements are ordered most recent
+first.
+
+@example
+@group
+(setq x 1)
+     @result{} 1
+@end group
+@group
+(list 'A (1+ 2) auto-save-default)
+     @result{} (A 3 t)
+@end group
+@group
+values
+     @result{} ((A 3 t) 1 @dots{})
+@end group
+@end example
+
+This variable is useful for referring back to values of forms recently
+evaluated.  It is generally a bad idea to print the value of
+@code{values} itself, since this may be very long.  Instead, examine
+particular elements, like this:
+
+@example
+@group
+;; @r{Refer to the most recent evaluation result.}
+(nth 0 values)
+     @result{} (A 3 t)
+@end group
+@group
+;; @r{That put a new element on,}
+;;   @r{so all elements move back one.}
+(nth 1 values)
+     @result{} (A 3 t)
+@end group
+@group
+;; @r{This gets the element that was next-to-most-recent}
+;;   @r{before this example.}
+(nth 3 values)
+     @result{} 1
+@end group
+@end example
+@end defvar
+
+@ignore
+   arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
+@end ignore
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
new file mode 100644
index 00000000000..bfcbe476f95
--- /dev/null
+++ b/doc/lispref/files.texi
@@ -0,0 +1,3108 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/files
+@node Files, Backups and Auto-Saving, Documentation, Top
+@comment  node-name,  next,  previous,  up
+@chapter Files
+
+  In Emacs, you can find, create, view, save, and otherwise work with
+files and file directories.  This chapter describes most of the
+file-related functions of Emacs Lisp, but a few others are described in
+@ref{Buffers}, and those related to backups and auto-saving are
+described in @ref{Backups and Auto-Saving}.
+
+  Many of the file functions take one or more arguments that are file
+names.  A file name is actually a string.  Most of these functions
+expand file name arguments by calling @code{expand-file-name}, so that
+@file{~} is handled correctly, as are relative file names (including
+@samp{../}).  These functions don't recognize environment variable
+substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.
+
+  When file I/O functions signal Lisp errors, they usually use the
+condition @code{file-error} (@pxref{Handling Errors}).  The error
+message is in most cases obtained from the operating system, according
+to locale @code{system-message-locale}, and decoded using coding system
+@code{locale-coding-system} (@pxref{Locales}).
+
+@menu
+* Visiting Files::           Reading files into Emacs buffers for editing.
+* Saving Buffers::           Writing changed buffers back into files.
+* Reading from Files::       Reading files into buffers without visiting.
+* Writing to Files::         Writing new files from parts of buffers.
+* File Locks::               Locking and unlocking files, to prevent
+                               simultaneous editing by two people.
+* Information about Files::  Testing existence, accessibility, size of files.
+* Changing Files::           Renaming files, changing protection, etc.
+* File Names::               Decomposing and expanding file names.
+* Contents of Directories::  Getting a list of the files in a directory.
+* Create/Delete Dirs::	     Creating and Deleting Directories.
+* Magic File Names::	     Defining "magic" special handling
+			       for certain file names.
+* Format Conversion::        Conversion to and from various file formats.
+@end menu
+
+@node Visiting Files
+@section Visiting Files
+@cindex finding files
+@cindex visiting files
+
+  Visiting a file means reading a file into a buffer.  Once this is
+done, we say that the buffer is @dfn{visiting} that file, and call the
+file ``the visited file'' of the buffer.
+
+  A file and a buffer are two different things.  A file is information
+recorded permanently in the computer (unless you delete it).  A buffer,
+on the other hand, is information inside of Emacs that will vanish at
+the end of the editing session (or when you kill the buffer).  Usually,
+a buffer contains information that you have copied from a file; then we
+say the buffer is visiting that file.  The copy in the buffer is what
+you modify with editing commands.  Such changes to the buffer do not
+change the file; therefore, to make the changes permanent, you must
+@dfn{save} the buffer, which means copying the altered buffer contents
+back into the file.
+
+  In spite of the distinction between files and buffers, people often
+refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
+``I am editing a file,'' rather than, ``I am editing a buffer that I
+will soon save as a file of the same name.''  Humans do not usually need
+to make the distinction explicit.  When dealing with a computer program,
+however, it is good to keep the distinction in mind.
+
+@menu
+* Visiting Functions::         The usual interface functions for visiting.
+* Subroutines of Visiting::    Lower-level subroutines that they use.
+@end menu
+
+@node Visiting Functions
+@subsection Functions for Visiting Files
+
+  This section describes the functions normally used to visit files.
+For historical reasons, these functions have names starting with
+@samp{find-} rather than @samp{visit-}.  @xref{Buffer File Name}, for
+functions and variables that access the visited file name of a buffer or
+that find an existing buffer by its visited file name.
+
+  In a Lisp program, if you want to look at the contents of a file but
+not alter it, the fastest way is to use @code{insert-file-contents} in a
+temporary buffer.  Visiting the file is not necessary and takes longer.
+@xref{Reading from Files}.
+
+@deffn Command find-file filename &optional wildcards
+This command selects a buffer visiting the file @var{filename},
+using an existing buffer if there is one, and otherwise creating a
+new buffer and reading the file into it.  It also returns that buffer.
+
+Aside from some technical details, the body of the @code{find-file}
+function is basically equivalent to:
+
+@smallexample
+(switch-to-buffer (find-file-noselect filename nil nil wildcards))
+@end smallexample
+
+@noindent
+(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
+
+If @var{wildcards} is non-@code{nil}, which is always true in an
+interactive call, then @code{find-file} expands wildcard characters in
+@var{filename} and visits all the matching files.
+
+When @code{find-file} is called interactively, it prompts for
+@var{filename} in the minibuffer.
+@end deffn
+
+@defun find-file-noselect filename &optional nowarn rawfile wildcards
+This function is the guts of all the file-visiting functions.  It
+returns a buffer visiting the file @var{filename}.  You may make the
+buffer current or display it in a window if you wish, but this
+function does not do so.
+
+The function returns an existing buffer if there is one; otherwise it
+creates a new buffer and reads the file into it.  When
+@code{find-file-noselect} uses an existing buffer, it first verifies
+that the file has not changed since it was last visited or saved in
+that buffer.  If the file has changed, this function asks the user
+whether to reread the changed file.  If the user says @samp{yes}, any
+edits previously made in the buffer are lost.
+
+Reading the file involves decoding the file's contents (@pxref{Coding
+Systems}), including end-of-line conversion, and format conversion
+(@pxref{Format Conversion}).  If @var{wildcards} is non-@code{nil},
+then @code{find-file-noselect} expands wildcard characters in
+@var{filename} and visits all the matching files.
+
+This function displays warning or advisory messages in various peculiar
+cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
+example, if it needs to create a buffer, and there is no file named
+@var{filename}, it displays the message @samp{(New file)} in the echo
+area, and leaves the buffer empty.
+
+The @code{find-file-noselect} function normally calls
+@code{after-find-file} after reading the file (@pxref{Subroutines of
+Visiting}).  That function sets the buffer major mode, parses local
+variables, warns the user if there exists an auto-save file more recent
+than the file just visited, and finishes by running the functions in
+@code{find-file-hook}.
+
+If the optional argument @var{rawfile} is non-@code{nil}, then
+@code{after-find-file} is not called, and the
+@code{find-file-not-found-functions} are not run in case of failure.
+What's more, a non-@code{nil} @var{rawfile} value suppresses coding
+system conversion and format conversion.
+
+The @code{find-file-noselect} function usually returns the buffer that
+is visiting the file @var{filename}.  But, if wildcards are actually
+used and expanded, it returns a list of buffers that are visiting the
+various files.
+
+@example
+@group
+(find-file-noselect "/etc/fstab")
+     @result{} #<buffer fstab>
+@end group
+@end example
+@end defun
+
+@deffn Command find-file-other-window filename &optional wildcards
+This command selects a buffer visiting the file @var{filename}, but
+does so in a window other than the selected window.  It may use another
+existing window or split a window; see @ref{Displaying Buffers}.
+
+When this command is called interactively, it prompts for
+@var{filename}.
+@end deffn
+
+@deffn Command find-file-read-only filename &optional wildcards
+This command selects a buffer visiting the file @var{filename}, like
+@code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
+Buffers}, for related functions and variables.
+
+When this command is called interactively, it prompts for
+@var{filename}.
+@end deffn
+
+@deffn Command view-file filename
+This command visits @var{filename} using View mode, returning to the
+previous buffer when you exit View mode.  View mode is a minor mode that
+provides commands to skim rapidly through the file, but does not let you
+modify the text.  Entering View mode runs the normal hook
+@code{view-mode-hook}.  @xref{Hooks}.
+
+When @code{view-file} is called interactively, it prompts for
+@var{filename}.
+@end deffn
+
+@defopt find-file-wildcards
+If this variable is non-@code{nil}, then the various @code{find-file}
+commands check for wildcard characters and visit all the files that
+match them (when invoked interactively or when their @var{wildcards}
+argument is non-@code{nil}).  If this option is @code{nil}, then
+the @code{find-file} commands ignore their @var{wildcards} argument
+and never treat wildcard characters specially.
+@end defopt
+
+@defvar find-file-hook
+The value of this variable is a list of functions to be called after a
+file is visited.  The file's local-variables specification (if any) will
+have been processed before the hooks are run.  The buffer visiting the
+file is current when the hook functions are run.
+
+This variable is a normal hook.  @xref{Hooks}.
+@end defvar
+
+@defvar find-file-not-found-functions
+The value of this variable is a list of functions to be called when
+@code{find-file} or @code{find-file-noselect} is passed a nonexistent
+file name.  @code{find-file-noselect} calls these functions as soon as
+it detects a nonexistent file.  It calls them in the order of the list,
+until one of them returns non-@code{nil}.  @code{buffer-file-name} is
+already set up.
+
+This is not a normal hook because the values of the functions are
+used, and in many cases only some of the functions are called.
+@end defvar
+
+@node Subroutines of Visiting
+@comment  node-name,  next,  previous,  up
+@subsection Subroutines of Visiting
+
+  The @code{find-file-noselect} function uses two important subroutines
+which are sometimes useful in user Lisp code: @code{create-file-buffer}
+and @code{after-find-file}.  This section explains how to use them.
+
+@defun create-file-buffer filename
+This function creates a suitably named buffer for visiting
+@var{filename}, and returns it.  It uses @var{filename} (sans directory)
+as the name if that name is free; otherwise, it appends a string such as
+@samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.
+
+@strong{Please note:} @code{create-file-buffer} does @emph{not}
+associate the new buffer with a file and does not select the buffer.
+It also does not use the default major mode.
+
+@example
+@group
+(create-file-buffer "foo")
+     @result{} #<buffer foo>
+@end group
+@group
+(create-file-buffer "foo")
+     @result{} #<buffer foo<2>>
+@end group
+@group
+(create-file-buffer "foo")
+     @result{} #<buffer foo<3>>
+@end group
+@end example
+
+This function is used by @code{find-file-noselect}.
+It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
+@end defun
+
+@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
+This function sets the buffer major mode, and parses local variables
+(@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
+and by the default revert function (@pxref{Reverting}).
+
+@cindex new file message
+@cindex file open error
+If reading the file got an error because the file does not exist, but
+its directory does exist, the caller should pass a non-@code{nil} value
+for @var{error}.  In that case, @code{after-find-file} issues a warning:
+@samp{(New file)}.  For more serious errors, the caller should usually not
+call @code{after-find-file}.
+
+If @var{warn} is non-@code{nil}, then this function issues a warning
+if an auto-save file exists and is more recent than the visited file.
+
+If @var{noauto} is non-@code{nil}, that says not to enable or disable
+Auto-Save mode.  The mode remains enabled if it was enabled before.
+
+If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
+means this call was from @code{revert-buffer}.  This has no direct
+effect, but some mode functions and hook functions check the value
+of this variable.
+
+If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
+major mode, don't process local variables specifications in the file,
+and don't run @code{find-file-hook}.  This feature is used by
+@code{revert-buffer} in some cases.
+
+The last thing @code{after-find-file} does is call all the functions
+in the list @code{find-file-hook}.
+@end defun
+
+@node Saving Buffers
+@section Saving Buffers
+@cindex saving buffers
+
+  When you edit a file in Emacs, you are actually working on a buffer
+that is visiting that file---that is, the contents of the file are
+copied into the buffer and the copy is what you edit.  Changes to the
+buffer do not change the file until you @dfn{save} the buffer, which
+means copying the contents of the buffer into the file.
+
+@deffn Command save-buffer &optional backup-option
+This function saves the contents of the current buffer in its visited
+file if the buffer has been modified since it was last visited or saved.
+Otherwise it does nothing.
+
+@code{save-buffer} is responsible for making backup files.  Normally,
+@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
+file only if this is the first save since visiting the file.  Other
+values for @var{backup-option} request the making of backup files in
+other circumstances:
+
+@itemize @bullet
+@item
+With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
+@code{save-buffer} function marks this version of the file to be
+backed up when the buffer is next saved.
+
+@item
+With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
+@code{save-buffer} function unconditionally backs up the previous
+version of the file before saving it.
+
+@item
+With an argument of 0, unconditionally do @emph{not} make any backup file.
+@end itemize
+@end deffn
+
+@deffn Command save-some-buffers &optional save-silently-p pred
+@anchor{Definition of save-some-buffers}
+This command saves some modified file-visiting buffers.  Normally it
+asks the user about each buffer.  But if @var{save-silently-p} is
+non-@code{nil}, it saves all the file-visiting buffers without querying
+the user.
+
+The optional @var{pred} argument controls which buffers to ask about
+(or to save silently if @var{save-silently-p} is non-@code{nil}).
+If it is @code{nil}, that means to ask only about file-visiting buffers.
+If it is @code{t}, that means also offer to save certain other non-file
+buffers---those that have a non-@code{nil} buffer-local value of
+@code{buffer-offer-save} (@pxref{Killing Buffers}).  A user who says
+@samp{yes} to saving a non-file buffer is asked to specify the file
+name to use.  The @code{save-buffers-kill-emacs} function passes the
+value @code{t} for @var{pred}.
+
+If @var{pred} is neither @code{t} nor @code{nil}, then it should be
+a function of no arguments.  It will be called in each buffer to decide
+whether to offer to save that buffer.  If it returns a non-@code{nil}
+value in a certain buffer, that means do offer to save that buffer.
+@end deffn
+
+@deffn Command write-file filename &optional confirm
+@anchor{Definition of write-file}
+This function writes the current buffer into file @var{filename}, makes
+the buffer visit that file, and marks it not modified.  Then it renames
+the buffer based on @var{filename}, appending a string like @samp{<2>}
+if necessary to make a unique buffer name.  It does most of this work by
+calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
+@code{save-buffer}.
+
+If @var{confirm} is non-@code{nil}, that means to ask for confirmation
+before overwriting an existing file.  Interactively, confirmation is
+required, unless the user supplies a prefix argument.
+
+If @var{filename} is an existing directory, or a symbolic link to one,
+@code{write-file} uses the name of the visited file, in directory
+@var{filename}.  If the buffer is not visiting a file, it uses the
+buffer name instead.
+@end deffn
+
+  Saving a buffer runs several hooks.  It also performs format
+conversion (@pxref{Format Conversion}).
+
+@defvar write-file-functions
+The value of this variable is a list of functions to be called before
+writing out a buffer to its visited file.  If one of them returns
+non-@code{nil}, the file is considered already written and the rest of
+the functions are not called, nor is the usual code for writing the file
+executed.
+
+If a function in @code{write-file-functions} returns non-@code{nil}, it
+is responsible for making a backup file (if that is appropriate).
+To do so, execute the following code:
+
+@example
+(or buffer-backed-up (backup-buffer))
+@end example
+
+You might wish to save the file modes value returned by
+@code{backup-buffer} and use that (if non-@code{nil}) to set the mode
+bits of the file that you write.  This is what @code{save-buffer}
+normally does. @xref{Making Backups,, Making Backup Files}.
+
+The hook functions in @code{write-file-functions} are also responsible
+for encoding the data (if desired): they must choose a suitable coding
+system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
+perform the encoding (@pxref{Explicit Encoding}), and set
+@code{last-coding-system-used} to the coding system that was used
+(@pxref{Encoding and I/O}).
+
+If you set this hook locally in a buffer, it is assumed to be
+associated with the file or the way the contents of the buffer were
+obtained.  Thus the variable is marked as a permanent local, so that
+changing the major mode does not alter a buffer-local value.  On the
+other hand, calling @code{set-visited-file-name} will reset it.
+If this is not what you want, you might like to use
+@code{write-contents-functions} instead.
+
+Even though this is not a normal hook, you can use @code{add-hook} and
+@code{remove-hook} to manipulate the list.  @xref{Hooks}.
+@end defvar
+
+@c Emacs 19 feature
+@defvar write-contents-functions
+This works just like @code{write-file-functions}, but it is intended
+for hooks that pertain to the buffer's contents, not to the particular
+visited file or its location.  Such hooks are usually set up by major
+modes, as buffer-local bindings for this variable.  This variable
+automatically becomes buffer-local whenever it is set; switching to a
+new major mode always resets this variable, but calling
+@code{set-visited-file-name} does not.
+
+If any of the functions in this hook returns non-@code{nil}, the file
+is considered already written and the rest are not called and neither
+are the functions in @code{write-file-functions}.
+@end defvar
+
+@defopt before-save-hook
+This normal hook runs before a buffer is saved in its visited file,
+regardless of whether that is done normally or by one of the hooks
+described above.  For instance, the @file{copyright.el} program uses
+this hook to make sure the file you are saving has the current year in
+its copyright notice.
+@end defopt
+
+@c Emacs 19 feature
+@defopt after-save-hook
+This normal hook runs after a buffer has been saved in its visited file.
+One use of this hook is in Fast Lock mode; it uses this hook to save the
+highlighting information in a cache file.
+@end defopt
+
+@defopt file-precious-flag
+If this variable is non-@code{nil}, then @code{save-buffer} protects
+against I/O errors while saving by writing the new file to a temporary
+name instead of the name it is supposed to have, and then renaming it to
+the intended name after it is clear there are no errors.  This procedure
+prevents problems such as a lack of disk space from resulting in an
+invalid file.
+
+As a side effect, backups are necessarily made by copying.  @xref{Rename
+or Copy}.  Yet, at the same time, saving a precious file always breaks
+all hard links between the file you save and other file names.
+
+Some modes give this variable a non-@code{nil} buffer-local value
+in particular buffers.
+@end defopt
+
+@defopt require-final-newline
+This variable determines whether files may be written out that do
+@emph{not} end with a newline.  If the value of the variable is
+@code{t}, then @code{save-buffer} silently adds a newline at the end of
+the file whenever the buffer being saved does not already end in one.
+If the value of the variable is non-@code{nil}, but not @code{t}, then
+@code{save-buffer} asks the user whether to add a newline each time the
+case arises.
+
+If the value of the variable is @code{nil}, then @code{save-buffer}
+doesn't add newlines at all.  @code{nil} is the default value, but a few
+major modes set it to @code{t} in particular buffers.
+@end defopt
+
+  See also the function @code{set-visited-file-name} (@pxref{Buffer File
+Name}).
+
+@node Reading from Files
+@comment  node-name,  next,  previous,  up
+@section Reading from Files
+@cindex reading from files
+
+  You can copy a file from the disk and insert it into a buffer
+using the @code{insert-file-contents} function.  Don't use the user-level
+command @code{insert-file} in a Lisp program, as that sets the mark.
+
+@defun insert-file-contents filename &optional visit beg end replace
+This function inserts the contents of file @var{filename} into the
+current buffer after point.  It returns a list of the absolute file name
+and the length of the data inserted.  An error is signaled if
+@var{filename} is not the name of a file that can be read.
+
+The function @code{insert-file-contents} checks the file contents
+against the defined file formats, and converts the file contents if
+appropriate and also calls the functions in
+the list @code{after-insert-file-functions}.  @xref{Format Conversion}.
+Normally, one of the functions in the
+@code{after-insert-file-functions} list determines the coding system
+(@pxref{Coding Systems}) used for decoding the file's contents,
+including end-of-line conversion.
+
+If @var{visit} is non-@code{nil}, this function additionally marks the
+buffer as unmodified and sets up various fields in the buffer so that it
+is visiting the file @var{filename}: these include the buffer's visited
+file name and its last save file modtime.  This feature is used by
+@code{find-file-noselect} and you probably should not use it yourself.
+
+If @var{beg} and @var{end} are non-@code{nil}, they should be integers
+specifying the portion of the file to insert.  In this case, @var{visit}
+must be @code{nil}.  For example,
+
+@example
+(insert-file-contents filename nil 0 500)
+@end example
+
+@noindent
+inserts the first 500 characters of a file.
+
+If the argument @var{replace} is non-@code{nil}, it means to replace the
+contents of the buffer (actually, just the accessible portion) with the
+contents of the file.  This is better than simply deleting the buffer
+contents and inserting the whole file, because (1) it preserves some
+marker positions and (2) it puts less data in the undo list.
+
+It is possible to read a special file (such as a FIFO or an I/O device)
+with @code{insert-file-contents}, as long as @var{replace} and
+@var{visit} are @code{nil}.
+@end defun
+
+@defun insert-file-contents-literally filename &optional visit beg end replace
+This function works like @code{insert-file-contents} except that it does
+not do format decoding (@pxref{Format Conversion}), does not do
+character code conversion (@pxref{Coding Systems}), does not run
+@code{find-file-hook}, does not perform automatic uncompression, and so
+on.
+@end defun
+
+If you want to pass a file name to another process so that another
+program can read the file, use the function @code{file-local-copy}; see
+@ref{Magic File Names}.
+
+@node Writing to Files
+@comment  node-name,  next,  previous,  up
+@section Writing to Files
+@cindex writing to files
+
+  You can write the contents of a buffer, or part of a buffer, directly
+to a file on disk using the @code{append-to-file} and
+@code{write-region} functions.  Don't use these functions to write to
+files that are being visited; that could cause confusion in the
+mechanisms for visiting.
+
+@deffn Command append-to-file start end filename
+This function appends the contents of the region delimited by
+@var{start} and @var{end} in the current buffer to the end of file
+@var{filename}.  If that file does not exist, it is created.  This
+function returns @code{nil}.
+
+An error is signaled if @var{filename} specifies a nonwritable file,
+or a nonexistent file in a directory where files cannot be created.
+
+When called from Lisp, this function is completely equivalent to:
+
+@example
+(write-region start end filename t)
+@end example
+@end deffn
+
+@deffn Command write-region start end filename &optional append visit lockname mustbenew
+This function writes the region delimited by @var{start} and @var{end}
+in the current buffer into the file specified by @var{filename}.
+
+If @var{start} is @code{nil}, then the command writes the entire buffer
+contents (@emph{not} just the accessible portion) to the file and
+ignores @var{end}.
+
+@c Emacs 19 feature
+If @var{start} is a string, then @code{write-region} writes or appends
+that string, rather than text from the buffer.  @var{end} is ignored in
+this case.
+
+If @var{append} is non-@code{nil}, then the specified text is appended
+to the existing file contents (if any).  If @var{append} is an
+integer, @code{write-region} seeks to that byte offset from the start
+of the file and writes the data from there.
+
+If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
+for confirmation if @var{filename} names an existing file.  If
+@var{mustbenew} is the symbol @code{excl}, then @code{write-region}
+does not ask for confirmation, but instead it signals an error
+@code{file-already-exists} if the file already exists.
+
+The test for an existing file, when @var{mustbenew} is @code{excl}, uses
+a special system feature.  At least for files on a local disk, there is
+no chance that some other program could create a file of the same name
+before Emacs does, without Emacs's noticing.
+
+If @var{visit} is @code{t}, then Emacs establishes an association
+between the buffer and the file: the buffer is then visiting that file.
+It also sets the last file modification time for the current buffer to
+@var{filename}'s modtime, and marks the buffer as not modified.  This
+feature is used by @code{save-buffer}, but you probably should not use
+it yourself.
+
+@c Emacs 19 feature
+If @var{visit} is a string, it specifies the file name to visit.  This
+way, you can write the data to one file (@var{filename}) while recording
+the buffer as visiting another file (@var{visit}).  The argument
+@var{visit} is used in the echo area message and also for file locking;
+@var{visit} is stored in @code{buffer-file-name}.  This feature is used
+to implement @code{file-precious-flag}; don't use it yourself unless you
+really know what you're doing.
+
+The optional argument @var{lockname}, if non-@code{nil}, specifies the
+file name to use for purposes of locking and unlocking, overriding
+@var{filename} and @var{visit} for that purpose.
+
+The function @code{write-region} converts the data which it writes to
+the appropriate file formats specified by @code{buffer-file-format}
+and also calls the functions in the list
+@code{write-region-annotate-functions}.
+@xref{Format Conversion}.
+
+Normally, @code{write-region} displays the message @samp{Wrote
+@var{filename}} in the echo area.  If @var{visit} is neither @code{t}
+nor @code{nil} nor a string, then this message is inhibited.  This
+feature is useful for programs that use files for internal purposes,
+files that the user does not need to know about.
+@end deffn
+
+@defmac with-temp-file file body@dots{}
+@anchor{Definition of with-temp-file}
+The @code{with-temp-file} macro evaluates the @var{body} forms with a
+temporary buffer as the current buffer; then, at the end, it writes the
+buffer contents into file @var{file}.  It kills the temporary buffer
+when finished, restoring the buffer that was current before the
+@code{with-temp-file} form.  Then it returns the value of the last form
+in @var{body}.
+
+The current buffer is restored even in case of an abnormal exit via
+@code{throw} or error (@pxref{Nonlocal Exits}).
+
+See also @code{with-temp-buffer} in @ref{Definition of
+with-temp-buffer,, The Current Buffer}.
+@end defmac
+
+@node File Locks
+@section File Locks
+@cindex file locks
+@cindex lock file
+
+  When two users edit the same file at the same time, they are likely
+to interfere with each other.  Emacs tries to prevent this situation
+from arising by recording a @dfn{file lock} when a file is being
+modified.  (File locks are not implemented on Microsoft systems.)
+Emacs can then detect the first attempt to modify a buffer visiting a
+file that is locked by another Emacs job, and ask the user what to do.
+The file lock is really a file, a symbolic link with a special name,
+stored in the same directory as the file you are editing.
+
+  When you access files using NFS, there may be a small probability that
+you and another user will both lock the same file ``simultaneously.''
+If this happens, it is possible for the two users to make changes
+simultaneously, but Emacs will still warn the user who saves second.
+Also, the detection of modification of a buffer visiting a file changed
+on disk catches some cases of simultaneous editing; see
+@ref{Modification Time}.
+
+@defun file-locked-p filename
+This function returns @code{nil} if the file @var{filename} is not
+locked.  It returns @code{t} if it is locked by this Emacs process, and
+it returns the name of the user who has locked it if it is locked by
+some other job.
+
+@example
+@group
+(file-locked-p "foo")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun lock-buffer &optional filename
+This function locks the file @var{filename}, if the current buffer is
+modified.  The argument @var{filename} defaults to the current buffer's
+visited file.  Nothing is done if the current buffer is not visiting a
+file, or is not modified, or if the system does not support locking.
+@end defun
+
+@defun unlock-buffer
+This function unlocks the file being visited in the current buffer,
+if the buffer is modified.  If the buffer is not modified, then
+the file should not be locked, so this function does nothing.  It also
+does nothing if the current buffer is not visiting a file, or if the
+system does not support locking.
+@end defun
+
+  File locking is not supported on some systems.  On systems that do not
+support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
+@code{file-locked-p} do nothing and return @code{nil}.
+
+@defun ask-user-about-lock file other-user
+This function is called when the user tries to modify @var{file}, but it
+is locked by another user named @var{other-user}.  The default
+definition of this function asks the user to say what to do.  The value
+this function returns determines what Emacs does next:
+
+@itemize @bullet
+@item
+A value of @code{t} says to grab the lock on the file.  Then
+this user may edit the file and @var{other-user} loses the lock.
+
+@item
+A value of @code{nil} says to ignore the lock and let this
+user edit the file anyway.
+
+@item
+@kindex file-locked
+This function may instead signal a @code{file-locked} error, in which
+case the change that the user was about to make does not take place.
+
+The error message for this error looks like this:
+
+@example
+@error{} File is locked: @var{file} @var{other-user}
+@end example
+
+@noindent
+where @code{file} is the name of the file and @var{other-user} is the
+name of the user who has locked the file.
+@end itemize
+
+If you wish, you can replace the @code{ask-user-about-lock} function
+with your own version that makes the decision in another way.  The code
+for its usual definition is in @file{userlock.el}.
+@end defun
+
+@node Information about Files
+@section Information about Files
+@cindex file, information about
+
+  The functions described in this section all operate on strings that
+designate file names.  With a few exceptions, all the functions have
+names that begin with the word @samp{file}.  These functions all
+return information about actual files or directories, so their
+arguments must all exist as actual files or directories unless
+otherwise noted.
+
+@menu
+* Testing Accessibility::   Is a given file readable?  Writable?
+* Kinds of Files::          Is it a directory?  A symbolic link?
+* Truenames::		    Eliminating symbolic links from a file name.
+* File Attributes::         How large is it?  Any other names?  Etc.
+* Locating Files::          How to find a file in standard places.
+@end menu
+
+@node Testing Accessibility
+@comment  node-name,  next,  previous,  up
+@subsection Testing Accessibility
+@cindex accessibility of a file
+@cindex file accessibility
+
+  These functions test for permission to access a file in specific
+ways.  Unless explicitly stated otherwise, they recursively follow
+symbolic links for their file name arguments, at all levels (at the
+level of the file itself and at all levels of parent directories).
+
+@defun file-exists-p filename
+This function returns @code{t} if a file named @var{filename} appears
+to exist.  This does not mean you can necessarily read the file, only
+that you can find out its attributes.  (On Unix and GNU/Linux, this is
+true if the file exists and you have execute permission on the
+containing directories, regardless of the protection of the file
+itself.)
+
+If the file does not exist, or if fascist access control policies
+prevent you from finding the attributes of the file, this function
+returns @code{nil}.
+
+Directories are files, so @code{file-exists-p} returns @code{t} when
+given a directory name.  However, symbolic links are treated
+specially; @code{file-exists-p} returns @code{t} for a symbolic link
+name only if the target file exists.
+@end defun
+
+@defun file-readable-p filename
+This function returns @code{t} if a file named @var{filename} exists
+and you can read it.  It returns @code{nil} otherwise.
+
+@example
+@group
+(file-readable-p "files.texi")
+     @result{} t
+@end group
+@group
+(file-exists-p "/usr/spool/mqueue")
+     @result{} t
+@end group
+@group
+(file-readable-p "/usr/spool/mqueue")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@c Emacs 19 feature
+@defun file-executable-p filename
+This function returns @code{t} if a file named @var{filename} exists and
+you can execute it.  It returns @code{nil} otherwise.  On Unix and
+GNU/Linux, if the file is a directory, execute permission means you can
+check the existence and attributes of files inside the directory, and
+open those files if their modes permit.
+@end defun
+
+@defun file-writable-p filename
+This function returns @code{t} if the file @var{filename} can be written
+or created by you, and @code{nil} otherwise.  A file is writable if the
+file exists and you can write it.  It is creatable if it does not exist,
+but the specified directory does exist and you can write in that
+directory.
+
+In the third example below, @file{foo} is not writable because the
+parent directory does not exist, even though the user could create such
+a directory.
+
+@example
+@group
+(file-writable-p "~/foo")
+     @result{} t
+@end group
+@group
+(file-writable-p "/foo")
+     @result{} nil
+@end group
+@group
+(file-writable-p "~/no-such-dir/foo")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@c Emacs 19 feature
+@defun file-accessible-directory-p dirname
+This function returns @code{t} if you have permission to open existing
+files in the directory whose name as a file is @var{dirname};
+otherwise (or if there is no such directory), it returns @code{nil}.
+The value of @var{dirname} may be either a directory name (such as
+@file{/foo/}) or the file name of a file which is a directory
+(such as @file{/foo}, without the final slash).
+
+Example: after the following,
+
+@example
+(file-accessible-directory-p "/foo")
+     @result{} nil
+@end example
+
+@noindent
+we can deduce that any attempt to read a file in @file{/foo/} will
+give an error.
+@end defun
+
+@defun access-file filename string
+This function opens file @var{filename} for reading, then closes it and
+returns @code{nil}.  However, if the open fails, it signals an error
+using @var{string} as the error message text.
+@end defun
+
+@defun file-ownership-preserved-p filename
+This function returns @code{t} if deleting the file @var{filename} and
+then creating it anew would keep the file's owner unchanged.  It also
+returns @code{t} for nonexistent files.
+
+If @var{filename} is a symbolic link, then, unlike the other functions
+discussed here, @code{file-ownership-preserved-p} does @emph{not}
+replace @var{filename} with its target.  However, it does recursively
+follow symbolic links at all levels of parent directories.
+@end defun
+
+@defun file-newer-than-file-p filename1 filename2
+@cindex file age
+@cindex file modification time
+This function returns @code{t} if the file @var{filename1} is
+newer than file @var{filename2}.  If @var{filename1} does not
+exist, it returns @code{nil}.  If @var{filename1} does exist, but
+@var{filename2} does not, it returns @code{t}.
+
+In the following example, assume that the file @file{aug-19} was written
+on the 19th, @file{aug-20} was written on the 20th, and the file
+@file{no-file} doesn't exist at all.
+
+@example
+@group
+(file-newer-than-file-p "aug-19" "aug-20")
+     @result{} nil
+@end group
+@group
+(file-newer-than-file-p "aug-20" "aug-19")
+     @result{} t
+@end group
+@group
+(file-newer-than-file-p "aug-19" "no-file")
+     @result{} t
+@end group
+@group
+(file-newer-than-file-p "no-file" "aug-19")
+     @result{} nil
+@end group
+@end example
+
+You can use @code{file-attributes} to get a file's last modification
+time as a list of two numbers.  @xref{File Attributes}.
+@end defun
+
+@node Kinds of Files
+@comment  node-name,  next,  previous,  up
+@subsection Distinguishing Kinds of Files
+
+  This section describes how to distinguish various kinds of files, such
+as directories, symbolic links, and ordinary files.
+
+@defun file-symlink-p filename
+@cindex file symbolic links
+If the file @var{filename} is a symbolic link, the
+@code{file-symlink-p} function returns the (non-recursive) link target
+as a string.  (Determining the file name that the link points to from
+the target is nontrivial.)  First, this function recursively follows
+symbolic links at all levels of parent directories.
+
+If the file @var{filename} is not a symbolic link (or there is no such file),
+@code{file-symlink-p} returns @code{nil}.
+
+@example
+@group
+(file-symlink-p "foo")
+     @result{} nil
+@end group
+@group
+(file-symlink-p "sym-link")
+     @result{} "foo"
+@end group
+@group
+(file-symlink-p "sym-link2")
+     @result{} "sym-link"
+@end group
+@group
+(file-symlink-p "/bin")
+     @result{} "/pub/bin"
+@end group
+@end example
+
+@c !!! file-symlink-p: should show output of ls -l for comparison
+@end defun
+
+The next two functions recursively follow symbolic links at
+all levels for @var{filename}.
+
+@defun file-directory-p filename
+This function returns @code{t} if @var{filename} is the name of an
+existing directory, @code{nil} otherwise.
+
+@example
+@group
+(file-directory-p "~rms")
+     @result{} t
+@end group
+@group
+(file-directory-p "~rms/lewis/files.texi")
+     @result{} nil
+@end group
+@group
+(file-directory-p "~rms/lewis/no-such-file")
+     @result{} nil
+@end group
+@group
+(file-directory-p "$HOME")
+     @result{} nil
+@end group
+@group
+(file-directory-p
+ (substitute-in-file-name "$HOME"))
+     @result{} t
+@end group
+@end example
+@end defun
+
+@defun file-regular-p filename
+This function returns @code{t} if the file @var{filename} exists and is
+a regular file (not a directory, named pipe, terminal, or
+other I/O device).
+@end defun
+
+@node Truenames
+@subsection Truenames
+@cindex truename (of file)
+
+@c Emacs 19 features
+  The @dfn{truename} of a file is the name that you get by following
+symbolic links at all levels until none remain, then simplifying away
+@samp{.}@: and @samp{..}@: appearing as name components.  This results
+in a sort of canonical name for the file.  A file does not always have a
+unique truename; the number of distinct truenames a file has is equal to
+the number of hard links to the file.  However, truenames are useful
+because they eliminate symbolic links as a cause of name variation.
+
+@defun file-truename filename
+The function @code{file-truename} returns the truename of the file
+@var{filename}.  The argument must be an absolute file name.
+
+This function does not expand environment variables.  Only
+@code{substitute-in-file-name} does that.  @xref{Definition of
+substitute-in-file-name}.
+
+If you may need to follow symbolic links preceding @samp{..}@:
+appearing as a name component, you should make sure to call
+@code{file-truename} without prior direct or indirect calls to
+@code{expand-file-name}, as otherwise the file name component
+immediately preceding @samp{..} will be ``simplified away'' before
+@code{file-truename} is called.  To eliminate the need for a call to
+@code{expand-file-name}, @code{file-truename} handles @samp{~} in the
+same way that @code{expand-file-name} does.  @xref{File Name
+Expansion,, Functions that Expand Filenames}.
+@end defun
+
+@defun file-chase-links filename &optional limit
+This function follows symbolic links, starting with @var{filename},
+until it finds a file name which is not the name of a symbolic link.
+Then it returns that file name.  This function does @emph{not} follow
+symbolic links at the level of parent directories.
+
+If you specify a number for @var{limit}, then after chasing through
+that many links, the function just returns what it has even if that is
+still a symbolic link.
+@end defun
+
+  To illustrate the difference between @code{file-chase-links} and
+@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
+the directory @file{/home/foo}, and @file{/home/foo/hello} is an
+ordinary file (or at least, not a symbolic link) or nonexistent.  Then
+we would have:
+
+@example
+(file-chase-links "/usr/foo/hello")
+     ;; @r{This does not follow the links in the parent directories.}
+     @result{} "/usr/foo/hello"
+(file-truename "/usr/foo/hello")
+     ;; @r{Assuming that @file{/home} is not a symbolic link.}
+     @result{} "/home/foo/hello"
+@end example
+
+  @xref{Buffer File Name}, for related information.
+
+@node File Attributes
+@comment  node-name,  next,  previous,  up
+@subsection Other Information about Files
+
+  This section describes the functions for getting detailed information
+about a file, other than its contents.  This information includes the
+mode bits that control access permission, the owner and group numbers,
+the number of names, the inode number, the size, and the times of access
+and modification.
+
+@defun file-modes filename
+@cindex permission
+@cindex file attributes
+This function returns the mode bits of @var{filename}, as an integer.
+The mode bits are also called the file permissions, and they specify
+access control in the usual Unix fashion.  If the low-order bit is 1,
+then the file is executable by all users, if the second-lowest-order bit
+is 1, then the file is writable by all users, etc.
+
+The highest value returnable is 4095 (7777 octal), meaning that
+everyone has read, write, and execute permission, that the @acronym{SUID} bit
+is set for both others and group, and that the sticky bit is set.
+
+If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
+
+This function recursively follows symbolic links at all levels.
+
+@example
+@group
+(file-modes "~/junk/diffs")
+     @result{} 492               ; @r{Decimal integer.}
+@end group
+@group
+(format "%o" 492)
+     @result{} "754"             ; @r{Convert to octal.}
+@end group
+
+@group
+(set-file-modes "~/junk/diffs" 438)
+     @result{} nil
+@end group
+
+@group
+(format "%o" 438)
+     @result{} "666"             ; @r{Convert to octal.}
+@end group
+
+@group
+% ls -l diffs
+  -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
+@end group
+@end example
+@end defun
+
+If the @var{filename} argument to the next two functions is a symbolic
+link, then these function do @emph{not} replace it with its target.
+However, they both recursively follow symbolic links at all levels of
+parent directories.
+
+@defun file-nlinks filename
+This functions returns the number of names (i.e., hard links) that
+file @var{filename} has.  If the file does not exist, then this function
+returns @code{nil}.  Note that symbolic links have no effect on this
+function, because they are not considered to be names of the files they
+link to.
+
+@example
+@group
+% ls -l foo*
+-rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
+-rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
+@end group
+
+@group
+(file-nlinks "foo")
+     @result{} 2
+@end group
+@group
+(file-nlinks "doesnt-exist")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun file-attributes filename &optional id-format
+@anchor{Definition of file-attributes}
+This function returns a list of attributes of file @var{filename}.  If
+the specified file cannot be opened, it returns @code{nil}.
+The optional parameter @var{id-format} specifies the preferred format
+of attributes @acronym{UID} and @acronym{GID} (see below)---the
+valid values are @code{'string} and @code{'integer}.  The latter is
+the default, but we plan to change that, so you should specify a
+non-@code{nil} value for @var{id-format} if you use the returned
+@acronym{UID} or @acronym{GID}.
+
+The elements of the list, in order, are:
+
+@enumerate 0
+@item
+@code{t} for a directory, a string for a symbolic link (the name
+linked to), or @code{nil} for a text file.
+
+@c Wordy so as to prevent an overfull hbox.  --rjc 15mar92
+@item
+The number of names the file has.  Alternate names, also known as hard
+links, can be created by using the @code{add-name-to-file} function
+(@pxref{Changing Files}).
+
+@item
+The file's @acronym{UID}, normally as a string.  However, if it does
+not correspond to a named user, the value is an integer or a floating
+point number.
+
+@item
+The file's @acronym{GID}, likewise.
+
+@item
+The time of last access, as a list of two integers.
+The first integer has the high-order 16 bits of time,
+the second has the low 16 bits.  (This is similar to the
+value of @code{current-time}; see @ref{Time of Day}.)
+
+@item
+The time of last modification as a list of two integers (as above).
+@cindex modification time of file
+
+@item
+The time of last status change as a list of two integers (as above).
+
+@item
+The size of the file in bytes.  If the size is too large to fit in a
+Lisp integer, this is a floating point number.
+
+@item
+The file's modes, as a string of ten letters or dashes,
+as in @samp{ls -l}.
+
+@item
+@code{t} if the file's @acronym{GID} would change if file were
+deleted and recreated; @code{nil} otherwise.
+
+@item
+The file's inode number.  If possible, this is an integer.  If the inode
+number is too large to be represented as an integer in Emacs Lisp, then
+the value has the form @code{(@var{high} . @var{low})}, where @var{low}
+holds the low 16 bits.
+
+@item
+The file system number of the file system that the file is in.
+Depending on the magnitude of the value, this can be either an integer
+or a cons cell, in the same manner as the inode number.  This element
+and the file's inode number together give enough information to
+distinguish any two files on the system---no two files can have the same
+values for both of these numbers.
+@end enumerate
+
+For example, here are the file attributes for @file{files.texi}:
+
+@example
+@group
+(file-attributes "files.texi" 'string)
+     @result{}  (nil 1 "lh" "users"
+          (8489 20284)
+          (8489 20284)
+          (8489 20285)
+          14906 "-rw-rw-rw-"
+          nil 129500 -32252)
+@end group
+@end example
+
+@noindent
+and here is how the result is interpreted:
+
+@table @code
+@item nil
+is neither a directory nor a symbolic link.
+
+@item 1
+has only one name (the name @file{files.texi} in the current default
+directory).
+
+@item "lh"
+is owned by the user with name "lh".
+
+@item "users"
+is in the group with name "users".
+
+@item (8489 20284)
+was last accessed on Aug 19 00:09.
+
+@item (8489 20284)
+was last modified on Aug 19 00:09.
+
+@item (8489 20285)
+last had its inode changed on Aug 19 00:09.
+
+@item 14906
+is 14906 bytes long.  (It may not contain 14906 characters, though,
+if some of the bytes belong to multibyte sequences.)
+
+@item "-rw-rw-rw-"
+has a mode of read and write access for the owner, group, and world.
+
+@item nil
+would retain the same @acronym{GID} if it were recreated.
+
+@item 129500
+has an inode number of 129500.
+@item -32252
+is on file system number -32252.
+@end table
+@end defun
+
+@node Locating Files
+@subsection How to Locate Files in Standard Places
+@cindex locate file in path
+@cindex find file in path
+
+  This section explains how to search for a file in a list of
+directories (a @dfn{path}).  One example is when you need to look for
+a program's executable file, e.g., to find out whether a given program
+is installed on the user's system.  Another example is the search for
+Lisp libraries (@pxref{Library Search}).  Such searches generally need
+to try various possible file name extensions, in addition to various
+possible directories.  Emacs provides a function for such a
+generalized search for a file.
+
+@defun locate-file filename path &optional suffixes predicate
+This function searches for a file whose name is @var{filename} in a
+list of directories given by @var{path}, trying the suffixes in
+@var{suffixes}.  If it finds such a file, it returns the full
+@dfn{absolute file name} of the file (@pxref{Relative File Names});
+otherwise it returns @code{nil}.
+
+The optional argument @var{suffixes} gives the list of file-name
+suffixes to append to @var{filename} when searching.
+@code{locate-file} tries each possible directory with each of these
+suffixes.  If @var{suffixes} is @code{nil}, or @code{("")}, then there
+are no suffixes, and @var{filename} is used only as-is.  Typical
+values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
+Creation, exec-suffixes}), @code{load-suffixes},
+@code{load-file-rep-suffixes} and the return value of the function
+@code{get-load-suffixes} (@pxref{Load Suffixes}).
+
+Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
+Creation, exec-path}) when looking for executable programs or
+@code{load-path} (@pxref{Library Search, load-path}) when looking for
+Lisp files.  If @var{filename} is absolute, @var{path} has no effect,
+but the suffixes in @var{suffixes} are still tried.
+
+The optional argument @var{predicate}, if non-@code{nil}, specifies
+the predicate function to use for testing whether a candidate file is
+suitable.  The predicate function is passed the candidate file name as
+its single argument.  If @var{predicate} is @code{nil} or unspecified,
+@code{locate-file} uses @code{file-readable-p} as the default
+predicate.  Useful non-default predicates include
+@code{file-executable-p}, @code{file-directory-p}, and other
+predicates described in @ref{Kinds of Files}.
+
+For compatibility, @var{predicate} can also be one of the symbols
+@code{executable}, @code{readable}, @code{writable}, @code{exists}, or
+a list of one or more of these symbols.
+@end defun
+
+@defun executable-find program
+This function searches for the executable file of the named
+@var{program} and returns the full absolute name of the executable,
+including its file-name extensions, if any.  It returns @code{nil} if
+the file is not found.  The functions searches in all the directories
+in @code{exec-path} and tries all the file-name extensions in
+@code{exec-suffixes}.
+@end defun
+
+@node Changing Files
+@section Changing File Names and Attributes
+@c @cindex renaming files  Duplicates rename-file
+@cindex copying files
+@cindex deleting files
+@cindex linking files
+@cindex setting modes of files
+
+  The functions in this section rename, copy, delete, link, and set the
+modes of files.
+
+  In the functions that have an argument @var{newname}, if a file by the
+name of @var{newname} already exists, the actions taken depend on the
+value of the argument @var{ok-if-already-exists}:
+
+@itemize @bullet
+@item
+Signal a @code{file-already-exists} error if
+@var{ok-if-already-exists} is @code{nil}.
+
+@item
+Request confirmation if @var{ok-if-already-exists} is a number.
+
+@item
+Replace the old file without confirmation if @var{ok-if-already-exists}
+is any other value.
+@end itemize
+
+The next four commands all recursively follow symbolic links at all
+levels of parent directories for their first argument, but, if that
+argument is itself a symbolic link, then only @code{copy-file}
+replaces it with its (recursive) target.
+
+@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
+@cindex file with multiple names
+@cindex file hard link
+This function gives the file named @var{oldname} the additional name
+@var{newname}.  This means that @var{newname} becomes a new ``hard
+link'' to @var{oldname}.
+
+In the first part of the following example, we list two files,
+@file{foo} and @file{foo3}.
+
+@example
+@group
+% ls -li fo*
+81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
+84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
+@end group
+@end example
+
+Now we create a hard link, by calling @code{add-name-to-file}, then list
+the files again.  This shows two names for one file, @file{foo} and
+@file{foo2}.
+
+@example
+@group
+(add-name-to-file "foo" "foo2")
+     @result{} nil
+@end group
+
+@group
+% ls -li fo*
+81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
+81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
+84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
+@end group
+@end example
+
+Finally, we evaluate the following:
+
+@example
+(add-name-to-file "foo" "foo3" t)
+@end example
+
+@noindent
+and list the files again.  Now there are three names
+for one file: @file{foo}, @file{foo2}, and @file{foo3}.  The old
+contents of @file{foo3} are lost.
+
+@example
+@group
+(add-name-to-file "foo1" "foo3")
+     @result{} nil
+@end group
+
+@group
+% ls -li fo*
+81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
+81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
+81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
+@end group
+@end example
+
+This function is meaningless on operating systems where multiple names
+for one file are not allowed.  Some systems implement multiple names
+by copying the file instead.
+
+See also @code{file-nlinks} in @ref{File Attributes}.
+@end deffn
+
+@deffn Command rename-file filename newname &optional ok-if-already-exists
+This command renames the file @var{filename} as @var{newname}.
+
+If @var{filename} has additional names aside from @var{filename}, it
+continues to have those names.  In fact, adding the name @var{newname}
+with @code{add-name-to-file} and then deleting @var{filename} has the
+same effect as renaming, aside from momentary intermediate states.
+@end deffn
+
+@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
+This command copies the file @var{oldname} to @var{newname}.  An
+error is signaled if @var{oldname} does not exist.  If @var{newname}
+names a directory, it copies @var{oldname} into that directory,
+preserving its final name component.
+
+If @var{time} is non-@code{nil}, then this function gives the new file
+the same last-modified time that the old one has.  (This works on only
+some operating systems.)  If setting the time gets an error,
+@code{copy-file} signals a @code{file-date-error} error.  In an
+interactive call, a prefix argument specifies a non-@code{nil} value
+for @var{time}.
+
+This function copies the file modes, too.
+
+If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
+system decide the user and group ownership of the new file (this is
+usually set to the user running Emacs).  If @var{preserve-uid-gid} is
+non-@code{nil}, we attempt to copy the user and group ownership of the
+file.  This works only on some operating systems, and only if you have
+the correct permissions to do so.
+@end deffn
+
+@deffn Command make-symbolic-link filename newname  &optional ok-if-exists
+@pindex ln
+@kindex file-already-exists
+This command makes a symbolic link to @var{filename}, named
+@var{newname}.  This is like the shell command @samp{ln -s
+@var{filename} @var{newname}}.
+
+This function is not available on systems that don't support symbolic
+links.
+@end deffn
+
+@deffn Command delete-file filename
+@pindex rm
+This command deletes the file @var{filename}, like the shell command
+@samp{rm @var{filename}}.  If the file has multiple names, it continues
+to exist under the other names.
+
+A suitable kind of @code{file-error} error is signaled if the file does
+not exist, or is not deletable.  (On Unix and GNU/Linux, a file is
+deletable if its directory is writable.)
+
+If @var{filename} is a symbolic link, @code{delete-file} does not
+replace it with its target, but it does follow symbolic links at all
+levels of parent directories.
+
+See also @code{delete-directory} in @ref{Create/Delete Dirs}.
+@end deffn
+
+@defun define-logical-name varname string
+This function defines the logical name @var{varname} to have the value
+@var{string}.  It is available only on VMS.
+@end defun
+
+@defun set-file-modes filename mode
+This function sets mode bits of @var{filename} to @var{mode} (which
+must be an integer).  Only the low 12 bits of @var{mode} are used.
+This function recursively follows symbolic links at all levels for
+@var{filename}.
+@end defun
+
+@c Emacs 19 feature
+@defun set-default-file-modes mode
+@cindex umask
+This function sets the default file protection for new files created by
+Emacs and its subprocesses.  Every file created with Emacs initially has
+this protection, or a subset of it (@code{write-region} will not give a
+file execute permission even if the default file protection allows
+execute permission).  On Unix and GNU/Linux, the default protection is
+the bitwise complement of the ``umask'' value.
+
+The argument @var{mode} must be an integer.  On most systems, only the
+low 9 bits of @var{mode} are meaningful.  You can use the Lisp construct
+for octal character codes to enter @var{mode}; for example,
+
+@example
+(set-default-file-modes ?\644)
+@end example
+
+Saving a modified version of an existing file does not count as creating
+the file; it preserves the existing file's mode, whatever that is.  So
+the default file protection has no effect.
+@end defun
+
+@defun default-file-modes
+This function returns the current default protection value.
+@end defun
+
+@defun set-file-times filename &optional time
+This function sets the access and modification times of @var{filename}
+to @var{time}.  The return value is @code{t} if the times are successfully
+set, otherwise it is @code{nil}.  @var{time} defaults to the current
+time and must be in the format returned by @code{current-time}
+(@pxref{Time of Day}).
+@end defun
+
+@cindex MS-DOS and file modes
+@cindex file modes and MS-DOS
+  On MS-DOS, there is no such thing as an ``executable'' file mode bit.
+So Emacs considers a file executable if its name ends in one of the
+standard executable extensions, such as @file{.com}, @file{.bat},
+@file{.exe}, and some others.  Files that begin with the Unix-standard
+@samp{#!} signature, such as shell and Perl scripts, are also considered
+as executable files.  This is reflected in the values returned by
+@code{file-modes} and @code{file-attributes}.  Directories are also
+reported with executable bit set, for compatibility with Unix.
+
+@node File Names
+@section File Names
+@cindex file names
+
+  Files are generally referred to by their names, in Emacs as elsewhere.
+File names in Emacs are represented as strings.  The functions that
+operate on a file all expect a file name argument.
+
+  In addition to operating on files themselves, Emacs Lisp programs
+often need to operate on file names; i.e., to take them apart and to use
+part of a name to construct related file names.  This section describes
+how to manipulate file names.
+
+  The functions in this section do not actually access files, so they
+can operate on file names that do not refer to an existing file or
+directory.
+
+  On MS-DOS and MS-Windows, these functions (like the function that
+actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
+where backslashes separate the components, as well as Unix syntax; but
+they always return Unix syntax.  On VMS, these functions (and the ones
+that operate on files) understand both VMS file-name syntax and Unix
+syntax.  This enables Lisp programs to specify file names in Unix syntax
+and work properly on all systems without change.
+
+@menu
+* File Name Components::  The directory part of a file name, and the rest.
+* Relative File Names::   Some file names are relative to a current directory.
+* Directory Names::       A directory's name as a directory
+                            is different from its name as a file.
+* File Name Expansion::   Converting relative file names to absolute ones.
+* Unique File Names::     Generating names for temporary files.
+* File Name Completion::  Finding the completions for a given file name.
+* Standard File Names::   If your package uses a fixed file name,
+                            how to handle various operating systems simply.
+@end menu
+
+@node File Name Components
+@subsection File Name Components
+@cindex directory part (of file name)
+@cindex nondirectory part (of file name)
+@cindex version number (in file name)
+
+  The operating system groups files into directories.  To specify a
+file, you must specify the directory and the file's name within that
+directory.  Therefore, Emacs considers a file name as having two main
+parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
+(or @dfn{file name within the directory}).  Either part may be empty.
+Concatenating these two parts reproduces the original file name.
+
+  On most systems, the directory part is everything up to and including
+the last slash (backslash is also allowed in input on MS-DOS or
+MS-Windows); the nondirectory part is the rest.  The rules in VMS syntax
+are complicated.
+
+  For some purposes, the nondirectory part is further subdivided into
+the name proper and the @dfn{version number}.  On most systems, only
+backup files have version numbers in their names.  On VMS, every file
+has a version number, but most of the time the file name actually used
+in Emacs omits the version number, so that version numbers in Emacs are
+found mostly in directory lists.
+
+@defun file-name-directory filename
+This function returns the directory part of @var{filename}, as a
+directory name (@pxref{Directory Names}), or @code{nil} if
+@var{filename} does not include a directory part.
+
+On GNU and Unix systems, a string returned by this function always
+ends in a slash.  On MS-DOS it can also end in a colon.  On VMS, it
+returns a string ending in one of the three characters @samp{:},
+@samp{]}, or @samp{>}.
+
+@example
+@group
+(file-name-directory "lewis/foo")  ; @r{Unix example}
+     @result{} "lewis/"
+@end group
+@group
+(file-name-directory "foo")        ; @r{Unix example}
+     @result{} nil
+@end group
+@group
+(file-name-directory "[X]FOO.TMP") ; @r{VMS example}
+     @result{} "[X]"
+@end group
+@end example
+@end defun
+
+@defun file-name-nondirectory filename
+This function returns the nondirectory part of @var{filename}.
+
+@example
+@group
+(file-name-nondirectory "lewis/foo")
+     @result{} "foo"
+@end group
+@group
+(file-name-nondirectory "foo")
+     @result{} "foo"
+@end group
+@group
+(file-name-nondirectory "lewis/")
+     @result{} ""
+@end group
+@group
+;; @r{The following example is accurate only on VMS.}
+(file-name-nondirectory "[X]FOO.TMP")
+     @result{} "FOO.TMP"
+@end group
+@end example
+@end defun
+
+@defun file-name-sans-versions filename &optional keep-backup-version
+This function returns @var{filename} with any file version numbers,
+backup version numbers, or trailing tildes discarded.
+
+If @var{keep-backup-version} is non-@code{nil}, then true file version
+numbers understood as such by the file system are discarded from the
+return value, but backup version numbers are kept.
+
+@example
+@group
+(file-name-sans-versions "~rms/foo.~1~")
+     @result{} "~rms/foo"
+@end group
+@group
+(file-name-sans-versions "~rms/foo~")
+     @result{} "~rms/foo"
+@end group
+@group
+(file-name-sans-versions "~rms/foo")
+     @result{} "~rms/foo"
+@end group
+@group
+;; @r{The following example applies to VMS only.}
+(file-name-sans-versions "foo;23")
+     @result{} "foo"
+@end group
+@end example
+@end defun
+
+@defun file-name-extension filename &optional period
+This function returns @var{filename}'s final ``extension,'' if any,
+after applying @code{file-name-sans-versions} to remove any
+version/backup part.  The extension, in a file name, is the part that
+starts with the last @samp{.} in the last name component (minus
+any version/backup part).
+
+This function returns @code{nil} for extensionless file names such as
+@file{foo}.  It returns @code{""} for null extensions, as in
+@file{foo.}.  If the last component of a file name begins with a
+@samp{.}, that @samp{.}  doesn't count as the beginning of an
+extension.  Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
+@samp{.emacs}.
+
+If @var{period} is non-@code{nil}, then the returned value includes
+the period that delimits the extension, and if @var{filename} has no
+extension, the value is @code{""}.
+@end defun
+
+@defun file-name-sans-extension filename
+This function returns @var{filename} minus its extension, if any.  The
+version/backup part, if present, is only removed if the file has an
+extension.  For example,
+
+@example
+(file-name-sans-extension "foo.lose.c")
+     @result{} "foo.lose"
+(file-name-sans-extension "big.hack/foo")
+     @result{} "big.hack/foo"
+(file-name-sans-extension "/my/home/.emacs")
+     @result{} "/my/home/.emacs"
+(file-name-sans-extension "/my/home/.emacs.el")
+     @result{} "/my/home/.emacs"
+(file-name-sans-extension "~/foo.el.~3~")
+     @result{} "~/foo"
+(file-name-sans-extension "~/foo.~3~")
+     @result{} "~/foo.~3~"
+@end example
+
+Note that the @samp{.~3~} in the two last examples is the backup part,
+not an extension.
+@end defun
+
+@ignore
+Andrew Innes says that this
+
+@c @defvar directory-sep-char
+This variable holds the character that Emacs normally uses to separate
+file name components.  The default value is @code{?/}, but on MS-Windows
+you can set it to @code{?\\}; then the functions that transform file names
+use backslashes in their output.
+
+File names using backslashes work as input to Lisp primitives even on
+MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
+value of @code{?/}.
+@end defvar
+@end ignore
+
+@node Relative File Names
+@subsection Absolute and Relative File Names
+@cindex absolute file name
+@cindex relative file name
+
+  All the directories in the file system form a tree starting at the
+root directory.  A file name can specify all the directory names
+starting from the root of the tree; then it is called an @dfn{absolute}
+file name.  Or it can specify the position of the file in the tree
+relative to a default directory; then it is called a @dfn{relative} file
+name.  On Unix and GNU/Linux, an absolute file name starts with a slash
+or a tilde (@samp{~}), and a relative one does not.  On MS-DOS and
+MS-Windows, an absolute file name starts with a slash or a backslash, or
+with a drive specification @samp{@var{x}:/}, where @var{x} is the
+@dfn{drive letter}.  The rules on VMS are complicated.
+
+@defun file-name-absolute-p filename
+This function returns @code{t} if file @var{filename} is an absolute
+file name, @code{nil} otherwise.  On VMS, this function understands both
+Unix syntax and VMS syntax.
+
+@example
+@group
+(file-name-absolute-p "~rms/foo")
+     @result{} t
+@end group
+@group
+(file-name-absolute-p "rms/foo")
+     @result{} nil
+@end group
+@group
+(file-name-absolute-p "/user/rms/foo")
+     @result{} t
+@end group
+@end example
+@end defun
+
+  Given a possibly relative file name, you can convert it to an
+absolute name using @code{expand-file-name} (@pxref{File Name
+Expansion}).  This function converts absolute file names to relative
+names:
+
+@defun file-relative-name filename &optional directory
+This function tries to return a relative name that is equivalent to
+@var{filename}, assuming the result will be interpreted relative to
+@var{directory} (an absolute directory name or directory file name).
+If @var{directory} is omitted or @code{nil}, it defaults to the
+current buffer's default directory.
+
+On some operating systems, an absolute file name begins with a device
+name.  On such systems, @var{filename} has no relative equivalent based
+on @var{directory} if they start with two different device names.  In
+this case, @code{file-relative-name} returns @var{filename} in absolute
+form.
+
+@example
+(file-relative-name "/foo/bar" "/foo/")
+     @result{} "bar"
+(file-relative-name "/foo/bar" "/hack/")
+     @result{} "../foo/bar"
+@end example
+@end defun
+
+@node Directory Names
+@comment  node-name,  next,  previous,  up
+@subsection Directory Names
+@cindex directory name
+@cindex file name of directory
+
+  A @dfn{directory name} is the name of a directory.  A directory is
+actually a kind of file, so it has a file name, which is related to
+the directory name but not identical to it.  (This is not quite the
+same as the usual Unix terminology.)  These two different names for
+the same entity are related by a syntactic transformation.  On GNU and
+Unix systems, this is simple: a directory name ends in a slash,
+whereas the directory's name as a file lacks that slash.  On MS-DOS and
+VMS, the relationship is more complicated.
+
+  The difference between a directory name and its name as a file is
+subtle but crucial.  When an Emacs variable or function argument is
+described as being a directory name, a file name of a directory is not
+acceptable.  When @code{file-name-directory} returns a string, that is
+always a directory name.
+
+  The following two functions convert between directory names and file
+names.  They do nothing special with environment variable substitutions
+such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
+
+@defun file-name-as-directory filename
+This function returns a string representing @var{filename} in a form
+that the operating system will interpret as the name of a directory.  On
+most systems, this means appending a slash to the string (if it does not
+already end in one).  On VMS, the function converts a string of the form
+@file{[X]Y.DIR.1} to the form @file{[X.Y]}.
+
+@example
+@group
+(file-name-as-directory "~rms/lewis")
+     @result{} "~rms/lewis/"
+@end group
+@end example
+@end defun
+
+@defun directory-file-name dirname
+This function returns a string representing @var{dirname} in a form that
+the operating system will interpret as the name of a file.  On most
+systems, this means removing the final slash (or backslash) from the
+string.  On VMS, the function converts a string of the form @file{[X.Y]}
+to @file{[X]Y.DIR.1}.
+
+@example
+@group
+(directory-file-name "~lewis/")
+     @result{} "~lewis"
+@end group
+@end example
+@end defun
+
+  Given a directory name, you can combine it with a relative file name
+using @code{concat}:
+
+@example
+(concat @var{dirname} @var{relfile})
+@end example
+
+@noindent
+Be sure to verify that the file name is relative before doing that.
+If you use an absolute file name, the results could be syntactically
+invalid or refer to the wrong file.
+
+  If you want to use a directory file name in making such a
+combination, you must first convert it to a directory name using
+@code{file-name-as-directory}:
+
+@example
+(concat (file-name-as-directory @var{dirfile}) @var{relfile})
+@end example
+
+@noindent
+Don't try concatenating a slash by hand, as in
+
+@example
+;;; @r{Wrong!}
+(concat @var{dirfile} "/" @var{relfile})
+@end example
+
+@noindent
+because this is not portable.  Always use
+@code{file-name-as-directory}.
+
+@cindex directory name abbreviation
+  Directory name abbreviations are useful for directories that are
+normally accessed through symbolic links.  Sometimes the users recognize
+primarily the link's name as ``the name'' of the directory, and find it
+annoying to see the directory's ``real'' name.  If you define the link
+name as an abbreviation for the ``real'' name, Emacs shows users the
+abbreviation instead.
+
+@defvar directory-abbrev-alist
+The variable @code{directory-abbrev-alist} contains an alist of
+abbreviations to use for file directories.  Each element has the form
+@code{(@var{from} . @var{to})}, and says to replace @var{from} with
+@var{to} when it appears in a directory name.  The @var{from} string is
+actually a regular expression; it should always start with @samp{^}.
+The @var{to} string should be an ordinary absolute directory name.  Do
+not use @samp{~} to stand for a home directory in that string.  The
+function @code{abbreviate-file-name} performs these substitutions.
+
+You can set this variable in @file{site-init.el} to describe the
+abbreviations appropriate for your site.
+
+Here's an example, from a system on which file system @file{/home/fsf}
+and so on are normally accessed through symbolic links named @file{/fsf}
+and so on.
+
+@example
+(("^/home/fsf" . "/fsf")
+ ("^/home/gp" . "/gp")
+ ("^/home/gd" . "/gd"))
+@end example
+@end defvar
+
+  To convert a directory name to its abbreviation, use this
+function:
+
+@defun abbreviate-file-name filename
+@anchor{Definition of abbreviate-file-name}
+This function applies abbreviations from @code{directory-abbrev-alist}
+to its argument, and substitutes @samp{~} for the user's home
+directory.  You can use it for directory names and for file names,
+because it recognizes abbreviations even as part of the name.
+@end defun
+
+@node File Name Expansion
+@subsection Functions that Expand Filenames
+@cindex expansion of file names
+
+  @dfn{Expansion} of a file name means converting a relative file name
+to an absolute one.  Since this is done relative to a default directory,
+you must specify the default directory name as well as the file name to
+be expanded.  Expansion also simplifies file names by eliminating
+redundancies such as @file{./} and @file{@var{name}/../}.
+
+@defun expand-file-name filename &optional directory
+This function converts @var{filename} to an absolute file name.  If
+@var{directory} is supplied, it is the default directory to start with
+if @var{filename} is relative.  (The value of @var{directory} should
+itself be an absolute directory name or directory file name; it may
+start with @samp{~}.)  Otherwise, the current buffer's value of
+@code{default-directory} is used.  For example:
+
+@example
+@group
+(expand-file-name "foo")
+     @result{} "/xcssun/users/rms/lewis/foo"
+@end group
+@group
+(expand-file-name "../foo")
+     @result{} "/xcssun/users/rms/foo"
+@end group
+@group
+(expand-file-name "foo" "/usr/spool/")
+     @result{} "/usr/spool/foo"
+@end group
+@group
+(expand-file-name "$HOME/foo")
+     @result{} "/xcssun/users/rms/lewis/$HOME/foo"
+@end group
+@end example
+
+If the part of the combined file name before the first slash is
+@samp{~}, it expands to the value of the @env{HOME} environment
+variable (usually your home directory).  If the part before the first
+slash is @samp{~@var{user}} and if @var{user} is a valid login name,
+it expands to @var{user}'s home directory.
+
+Filenames containing @samp{.} or @samp{..} are simplified to their
+canonical form:
+
+@example
+@group
+(expand-file-name "bar/../foo")
+     @result{} "/xcssun/users/rms/lewis/foo"
+@end group
+@end example
+
+In some cases, a leading @samp{..} component can remain in the output:
+
+@example
+@group
+(expand-file-name "../home" "/")
+     @result{} "/../home"
+@end group
+@end example
+
+@noindent
+This is for the sake of filesystems that have the concept of a
+``superroot'' above the root directory @file{/}.  On other filesystems,
+@file{/../} is interpreted exactly the same as @file{/}.
+
+Note that @code{expand-file-name} does @emph{not} expand environment
+variables; only @code{substitute-in-file-name} does that.
+
+Note also that @code{expand-file-name} does not follow symbolic links
+at any level.  This results in a difference between the way
+@code{file-truename} and @code{expand-file-name} treat @samp{..}.
+Assuming that @samp{/tmp/bar} is a symbolic link to the directory
+@samp{/tmp/foo/bar} we get:
+
+@example
+@group
+(file-truename "/tmp/bar/../myfile")
+     @result{} "/tmp/foo/myfile"
+@end group
+@group
+(expand-file-name "/tmp/bar/../myfile")
+     @result{} "/tmp/myfile"
+@end group
+@end example
+
+If you may need to follow symbolic links preceding @samp{..}, you
+should make sure to call @code{file-truename} without prior direct or
+indirect calls to @code{expand-file-name}.  @xref{Truenames}.
+@end defun
+
+@defvar default-directory
+The value of this buffer-local variable is the default directory for the
+current buffer.  It should be an absolute directory name; it may start
+with @samp{~}.  This variable is buffer-local in every buffer.
+
+@code{expand-file-name} uses the default directory when its second
+argument is @code{nil}.
+
+Aside from VMS, the value is always a string ending with a slash.
+
+@example
+@group
+default-directory
+     @result{} "/user/lewis/manual/"
+@end group
+@end example
+@end defvar
+
+@defun substitute-in-file-name filename
+@anchor{Definition of substitute-in-file-name}
+This function replaces environment variable references in
+@var{filename} with the environment variable values.  Following
+standard Unix shell syntax, @samp{$} is the prefix to substitute an
+environment variable value.  If the input contains @samp{$$}, that is
+converted to @samp{$}; this gives the user a way to ``quote'' a
+@samp{$}.
+
+The environment variable name is the series of alphanumeric characters
+(including underscores) that follow the @samp{$}.  If the character following
+the @samp{$} is a @samp{@{}, then the variable name is everything up to the
+matching @samp{@}}.
+
+Calling @code{substitute-in-file-name} on output produced by
+@code{substitute-in-file-name} tends to give incorrect results.  For
+instance, use of @samp{$$} to quote a single @samp{$} won't work
+properly, and @samp{$} in an environment variable's value could lead
+to repeated substitution.  Therefore, programs that call this function
+and put the output where it will be passed to this function need to
+double all @samp{$} characters to prevent subsequent incorrect
+results.
+
+@c Wordy to avoid overfull hbox.  --rjc 15mar92
+Here we assume that the environment variable @code{HOME}, which holds
+the user's home directory name, has value @samp{/xcssun/users/rms}.
+
+@example
+@group
+(substitute-in-file-name "$HOME/foo")
+     @result{} "/xcssun/users/rms/foo"
+@end group
+@end example
+
+After substitution, if a @samp{~} or a @samp{/} appears immediately
+after another @samp{/}, the function discards everything before it (up
+through the immediately preceding @samp{/}).
+
+@example
+@group
+(substitute-in-file-name "bar/~/foo")
+     @result{} "~/foo"
+@end group
+@group
+(substitute-in-file-name "/usr/local/$HOME/foo")
+     @result{} "/xcssun/users/rms/foo"
+     ;; @r{@file{/usr/local/} has been discarded.}
+@end group
+@end example
+
+On VMS, @samp{$} substitution is not done, so this function does nothing
+on VMS except discard superfluous initial components as shown above.
+@end defun
+
+@node Unique File Names
+@subsection Generating Unique File Names
+
+  Some programs need to write temporary files.  Here is the usual way to
+construct a name for such a file:
+
+@example
+(make-temp-file @var{name-of-application})
+@end example
+
+@noindent
+The job of @code{make-temp-file} is to prevent two different users or
+two different jobs from trying to use the exact same file name.
+
+@defun make-temp-file prefix &optional dir-flag suffix
+This function creates a temporary file and returns its name.  Emacs
+creates the temporary file's name by adding to @var{prefix} some
+random characters that are different in each Emacs job.  The result is
+guaranteed to be a newly created empty file.  On MS-DOS, this function
+can truncate the @var{string} prefix to fit into the 8+3 file-name
+limits.  If @var{prefix} is a relative file name, it is expanded
+against @code{temporary-file-directory}.
+
+@example
+@group
+(make-temp-file "foo")
+     @result{} "/tmp/foo232J6v"
+@end group
+@end example
+
+When @code{make-temp-file} returns, the file has been created and is
+empty.  At that point, you should write the intended contents into the
+file.
+
+If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
+empty directory instead of an empty file.  It returns the file name,
+not the directory name, of that directory.  @xref{Directory Names}.
+
+If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
+the end of the file name.
+
+To prevent conflicts among different libraries running in the same
+Emacs, each Lisp program that uses @code{make-temp-file} should have its
+own @var{prefix}.  The number added to the end of @var{prefix}
+distinguishes between the same application running in different Emacs
+jobs.  Additional added characters permit a large number of distinct
+names even in one Emacs job.
+@end defun
+
+  The default directory for temporary files is controlled by the
+variable @code{temporary-file-directory}.  This variable gives the user
+a uniform way to specify the directory for all temporary files.  Some
+programs use @code{small-temporary-file-directory} instead, if that is
+non-@code{nil}.  To use it, you should expand the prefix against
+the proper directory before calling @code{make-temp-file}.
+
+  In older Emacs versions where @code{make-temp-file} does not exist,
+you should use @code{make-temp-name} instead:
+
+@example
+(make-temp-name
+ (expand-file-name @var{name-of-application}
+                   temporary-file-directory))
+@end example
+
+@defun make-temp-name string
+This function generates a string that can be used as a unique file
+name.  The name starts with @var{string}, and has several random
+characters appended to it, which are different in each Emacs job.  It
+is like @code{make-temp-file} except that it just constructs a name,
+and does not create a file.  Another difference is that @var{string}
+should be an absolute file name.  On MS-DOS, this function can
+truncate the @var{string} prefix to fit into the 8+3 file-name limits.
+@end defun
+
+@defvar temporary-file-directory
+@cindex @code{TMPDIR} environment variable
+@cindex @code{TMP} environment variable
+@cindex @code{TEMP} environment variable
+This variable specifies the directory name for creating temporary files.
+Its value should be a directory name (@pxref{Directory Names}), but it
+is good for Lisp programs to cope if the value is a directory's file
+name instead.  Using the value as the second argument to
+@code{expand-file-name} is a good way to achieve that.
+
+The default value is determined in a reasonable way for your operating
+system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
+environment variables, with a fall-back to a system-dependent name if
+none of these variables is defined.
+
+Even if you do not use @code{make-temp-file} to create the temporary
+file, you should still use this variable to decide which directory to
+put the file in.  However, if you expect the file to be small, you
+should use @code{small-temporary-file-directory} first if that is
+non-@code{nil}.
+@end defvar
+
+@defvar small-temporary-file-directory
+This variable specifies the directory name for
+creating certain temporary files, which are likely to be small.
+
+If you want to write a temporary file which is likely to be small, you
+should compute the directory like this:
+
+@example
+(make-temp-file
+  (expand-file-name @var{prefix}
+                    (or small-temporary-file-directory
+                        temporary-file-directory)))
+@end example
+@end defvar
+
+@node File Name Completion
+@subsection File Name Completion
+@cindex file name completion subroutines
+@cindex completion, file name
+
+  This section describes low-level subroutines for completing a file
+name.  For higher level functions, see @ref{Reading File Names}.
+
+@defun file-name-all-completions partial-filename directory
+This function returns a list of all possible completions for a file
+whose name starts with @var{partial-filename} in directory
+@var{directory}.  The order of the completions is the order of the files
+in the directory, which is unpredictable and conveys no useful
+information.
+
+The argument @var{partial-filename} must be a file name containing no
+directory part and no slash (or backslash on some systems).  The current
+buffer's default directory is prepended to @var{directory}, if
+@var{directory} is not absolute.
+
+In the following example, suppose that @file{~rms/lewis} is the current
+default directory, and has five files whose names begin with @samp{f}:
+@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
+@file{file.c.~2~}.@refill
+
+@example
+@group
+(file-name-all-completions "f" "")
+     @result{} ("foo" "file~" "file.c.~2~"
+                "file.c.~1~" "file.c")
+@end group
+
+@group
+(file-name-all-completions "fo" "")
+     @result{} ("foo")
+@end group
+@end example
+@end defun
+
+@defun file-name-completion filename directory &optional predicate
+This function completes the file name @var{filename} in directory
+@var{directory}.  It returns the longest prefix common to all file names
+in directory @var{directory} that start with @var{filename}.  If
+@var{predicate} is non-@code{nil} then it ignores possible completions
+that don't satisfy @var{predicate}, after calling that function
+with one argument, the expanded absolute file name.
+
+If only one match exists and @var{filename} matches it exactly, the
+function returns @code{t}.  The function returns @code{nil} if directory
+@var{directory} contains no name starting with @var{filename}.
+
+In the following example, suppose that the current default directory
+has five files whose names begin with @samp{f}: @file{foo},
+@file{file~}, @file{file.c}, @file{file.c.~1~}, and
+@file{file.c.~2~}.@refill
+
+@example
+@group
+(file-name-completion "fi" "")
+     @result{} "file"
+@end group
+
+@group
+(file-name-completion "file.c.~1" "")
+     @result{} "file.c.~1~"
+@end group
+
+@group
+(file-name-completion "file.c.~1~" "")
+     @result{} t
+@end group
+
+@group
+(file-name-completion "file.c.~3" "")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defopt completion-ignored-extensions
+@code{file-name-completion} usually ignores file names that end in any
+string in this list.  It does not ignore them when all the possible
+completions end in one of these suffixes.  This variable has no effect
+on @code{file-name-all-completions}.@refill
+
+A typical value might look like this:
+
+@example
+@group
+completion-ignored-extensions
+     @result{} (".o" ".elc" "~" ".dvi")
+@end group
+@end example
+
+If an element of @code{completion-ignored-extensions} ends in a slash
+@samp{/}, it signals a directory.  The elements which do @emph{not} end
+in a slash will never match a directory; thus, the above value will not
+filter out a directory named @file{foo.elc}.
+@end defopt
+
+@node Standard File Names
+@subsection Standard File Names
+
+  Most of the file names used in Lisp programs are entered by the user.
+But occasionally a Lisp program needs to specify a standard file name
+for a particular use---typically, to hold customization information
+about each user.  For example, abbrev definitions are stored (by
+default) in the file @file{~/.abbrev_defs}; the @code{completion}
+package stores completions in the file @file{~/.completions}.  These are
+two of the many standard file names used by parts of Emacs for certain
+purposes.
+
+  Various operating systems have their own conventions for valid file
+names and for which file names to use for user profile data.  A Lisp
+program which reads a file using a standard file name ought to use, on
+each type of system, a file name suitable for that system.  The function
+@code{convert-standard-filename} makes this easy to do.
+
+@defun convert-standard-filename filename
+This function alters the file name @var{filename} to fit the conventions
+of the operating system in use, and returns the result as a new string.
+@end defun
+
+  The recommended way to specify a standard file name in a Lisp program
+is to choose a name which fits the conventions of GNU and Unix systems,
+usually with a nondirectory part that starts with a period, and pass it
+to @code{convert-standard-filename} instead of using it directly.  Here
+is an example from the @code{completion} package:
+
+@example
+(defvar save-completions-file-name
+        (convert-standard-filename "~/.completions")
+  "*The file name to save completions to.")
+@end example
+
+  On GNU and Unix systems, and on some other systems as well,
+@code{convert-standard-filename} returns its argument unchanged.  On
+some other systems, it alters the name to fit the system's conventions.
+
+  For example, on MS-DOS the alterations made by this function include
+converting a leading @samp{.}  to @samp{_}, converting a @samp{_} in the
+middle of the name to @samp{.} if there is no other @samp{.}, inserting
+a @samp{.} after eight characters if there is none, and truncating to
+three characters after the @samp{.}.  (It makes other changes as well.)
+Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
+@file{.completions} becomes @file{_complet.ion}.
+
+@node Contents of Directories
+@section Contents of Directories
+@cindex directory-oriented functions
+@cindex file names in directory
+
+  A directory is a kind of file that contains other files entered under
+various names.  Directories are a feature of the file system.
+
+  Emacs can list the names of the files in a directory as a Lisp list,
+or display the names in a buffer using the @code{ls} shell command.  In
+the latter case, it can optionally display information about each file,
+depending on the options passed to the @code{ls} command.
+
+@defun directory-files directory &optional full-name match-regexp nosort
+This function returns a list of the names of the files in the directory
+@var{directory}.  By default, the list is in alphabetical order.
+
+If @var{full-name} is non-@code{nil}, the function returns the files'
+absolute file names.  Otherwise, it returns the names relative to
+the specified directory.
+
+If @var{match-regexp} is non-@code{nil}, this function returns only
+those file names that contain a match for that regular expression---the
+other file names are excluded from the list.  On case-insensitive
+filesystems, the regular expression matching is case-insensitive.
+
+@c Emacs 19 feature
+If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
+the list, so you get the file names in no particular order.  Use this if
+you want the utmost possible speed and don't care what order the files
+are processed in.  If the order of processing is visible to the user,
+then the user will probably be happier if you do sort the names.
+
+@example
+@group
+(directory-files "~lewis")
+     @result{} ("#foo#" "#foo.el#" "." ".."
+         "dired-mods.el" "files.texi"
+         "files.texi.~1~")
+@end group
+@end example
+
+An error is signaled if @var{directory} is not the name of a directory
+that can be read.
+@end defun
+
+@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
+This is similar to @code{directory-files} in deciding which files
+to report on and how to report their names.  However, instead
+of returning a list of file names, it returns for each file a
+list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
+is what @code{file-attributes} would return for that file.
+The optional argument @var{id-format} has the same meaning as the
+corresponding argument to @code{file-attributes} (@pxref{Definition
+of file-attributes}).
+@end defun
+
+@defun file-name-all-versions file dirname
+This function returns a list of all versions of the file named
+@var{file} in directory @var{dirname}.  It is only available on VMS.
+@end defun
+
+@defun file-expand-wildcards pattern &optional full
+This function expands the wildcard pattern @var{pattern}, returning
+a list of file names that match it.
+
+If @var{pattern} is written as an absolute file name,
+the values are absolute also.
+
+If @var{pattern} is written as a relative file name, it is interpreted
+relative to the current default directory.  The file names returned are
+normally also relative to the current default directory.  However, if
+@var{full} is non-@code{nil}, they are absolute.
+@end defun
+
+@defun insert-directory file switches &optional wildcard full-directory-p
+This function inserts (in the current buffer) a directory listing for
+directory @var{file}, formatted with @code{ls} according to
+@var{switches}.  It leaves point after the inserted text.
+@var{switches} may be a string of options, or a list of strings
+representing individual options.
+
+The argument @var{file} may be either a directory name or a file
+specification including wildcard characters.  If @var{wildcard} is
+non-@code{nil}, that means treat @var{file} as a file specification with
+wildcards.
+
+If @var{full-directory-p} is non-@code{nil}, that means the directory
+listing is expected to show the full contents of a directory.  You
+should specify @code{t} when @var{file} is a directory and switches do
+not contain @samp{-d}.  (The @samp{-d} option to @code{ls} says to
+describe a directory itself as a file, rather than showing its
+contents.)
+
+On most systems, this function works by running a directory listing
+program whose name is in the variable @code{insert-directory-program}.
+If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
+@code{shell-file-name}, to expand the wildcards.
+
+MS-DOS and MS-Windows systems usually lack the standard Unix program
+@code{ls}, so this function emulates the standard Unix program @code{ls}
+with Lisp code.
+
+As a technical detail, when @var{switches} contains the long
+@samp{--dired} option, @code{insert-directory} treats it specially,
+for the sake of dired.  However, the normally equivalent short
+@samp{-D} option is just passed on to @code{insert-directory-program},
+as any other option.
+@end defun
+
+@defvar insert-directory-program
+This variable's value is the program to run to generate a directory listing
+for the function @code{insert-directory}.  It is ignored on systems
+which generate the listing with Lisp code.
+@end defvar
+
+@node Create/Delete Dirs
+@section Creating and Deleting Directories
+@cindex creating and deleting directories
+@c Emacs 19 features
+
+  Most Emacs Lisp file-manipulation functions get errors when used on
+files that are directories.  For example, you cannot delete a directory
+with @code{delete-file}.  These special functions exist to create and
+delete directories.
+
+@defun make-directory dirname &optional parents
+This function creates a directory named @var{dirname}.
+If @var{parents} is non-@code{nil}, as is always the case in an
+interactive call, that means to create the parent directories first,
+if they don't already exist.
+@end defun
+
+@defun delete-directory dirname
+This function deletes the directory named @var{dirname}.  The function
+@code{delete-file} does not work for files that are directories; you
+must use @code{delete-directory} for them.  If the directory contains
+any files, @code{delete-directory} signals an error.
+
+This function only follows symbolic links at the level of parent
+directories.
+@end defun
+
+@node Magic File Names
+@section Making Certain File Names ``Magic''
+@cindex magic file names
+
+@c Emacs 19 feature
+  You can implement special handling for certain file names.  This is
+called making those names @dfn{magic}.  The principal use for this
+feature is in implementing remote file names (@pxref{Remote Files,,
+Remote Files, emacs, The GNU Emacs Manual}).
+
+  To define a kind of magic file name, you must supply a regular
+expression to define the class of names (all those that match the
+regular expression), plus a handler that implements all the primitive
+Emacs file operations for file names that do match.
+
+  The variable @code{file-name-handler-alist} holds a list of handlers,
+together with regular expressions that determine when to apply each
+handler.  Each element has this form:
+
+@example
+(@var{regexp} . @var{handler})
+@end example
+
+@noindent
+All the Emacs primitives for file access and file name transformation
+check the given file name against @code{file-name-handler-alist}.  If
+the file name matches @var{regexp}, the primitives handle that file by
+calling @var{handler}.
+
+  The first argument given to @var{handler} is the name of the
+primitive, as a symbol; the remaining arguments are the arguments that
+were passed to that primitive.  (The first of these arguments is most
+often the file name itself.)  For example, if you do this:
+
+@example
+(file-exists-p @var{filename})
+@end example
+
+@noindent
+and @var{filename} has handler @var{handler}, then @var{handler} is
+called like this:
+
+@example
+(funcall @var{handler} 'file-exists-p @var{filename})
+@end example
+
+  When a function takes two or more arguments that must be file names,
+it checks each of those names for a handler.  For example, if you do
+this:
+
+@example
+(expand-file-name @var{filename} @var{dirname})
+@end example
+
+@noindent
+then it checks for a handler for @var{filename} and then for a handler
+for @var{dirname}.  In either case, the @var{handler} is called like
+this:
+
+@example
+(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
+@end example
+
+@noindent
+The @var{handler} then needs to figure out whether to handle
+@var{filename} or @var{dirname}.
+
+  If the specified file name matches more than one handler, the one
+whose match starts last in the file name gets precedence.  This rule
+is chosen so that handlers for jobs such as uncompression are handled
+first, before handlers for jobs such as remote file access.
+
+  Here are the operations that a magic file name handler gets to handle:
+
+@ifnottex
+@noindent
+@code{access-file}, @code{add-name-to-file},
+@code{byte-compiler-base-file-name},@*
+@code{copy-file}, @code{delete-directory},
+@code{delete-file},
+@code{diff-latest-backup-file},
+@code{directory-file-name},
+@code{directory-files},
+@code{directory-files-and-attributes},
+@code{dired-compress-file}, @code{dired-uncache},@*
+@code{expand-file-name},
+@code{file-accessible-directory-p},
+@code{file-attributes},
+@code{file-directory-p},
+@code{file-executable-p}, @code{file-exists-p},
+@code{file-local-copy}, @code{file-remote-p},
+@code{file-modes}, @code{file-name-all-completions},
+@code{file-name-as-directory},
+@code{file-name-completion},
+@code{file-name-directory},
+@code{file-name-nondirectory},
+@code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-ownership-preserved-p},
+@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
+@code{file-truename}, @code{file-writable-p},
+@code{find-backup-file-name},
+@code{find-file-noselect},@*
+@code{get-file-buffer},
+@code{insert-directory},
+@code{insert-file-contents},@*
+@code{load},
+@code{make-auto-save-file-name},
+@code{make-directory},
+@code{make-directory-internal},
+@code{make-symbolic-link},@*
+@code{process-file},
+@code{rename-file}, @code{set-file-modes}, @code{set-file-times},
+@code{set-visited-file-modtime}, @code{shell-command},
+@code{start-file-process},
+@code{substitute-in-file-name},@*
+@code{unhandled-file-name-directory},
+@code{vc-registered},
+@code{verify-visited-file-modtime},@*
+@code{write-region}.
+@end ifnottex
+@iftex
+@noindent
+@flushleft
+@code{access-file}, @code{add-name-to-file},
+@code{byte-com@discretionary{}{}{}piler-base-file-name},
+@code{copy-file}, @code{delete-directory},
+@code{delete-file},
+@code{diff-latest-backup-file},
+@code{directory-file-name},
+@code{directory-files},
+@code{directory-files-and-at@discretionary{}{}{}tributes},
+@code{dired-compress-file}, @code{dired-uncache},
+@code{expand-file-name},
+@code{file-accessible-direc@discretionary{}{}{}tory-p},
+@code{file-attributes},
+@code{file-direct@discretionary{}{}{}ory-p},
+@code{file-executable-p}, @code{file-exists-p},
+@code{file-local-copy}, @code{file-remote-p},
+@code{file-modes}, @code{file-name-all-completions},
+@code{file-name-as-directory},
+@code{file-name-completion},
+@code{file-name-directory},
+@code{file-name-nondirec@discretionary{}{}{}tory},
+@code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-ownership-pre@discretionary{}{}{}served-p},
+@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
+@code{file-truename}, @code{file-writable-p},
+@code{find-backup-file-name},
+@code{find-file-noselect},
+@code{get-file-buffer},
+@code{insert-directory},
+@code{insert-file-contents},
+@code{load}, @code{make-direc@discretionary{}{}{}tory},
+@code{make-direc@discretionary{}{}{}tory-internal},
+@code{make-symbolic-link},
+@code{process-file},
+@code{rename-file}, @code{set-file-modes},
+@code{set-visited-file-modtime}, @code{shell-command},
+@code{start-file-process},
+@code{substitute-in-file-name},
+@code{unhandled-file-name-directory},
+@code{vc-regis@discretionary{}{}{}tered},
+@code{verify-visited-file-modtime},
+@code{write-region}.
+@end flushleft
+@end iftex
+
+  Handlers for @code{insert-file-contents} typically need to clear the
+buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
+@var{visit} argument is non-@code{nil}.  This also has the effect of
+unlocking the buffer if it is locked.
+
+  The handler function must handle all of the above operations, and
+possibly others to be added in the future.  It need not implement all
+these operations itself---when it has nothing special to do for a
+certain operation, it can reinvoke the primitive, to handle the
+operation ``in the usual way.''  It should always reinvoke the primitive
+for an operation it does not recognize.  Here's one way to do this:
+
+@smallexample
+(defun my-file-handler (operation &rest args)
+  ;; @r{First check for the specific operations}
+  ;; @r{that we have special handling for.}
+  (cond ((eq operation 'insert-file-contents) @dots{})
+        ((eq operation 'write-region) @dots{})
+        @dots{}
+        ;; @r{Handle any operation we don't know about.}
+        (t (let ((inhibit-file-name-handlers
+                  (cons 'my-file-handler
+                        (and (eq inhibit-file-name-operation operation)
+                             inhibit-file-name-handlers)))
+                 (inhibit-file-name-operation operation))
+             (apply operation args)))))
+@end smallexample
+
+  When a handler function decides to call the ordinary Emacs primitive for
+the operation at hand, it needs to prevent the primitive from calling
+the same handler once again, thus leading to an infinite recursion.  The
+example above shows how to do this, with the variables
+@code{inhibit-file-name-handlers} and
+@code{inhibit-file-name-operation}.  Be careful to use them exactly as
+shown above; the details are crucial for proper behavior in the case of
+multiple handlers, and for operations that have two file names that may
+each have handlers.
+
+@kindex safe-magic (@r{property})
+  Handlers that don't really do anything special for actual access to the
+file---such as the ones that implement completion of host names for
+remote file names---should have a non-@code{nil} @code{safe-magic}
+property.  For instance, Emacs normally ``protects'' directory names
+it finds in @code{PATH} from becoming magic, if they look like magic
+file names, by prefixing them with @samp{/:}.  But if the handler that
+would be used for them has a non-@code{nil} @code{safe-magic}
+property, the @samp{/:} is not added.
+
+@kindex operations (@r{property})
+  A file name handler can have an @code{operations} property to
+declare which operations it handles in a nontrivial way.  If this
+property has a non-@code{nil} value, it should be a list of
+operations; then only those operations will call the handler.  This
+avoids inefficiency, but its main purpose is for autoloaded handler
+functions, so that they won't be loaded except when they have real
+work to do.
+
+  Simply deferring all operations to the usual primitives does not
+work.  For instance, if the file name handler applies to
+@code{file-exists-p}, then it must handle @code{load} itself, because
+the usual @code{load} code won't work properly in that case.  However,
+if the handler uses the @code{operations} property to say it doesn't
+handle @code{file-exists-p}, then it need not handle @code{load}
+nontrivially.
+
+@defvar inhibit-file-name-handlers
+This variable holds a list of handlers whose use is presently inhibited
+for a certain operation.
+@end defvar
+
+@defvar inhibit-file-name-operation
+The operation for which certain handlers are presently inhibited.
+@end defvar
+
+@defun find-file-name-handler file operation
+This function returns the handler function for file name @var{file},
+or @code{nil} if there is none.  The argument @var{operation} should
+be the operation to be performed on the file---the value you will pass
+to the handler as its first argument when you call it.  If
+@var{operation} equals @code{inhibit-file-name-operation}, or if it is
+not found in the @code{operations} property of the handler, this
+function returns @code{nil}.
+@end defun
+
+@defun file-local-copy filename
+This function copies file @var{filename} to an ordinary non-magic file
+on the local machine, if it isn't on the local machine already.  Magic
+file names should handle the @code{file-local-copy} operation if they
+refer to files on other machines.  A magic file name that is used for
+other purposes than remote file access should not handle
+@code{file-local-copy}; then this function will treat the file as
+local.
+
+If @var{filename} is local, whether magic or not, this function does
+nothing and returns @code{nil}.  Otherwise it returns the file name
+of the local copy file.
+@end defun
+
+@defun file-remote-p filename &optional identification connected
+This function tests whether @var{filename} is a remote file.  If
+@var{filename} is local (not remote), the return value is @code{nil}.
+If @var{filename} is indeed remote, the return value is a string that
+identifies the remote system.
+
+This identifier string can include a host name and a user name, as
+well as characters designating the method used to access the remote
+system.  For example, the remote identifier string for the filename
+@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
+
+If @code{file-remote-p} returns the same identifier for two different
+filenames, that means they are stored on the same file system and can
+be accessed locally with respect to each other.  This means, for
+example, that it is possible to start a remote process accessing both
+files at the same time.  Implementors of file handlers need to ensure
+this principle is valid.
+
+@var{identification} specifies which part of the identifier shall be
+returned as string.  @var{identification} can be the symbol
+@code{method}, @code{user} or @code{host}; any other value is handled
+like @code{nil} and means to return the complete identifier string.
+In the example above, the remote @code{user} identifier string would
+be @code{root}.
+
+If @var{connected} is non-@code{nil}, this function returns @code{nil}
+even if @var{filename} is remote, if Emacs has no network connection
+to its host.  This is useful when you want to avoid the delay of
+making connections when they don't exist.
+@end defun
+
+@defun unhandled-file-name-directory filename
+This function returns the name of a directory that is not magic.  It
+uses the directory part of @var{filename} if that is not magic.  For a
+magic file name, it invokes the file name handler, which therefore
+decides what value to return.
+
+This is useful for running a subprocess; every subprocess must have a
+non-magic directory to serve as its current directory, and this function
+is a good way to come up with one.
+@end defun
+
+@node Format Conversion
+@section File Format Conversion
+
+@cindex file format conversion
+@cindex encoding file formats
+@cindex decoding file formats
+@cindex text properties in files
+@cindex saving text properties
+  Emacs performs several steps to convert the data in a buffer (text,
+text properties, and possibly other information) to and from a
+representation suitable for storing into a file.  This section describes
+the fundamental functions that perform this @dfn{format conversion},
+namely @code{insert-file-contents} for reading a file into a buffer,
+and @code{write-region} for writing a buffer into a file.
+
+@menu
+* Overview: Format Conversion Overview.     @code{insert-file-contents} and @code{write-region}
+* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
+* Piecemeal: Format Conversion Piecemeal.   Specifying non-paired conversion.
+@end menu
+
+@node Format Conversion Overview
+@subsection Overview
+@noindent
+The function @code{insert-file-contents}:
+
+@itemize
+@item initially, inserts bytes from the file into the buffer;
+@item decodes bytes to characters as appropriate;
+@item processes formats as defined by entries in @code{format-alist}; and
+@item calls functions in @code{after-insert-file-functions}.
+@end itemize
+
+@noindent
+The function @code{write-region}:
+
+@itemize
+@item initially, calls functions in @code{write-region-annotate-functions};
+@item processes formats as defined by entries in @code{format-alist};
+@item encodes characters to bytes as appropriate; and
+@item modifies the file with the bytes.
+@end itemize
+
+  This shows the symmetry of the lowest-level operations; reading and
+writing handle things in opposite order.  The rest of this section
+describes the two facilities surrounding the three variables named
+above, as well as some related functions.  @ref{Coding Systems}, for
+details on character encoding and decoding.
+
+@node Format Conversion Round-Trip
+@subsection Round-Trip Specification
+
+  The most general of the two facilities is controlled by the variable
+@code{format-alist}, a list of @dfn{file format} specifications, which
+describe textual representations used in files for the data in an Emacs
+buffer.  The descriptions for reading and writing are paired, which is
+why we call this ``round-trip'' specification
+(@pxref{Format Conversion Piecemeal}, for non-paired specification).
+
+@defvar format-alist
+This list contains one format definition for each defined file format.
+Each format definition is a list of this form:
+
+@example
+(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
+@end example
+@end defvar
+
+@cindex format definition
+@noindent
+Here is what the elements in a format definition mean:
+
+@table @var
+@item name
+The name of this format.
+
+@item doc-string
+A documentation string for the format.
+
+@item regexp
+A regular expression which is used to recognize files represented in
+this format.
+
+@item from-fn
+A shell command or function to decode data in this format (to convert
+file data into the usual Emacs data representation).
+
+A shell command is represented as a string; Emacs runs the command as a
+filter to perform the conversion.
+
+If @var{from-fn} is a function, it is called with two arguments, @var{begin}
+and @var{end}, which specify the part of the buffer it should convert.
+It should convert the text by editing it in place.  Since this can
+change the length of the text, @var{from-fn} should return the modified
+end position.
+
+One responsibility of @var{from-fn} is to make sure that the beginning
+of the file no longer matches @var{regexp}.  Otherwise it is likely to
+get called again.
+
+@item to-fn
+A shell command or function to encode data in this format---that is, to
+convert the usual Emacs data representation into this format.
+
+If @var{to-fn} is a string, it is a shell command; Emacs runs the
+command as a filter to perform the conversion.
+
+If @var{to-fn} is a function, it is called with three arguments:
+@var{begin} and @var{end}, which specify the part of the buffer it
+should convert, and @var{buffer}, which specifies which buffer.  There
+are two ways it can do the conversion:
+
+@itemize @bullet
+@item
+By editing the buffer in place.  In this case, @var{to-fn} should
+return the end-position of the range of text, as modified.
+
+@item
+By returning a list of annotations.  This is a list of elements of the
+form @code{(@var{position} . @var{string})}, where @var{position} is an
+integer specifying the relative position in the text to be written, and
+@var{string} is the annotation to add there.  The list must be sorted in
+order of position when @var{to-fn} returns it.
+
+When @code{write-region} actually writes the text from the buffer to the
+file, it intermixes the specified annotations at the corresponding
+positions.  All this takes place without modifying the buffer.
+@end itemize
+
+@item modify
+A flag, @code{t} if the encoding function modifies the buffer, and
+@code{nil} if it works by returning a list of annotations.
+
+@item mode-fn
+A minor-mode function to call after visiting a file converted from this
+format.  The function is called with one argument, the integer 1;
+that tells a minor-mode function to enable the mode.
+@end table
+
+The function @code{insert-file-contents} automatically recognizes file
+formats when it reads the specified file.  It checks the text of the
+beginning of the file against the regular expressions of the format
+definitions, and if it finds a match, it calls the decoding function for
+that format.  Then it checks all the known formats over again.
+It keeps checking them until none of them is applicable.
+
+Visiting a file, with @code{find-file-noselect} or the commands that use
+it, performs conversion likewise (because it calls
+@code{insert-file-contents}); it also calls the mode function for each
+format that it decodes.  It stores a list of the format names in the
+buffer-local variable @code{buffer-file-format}.
+
+@defvar buffer-file-format
+This variable states the format of the visited file.  More precisely,
+this is a list of the file format names that were decoded in the course
+of visiting the current buffer's file.  It is always buffer-local in all
+buffers.
+@end defvar
+
+When @code{write-region} writes data into a file, it first calls the
+encoding functions for the formats listed in @code{buffer-file-format},
+in the order of appearance in the list.
+
+@deffn Command format-write-file file format &optional confirm
+This command writes the current buffer contents into the file
+@var{file} in format @var{format}, and makes that format the default
+for future saves of the buffer.  The argument @var{format} is a list
+of format names.  Except for the @var{format} argument, this command
+is similar to @code{write-file}.  In particular, @var{confirm} has the
+same meaning and interactive treatment as the corresponding argument
+to @code{write-file}.  @xref{Definition of write-file}.
+@end deffn
+
+@deffn Command format-find-file file format
+This command finds the file @var{file}, converting it according to
+format @var{format}.  It also makes @var{format} the default if the
+buffer is saved later.
+
+The argument @var{format} is a list of format names.  If @var{format} is
+@code{nil}, no conversion takes place.  Interactively, typing just
+@key{RET} for @var{format} specifies @code{nil}.
+@end deffn
+
+@deffn Command format-insert-file file format &optional beg end
+This command inserts the contents of file @var{file}, converting it
+according to format @var{format}.  If @var{beg} and @var{end} are
+non-@code{nil}, they specify which part of the file to read, as in
+@code{insert-file-contents} (@pxref{Reading from Files}).
+
+The return value is like what @code{insert-file-contents} returns: a
+list of the absolute file name and the length of the data inserted
+(after conversion).
+
+The argument @var{format} is a list of format names.  If @var{format} is
+@code{nil}, no conversion takes place.  Interactively, typing just
+@key{RET} for @var{format} specifies @code{nil}.
+@end deffn
+
+@defvar buffer-auto-save-file-format
+This variable specifies the format to use for auto-saving.  Its value is
+a list of format names, just like the value of
+@code{buffer-file-format}; however, it is used instead of
+@code{buffer-file-format} for writing auto-save files.  If the value
+is @code{t}, the default, auto-saving uses the same format as a
+regular save in the same buffer.  This variable is always buffer-local
+in all buffers.
+@end defvar
+
+@node Format Conversion Piecemeal
+@subsection Piecemeal Specification
+
+  In contrast to the round-trip specification described in the previous
+subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
+@code{after-insert-file-functions} and @code{write-region-annotate-functions}
+to separately control the respective reading and writing conversions.
+
+  Conversion starts with one representation and produces another
+representation.  When there is only one conversion to do, there is no
+conflict about what to start with.  However, when there are multiple
+conversions involved, conflict may arise when two conversions need to
+start with the same data.
+
+  This situation is best understood in the context of converting text
+properties during @code{write-region}.  For example, the character at
+position 42 in a buffer is @samp{X} with a text property @code{foo}.  If
+the conversion for @code{foo} is done by inserting into the buffer, say,
+@samp{FOO:}, then that changes the character at position 42 from
+@samp{X} to @samp{F}.  The next conversion will start with the wrong
+data straight away.
+
+  To avoid conflict, cooperative conversions do not modify the buffer,
+but instead specify @dfn{annotations}, a list of elements of the form
+@code{(@var{position} . @var{string})}, sorted in order of increasing
+@var{position}.
+
+  If there is more than one conversion, @code{write-region} merges their
+annotations destructively into one sorted list.  Later, when the text
+from the buffer is actually written to the file, it intermixes the
+specified annotations at the corresponding positions.  All this takes
+place without modifying the buffer.
+
+@c ??? What about ``overriding'' conversions like those allowed
+@c ??? for `write-region-annotate-functions', below?  --ttn
+
+  In contrast, when reading, the annotations intermixed with the text
+are handled immediately.  @code{insert-file-contents} sets point to the
+beginning of some text to be converted, then calls the conversion
+functions with the length of that text.  These functions should always
+return with point at the beginning of the inserted text.  This approach
+makes sense for reading because annotations removed by the first
+converter can't be mistakenly processed by a later converter.
+
+  Each conversion function should scan for the annotations it
+recognizes, remove the annotation, modify the buffer text (to set a text
+property, for example), and return the updated length of the text, as it
+stands after those changes.  The value returned by one function becomes
+the argument to the next function.
+
+@defvar write-region-annotate-functions
+A list of functions for @code{write-region} to call.  Each function in
+the list is called with two arguments: the start and end of the region
+to be written.  These functions should not alter the contents of the
+buffer.  Instead, they should return annotations.
+
+@c ??? Following adapted from comment in `build_annotations' (fileio.c).
+@c ??? Perhaps this is intended for internal use only?
+@c ??? Someone who understands this, please reword it. --ttn
+As a special case, if a function returns with a different buffer
+current, Emacs takes it to mean the current buffer contains altered text
+to be output, and discards all previous annotations because they should
+have been dealt with by this function.
+@end defvar
+
+@defvar after-insert-file-functions
+Each function in this list is called by @code{insert-file-contents}
+with one argument, the number of characters inserted, and with point
+at the beginning of the inserted text.  Each function should leave
+point unchanged, and return the new character count describing the
+inserted text as modified by the function.
+@c ??? The docstring mentions a handler from `file-name-handler-alist'
+@c     "intercepting" `insert-file-contents'.  Hmmm.  --ttn
+@end defvar
+
+  We invite users to write Lisp programs to store and retrieve text
+properties in files, using these hooks, and thus to experiment with
+various data formats and find good ones.  Eventually we hope users
+will produce good, general extensions we can install in Emacs.
+
+  We suggest not trying to handle arbitrary Lisp objects as text property
+names or values---because a program that general is probably difficult
+to write, and slow.  Instead, choose a set of possible data types that
+are reasonably flexible, and not too hard to encode.
+
+@ignore
+   arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
+@end ignore
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
new file mode 100644
index 00000000000..7d2ea7cf70e
--- /dev/null
+++ b/doc/lispref/frames.texi
@@ -0,0 +1,2208 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/frames
+@node Frames, Positions, Windows, Top
+@chapter Frames
+@cindex frame
+
+  In Emacs editing, A @dfn{frame} is a screen object that contains one
+or more Emacs windows.  It's the kind of object that is called a
+``window'' in the terminology of graphical environments; but we can't
+call it a ``window'' here, because Emacs uses that word in a different
+way.
+
+  A frame initially contains a single main window and/or a minibuffer
+window; you can subdivide the main window vertically or horizontally
+into smaller windows.  In Emacs Lisp, a @dfn{frame object} is a Lisp
+object that represents a frame on the screen.
+
+@cindex terminal frame
+  When Emacs runs on a text-only terminal, it starts with one
+@dfn{terminal frame}.  If you create additional ones, Emacs displays
+one and only one at any given time---on the terminal screen, of course.
+
+@cindex window frame
+  When Emacs communicates directly with a supported window system, such
+as X, it does not have a terminal frame; instead, it starts with
+a single @dfn{window frame}, but you can create more, and Emacs can
+display several such frames at once as is usual for window systems.
+
+@defun framep object
+This predicate returns a non-@code{nil} value if @var{object} is a
+frame, and @code{nil} otherwise.  For a frame, the value indicates which
+kind of display the frame uses:
+
+@table @code
+@item x
+The frame is displayed in an X window.
+@item t
+A terminal frame on a character display.
+@item mac
+The frame is displayed on a Macintosh.
+@item w32
+The frame is displayed on MS-Windows 9X/NT.
+@item pc
+The frame is displayed on an MS-DOS terminal.
+@end table
+@end defun
+
+@menu
+* Creating Frames::		Creating additional frames.
+* Multiple Displays::           Creating frames on other displays.
+* Frame Parameters::		Controlling frame size, position, font, etc.
+* Frame Titles::                Automatic updating of frame titles.
+* Deleting Frames::		Frames last until explicitly deleted.
+* Finding All Frames::		How to examine all existing frames.
+* Frames and Windows::		A frame contains windows;
+				  display of text always works through windows.
+* Minibuffers and Frames::	How a frame finds the minibuffer to use.
+* Input Focus::			Specifying the selected frame.
+* Visibility of Frames::	Frames may be visible or invisible, or icons.
+* Raising and Lowering::	Raising a frame makes it hide other windows;
+				  lowering it makes the others hide it.
+* Frame Configurations::	Saving the state of all frames.
+* Mouse Tracking::		Getting events that say when the mouse moves.
+* Mouse Position::		Asking where the mouse is, or moving it.
+* Pop-Up Menus::		Displaying a menu for the user to select from.
+* Dialog Boxes::                Displaying a box to ask yes or no.
+* Pointer Shape::               Specifying the shape of the mouse pointer.
+* Window System Selections::    Transferring text to and from other X clients.
+* Drag and Drop::               Internals of Drag-and-Drop implementation.
+* Color Names::	                Getting the definitions of color names.
+* Text Terminal Colors::        Defining colors for text-only terminals.
+* Resources::		        Getting resource values from the server.
+* Display Feature Testing::     Determining the features of a terminal.
+@end menu
+
+  @xref{Display}, for information about the related topic of
+controlling Emacs redisplay.
+
+@node Creating Frames
+@section Creating Frames
+
+To create a new frame, call the function @code{make-frame}.
+
+@defun make-frame &optional alist
+This function creates and returns a new frame, displaying the current
+buffer.  If you are using a supported window system, it makes a window
+frame; otherwise, it makes a terminal frame.
+
+The argument is an alist specifying frame parameters.  Any parameters
+not mentioned in @var{alist} default according to the value of the
+variable @code{default-frame-alist}; parameters not specified even there
+default from the standard X resources or whatever is used instead on
+your system.
+
+The set of possible parameters depends in principle on what kind of
+window system Emacs uses to display its frames.  @xref{Window Frame
+Parameters}, for documentation of individual parameters you can specify.
+
+This function itself does not make the new frame the selected frame.
+@xref{Input Focus}.  The previously selected frame remains selected.
+However, the window system may select the new frame for its own reasons,
+for instance if the frame appears under the mouse pointer and your
+setup is for focus to follow the pointer.
+@end defun
+
+@defvar before-make-frame-hook
+A normal hook run by @code{make-frame} before it actually creates the
+frame.
+@end defvar
+
+@defvar after-make-frame-functions
+An abnormal hook run by @code{make-frame} after it creates the frame.
+Each function in @code{after-make-frame-functions} receives one argument, the
+frame just created.
+@end defvar
+
+@node Multiple Displays
+@section Multiple Displays
+@cindex multiple X displays
+@cindex displays, multiple
+
+  A single Emacs can talk to more than one X display.
+Initially, Emacs uses just one display---the one chosen with the
+@code{DISPLAY} environment variable or with the @samp{--display} option
+(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}).  To connect to
+another display, use the command @code{make-frame-on-display} or specify
+the @code{display} frame parameter when you create the frame.
+
+  Emacs treats each X server as a separate terminal, giving each one its
+own selected frame and its own minibuffer windows.  However, only one of
+those frames is ``@emph{the} selected frame'' at any given moment, see
+@ref{Input Focus}.
+
+  A few Lisp variables are @dfn{terminal-local}; that is, they have a
+separate binding for each terminal.  The binding in effect at any time
+is the one for the terminal that the currently selected frame belongs
+to.  These variables include @code{default-minibuffer-frame},
+@code{defining-kbd-macro}, @code{last-kbd-macro}, and
+@code{system-key-alist}.  They are always terminal-local, and can never
+be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
+
+  A single X server can handle more than one screen.  A display name
+@samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
+part specifies the screen number for a given server.  When you use two
+screens belonging to one server, Emacs knows by the similarity in their
+names that they share a single keyboard, and it treats them as a single
+terminal.
+
+  Note that some graphical terminals can output to more than a one
+monitor (or other output device) at the same time.  On these
+``multi-monitor'' setups, a single @var{display} value controls the
+output to all the physical monitors.  In this situation, there is
+currently no platform-independent way for Emacs to distinguish between
+the different physical monitors.
+
+@deffn Command make-frame-on-display display &optional parameters
+This creates and returns a new frame on display @var{display}, taking
+the other frame parameters from @var{parameters}.  Aside from the
+@var{display} argument, it is like @code{make-frame} (@pxref{Creating
+Frames}).
+@end deffn
+
+@defun x-display-list
+This returns a list that indicates which X displays Emacs has a
+connection to.  The elements of the list are strings, and each one is
+a display name.
+@end defun
+
+@defun x-open-connection display &optional xrm-string must-succeed
+This function opens a connection to the X display @var{display}.  It
+does not create a frame on that display, but it permits you to check
+that communication can be established with that display.
+
+The optional argument @var{xrm-string}, if not @code{nil}, is a
+string of resource names and values, in the same format used in the
+@file{.Xresources} file.  The values you specify override the resource
+values recorded in the X server itself; they apply to all Emacs frames
+created on this display.  Here's an example of what this string might
+look like:
+
+@example
+"*BorderWidth: 3\n*InternalBorder: 2\n"
+@end example
+
+@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
+
+If @var{must-succeed} is non-@code{nil}, failure to open the connection
+terminates Emacs.  Otherwise, it is an ordinary Lisp error.
+@end defun
+
+@defun x-close-connection display
+This function closes the connection to display @var{display}.  Before
+you can do this, you must first delete all the frames that were open on
+that display (@pxref{Deleting Frames}).
+@end defun
+
+@node Frame Parameters
+@section Frame Parameters
+@cindex frame parameters
+
+  A frame has many parameters that control its appearance and behavior.
+Just what parameters a frame has depends on what display mechanism it
+uses.
+
+  Frame parameters exist mostly for the sake of window systems.  A
+terminal frame has a few parameters, mostly for compatibility's sake;
+only the @code{height}, @code{width}, @code{name}, @code{title},
+@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
+parameters do something special.  If the terminal supports colors, the
+parameters @code{foreground-color}, @code{background-color},
+@code{background-mode} and @code{display-type} are also meaningful.
+
+@menu
+* Parameter Access::       How to change a frame's parameters.
+* Initial Parameters::	   Specifying frame parameters when you make a frame.
+* Window Frame Parameters:: List of frame parameters for window systems.
+* Size and Position::      Changing the size and position of a frame.
+* Geometry::               Parsing geometry specifications.
+@end menu
+
+@node Parameter Access
+@subsection Access to Frame Parameters
+
+These functions let you read and change the parameter values of a
+frame.
+
+@defun frame-parameter frame parameter
+This function returns the value of the parameter @var{parameter} (a
+symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
+selected frame's parameter.  If @var{frame} has no setting for
+@var{parameter}, this function returns @code{nil}.
+@end defun
+
+@defun frame-parameters &optional frame
+The function @code{frame-parameters} returns an alist listing all the
+parameters of @var{frame} and their values.  If @var{frame} is
+@code{nil} or omitted, this returns the selected frame's parameters
+@end defun
+
+@defun modify-frame-parameters frame alist
+This function alters the parameters of frame @var{frame} based on the
+elements of @var{alist}.  Each element of @var{alist} has the form
+@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
+parameter.  If you don't mention a parameter in @var{alist}, its value
+doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
+frame.
+@end defun
+
+@defun modify-all-frames-parameters alist
+This function alters the frame parameters of all existing frames
+according to @var{alist}, then modifies @code{default-frame-alist}
+(and, if necessary, @code{initial-frame-alist}) to apply the same
+parameter values to frames that will be created henceforth.
+@end defun
+
+@node Initial Parameters
+@subsection Initial Frame Parameters
+
+You can specify the parameters for the initial startup frame
+by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
+
+@defvar initial-frame-alist
+This variable's value is an alist of parameter values used when creating
+the initial window frame.  You can set this variable to specify the
+appearance of the initial frame without altering subsequent frames.
+Each element has the form:
+
+@example
+(@var{parameter} . @var{value})
+@end example
+
+Emacs creates the initial frame before it reads your init
+file.  After reading that file, Emacs checks @code{initial-frame-alist},
+and applies the parameter settings in the altered value to the already
+created initial frame.
+
+If these settings affect the frame geometry and appearance, you'll see
+the frame appear with the wrong ones and then change to the specified
+ones.  If that bothers you, you can specify the same geometry and
+appearance with X resources; those do take effect before the frame is
+created.  @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
+
+X resource settings typically apply to all frames.  If you want to
+specify some X resources solely for the sake of the initial frame, and
+you don't want them to apply to subsequent frames, here's how to achieve
+this.  Specify parameters in @code{default-frame-alist} to override the
+X resources for subsequent frames; then, to prevent these from affecting
+the initial frame, specify the same parameters in
+@code{initial-frame-alist} with values that match the X resources.
+@end defvar
+
+If these parameters specify a separate minibuffer-only frame with
+@code{(minibuffer . nil)}, and you have not created one, Emacs creates
+one for you.
+
+@defvar minibuffer-frame-alist
+This variable's value is an alist of parameter values used when creating
+an initial minibuffer-only frame---if such a frame is needed, according
+to the parameters for the main initial frame.
+@end defvar
+
+@defvar default-frame-alist
+This is an alist specifying default values of frame parameters for all
+Emacs frames---the first frame, and subsequent frames.  When using the X
+Window System, you can get the same results by means of X resources
+in many cases.
+
+Setting this variable does not affect existing frames.
+@end defvar
+
+See also @code{special-display-frame-alist}.  @xref{Definition of
+special-display-frame-alist}.
+
+If you use options that specify window appearance when you invoke Emacs,
+they take effect by adding elements to @code{default-frame-alist}.  One
+exception is @samp{-geometry}, which adds the specified position to
+@code{initial-frame-alist} instead.  @xref{Emacs Invocation,, Command
+Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
+
+@node Window Frame Parameters
+@subsection Window Frame Parameters
+
+  Just what parameters a frame has depends on what display mechanism
+it uses.  This section describes the parameters that have special
+meanings on some or all kinds of terminals.  Of these, @code{name},
+@code{title}, @code{height}, @code{width}, @code{buffer-list} and
+@code{buffer-predicate} provide meaningful information in terminal
+frames, and @code{tty-color-mode} is meaningful @emph{only} in
+terminal frames.
+
+@menu
+* Basic Parameters::            Parameters that are fundamental.
+* Position Parameters::         The position of the frame on the screen.
+* Size Parameters::             Frame's size.
+* Layout Parameters::           Size of parts of the frame, and
+                                  enabling or disabling some parts.
+* Buffer Parameters::           Which buffers have been or should be shown.
+* Management Parameters::       Communicating with the window manager.
+* Cursor Parameters::           Controlling the cursor appearance.
+* Color Parameters::            Colors of various parts of the frame.
+@end menu
+
+@node Basic Parameters
+@subsubsection Basic Parameters
+
+  These frame parameters give the most basic information about the
+frame.  @code{title} and @code{name} are meaningful on all terminals.
+
+@table @code
+@item display
+The display on which to open this frame.  It should be a string of the
+form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
+@code{DISPLAY} environment variable.
+
+@item display-type
+This parameter describes the range of possible colors that can be used
+in this frame.  Its value is @code{color}, @code{grayscale} or
+@code{mono}.
+
+@item title
+If a frame has a non-@code{nil} title, it appears in the window system's
+border for the frame, and also in the mode line of windows in that frame
+if @code{mode-line-frame-identification} uses @samp{%F}
+(@pxref{%-Constructs}).  This is normally the case when Emacs is not
+using a window system, and can only display one frame at a time.
+@xref{Frame Titles}.
+
+@item name
+The name of the frame.  The frame name serves as a default for the frame
+title, if the @code{title} parameter is unspecified or @code{nil}.  If
+you don't specify a name, Emacs sets the frame name automatically
+(@pxref{Frame Titles}).
+
+If you specify the frame name explicitly when you create the frame, the
+name is also used (instead of the name of the Emacs executable) when
+looking up X resources for the frame.
+
+@item display-environment-variable
+The value of the @code{DISPLAY} environment variable for the frame. It
+is passed to child processes.
+
+@item term-environment-variable
+The value of the @code{TERM} environment variable for the frame. It
+is passed to child processes.
+@end table
+
+@node Position Parameters
+@subsubsection Position Parameters
+
+  Position parameters' values are normally measured in pixels, but on
+text-only terminals they count characters or lines instead.
+
+@table @code
+@item left
+The screen position of the left edge, in pixels, with respect to the
+left edge of the screen.  The value may be a positive number @var{pos},
+or a list of the form @code{(+ @var{pos})} which permits specifying a
+negative @var{pos} value.
+
+A negative number @minus{}@var{pos}, or a list of the form @code{(-
+@var{pos})}, actually specifies the position of the right edge of the
+window with respect to the right edge of the screen.  A positive value
+of @var{pos} counts toward the left.  @strong{Reminder:} if the
+parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
+positive.
+
+Some window managers ignore program-specified positions.  If you want to
+be sure the position you specify is not ignored, specify a
+non-@code{nil} value for the @code{user-position} parameter as well.
+
+@item top
+The screen position of the top edge, in pixels, with respect to the
+top edge of the screen.  It works just like @code{left}, except vertically
+instead of horizontally.
+
+@item icon-left
+The screen position of the left edge @emph{of the frame's icon}, in
+pixels, counting from the left edge of the screen.  This takes effect if
+and when the frame is iconified.
+
+If you specify a value for this parameter, then you must also specify
+a value for @code{icon-top} and vice versa.  The window manager may
+ignore these two parameters.
+
+@item icon-top
+The screen position of the top edge @emph{of the frame's icon}, in
+pixels, counting from the top edge of the screen.  This takes effect if
+and when the frame is iconified.
+
+@item user-position
+When you create a frame and specify its screen position with the
+@code{left} and @code{top} parameters, use this parameter to say whether
+the specified position was user-specified (explicitly requested in some
+way by a human user) or merely program-specified (chosen by a program).
+A non-@code{nil} value says the position was user-specified.
+
+Window managers generally heed user-specified positions, and some heed
+program-specified positions too.  But many ignore program-specified
+positions, placing the window in a default fashion or letting the user
+place it with the mouse.  Some window managers, including @code{twm},
+let the user specify whether to obey program-specified positions or
+ignore them.
+
+When you call @code{make-frame}, you should specify a non-@code{nil}
+value for this parameter if the values of the @code{left} and @code{top}
+parameters represent the user's stated preference; otherwise, use
+@code{nil}.
+@end table
+
+@node Size Parameters
+@subsubsection Size Parameters
+
+  Size parameters' values are normally measured in pixels, but on
+text-only terminals they count characters or lines instead.
+
+@table @code
+@item height
+The height of the frame contents, in characters.  (To get the height in
+pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
+
+@item width
+The width of the frame contents, in characters.  (To get the height in
+pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
+
+@item user-size
+This does for the size parameters @code{height} and @code{width} what
+the @code{user-position} parameter (see above) does for the position
+parameters @code{top} and @code{left}.
+
+@item fullscreen
+Specify that width, height or both shall be set to the size of the screen.
+The value @code{fullwidth} specifies that width shall be the size of the
+screen.  The value @code{fullheight} specifies that height shall be the
+size of the screen.  The value @code{fullboth} specifies that both the
+width and the height shall be set to the size of the screen.
+@end table
+
+@node Layout Parameters
+@subsubsection Layout Parameters
+
+  These frame parameters enable or disable various parts of the
+frame, or control their sizes.
+
+@table @code
+@item border-width
+The width in pixels of the frame's border.
+
+@item internal-border-width
+The distance in pixels between text (or fringe) and the frame's border.
+
+@item vertical-scroll-bars
+Whether the frame has scroll bars for vertical scrolling, and which side
+of the frame they should be on.  The possible values are @code{left},
+@code{right}, and @code{nil} for no scroll bars.
+
+@ignore
+@item horizontal-scroll-bars
+Whether the frame has scroll bars for horizontal scrolling
+(non-@code{nil} means yes).  Horizontal scroll bars are not currently
+implemented.
+@end ignore
+
+@item scroll-bar-width
+The width of vertical scroll bars, in pixels, or @code{nil} meaning to
+use the default width.
+
+@item left-fringe
+@itemx right-fringe
+The default width of the left and right fringes of windows in this
+frame (@pxref{Fringes}).  If either of these is zero, that effectively
+removes the corresponding fringe.  A value of @code{nil} stands for
+the standard fringe width, which is the width needed to display the
+fringe bitmaps.
+
+The combined fringe widths must add up to an integral number of
+columns, so the actual default fringe widths for the frame may be
+larger than the specified values.  The extra width needed to reach an
+acceptable total is distributed evenly between the left and right
+fringe.  However, you can force one fringe or the other to a precise
+width by specifying that width as a negative integer.  If both widths are
+negative, only the left fringe gets the specified width.
+
+@item menu-bar-lines
+The number of lines to allocate at the top of the frame for a menu
+bar.  The default is 1.  A value of @code{nil} means don't display a
+menu bar.  @xref{Menu Bar}.  (The X toolkit and GTK allow at most one
+menu bar line; they treat larger values as 1.)
+
+@item tool-bar-lines
+The number of lines to use for the tool bar.  A value of @code{nil}
+means don't display a tool bar.  (GTK allows at most one tool bar line;
+it treats larger values as 1.)
+
+@item line-spacing
+Additional space to leave below each text line, in pixels (a positive
+integer).  @xref{Line Height}, for more information.
+@end table
+
+@node Buffer Parameters
+@subsubsection Buffer Parameters
+
+  These frame parameters, meaningful on all kinds of terminals, deal
+with which buffers have been, or should, be displayed in the frame.
+
+@table @code
+@item minibuffer
+Whether this frame has its own minibuffer.  The value @code{t} means
+yes, @code{nil} means no, @code{only} means this frame is just a
+minibuffer.  If the value is a minibuffer window (in some other frame),
+the new frame uses that minibuffer.
+
+@item buffer-predicate
+The buffer-predicate function for this frame.  The function
+@code{other-buffer} uses this predicate (from the selected frame) to
+decide which buffers it should consider, if the predicate is not
+@code{nil}.  It calls the predicate with one argument, a buffer, once for
+each buffer; if the predicate returns a non-@code{nil} value, it
+considers that buffer.
+
+@item buffer-list
+A list of buffers that have been selected in this frame,
+ordered most-recently-selected first.
+
+@item unsplittable
+If non-@code{nil}, this frame's window is never split automatically.
+@end table
+
+@node Management Parameters
+@subsubsection Window Management Parameters
+@cindex window manager, and frame parameters
+
+  These frame parameters, meaningful only on window system displays,
+interact with the window manager.
+
+@table @code
+@item visibility
+The state of visibility of the frame.  There are three possibilities:
+@code{nil} for invisible, @code{t} for visible, and @code{icon} for
+iconified.  @xref{Visibility of Frames}.
+
+@item auto-raise
+Whether selecting the frame raises it (non-@code{nil} means yes).
+
+@item auto-lower
+Whether deselecting the frame lowers it (non-@code{nil} means yes).
+
+@item icon-type
+The type of icon to use for this frame when it is iconified.  If the
+value is a string, that specifies a file containing a bitmap to use.
+Any other non-@code{nil} value specifies the default bitmap icon (a
+picture of a gnu); @code{nil} specifies a text icon.
+
+@item icon-name
+The name to use in the icon for this frame, when and if the icon
+appears.  If this is @code{nil}, the frame's title is used.
+
+@item window-id
+The number of the window-system window used by the frame
+to contain the actual Emacs windows.
+
+@item outer-window-id
+The number of the outermost window-system window used for the whole frame.
+
+@item wait-for-wm
+If non-@code{nil}, tell Xt to wait for the window manager to confirm
+geometry changes.  Some window managers, including versions of Fvwm2
+and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
+prevent hanging with those window managers.
+
+@ignore
+@item parent-id
+@c ??? Not yet working.
+The X window number of the window that should be the parent of this one.
+Specifying this lets you create an Emacs window inside some other
+application's window.  (It is not certain this will be implemented; try
+it and see if it works.)
+@end ignore
+@end table
+
+@node Cursor Parameters
+@subsubsection Cursor Parameters
+
+  This frame parameter controls the way the cursor looks.
+
+@table @code
+@item cursor-type
+How to display the cursor.  Legitimate values are:
+
+@table @code
+@item box
+Display a filled box.  (This is the default.)
+@item hollow
+Display a hollow box.
+@item nil
+Don't display a cursor.
+@item bar
+Display a vertical bar between characters.
+@item (bar . @var{width})
+Display a vertical bar @var{width} pixels wide between characters.
+@item hbar
+Display a horizontal bar.
+@item (hbar . @var{height})
+Display a horizontal bar @var{height} pixels high.
+@end table
+@end table
+
+@vindex cursor-type
+The buffer-local variable @code{cursor-type} overrides the value of
+the @code{cursor-type} frame parameter, but if it is @code{t}, that
+means to use the cursor specified for the frame.
+
+@defvar blink-cursor-alist
+This variable specifies how to blink the cursor.  Each element has the
+form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
+type equals @var{on-state} (comparing using @code{equal}), the
+corresponding @var{off-state} specifies what the cursor looks like
+when it blinks ``off.''  Both @var{on-state} and @var{off-state}
+should be suitable values for the @code{cursor-type} frame parameter.
+
+There are various defaults for how to blink each type of cursor, if
+the type is not mentioned as an @var{on-state} here.  Changes in this
+variable do not take effect immediately, because the variable is
+examined only when you specify the @code{cursor-type} parameter.
+@end defvar
+
+@node Color Parameters
+@subsubsection Color Parameters
+
+  These frame parameters control the use of colors.
+
+@table @code
+@item background-mode
+This parameter is either @code{dark} or @code{light}, according
+to whether the background color is a light one or a dark one.
+
+@item tty-color-mode
+@cindex standard colors for character terminals
+This parameter overrides the terminal's color support as given by the
+system's terminal capabilities database in that this parameter's value
+specifies the color mode to use in terminal frames.  The value can be
+either a symbol or a number.  A number specifies the number of colors
+to use (and, indirectly, what commands to issue to produce each
+color).  For example, @code{(tty-color-mode . 8)} specifies use of the
+ANSI escape sequences for 8 standard text colors.  A value of -1 turns
+off color support.
+
+If the parameter's value is a symbol, it specifies a number through
+the value of @code{tty-color-mode-alist}, and the associated number is
+used instead.
+
+@item screen-gamma
+@cindex gamma correction
+If this is a number, Emacs performs ``gamma correction'' which adjusts
+the brightness of all colors.  The value should be the screen gamma of
+your display, a floating point number.
+
+Usual PC monitors have a screen gamma of 2.2, so color values in
+Emacs, and in X windows generally, are calibrated to display properly
+on a monitor with that gamma value.  If you specify 2.2 for
+@code{screen-gamma}, that means no correction is needed.  Other values
+request correction, designed to make the corrected colors appear on
+your screen the way they would have appeared without correction on an
+ordinary monitor with a gamma value of 2.2.
+
+If your monitor displays colors too light, you should specify a
+@code{screen-gamma} value smaller than 2.2.  This requests correction
+that makes colors darker.  A screen gamma value of 1.5 may give good
+results for LCD color displays.
+@end table
+
+These frame parameters are semi-obsolete in that they are automatically
+equivalent to particular face attributes of particular faces.
+@xref{Standard Faces,,, emacs, The Emacs Manual}.
+
+@table @code
+@item font
+The name of the font for displaying text in the frame.  This is a
+string, either a valid font name for your system or the name of an Emacs
+fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
+attribute of the @code{default} face.
+
+@item foreground-color
+The color to use for the image of a character.  It is equivalent to
+the @code{:foreground} attribute of the @code{default} face.
+
+@item background-color
+The color to use for the background of characters.  It is equivalent to
+the @code{:background} attribute of the @code{default} face.
+
+@item mouse-color
+The color for the mouse pointer.  It is equivalent to the @code{:background}
+attribute of the @code{mouse} face.
+
+@item cursor-color
+The color for the cursor that shows point.  It is equivalent to the
+@code{:background} attribute of the @code{cursor} face.
+
+@item border-color
+The color for the border of the frame.  It is equivalent to the
+@code{:background} attribute of the @code{border} face.
+
+@item scroll-bar-foreground
+If non-@code{nil}, the color for the foreground of scroll bars.  It is
+equivalent to the @code{:foreground} attribute of the
+@code{scroll-bar} face.
+
+@item scroll-bar-background
+If non-@code{nil}, the color for the background of scroll bars.  It is
+equivalent to the @code{:background} attribute of the
+@code{scroll-bar} face.
+@end table
+
+@node Size and Position
+@subsection Frame Size And Position
+@cindex size of frame
+@cindex screen size
+@cindex frame size
+@cindex resize frame
+
+  You can read or change the size and position of a frame using the
+frame parameters @code{left}, @code{top}, @code{height}, and
+@code{width}.  Whatever geometry parameters you don't specify are chosen
+by the window manager in its usual fashion.
+
+  Here are some special features for working with sizes and positions.
+(For the precise meaning of ``selected frame'' used by these functions,
+see @ref{Input Focus}.)
+
+@defun set-frame-position frame left top
+This function sets the position of the top left corner of @var{frame} to
+@var{left} and @var{top}.  These arguments are measured in pixels, and
+normally count from the top left corner of the screen.
+
+Negative parameter values position the bottom edge of the window up from
+the bottom edge of the screen, or the right window edge to the left of
+the right edge of the screen.  It would probably be better if the values
+were always counted from the left and top, so that negative arguments
+would position the frame partly off the top or left edge of the screen,
+but it seems inadvisable to change that now.
+@end defun
+
+@defun frame-height &optional frame
+@defunx frame-width &optional frame
+These functions return the height and width of @var{frame}, measured in
+lines and columns.  If you don't supply @var{frame}, they use the
+selected frame.
+@end defun
+
+@defun screen-height
+@defunx screen-width
+These functions are old aliases for @code{frame-height} and
+@code{frame-width}.  When you are using a non-window terminal, the size
+of the frame is normally the same as the size of the terminal screen.
+@end defun
+
+@defun frame-pixel-height &optional frame
+@defunx frame-pixel-width &optional frame
+These functions return the height and width of @var{frame}, measured in
+pixels.  If you don't supply @var{frame}, they use the selected frame.
+@end defun
+
+@defun frame-char-height &optional frame
+@defunx frame-char-width &optional frame
+These functions return the height and width of a character in
+@var{frame}, measured in pixels.  The values depend on the choice of
+font.  If you don't supply @var{frame}, these functions use the selected
+frame.
+@end defun
+
+@defun set-frame-size frame cols rows
+This function sets the size of @var{frame}, measured in characters;
+@var{cols} and @var{rows} specify the new width and height.
+
+To set the size based on values measured in pixels, use
+@code{frame-char-height} and @code{frame-char-width} to convert
+them to units of characters.
+@end defun
+
+@defun set-frame-height frame lines &optional pretend
+This function resizes @var{frame} to a height of @var{lines} lines.  The
+sizes of existing windows in @var{frame} are altered proportionally to
+fit.
+
+If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
+lines of output in @var{frame}, but does not change its value for the
+actual height of the frame.  This is only useful for a terminal frame.
+Using a smaller height than the terminal actually implements may be
+useful to reproduce behavior observed on a smaller screen, or if the
+terminal malfunctions when using its whole screen.  Setting the frame
+height ``for real'' does not always work, because knowing the correct
+actual size may be necessary for correct cursor positioning on a
+terminal frame.
+@end defun
+
+@defun set-frame-width frame width &optional pretend
+This function sets the width of @var{frame}, measured in characters.
+The argument @var{pretend} has the same meaning as in
+@code{set-frame-height}.
+@end defun
+
+@findex set-screen-height
+@findex set-screen-width
+  The older functions @code{set-screen-height} and
+@code{set-screen-width} were used to specify the height and width of the
+screen, in Emacs versions that did not support multiple frames.  They
+are semi-obsolete, but still work; they apply to the selected frame.
+
+@node Geometry
+@subsection Geometry
+
+  Here's how to examine the data in an X-style window geometry
+specification:
+
+@defun x-parse-geometry geom
+@cindex geometry specification
+The function @code{x-parse-geometry} converts a standard X window
+geometry string to an alist that you can use as part of the argument to
+@code{make-frame}.
+
+The alist describes which parameters were specified in @var{geom}, and
+gives the values specified for them.  Each element looks like
+@code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
+values are @code{left}, @code{top}, @code{width}, and @code{height}.
+
+For the size parameters, the value must be an integer.  The position
+parameter names @code{left} and @code{top} are not totally accurate,
+because some values indicate the position of the right or bottom edges
+instead.  These are the @var{value} possibilities for the position
+parameters:
+
+@table @asis
+@item an integer
+A positive integer relates the left edge or top edge of the window to
+the left or top edge of the screen.  A negative integer relates the
+right or bottom edge of the window to the right or bottom edge of the
+screen.
+
+@item @code{(+ @var{position})}
+This specifies the position of the left or top edge of the window
+relative to the left or top edge of the screen.  The integer
+@var{position} may be positive or negative; a negative value specifies a
+position outside the screen.
+
+@item @code{(- @var{position})}
+This specifies the position of the right or bottom edge of the window
+relative to the right or bottom edge of the screen.  The integer
+@var{position} may be positive or negative; a negative value specifies a
+position outside the screen.
+@end table
+
+Here is an example:
+
+@example
+(x-parse-geometry "35x70+0-0")
+     @result{} ((height . 70) (width . 35)
+         (top - 0) (left . 0))
+@end example
+@end defun
+
+@node Frame Titles
+@section Frame Titles
+@cindex frame title
+
+  Every frame has a @code{name} parameter; this serves as the default
+for the frame title which window systems typically display at the top of
+the frame.  You can specify a name explicitly by setting the @code{name}
+frame property.
+
+  Normally you don't specify the name explicitly, and Emacs computes the
+frame name automatically based on a template stored in the variable
+@code{frame-title-format}.  Emacs recomputes the name each time the
+frame is redisplayed.
+
+@defvar frame-title-format
+This variable specifies how to compute a name for a frame when you have
+not explicitly specified one.  The variable's value is actually a mode
+line construct, just like @code{mode-line-format}, except that the
+@samp{%c} and @samp{%l} constructs are ignored.  @xref{Mode Line
+Data}.
+@end defvar
+
+@defvar icon-title-format
+This variable specifies how to compute the name for an iconified frame,
+when you have not explicitly specified the frame title.  This title
+appears in the icon itself.
+@end defvar
+
+@defvar multiple-frames
+This variable is set automatically by Emacs.  Its value is @code{t} when
+there are two or more frames (not counting minibuffer-only frames or
+invisible frames).  The default value of @code{frame-title-format} uses
+@code{multiple-frames} so as to put the buffer name in the frame title
+only when there is more than one frame.
+
+The value of this variable is not guaranteed to be accurate except
+while processing @code{frame-title-format} or
+@code{icon-title-format}.
+@end defvar
+
+@node Deleting Frames
+@section Deleting Frames
+@cindex deleting frames
+
+Frames remain potentially visible until you explicitly @dfn{delete}
+them.  A deleted frame cannot appear on the screen, but continues to
+exist as a Lisp object until there are no references to it.
+
+@deffn Command delete-frame &optional frame force
+@vindex delete-frame-functions
+This function deletes the frame @var{frame}.  Unless @var{frame} is a
+tooltip, it first runs the hook @code{delete-frame-functions} (each
+function gets one argument, @var{frame}).  By default, @var{frame} is
+the selected frame.
+
+A frame cannot be deleted if its minibuffer is used by other frames.
+Normally, you cannot delete a frame if all other frames are invisible,
+but if the @var{force} is non-@code{nil}, then you are allowed to do so.
+@end deffn
+
+@defun frame-live-p frame
+The function @code{frame-live-p} returns non-@code{nil} if the frame
+@var{frame} has not been deleted.  The possible non-@code{nil} return
+values are like those of @code{framep}.  @xref{Frames}.
+@end defun
+
+  Some window managers provide a command to delete a window.  These work
+by sending a special message to the program that operates the window.
+When Emacs gets one of these commands, it generates a
+@code{delete-frame} event, whose normal definition is a command that
+calls the function @code{delete-frame}.  @xref{Misc Events}.
+
+@node Finding All Frames
+@section Finding All Frames
+@cindex frames, scanning all
+
+@defun frame-list
+The function @code{frame-list} returns a list of all the frames that
+have not been deleted.  It is analogous to @code{buffer-list} for
+buffers, and includes frames on all terminals.  The list that you get is
+newly created, so modifying the list doesn't have any effect on the
+internals of Emacs.
+@end defun
+
+@defun visible-frame-list
+This function returns a list of just the currently visible frames.
+@xref{Visibility of Frames}.  (Terminal frames always count as
+``visible,'' even though only the selected one is actually displayed.)
+@end defun
+
+@defun next-frame &optional frame minibuf
+The function @code{next-frame} lets you cycle conveniently through all
+the frames on the current display from an arbitrary starting point.  It
+returns the ``next'' frame after @var{frame} in the cycle.  If
+@var{frame} is omitted or @code{nil}, it defaults to the selected frame
+(@pxref{Input Focus}).
+
+The second argument, @var{minibuf}, says which frames to consider:
+
+@table @asis
+@item @code{nil}
+Exclude minibuffer-only frames.
+@item @code{visible}
+Consider all visible frames.
+@item 0
+Consider all visible or iconified frames.
+@item a window
+Consider only the frames using that particular window as their
+minibuffer.
+@item anything else
+Consider all frames.
+@end table
+@end defun
+
+@defun previous-frame &optional frame minibuf
+Like @code{next-frame}, but cycles through all frames in the opposite
+direction.
+@end defun
+
+  See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
+Window Ordering}.
+
+@node Frames and Windows
+@section Frames and Windows
+
+  Each window is part of one and only one frame; you can get the frame
+with @code{window-frame}.
+
+@defun window-frame window
+This function returns the frame that @var{window} is on.
+@end defun
+
+  All the non-minibuffer windows in a frame are arranged in a cyclic
+order.  The order runs from the frame's top window, which is at the
+upper left corner, down and to the right, until it reaches the window at
+the lower right corner (always the minibuffer window, if the frame has
+one), and then it moves back to the top.  @xref{Cyclic Window Ordering}.
+
+@defun frame-first-window &optional frame
+This returns the topmost, leftmost window of frame @var{frame}.
+If omitted or @code{nil}, @var{frame} defaults to the selected frame.
+@end defun
+
+At any time, exactly one window on any frame is @dfn{selected within the
+frame}.  The significance of this designation is that selecting the
+frame also selects this window.  You can get the frame's current
+selected window with @code{frame-selected-window}.
+
+@defun frame-selected-window  &optional frame
+This function returns the window on @var{frame} that is selected
+within @var{frame}.  If omitted or @code{nil}, @var{frame} defaults to
+the selected frame.
+@end defun
+
+@defun set-frame-selected-window frame window
+This sets the selected window of frame @var{frame} to @var{window}.
+If @var{frame} is @code{nil}, it operates on the selected frame.  If
+@var{frame} is the selected frame, this makes @var{window} the
+selected window.  This function returns @var{window}.
+@end defun
+
+  Conversely, selecting a window for Emacs with @code{select-window} also
+makes that window selected within its frame.  @xref{Selecting Windows}.
+
+  Another function that (usually) returns one of the windows in a given
+frame is @code{minibuffer-window}.  @xref{Definition of minibuffer-window}.
+
+@node Minibuffers and Frames
+@section Minibuffers and Frames
+
+Normally, each frame has its own minibuffer window at the bottom, which
+is used whenever that frame is selected.  If the frame has a minibuffer,
+you can get it with @code{minibuffer-window} (@pxref{Definition of
+minibuffer-window}).
+
+However, you can also create a frame with no minibuffer.  Such a frame
+must use the minibuffer window of some other frame.  When you create the
+frame, you can specify explicitly the minibuffer window to use (in some
+other frame).  If you don't, then the minibuffer is found in the frame
+which is the value of the variable @code{default-minibuffer-frame}.  Its
+value should be a frame that does have a minibuffer.
+
+If you use a minibuffer-only frame, you might want that frame to raise
+when you enter the minibuffer.  If so, set the variable
+@code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.
+
+@defvar default-minibuffer-frame
+This variable specifies the frame to use for the minibuffer window, by
+default.  It does not affect existing frames.  It is always local to
+the current terminal and cannot be buffer-local.  @xref{Multiple
+Displays}.
+@end defvar
+
+@node Input Focus
+@section Input Focus
+@cindex input focus
+@c @cindex selected frame    Duplicates selected-frame
+
+At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
+window always resides on the selected frame.
+
+When Emacs displays its frames on several terminals (@pxref{Multiple
+Displays}), each terminal has its own selected frame.  But only one of
+these is ``@emph{the} selected frame'': it's the frame that belongs to
+the terminal from which the most recent input came.  That is, when Emacs
+runs a command that came from a certain terminal, the selected frame is
+the one of that terminal.  Since Emacs runs only a single command at any
+given time, it needs to consider only one selected frame at a time; this
+frame is what we call @dfn{the selected frame} in this manual.  The
+display on which the selected frame is displayed is the @dfn{selected
+frame's display}.
+
+@defun selected-frame
+This function returns the selected frame.
+@end defun
+
+Some window systems and window managers direct keyboard input to the
+window object that the mouse is in; others require explicit clicks or
+commands to @dfn{shift the focus} to various window objects.  Either
+way, Emacs automatically keeps track of which frame has the focus.  To
+switch to a different frame from a Lisp function, call
+@code{select-frame-set-input-focus}.
+
+Lisp programs can also switch frames ``temporarily'' by calling the
+function @code{select-frame}.  This does not alter the window system's
+concept of focus; rather, it escapes from the window manager's control
+until that control is somehow reasserted.
+
+When using a text-only terminal, only one frame can be displayed at a
+time on the terminal, so after a call to @code{select-frame}, the next
+redisplay actually displays the newly selected frame.  This frame
+remains selected until a subsequent call to @code{select-frame} or
+@code{select-frame-set-input-focus}.  Each terminal frame has a number
+which appears in the mode line before the buffer name (@pxref{Mode
+Line Variables}).
+
+@defun select-frame-set-input-focus frame
+This function makes @var{frame} the selected frame, raises it (should
+it happen to be obscured by other frames) and tries to give it the X
+server's focus.  On a text-only terminal, the next redisplay displays
+the new frame on the entire terminal screen.  The return value of this
+function is not significant.
+@end defun
+
+@c ??? This is not yet implemented properly.
+@defun select-frame frame
+This function selects frame @var{frame}, temporarily disregarding the
+focus of the X server if any.  The selection of @var{frame} lasts until
+the next time the user does something to select a different frame, or
+until the next time this function is called.  (If you are using a
+window system, the previously selected frame may be restored as the
+selected frame after return to the command loop, because it still may
+have the window system's input focus.)  The specified @var{frame}
+becomes the selected frame, as explained above, and the terminal that
+@var{frame} is on becomes the selected terminal.  This function
+returns @var{frame}, or @code{nil} if @var{frame} has been deleted.
+
+In general, you should never use @code{select-frame} in a way that could
+switch to a different terminal without switching back when you're done.
+@end defun
+
+Emacs cooperates with the window system by arranging to select frames as
+the server and window manager request.  It does so by generating a
+special kind of input event, called a @dfn{focus} event, when
+appropriate.  The command loop handles a focus event by calling
+@code{handle-switch-frame}.  @xref{Focus Events}.
+
+@deffn Command handle-switch-frame frame
+This function handles a focus event by selecting frame @var{frame}.
+
+Focus events normally do their job by invoking this command.
+Don't call it for any other reason.
+@end deffn
+
+@defun redirect-frame-focus frame &optional focus-frame
+This function redirects focus from @var{frame} to @var{focus-frame}.
+This means that @var{focus-frame} will receive subsequent keystrokes and
+events intended for @var{frame}.  After such an event, the value of
+@code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
+events specifying @var{frame} will instead select @var{focus-frame}.
+
+If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
+redirection for @var{frame}, which therefore once again receives its own
+events.
+
+One use of focus redirection is for frames that don't have minibuffers.
+These frames use minibuffers on other frames.  Activating a minibuffer
+on another frame redirects focus to that frame.  This puts the focus on
+the minibuffer's frame, where it belongs, even though the mouse remains
+in the frame that activated the minibuffer.
+
+Selecting a frame can also change focus redirections.  Selecting frame
+@code{bar}, when @code{foo} had been selected, changes any redirections
+pointing to @code{foo} so that they point to @code{bar} instead.  This
+allows focus redirection to work properly when the user switches from
+one frame to another using @code{select-window}.
+
+This means that a frame whose focus is redirected to itself is treated
+differently from a frame whose focus is not redirected.
+@code{select-frame} affects the former but not the latter.
+
+The redirection lasts until @code{redirect-frame-focus} is called to
+change it.
+@end defun
+
+@defopt focus-follows-mouse
+This option is how you inform Emacs whether the window manager transfers
+focus when the user moves the mouse.  Non-@code{nil} says that it does.
+When this is so, the command @code{other-frame} moves the mouse to a
+position consistent with the new selected frame.  (This option has no
+effect on MS-Windows, where the mouse pointer is always automatically
+moved by the OS to the selected frame.)
+@end defopt
+
+@node Visibility of Frames
+@section Visibility of Frames
+@cindex visible frame
+@cindex invisible frame
+@cindex iconified frame
+@cindex frame visibility
+
+A window frame may be @dfn{visible}, @dfn{invisible}, or
+@dfn{iconified}.  If it is visible, you can see its contents, unless
+other windows cover it.  If it is iconified, the frame's contents do
+not appear on the screen, but an icon does.  If the frame is
+invisible, it doesn't show on the screen, not even as an icon.
+
+Visibility is meaningless for terminal frames, since only the selected
+one is actually displayed in any case.
+
+@deffn Command make-frame-visible &optional frame
+This function makes frame @var{frame} visible.  If you omit
+@var{frame}, it makes the selected frame visible.  This does not raise
+the frame, but you can do that with @code{raise-frame} if you wish
+(@pxref{Raising and Lowering}).
+@end deffn
+
+@deffn Command make-frame-invisible &optional frame force
+This function makes frame @var{frame} invisible.  If you omit
+@var{frame}, it makes the selected frame invisible.
+
+Unless @var{force} is non-@code{nil}, this function refuses to make
+@var{frame} invisible if all other frames are invisible..
+@end deffn
+
+@deffn Command iconify-frame &optional frame
+This function iconifies frame @var{frame}.  If you omit @var{frame}, it
+iconifies the selected frame.
+@end deffn
+
+@defun frame-visible-p frame
+This returns the visibility status of frame @var{frame}.  The value is
+@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
+@code{icon} if it is iconified.
+
+On a text-only terminal, all frames are considered visible, whether
+they are currently being displayed or not, and this function returns
+@code{t} for all frames.
+@end defun
+
+  The visibility status of a frame is also available as a frame
+parameter.  You can read or change it as such.  @xref{Management
+Parameters}.
+
+  The user can iconify and deiconify frames with the window manager.
+This happens below the level at which Emacs can exert any control, but
+Emacs does provide events that you can use to keep track of such
+changes.  @xref{Misc Events}.
+
+@node Raising and Lowering
+@section Raising and Lowering Frames
+
+  Most window systems use a desktop metaphor.  Part of this metaphor is
+the idea that windows are stacked in a notional third dimension
+perpendicular to the screen surface, and thus ordered from ``highest''
+to ``lowest.''  Where two windows overlap, the one higher up covers
+the one underneath.  Even a window at the bottom of the stack can be
+seen if no other window overlaps it.
+
+@c @cindex raising a frame  redundant with raise-frame
+@cindex lowering a frame
+  A window's place in this ordering is not fixed; in fact, users tend
+to change the order frequently.  @dfn{Raising} a window means moving
+it ``up,'' to the top of the stack.  @dfn{Lowering} a window means
+moving it to the bottom of the stack.  This motion is in the notional
+third dimension only, and does not change the position of the window
+on the screen.
+
+  You can raise and lower Emacs frame Windows with these functions:
+
+@deffn Command raise-frame &optional frame
+This function raises frame @var{frame} (default, the selected frame).
+If @var{frame} is invisible or iconified, this makes it visible.
+@end deffn
+
+@deffn Command lower-frame &optional frame
+This function lowers frame @var{frame} (default, the selected frame).
+@end deffn
+
+@defopt minibuffer-auto-raise
+If this is non-@code{nil}, activation of the minibuffer raises the frame
+that the minibuffer window is in.
+@end defopt
+
+You can also enable auto-raise (raising automatically when a frame is
+selected) or auto-lower (lowering automatically when it is deselected)
+for any frame using frame parameters.  @xref{Management Parameters}.
+
+@node Frame Configurations
+@section Frame Configurations
+@cindex frame configuration
+
+  A @dfn{frame configuration} records the current arrangement of frames,
+all their properties, and the window configuration of each one.
+(@xref{Window Configurations}.)
+
+@defun current-frame-configuration
+This function returns a frame configuration list that describes
+the current arrangement of frames and their contents.
+@end defun
+
+@defun set-frame-configuration configuration &optional nodelete
+This function restores the state of frames described in
+@var{configuration}.  However, this function does not restore deleted
+frames.
+
+Ordinarily, this function deletes all existing frames not listed in
+@var{configuration}.  But if @var{nodelete} is non-@code{nil}, the
+unwanted frames are iconified instead.
+@end defun
+
+@node Mouse Tracking
+@section Mouse Tracking
+@cindex mouse tracking
+@c @cindex tracking the mouse   Duplicates track-mouse
+
+  Sometimes it is useful to @dfn{track} the mouse, which means to display
+something to indicate where the mouse is and move the indicator as the
+mouse moves.  For efficient mouse tracking, you need a way to wait until
+the mouse actually moves.
+
+  The convenient way to track the mouse is to ask for events to represent
+mouse motion.  Then you can wait for motion by waiting for an event.  In
+addition, you can easily handle any other sorts of events that may
+occur.  That is useful, because normally you don't want to track the
+mouse forever---only until some other event, such as the release of a
+button.
+
+@defspec track-mouse body@dots{}
+This special form executes @var{body}, with generation of mouse motion
+events enabled.  Typically @var{body} would use @code{read-event} to
+read the motion events and modify the display accordingly.  @xref{Motion
+Events}, for the format of mouse motion events.
+
+The value of @code{track-mouse} is that of the last form in @var{body}.
+You should design @var{body} to return when it sees the up-event that
+indicates the release of the button, or whatever kind of event means
+it is time to stop tracking.
+@end defspec
+
+The usual purpose of tracking mouse motion is to indicate on the screen
+the consequences of pushing or releasing a button at the current
+position.
+
+In many cases, you can avoid the need to track the mouse by using
+the @code{mouse-face} text property (@pxref{Special Properties}).
+That works at a much lower level and runs more smoothly than
+Lisp-level mouse tracking.
+
+@ignore
+@c These are not implemented yet.
+
+These functions change the screen appearance instantaneously.  The
+effect is transient, only until the next ordinary Emacs redisplay.  That
+is OK for mouse tracking, since it doesn't make sense for mouse tracking
+to change the text, and the body of @code{track-mouse} normally reads
+the events itself and does not do redisplay.
+
+@defun x-contour-region window beg end
+This function draws lines to make a box around the text from @var{beg}
+to @var{end}, in window @var{window}.
+@end defun
+
+@defun x-uncontour-region window beg end
+This function erases the lines that would make a box around the text
+from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
+a contour that you previously made by calling @code{x-contour-region}.
+@end defun
+
+@defun x-draw-rectangle frame left top right bottom
+This function draws a hollow rectangle on frame @var{frame} with the
+specified edge coordinates, all measured in pixels from the inside top
+left corner.  It uses the cursor color, the one used for indicating the
+location of point.
+@end defun
+
+@defun x-erase-rectangle frame left top right bottom
+This function erases a hollow rectangle on frame @var{frame} with the
+specified edge coordinates, all measured in pixels from the inside top
+left corner.  Erasure means redrawing the text and background that
+normally belong in the specified rectangle.
+@end defun
+@end ignore
+
+@node Mouse Position
+@section Mouse Position
+@cindex mouse position
+@cindex position of mouse
+
+  The functions @code{mouse-position} and @code{set-mouse-position}
+give access to the current position of the mouse.
+
+@defun mouse-position
+This function returns a description of the position of the mouse.  The
+value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
+and @var{y} are integers giving the position in characters relative to
+the top left corner of the inside of @var{frame}.
+@end defun
+
+@defvar mouse-position-function
+If non-@code{nil}, the value of this variable is a function for
+@code{mouse-position} to call.  @code{mouse-position} calls this
+function just before returning, with its normal return value as the
+sole argument, and it returns whatever this function returns to it.
+
+This abnormal hook exists for the benefit of packages like
+@file{xt-mouse.el} that need to do mouse handling at the Lisp level.
+@end defvar
+
+@defun set-mouse-position frame x y
+This function @dfn{warps the mouse} to position @var{x}, @var{y} in
+frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
+giving the position in characters relative to the top left corner of the
+inside of @var{frame}.  If @var{frame} is not visible, this function
+does nothing.  The return value is not significant.
+@end defun
+
+@defun mouse-pixel-position
+This function is like @code{mouse-position} except that it returns
+coordinates in units of pixels rather than units of characters.
+@end defun
+
+@defun set-mouse-pixel-position frame x y
+This function warps the mouse like @code{set-mouse-position} except that
+@var{x} and @var{y} are in units of pixels rather than units of
+characters.  These coordinates are not required to be within the frame.
+
+If @var{frame} is not visible, this function does nothing.  The return
+value is not significant.
+@end defun
+
+@need 3000
+
+@node Pop-Up Menus
+@section Pop-Up Menus
+
+  When using a window system, a Lisp program can pop up a menu so that
+the user can choose an alternative with the mouse.
+
+@defun x-popup-menu position menu
+This function displays a pop-up menu and returns an indication of
+what selection the user makes.
+
+The argument @var{position} specifies where on the screen to put the
+top left corner of the menu.  It can be either a mouse button event
+(which says to put the menu where the user actuated the button) or a
+list of this form:
+
+@example
+((@var{xoffset} @var{yoffset}) @var{window})
+@end example
+
+@noindent
+where @var{xoffset} and @var{yoffset} are coordinates, measured in
+pixels, counting from the top left corner of @var{window}.  @var{window}
+may be a window or a frame.
+
+If @var{position} is @code{t}, it means to use the current mouse
+position.  If @var{position} is @code{nil}, it means to precompute the
+key binding equivalents for the keymaps specified in @var{menu},
+without actually displaying or popping up the menu.
+
+The argument @var{menu} says what to display in the menu.  It can be a
+keymap or a list of keymaps (@pxref{Menu Keymaps}).  In this case, the
+return value is the list of events corresponding to the user's choice.
+(This list has more than one element if the choice occurred in a
+submenu.)  Note that @code{x-popup-menu} does not actually execute the
+command bound to that sequence of events.
+
+Alternatively, @var{menu} can have the following form:
+
+@example
+(@var{title} @var{pane1} @var{pane2}...)
+@end example
+
+@noindent
+where each pane is a list of form
+
+@example
+(@var{title} @var{item1} @var{item2}...)
+@end example
+
+Each item should normally be a cons cell @code{(@var{line} . @var{value})},
+where @var{line} is a string, and @var{value} is the value to return if
+that @var{line} is chosen.  An item can also be a string; this makes a
+non-selectable line in the menu.
+
+If the user gets rid of the menu without making a valid choice, for
+instance by clicking the mouse away from a valid choice or by typing
+keyboard input, then this normally results in a quit and
+@code{x-popup-menu} does not return.  But if @var{position} is a mouse
+button event (indicating that the user invoked the menu with the
+mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
+@end defun
+
+  @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
+if you could do the job with a prefix key defined with a menu keymap.
+If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
+a} can see the individual items in that menu and provide help for them.
+If instead you implement the menu by defining a command that calls
+@code{x-popup-menu}, the help facilities cannot know what happens inside
+that command, so they cannot give any help for the menu's items.
+
+  The menu bar mechanism, which lets you switch between submenus by
+moving the mouse, cannot look within the definition of a command to see
+that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
+submenu using @code{x-popup-menu}, it cannot work with the menu bar in
+an integrated fashion.  This is why all menu bar submenus are
+implemented with menu keymaps within the parent menu, and never with
+@code{x-popup-menu}.  @xref{Menu Bar}.
+
+  If you want a menu bar submenu to have contents that vary, you should
+still use a menu keymap to implement it.  To make the contents vary, add
+a hook function to @code{menu-bar-update-hook} to update the contents of
+the menu keymap as necessary.
+
+@node Dialog Boxes
+@section Dialog Boxes
+@cindex dialog boxes
+
+  A dialog box is a variant of a pop-up menu---it looks a little
+different, it always appears in the center of a frame, and it has just
+one level and one or more buttons.  The main use of dialog boxes is
+for asking questions that the user can answer with ``yes,'' ``no,''
+and a few other alternatives.  With a single button, they can also
+force the user to acknowledge important information.  The functions
+@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
+keyboard, when called from commands invoked by mouse clicks.
+
+@defun x-popup-dialog position contents &optional header
+This function displays a pop-up dialog box and returns an indication of
+what selection the user makes.  The argument @var{contents} specifies
+the alternatives to offer; it has this format:
+
+@example
+(@var{title} (@var{string} . @var{value})@dots{})
+@end example
+
+@noindent
+which looks like the list that specifies a single pane for
+@code{x-popup-menu}.
+
+The return value is @var{value} from the chosen alternative.
+
+As for @code{x-popup-menu}, an element of the list may be just a
+string instead of a cons cell @code{(@var{string} . @var{value})}.
+That makes a box that cannot be selected.
+
+If @code{nil} appears in the list, it separates the left-hand items from
+the right-hand items; items that precede the @code{nil} appear on the
+left, and items that follow the @code{nil} appear on the right.  If you
+don't include a @code{nil} in the list, then approximately half the
+items appear on each side.
+
+Dialog boxes always appear in the center of a frame; the argument
+@var{position} specifies which frame.  The possible values are as in
+@code{x-popup-menu}, but the precise coordinates or the individual
+window don't matter; only the frame matters.
+
+If @var{header} is non-@code{nil}, the frame title for the box is
+@samp{Information}, otherwise it is @samp{Question}.  The former is used
+for @code{message-box} (@pxref{message-box}).
+
+In some configurations, Emacs cannot display a real dialog box; so
+instead it displays the same items in a pop-up menu in the center of the
+frame.
+
+If the user gets rid of the dialog box without making a valid choice,
+for instance using the window manager, then this produces a quit and
+@code{x-popup-dialog} does not return.
+@end defun
+
+@node Pointer Shape
+@section Pointer Shape
+@cindex pointer shape
+@cindex mouse pointer shape
+
+  You can specify the mouse pointer style for particular text or
+images using the @code{pointer} text property, and for images with the
+@code{:pointer} and @code{:map} image properties.  The values you can
+use in these properties are @code{text} (or @code{nil}), @code{arrow},
+@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
+@code{hourglass}.  @code{text} stands for the usual mouse pointer
+style used over text.
+
+  Over void parts of the window (parts that do not correspond to any
+of the buffer contents), the mouse pointer usually uses the
+@code{arrow} style, but you can specify a different style (one of
+those above) by setting @code{void-text-area-pointer}.
+
+@defvar void-text-area-pointer
+This variable specifies the mouse pointer style for void text areas.
+These include the areas after the end of a line or below the last line
+in the buffer.  The default is to use the @code{arrow} (non-text)
+pointer style.
+@end defvar
+
+  You can specify what the @code{text} pointer style really looks like
+by setting the variable @code{x-pointer-shape}.
+
+@defvar x-pointer-shape
+This variable specifies the pointer shape to use ordinarily in the
+Emacs frame, for the @code{text} pointer style.
+@end defvar
+
+@defvar x-sensitive-text-pointer-shape
+This variable specifies the pointer shape to use when the mouse
+is over mouse-sensitive text.
+@end defvar
+
+  These variables affect newly created frames.  They do not normally
+affect existing frames; however, if you set the mouse color of a
+frame, that also installs the current value of those two variables.
+@xref{Color Parameters}.
+
+  The values you can use, to specify either of these pointer shapes, are
+defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
+@key{RET} x-pointer @key{RET}} to see a list of them.
+
+@node Window System Selections
+@section Window System Selections
+@cindex selection (for window systems)
+
+The X server records a set of @dfn{selections} which permit transfer of
+data between application programs.  The various selections are
+distinguished by @dfn{selection types}, represented in Emacs by
+symbols.  X clients including Emacs can read or set the selection for
+any given type.
+
+@deffn Command x-set-selection type data
+This function sets a ``selection'' in the X server.  It takes two
+arguments: a selection type @var{type}, and the value to assign to it,
+@var{data}.  If @var{data} is @code{nil}, it means to clear out the
+selection.  Otherwise, @var{data} may be a string, a symbol, an integer
+(or a cons of two integers or list of two integers), an overlay, or a
+cons of two markers pointing to the same buffer.  An overlay or a pair
+of markers stands for text in the overlay or between the markers.
+
+The argument @var{data} may also be a vector of valid non-vector
+selection values.
+
+Each possible @var{type} has its own selection value, which changes
+independently.  The usual values of @var{type} are @code{PRIMARY},
+@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
+names, in accord with X Window System conventions.  If @var{type} is
+@code{nil}, that stands for @code{PRIMARY}.
+
+This function returns @var{data}.
+@end deffn
+
+@defun x-get-selection &optional type data-type
+This function accesses selections set up by Emacs or by other X
+clients.  It takes two optional arguments, @var{type} and
+@var{data-type}.  The default for @var{type}, the selection type, is
+@code{PRIMARY}.
+
+The @var{data-type} argument specifies the form of data conversion to
+use, to convert the raw data obtained from another X client into Lisp
+data.  Meaningful values include @code{TEXT}, @code{STRING},
+@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
+@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
+@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
+@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
+@code{INTEGER}.  (These are symbols with upper-case names in accord
+with X conventions.)  The default for @var{data-type} is
+@code{STRING}.
+@end defun
+
+@cindex cut buffer
+The X server also has a set of eight numbered @dfn{cut buffers} which can
+store text or other data being moved between applications.  Cut buffers
+are considered obsolete, but Emacs supports them for the sake of X
+clients that still use them.  Cut buffers are numbered from 0 to 7.
+
+@defun x-get-cut-buffer &optional n
+This function returns the contents of cut buffer number @var{n}.
+If omitted @var{n} defaults to 0.
+@end defun
+
+@defun x-set-cut-buffer string &optional push
+@anchor{Definition of x-set-cut-buffer}
+This function stores @var{string} into the first cut buffer (cut buffer
+0).  If @var{push} is @code{nil}, only the first cut buffer is changed.
+If @var{push} is non-@code{nil}, that says to move the values down
+through the series of cut buffers, much like the way successive kills in
+Emacs move down the kill ring.  In other words, the previous value of
+the first cut buffer moves into the second cut buffer, and the second to
+the third, and so on through all eight cut buffers.
+@end defun
+
+@defvar selection-coding-system
+This variable specifies the coding system to use when reading and
+writing selections or the clipboard.  @xref{Coding
+Systems}.  The default is @code{compound-text-with-extensions}, which
+converts to the text representation that X11 normally uses.
+@end defvar
+
+@cindex clipboard support (for MS-Windows)
+When Emacs runs on MS-Windows, it does not implement X selections in
+general, but it does support the clipboard.  @code{x-get-selection}
+and @code{x-set-selection} on MS-Windows support the text data type
+only; if the clipboard holds other types of data, Emacs treats the
+clipboard as empty.
+
+@cindex scrap support (for Mac OS)
+On Mac OS, selection-like data transfer between applications is
+performed through a mechanism called @dfn{scraps}.  The clipboard is a
+particular scrap named @code{com.apple.scrap.clipboard}.  Types of scrap
+data are called @dfn{scrap flavor types}, which are identified by
+four-char codes such as @code{TEXT}.  Emacs associates a selection with
+a scrap, and a selection type with a scrap flavor type via
+@code{mac-scrap-name} and @code{mac-ostype} properties, respectively.
+
+@example
+(get 'CLIPBOARD 'mac-scrap-name)
+     @result{} "com.apple.scrap.clipboard"
+(get 'com.apple.traditional-mac-plain-text 'mac-ostype)
+     @result{} "TEXT"
+@end example
+
+Conventionally, selection types for scrap flavor types on Mac OS have
+the form of @acronym{UTI, Uniform Type Identifier} such as
+@code{com.apple.traditional-mac-plain-text},
+@code{public.utf16-plain-text}, and @code{public.file-url}.
+
+@defopt x-select-enable-clipboard
+If this is non-@code{nil}, the Emacs yank functions consult the
+clipboard before the primary selection, and the kill functions store in
+the clipboard as well as the primary selection.  Otherwise they do not
+access the clipboard at all.  The default is @code{nil} on most systems,
+but @code{t} on MS-Windows and Mac.
+@end defopt
+
+@node Drag and Drop
+@section Drag and Drop
+
+@vindex x-dnd-test-function
+@vindex x-dnd-known-types
+  When a user drags something from another application over Emacs, that other
+application expects Emacs to tell it if Emacs can handle the data that is
+dragged.  The variable @code{x-dnd-test-function} is used by Emacs to determine
+what to reply.  The default value is @code{x-dnd-default-test-function}
+which accepts drops if the type of the data to be dropped is present in
+@code{x-dnd-known-types}.  You can customize @code{x-dnd-test-function} and/or
+@code{x-dnd-known-types} if you want Emacs to accept or reject drops based
+on some other criteria.
+
+@vindex x-dnd-types-alist
+  If you want to change the way Emacs handles drop of different types
+or add a new type, customize @code{x-dnd-types-alist}.  This requires
+detailed knowledge of what types other applications use for drag and
+drop.
+
+@vindex dnd-protocol-alist
+  When an URL is dropped on Emacs it may be a file, but it may also be
+another URL type (ftp, http, etc.).  Emacs first checks
+@code{dnd-protocol-alist} to determine what to do with the URL.  If
+there is no match there and if @code{browse-url-browser-function} is
+an alist, Emacs looks for a match there.  If no match is found the
+text for the URL is inserted.  If you want to alter Emacs behavior,
+you can customize these variables.
+
+@node Color Names
+@section Color Names
+
+@cindex color names
+@cindex specify color
+@cindex numerical RGB color specification
+  A color name is text (usually in a string) that specifies a color.
+Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
+are allowed; use @kbd{M-x list-colors-display} to see a list of
+defined names.  You can also specify colors numerically in forms such
+as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
+@var{r} specifies the red level, @var{g} specifies the green level,
+and @var{b} specifies the blue level.  You can use either one, two,
+three, or four hex digits for @var{r}; then you must use the same
+number of hex digits for all @var{g} and @var{b} as well, making
+either 3, 6, 9 or 12 hex digits in all.  (See the documentation of the
+X Window System for more details about numerical RGB specification of
+colors.)
+
+  These functions provide a way to determine which color names are
+valid, and what they look like.  In some cases, the value depends on the
+@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
+meaning of the term ``selected frame.''
+
+@defun color-defined-p color &optional frame
+This function reports whether a color name is meaningful.  It returns
+@code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
+which frame's display to ask about; if @var{frame} is omitted or
+@code{nil}, the selected frame is used.
+
+Note that this does not tell you whether the display you are using
+really supports that color.  When using X, you can ask for any defined
+color on any kind of display, and you will get some result---typically,
+the closest it can do.  To determine whether a frame can really display
+a certain color, use @code{color-supported-p} (see below).
+
+@findex x-color-defined-p
+This function used to be called @code{x-color-defined-p},
+and that name is still supported as an alias.
+@end defun
+
+@defun defined-colors &optional frame
+This function returns a list of the color names that are defined
+and supported on frame @var{frame} (default, the selected frame).
+If @var{frame} does not support colors, the value is @code{nil}.
+
+@findex x-defined-colors
+This function used to be called @code{x-defined-colors},
+and that name is still supported as an alias.
+@end defun
+
+@defun color-supported-p color &optional frame background-p
+This returns @code{t} if @var{frame} can really display the color
+@var{color} (or at least something close to it).  If @var{frame} is
+omitted or @code{nil}, the question applies to the selected frame.
+
+Some terminals support a different set of colors for foreground and
+background.  If @var{background-p} is non-@code{nil}, that means you are
+asking whether @var{color} can be used as a background; otherwise you
+are asking whether it can be used as a foreground.
+
+The argument @var{color} must be a valid color name.
+@end defun
+
+@defun color-gray-p color &optional frame
+This returns @code{t} if @var{color} is a shade of gray, as defined on
+@var{frame}'s display.  If @var{frame} is omitted or @code{nil}, the
+question applies to the selected frame.  If @var{color} is not a valid
+color name, this function returns @code{nil}.
+@end defun
+
+@defun color-values color &optional frame
+@cindex rgb value
+This function returns a value that describes what @var{color} should
+ideally look like on @var{frame}.  If @var{color} is defined, the
+value is a list of three integers, which give the amount of red, the
+amount of green, and the amount of blue.  Each integer ranges in
+principle from 0 to 65535, but some displays may not use the full
+range.  This three-element list is called the @dfn{rgb values} of the
+color.
+
+If @var{color} is not defined, the value is @code{nil}.
+
+@example
+(color-values "black")
+     @result{} (0 0 0)
+(color-values "white")
+     @result{} (65280 65280 65280)
+(color-values "red")
+     @result{} (65280 0 0)
+(color-values "pink")
+     @result{} (65280 49152 51968)
+(color-values "hungry")
+     @result{} nil
+@end example
+
+The color values are returned for @var{frame}'s display.  If
+@var{frame} is omitted or @code{nil}, the information is returned for
+the selected frame's display.  If the frame cannot display colors, the
+value is @code{nil}.
+
+@findex x-color-values
+This function used to be called @code{x-color-values},
+and that name is still supported as an alias.
+@end defun
+
+@node Text Terminal Colors
+@section Text Terminal Colors
+@cindex colors on text-only terminals
+
+  Text-only terminals usually support only a small number of colors,
+and the computer uses small integers to select colors on the terminal.
+This means that the computer cannot reliably tell what the selected
+color looks like; instead, you have to inform your application which
+small integers correspond to which colors.  However, Emacs does know
+the standard set of colors and will try to use them automatically.
+
+  The functions described in this section control how terminal colors
+are used by Emacs.
+
+  Several of these functions use or return @dfn{rgb values}, described
+in @ref{Color Names}.
+
+  These functions accept a display (either a frame or the name of a
+terminal) as an optional argument.  We hope in the future to make Emacs
+support more than one text-only terminal at one time; then this argument
+will specify which terminal to operate on (the default being the
+selected frame's terminal; @pxref{Input Focus}).  At present, though,
+the @var{frame} argument has no effect.
+
+@defun tty-color-define name number &optional rgb frame
+This function associates the color name @var{name} with
+color number @var{number} on the terminal.
+
+The optional argument @var{rgb}, if specified, is an rgb value, a list
+of three numbers that specify what the color actually looks like.
+If you do not specify @var{rgb}, then this color cannot be used by
+@code{tty-color-approximate} to approximate other colors, because
+Emacs will not know what it looks like.
+@end defun
+
+@defun tty-color-clear &optional frame
+This function clears the table of defined colors for a text-only terminal.
+@end defun
+
+@defun tty-color-alist &optional frame
+This function returns an alist recording the known colors supported by a
+text-only terminal.
+
+Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
+or @code{(@var{name} @var{number})}.  Here, @var{name} is the color
+name, @var{number} is the number used to specify it to the terminal.
+If present, @var{rgb} is a list of three color values (for red, green,
+and blue) that says what the color actually looks like.
+@end defun
+
+@defun tty-color-approximate rgb &optional frame
+This function finds the closest color, among the known colors
+supported for @var{display}, to that described by the rgb value
+@var{rgb} (a list of color values).  The return value is an element of
+@code{tty-color-alist}.
+@end defun
+
+@defun tty-color-translate color &optional frame
+This function finds the closest color to @var{color} among the known
+colors supported for @var{display} and returns its index (an integer).
+If the name @var{color} is not defined, the value is @code{nil}.
+@end defun
+
+@node Resources
+@section X Resources
+
+@defun x-get-resource attribute class &optional component subclass
+The function @code{x-get-resource} retrieves a resource value from the X
+Window defaults database.
+
+Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
+This function searches using a key of the form
+@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
+under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
+the class.
+
+The optional arguments @var{component} and @var{subclass} add to the key
+and the class, respectively.  You must specify both of them or neither.
+If you specify them, the key is
+@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
+@samp{Emacs.@var{class}.@var{subclass}}.
+@end defun
+
+@defvar x-resource-class
+This variable specifies the application name that @code{x-get-resource}
+should look up.  The default value is @code{"Emacs"}.  You can examine X
+resources for application names other than ``Emacs'' by binding this
+variable to some other string, around a call to @code{x-get-resource}.
+@end defvar
+
+@defvar x-resource-name
+This variable specifies the instance name that @code{x-get-resource}
+should look up.  The default value is the name Emacs was invoked with,
+or the value specified with the @samp{-name} or @samp{-rn} switches.
+@end defvar
+
+To illustrate some of the above, suppose that you have the line:
+
+@example
+xterm.vt100.background: yellow
+@end example
+
+@noindent
+in your X resources file (whose name is usually @file{~/.Xdefaults}
+or @file{~/.Xresources}).  Then:
+
+@example
+@group
+(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
+  (x-get-resource "vt100.background" "VT100.Background"))
+     @result{} "yellow"
+@end group
+@group
+(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
+  (x-get-resource "background" "VT100" "vt100" "Background"))
+     @result{} "yellow"
+@end group
+@end example
+
+  @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
+
+@node Display Feature Testing
+@section Display Feature Testing
+@cindex display feature testing
+
+  The functions in this section describe the basic capabilities of a
+particular display.  Lisp programs can use them to adapt their behavior
+to what the display can do.  For example, a program that ordinarily uses
+a popup menu could use the minibuffer if popup menus are not supported.
+
+  The optional argument @var{display} in these functions specifies which
+display to ask the question about.  It can be a display name, a frame
+(which designates the display that frame is on), or @code{nil} (which
+refers to the selected frame's display, @pxref{Input Focus}).
+
+  @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
+obtain information about displays.
+
+@defun display-popup-menus-p &optional display
+This function returns @code{t} if popup menus are supported on
+@var{display}, @code{nil} if not.  Support for popup menus requires that
+the mouse be available, since the user cannot choose menu items without
+a mouse.
+@end defun
+
+@defun display-graphic-p &optional display
+This function returns @code{t} if @var{display} is a graphic display
+capable of displaying several frames and several different fonts at
+once.  This is true for displays that use a window system such as X, and
+false for text-only terminals.
+@end defun
+
+@defun display-mouse-p &optional display
+@cindex mouse, availability
+This function returns @code{t} if @var{display} has a mouse available,
+@code{nil} if not.
+@end defun
+
+@defun display-color-p &optional display
+@findex x-display-color-p
+This function returns @code{t} if the screen is a color screen.
+It used to be called @code{x-display-color-p}, and that name
+is still supported as an alias.
+@end defun
+
+@defun display-grayscale-p &optional display
+This function returns @code{t} if the screen can display shades of gray.
+(All color displays can do this.)
+@end defun
+
+@defun display-supports-face-attributes-p attributes &optional display
+@anchor{Display Face Attribute Testing}
+This function returns non-@code{nil} if all the face attributes in
+@var{attributes} are supported (@pxref{Face Attributes}).
+
+The definition of `supported' is somewhat heuristic, but basically
+means that a face containing all the attributes in @var{attributes},
+when merged with the default face for display, can be represented in a
+way that's
+
+@enumerate
+@item
+different in appearance than the default face, and
+
+@item
+`close in spirit' to what the attributes specify, if not exact.
+@end enumerate
+
+Point (2) implies that a @code{:weight black} attribute will be
+satisfied by any display that can display bold, as will
+@code{:foreground "yellow"} as long as some yellowish color can be
+displayed, but @code{:slant italic} will @emph{not} be satisfied by
+the tty display code's automatic substitution of a `dim' face for
+italic.
+@end defun
+
+@defun display-selections-p &optional display
+This function returns @code{t} if @var{display} supports selections.
+Windowed displays normally support selections, but they may also be
+supported in some other cases.
+@end defun
+
+@defun display-images-p &optional display
+This function returns @code{t} if @var{display} can display images.
+Windowed displays ought in principle to handle images, but some
+systems lack the support for that.  On a display that does not support
+images, Emacs cannot display a tool bar.
+@end defun
+
+@defun display-screens &optional display
+This function returns the number of screens associated with the display.
+@end defun
+
+@defun display-pixel-height &optional display
+This function returns the height of the screen in pixels.
+On a character terminal, it gives the height in characters.
+
+For graphical terminals, note that on ``multi-monitor'' setups this
+refers to the pixel width for all physical monitors associated with
+@var{display}.  @xref{Multiple Displays}.
+@end defun
+
+@defun display-pixel-width &optional display
+This function returns the width of the screen in pixels.
+On a character terminal, it gives the width in characters.
+
+For graphical terminals, note that on ``multi-monitor'' setups this
+refers to the pixel width for all physical monitors associated with
+@var{display}.  @xref{Multiple Displays}.
+@end defun
+
+@defun display-mm-height &optional display
+This function returns the height of the screen in millimeters,
+or @code{nil} if Emacs cannot get that information.
+@end defun
+
+@defun display-mm-width &optional display
+This function returns the width of the screen in millimeters,
+or @code{nil} if Emacs cannot get that information.
+@end defun
+
+@defvar display-mm-dimensions-alist
+This variable allows the user to specify the dimensions of graphical
+displays returned by @code{display-mm-height} and
+@code{display-mm-width} in case the system provides incorrect values.
+@end defvar
+
+@defun display-backing-store &optional display
+This function returns the backing store capability of the display.
+Backing store means recording the pixels of windows (and parts of
+windows) that are not exposed, so that when exposed they can be
+displayed very quickly.
+
+Values can be the symbols @code{always}, @code{when-mapped}, or
+@code{not-useful}.  The function can also return @code{nil}
+when the question is inapplicable to a certain kind of display.
+@end defun
+
+@defun display-save-under &optional display
+This function returns non-@code{nil} if the display supports the
+SaveUnder feature.  That feature is used by pop-up windows
+to save the pixels they obscure, so that they can pop down
+quickly.
+@end defun
+
+@defun display-planes &optional display
+This function returns the number of planes the display supports.
+This is typically the number of bits per pixel.
+For a tty display, it is log to base two of the number of colors supported.
+@end defun
+
+@defun display-visual-class &optional display
+This function returns the visual class for the screen.  The value is one
+of the symbols @code{static-gray}, @code{gray-scale},
+@code{static-color}, @code{pseudo-color}, @code{true-color}, and
+@code{direct-color}.
+@end defun
+
+@defun display-color-cells &optional display
+This function returns the number of color cells the screen supports.
+@end defun
+
+  These functions obtain additional information specifically
+about X displays.
+
+@defun x-server-version &optional display
+This function returns the list of version numbers of the X server
+running the display.  The value is a list of three integers: the major
+and minor version numbers of the X protocol, and the
+distributor-specific release number of the X server software itself.
+@end defun
+
+@defun x-server-vendor &optional display
+This function returns the ``vendor'' that provided the X server
+software (as a string).  Really this means whoever distributes the X
+server.
+
+When the developers of X labelled software distributors as
+``vendors,'' they showed their false assumption that no system could
+ever be developed and distributed noncommercially.
+@end defun
+
+@ignore
+@defvar x-no-window-manager
+This variable's value is @code{t} if no X window manager is in use.
+@end defvar
+@end ignore
+
+@ignore
+@item
+The functions @code{x-pixel-width} and @code{x-pixel-height} return the
+width and height of an X Window frame, measured in pixels.
+@end ignore
+
+@ignore
+   arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
+@end ignore
diff --git a/doc/lispref/front-cover-1.texi b/doc/lispref/front-cover-1.texi
new file mode 100644
index 00000000000..5c9f4351f42
--- /dev/null
+++ b/doc/lispref/front-cover-1.texi
@@ -0,0 +1,56 @@
+\input texinfo    @c -*-texinfo-*-
+@comment %**start of header
+@setfilename front1.info
+@settitle GNU Emacs Lisp Reference Manual
+@smallbook
+@comment %**end of header
+
+@titlepage
+.
+@sp 2
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@sp 2
+@center GNU Emacs Version 19.29
+@center for Unix Users
+@center Edition 2.4, June 1995
+@sp 2
+@center @titlefont{Volume 1}
+@sp 2
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+@page
+.
+@sp 5
+@center @titlefont{The}
+@sp 1
+@center @titlefont{GNU}
+@sp 1
+@center @titlefont{Emacs Lisp}
+@sp 1
+@center @titlefont{Reference}
+@sp 1
+@center @titlefont{Manual}
+@sp 2
+@center GNU Emacs Version 19.29
+@center for Unix Users
+@center Edition 2.4, June 1995
+@sp 2
+@center @titlefont{Volume 2}
+@sp 2
+@center by Bil Lewis, Dan LaLiberte,
+@center and the GNU Manual Group
+
+@end titlepage
+@bye
+
+@ignore
+   arch-tag: 5182b306-c403-4e4f-ba24-e1911bc6da9d
+@end ignore
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
new file mode 100644
index 00000000000..eedfa8c124f
--- /dev/null
+++ b/doc/lispref/functions.texi
@@ -0,0 +1,1374 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/functions
+@node Functions, Macros, Variables, Top
+@chapter Functions
+
+  A Lisp program is composed mainly of Lisp functions.  This chapter
+explains what functions are, how they accept arguments, and how to
+define them.
+
+@menu
+* What Is a Function::    Lisp functions vs. primitives; terminology.
+* Lambda Expressions::    How functions are expressed as Lisp objects.
+* Function Names::        A symbol can serve as the name of a function.
+* Defining Functions::    Lisp expressions for defining functions.
+* Calling Functions::     How to use an existing function.
+* Mapping Functions::     Applying a function to each element of a list, etc.
+* Anonymous Functions::   Lambda expressions are functions with no names.
+* Function Cells::        Accessing or setting the function definition
+                            of a symbol.
+* Obsolete Functions::    Declaring functions obsolete.
+* Inline Functions::	  Defining functions that the compiler will open code.
+* Function Safety::       Determining whether a function is safe to call.
+* Related Topics::        Cross-references to specific Lisp primitives
+                            that have a special bearing on how functions work.
+@end menu
+
+@node What Is a Function
+@section What Is a Function?
+
+  In a general sense, a function is a rule for carrying on a computation
+given several values called @dfn{arguments}.  The result of the
+computation is called the value of the function.  The computation can
+also have side effects: lasting changes in the values of variables or
+the contents of data structures.
+
+  Here are important terms for functions in Emacs Lisp and for other
+function-like objects.
+
+@table @dfn
+@item function
+@cindex function
+In Emacs Lisp, a @dfn{function} is anything that can be applied to
+arguments in a Lisp program.  In some cases, we use it more
+specifically to mean a function written in Lisp.  Special forms and
+macros are not functions.
+
+@item primitive
+@cindex primitive
+@cindex subr
+@cindex built-in function
+A @dfn{primitive} is a function callable from Lisp that is written in C,
+such as @code{car} or @code{append}.  These functions are also called
+@dfn{built-in functions}, or @dfn{subrs}.  (Special forms are also
+considered primitives.)
+
+Usually the reason we implement a function as a primitive is either
+because it is fundamental, because it provides a low-level interface
+to operating system services, or because it needs to run fast.
+Primitives can be modified or added only by changing the C sources and
+recompiling the editor.  See @ref{Writing Emacs Primitives}.
+
+@item lambda expression
+A @dfn{lambda expression} is a function written in Lisp.
+These are described in the following section.
+@ifnottex
+@xref{Lambda Expressions}.
+@end ifnottex
+
+@item special form
+A @dfn{special form} is a primitive that is like a function but does not
+evaluate all of its arguments in the usual way.  It may evaluate only
+some of the arguments, or may evaluate them in an unusual order, or
+several times.  Many special forms are described in @ref{Control
+Structures}.
+
+@item macro
+@cindex macro
+A @dfn{macro} is a construct defined in Lisp by the programmer.  It
+differs from a function in that it translates a Lisp expression that you
+write into an equivalent expression to be evaluated instead of the
+original expression.  Macros enable Lisp programmers to do the sorts of
+things that special forms can do.  @xref{Macros}, for how to define and
+use macros.
+
+@item command
+@cindex command
+A @dfn{command} is an object that @code{command-execute} can invoke; it
+is a possible definition for a key sequence.  Some functions are
+commands; a function written in Lisp is a command if it contains an
+interactive declaration (@pxref{Defining Commands}).  Such a function
+can be called from Lisp expressions like other functions; in this case,
+the fact that the function is a command makes no difference.
+
+Keyboard macros (strings and vectors) are commands also, even though
+they are not functions.  A symbol is a command if its function
+definition is a command; such symbols can be invoked with @kbd{M-x}.
+The symbol is a function as well if the definition is a function.
+@xref{Interactive Call}.
+
+@item keystroke command
+@cindex keystroke command
+A @dfn{keystroke command} is a command that is bound to a key sequence
+(typically one to three keystrokes).  The distinction is made here
+merely to avoid confusion with the meaning of ``command'' in non-Emacs
+editors; for Lisp programs, the distinction is normally unimportant.
+
+@item byte-code function
+A @dfn{byte-code function} is a function that has been compiled by the
+byte compiler.  @xref{Byte-Code Type}.
+@end table
+
+@defun functionp object
+This function returns @code{t} if @var{object} is any kind of
+function, or a special form, or, recursively, a symbol whose function
+definition is a function or special form.  (This does not include
+macros.)
+@end defun
+
+Unlike @code{functionp}, the next three functions do @emph{not}
+treat a symbol as its function definition.
+
+@defun subrp object
+This function returns @code{t} if @var{object} is a built-in function
+(i.e., a Lisp primitive).
+
+@example
+@group
+(subrp 'message)            ; @r{@code{message} is a symbol,}
+     @result{} nil                 ;   @r{not a subr object.}
+@end group
+@group
+(subrp (symbol-function 'message))
+     @result{} t
+@end group
+@end example
+@end defun
+
+@defun byte-code-function-p object
+This function returns @code{t} if @var{object} is a byte-code
+function.  For example:
+
+@example
+@group
+(byte-code-function-p (symbol-function 'next-line))
+     @result{} t
+@end group
+@end example
+@end defun
+
+@defun subr-arity subr
+This function provides information about the argument list of a
+primitive, @var{subr}.  The returned value is a pair
+@code{(@var{min} . @var{max})}.  @var{min} is the minimum number of
+args.  @var{max} is the maximum number or the symbol @code{many}, for a
+function with @code{&rest} arguments, or the symbol @code{unevalled} if
+@var{subr} is a special form.
+@end defun
+
+@node Lambda Expressions
+@section Lambda Expressions
+@cindex lambda expression
+
+  A function written in Lisp is a list that looks like this:
+
+@example
+(lambda (@var{arg-variables}@dots{})
+  @r{[}@var{documentation-string}@r{]}
+  @r{[}@var{interactive-declaration}@r{]}
+  @var{body-forms}@dots{})
+@end example
+
+@noindent
+Such a list is called a @dfn{lambda expression}.  In Emacs Lisp, it
+actually is valid as an expression---it evaluates to itself.  In some
+other Lisp dialects, a lambda expression is not a valid expression at
+all.  In either case, its main use is not to be evaluated as an
+expression, but to be called as a function.
+
+@menu
+* Lambda Components::       The parts of a lambda expression.
+* Simple Lambda::           A simple example.
+* Argument List::           Details and special features of argument lists.
+* Function Documentation::  How to put documentation in a function.
+@end menu
+
+@node Lambda Components
+@subsection Components of a Lambda Expression
+
+@ifnottex
+
+  A function written in Lisp (a ``lambda expression'') is a list that
+looks like this:
+
+@example
+(lambda (@var{arg-variables}@dots{})
+  [@var{documentation-string}]
+  [@var{interactive-declaration}]
+  @var{body-forms}@dots{})
+@end example
+@end ifnottex
+
+@cindex lambda list
+  The first element of a lambda expression is always the symbol
+@code{lambda}.  This indicates that the list represents a function.  The
+reason functions are defined to start with @code{lambda} is so that
+other lists, intended for other uses, will not accidentally be valid as
+functions.
+
+  The second element is a list of symbols---the argument variable names.
+This is called the @dfn{lambda list}.  When a Lisp function is called,
+the argument values are matched up against the variables in the lambda
+list, which are given local bindings with the values provided.
+@xref{Local Variables}.
+
+  The documentation string is a Lisp string object placed within the
+function definition to describe the function for the Emacs help
+facilities.  @xref{Function Documentation}.
+
+  The interactive declaration is a list of the form @code{(interactive
+@var{code-string})}.  This declares how to provide arguments if the
+function is used interactively.  Functions with this declaration are called
+@dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
+Functions not intended to be called in this way should not have interactive
+declarations.  @xref{Defining Commands}, for how to write an interactive
+declaration.
+
+@cindex body of function
+  The rest of the elements are the @dfn{body} of the function: the Lisp
+code to do the work of the function (or, as a Lisp programmer would say,
+``a list of Lisp forms to evaluate'').  The value returned by the
+function is the value returned by the last element of the body.
+
+@node Simple Lambda
+@subsection A Simple Lambda-Expression Example
+
+  Consider for example the following function:
+
+@example
+(lambda (a b c) (+ a b c))
+@end example
+
+@noindent
+We can call this function by writing it as the @sc{car} of an
+expression, like this:
+
+@example
+@group
+((lambda (a b c) (+ a b c))
+ 1 2 3)
+@end group
+@end example
+
+@noindent
+This call evaluates the body of the lambda expression  with the variable
+@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
+Evaluation of the body adds these three numbers, producing the result 6;
+therefore, this call to the function returns the value 6.
+
+  Note that the arguments can be the results of other function calls, as in
+this example:
+
+@example
+@group
+((lambda (a b c) (+ a b c))
+ 1 (* 2 3) (- 5 4))
+@end group
+@end example
+
+@noindent
+This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
+4)} from left to right.  Then it applies the lambda expression to the
+argument values 1, 6 and 1 to produce the value 8.
+
+  It is not often useful to write a lambda expression as the @sc{car} of
+a form in this way.  You can get the same result, of making local
+variables and giving them values, using the special form @code{let}
+(@pxref{Local Variables}).  And @code{let} is clearer and easier to use.
+In practice, lambda expressions are either stored as the function
+definitions of symbols, to produce named functions, or passed as
+arguments to other functions (@pxref{Anonymous Functions}).
+
+  However, calls to explicit lambda expressions were very useful in the
+old days of Lisp, before the special form @code{let} was invented.  At
+that time, they were the only way to bind and initialize local
+variables.
+
+@node Argument List
+@subsection Other Features of Argument Lists
+@kindex wrong-number-of-arguments
+@cindex argument binding
+@cindex binding arguments
+@cindex argument lists, features
+
+  Our simple sample function, @code{(lambda (a b c) (+ a b c))},
+specifies three argument variables, so it must be called with three
+arguments: if you try to call it with only two arguments or four
+arguments, you get a @code{wrong-number-of-arguments} error.
+
+  It is often convenient to write a function that allows certain
+arguments to be omitted.  For example, the function @code{substring}
+accepts three arguments---a string, the start index and the end
+index---but the third argument defaults to the @var{length} of the
+string if you omit it.  It is also convenient for certain functions to
+accept an indefinite number of arguments, as the functions @code{list}
+and @code{+} do.
+
+@cindex optional arguments
+@cindex rest arguments
+@kindex &optional
+@kindex &rest
+  To specify optional arguments that may be omitted when a function
+is called, simply include the keyword @code{&optional} before the optional
+arguments.  To specify a list of zero or more extra arguments, include the
+keyword @code{&rest} before one final argument.
+
+  Thus, the complete syntax for an argument list is as follows:
+
+@example
+@group
+(@var{required-vars}@dots{}
+ @r{[}&optional @var{optional-vars}@dots{}@r{]}
+ @r{[}&rest @var{rest-var}@r{]})
+@end group
+@end example
+
+@noindent
+The square brackets indicate that the @code{&optional} and @code{&rest}
+clauses, and the variables that follow them, are optional.
+
+  A call to the function requires one actual argument for each of the
+@var{required-vars}.  There may be actual arguments for zero or more of
+the @var{optional-vars}, and there cannot be any actual arguments beyond
+that unless the lambda list uses @code{&rest}.  In that case, there may
+be any number of extra actual arguments.
+
+  If actual arguments for the optional and rest variables are omitted,
+then they always default to @code{nil}.  There is no way for the
+function to distinguish between an explicit argument of @code{nil} and
+an omitted argument.  However, the body of the function is free to
+consider @code{nil} an abbreviation for some other meaningful value.
+This is what @code{substring} does; @code{nil} as the third argument to
+@code{substring} means to use the length of the string supplied.
+
+@cindex CL note---default optional arg
+@quotation
+@b{Common Lisp note:} Common Lisp allows the function to specify what
+default value to use when an optional argument is omitted; Emacs Lisp
+always uses @code{nil}.  Emacs Lisp does not support ``supplied-p''
+variables that tell you whether an argument was explicitly passed.
+@end quotation
+
+  For example, an argument list that looks like this:
+
+@example
+(a b &optional c d &rest e)
+@end example
+
+@noindent
+binds @code{a} and @code{b} to the first two actual arguments, which are
+required.  If one or two more arguments are provided, @code{c} and
+@code{d} are bound to them respectively; any arguments after the first
+four are collected into a list and @code{e} is bound to that list.  If
+there are only two arguments, @code{c} is @code{nil}; if two or three
+arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
+is @code{nil}.
+
+  There is no way to have required arguments following optional
+ones---it would not make sense.  To see why this must be so, suppose
+that @code{c} in the example were optional and @code{d} were required.
+Suppose three actual arguments are given; which variable would the
+third argument be for?  Would it be used for the @var{c}, or for
+@var{d}?  One can argue for both possibilities.  Similarly, it makes
+no sense to have any more arguments (either required or optional)
+after a @code{&rest} argument.
+
+  Here are some examples of argument lists and proper calls:
+
+@smallexample
+((lambda (n) (1+ n))                ; @r{One required:}
+ 1)                                 ; @r{requires exactly one argument.}
+     @result{} 2
+((lambda (n &optional n1)           ; @r{One required and one optional:}
+         (if n1 (+ n n1) (1+ n)))   ; @r{1 or 2 arguments.}
+ 1 2)
+     @result{} 3
+((lambda (n &rest ns)               ; @r{One required and one rest:}
+         (+ n (apply '+ ns)))       ; @r{1 or more arguments.}
+ 1 2 3 4 5)
+     @result{} 15
+@end smallexample
+
+@node Function Documentation
+@subsection Documentation Strings of Functions
+@cindex documentation of function
+
+  A lambda expression may optionally have a @dfn{documentation string} just
+after the lambda list.  This string does not affect execution of the
+function; it is a kind of comment, but a systematized comment which
+actually appears inside the Lisp world and can be used by the Emacs help
+facilities.  @xref{Documentation}, for how the @var{documentation-string} is
+accessed.
+
+  It is a good idea to provide documentation strings for all the
+functions in your program, even those that are called only from within
+your program.  Documentation strings are like comments, except that they
+are easier to access.
+
+  The first line of the documentation string should stand on its own,
+because @code{apropos} displays just this first line.  It should consist
+of one or two complete sentences that summarize the function's purpose.
+
+  The start of the documentation string is usually indented in the
+source file, but since these spaces come before the starting
+double-quote, they are not part of the string.  Some people make a
+practice of indenting any additional lines of the string so that the
+text lines up in the program source.  @emph{That is a mistake.}  The
+indentation of the following lines is inside the string; what looks
+nice in the source code will look ugly when displayed by the help
+commands.
+
+  You may wonder how the documentation string could be optional, since
+there are required components of the function that follow it (the body).
+Since evaluation of a string returns that string, without any side effects,
+it has no effect if it is not the last form in the body.  Thus, in
+practice, there is no confusion between the first form of the body and the
+documentation string; if the only body form is a string then it serves both
+as the return value and as the documentation.
+
+  The last line of the documentation string can specify calling
+conventions different from the actual function arguments.  Write
+text like this:
+
+@example
+\(fn @var{arglist})
+@end example
+
+@noindent
+following a blank line, at the beginning of the line, with no newline
+following it inside the documentation string.  (The @samp{\} is used
+to avoid confusing the Emacs motion commands.)  The calling convention
+specified in this way appears in help messages in place of the one
+derived from the actual arguments of the function.
+
+  This feature is particularly useful for macro definitions, since the
+arguments written in a macro definition often do not correspond to the
+way users think of the parts of the macro call.
+
+@node Function Names
+@section Naming a Function
+@cindex function definition
+@cindex named function
+@cindex function name
+
+  In most computer languages, every function has a name; the idea of a
+function without a name is nonsensical.  In Lisp, a function in the
+strictest sense has no name.  It is simply a list whose first element is
+@code{lambda}, a byte-code function object, or a primitive subr-object.
+
+  However, a symbol can serve as the name of a function.  This happens
+when you put the function in the symbol's @dfn{function cell}
+(@pxref{Symbol Components}).  Then the symbol itself becomes a valid,
+callable function, equivalent to the list or subr-object that its
+function cell refers to.  The contents of the function cell are also
+called the symbol's @dfn{function definition}.  The procedure of using a
+symbol's function definition in place of the symbol is called
+@dfn{symbol function indirection}; see @ref{Function Indirection}.
+
+  In practice, nearly all functions are given names in this way and
+referred to through their names.  For example, the symbol @code{car} works
+as a function and does what it does because the primitive subr-object
+@code{#<subr car>} is stored in its function cell.
+
+  We give functions names because it is convenient to refer to them by
+their names in Lisp expressions.  For primitive subr-objects such as
+@code{#<subr car>}, names are the only way you can refer to them: there
+is no read syntax for such objects.  For functions written in Lisp, the
+name is more convenient to use in a call than an explicit lambda
+expression.  Also, a function with a name can refer to itself---it can
+be recursive.  Writing the function's name in its own definition is much
+more convenient than making the function definition point to itself
+(something that is not impossible but that has various disadvantages in
+practice).
+
+  We often identify functions with the symbols used to name them.  For
+example, we often speak of ``the function @code{car},'' not
+distinguishing between the symbol @code{car} and the primitive
+subr-object that is its function definition.  For most purposes, the
+distinction is not important.
+
+  Even so, keep in mind that a function need not have a unique name.  While
+a given function object @emph{usually} appears in the function cell of only
+one symbol, this is just a matter of convenience.  It is easy to store
+it in several symbols using @code{fset}; then each of the symbols is
+equally well a name for the same function.
+
+  A symbol used as a function name may also be used as a variable; these
+two uses of a symbol are independent and do not conflict.  (Some Lisp
+dialects, such as Scheme, do not distinguish between a symbol's value
+and its function definition; a symbol's value as a variable is also its
+function definition.)  If you have not given a symbol a function
+definition, you cannot use it as a function; whether the symbol has a
+value as a variable makes no difference to this.
+
+@node Defining Functions
+@section Defining Functions
+@cindex defining a function
+
+  We usually give a name to a function when it is first created.  This
+is called @dfn{defining a function}, and it is done with the
+@code{defun} special form.
+
+@defspec defun name argument-list body-forms
+@code{defun} is the usual way to define new Lisp functions.  It
+defines the symbol @var{name} as a function that looks like this:
+
+@example
+(lambda @var{argument-list} . @var{body-forms})
+@end example
+
+@code{defun} stores this lambda expression in the function cell of
+@var{name}.  It returns the value @var{name}, but usually we ignore this
+value.
+
+As described previously, @var{argument-list} is a list of argument
+names and may include the keywords @code{&optional} and @code{&rest}
+(@pxref{Lambda Expressions}).  Also, the first two of the
+@var{body-forms} may be a documentation string and an interactive
+declaration.
+
+There is no conflict if the same symbol @var{name} is also used as a
+variable, since the symbol's value cell is independent of the function
+cell.  @xref{Symbol Components}.
+
+Here are some examples:
+
+@example
+@group
+(defun foo () 5)
+     @result{} foo
+@end group
+@group
+(foo)
+     @result{} 5
+@end group
+
+@group
+(defun bar (a &optional b &rest c)
+    (list a b c))
+     @result{} bar
+@end group
+@group
+(bar 1 2 3 4 5)
+     @result{} (1 2 (3 4 5))
+@end group
+@group
+(bar 1)
+     @result{} (1 nil nil)
+@end group
+@group
+(bar)
+@error{} Wrong number of arguments.
+@end group
+
+@group
+(defun capitalize-backwards ()
+  "Upcase the last letter of a word."
+  (interactive)
+  (backward-word 1)
+  (forward-word 1)
+  (backward-char 1)
+  (capitalize-word 1))
+     @result{} capitalize-backwards
+@end group
+@end example
+
+Be careful not to redefine existing functions unintentionally.
+@code{defun} redefines even primitive functions such as @code{car}
+without any hesitation or notification.  Redefining a function already
+defined is often done deliberately, and there is no way to distinguish
+deliberate redefinition from unintentional redefinition.
+@end defspec
+
+@cindex function aliases
+@defun defalias name definition &optional docstring
+@anchor{Definition of defalias}
+This special form defines the symbol @var{name} as a function, with
+definition @var{definition} (which can be any valid Lisp function).
+It returns @var{definition}.
+
+If @var{docstring} is non-@code{nil}, it becomes the function
+documentation of @var{name}.  Otherwise, any documentation provided by
+@var{definition} is used.
+
+The proper place to use @code{defalias} is where a specific function
+name is being defined---especially where that name appears explicitly in
+the source file being loaded.  This is because @code{defalias} records
+which file defined the function, just like @code{defun}
+(@pxref{Unloading}).
+
+By contrast, in programs that manipulate function definitions for other
+purposes, it is better to use @code{fset}, which does not keep such
+records.  @xref{Function Cells}.
+@end defun
+
+  You cannot create a new primitive function with @code{defun} or
+@code{defalias}, but you can use them to change the function definition of
+any symbol, even one such as @code{car} or @code{x-popup-menu} whose
+normal definition is a primitive.  However, this is risky: for
+instance, it is next to impossible to redefine @code{car} without
+breaking Lisp completely.  Redefining an obscure function such as
+@code{x-popup-menu} is less dangerous, but it still may not work as
+you expect.  If there are calls to the primitive from C code, they
+call the primitive's C definition directly, so changing the symbol's
+definition will have no effect on them.
+
+  See also @code{defsubst}, which defines a function like @code{defun}
+and tells the Lisp compiler to open-code it.  @xref{Inline Functions}.
+
+@node Calling Functions
+@section Calling Functions
+@cindex function invocation
+@cindex calling a function
+
+  Defining functions is only half the battle.  Functions don't do
+anything until you @dfn{call} them, i.e., tell them to run.  Calling a
+function is also known as @dfn{invocation}.
+
+  The most common way of invoking a function is by evaluating a list.
+For example, evaluating the list @code{(concat "a" "b")} calls the
+function @code{concat} with arguments @code{"a"} and @code{"b"}.
+@xref{Evaluation}, for a description of evaluation.
+
+  When you write a list as an expression in your program, you specify
+which function to call, and how many arguments to give it, in the text
+of the program.  Usually that's just what you want.  Occasionally you
+need to compute at run time which function to call.  To do that, use
+the function @code{funcall}.  When you also need to determine at run
+time how many arguments to pass, use @code{apply}.
+
+@defun funcall function &rest arguments
+@code{funcall} calls @var{function} with @var{arguments}, and returns
+whatever @var{function} returns.
+
+Since @code{funcall} is a function, all of its arguments, including
+@var{function}, are evaluated before @code{funcall} is called.  This
+means that you can use any expression to obtain the function to be
+called.  It also means that @code{funcall} does not see the
+expressions you write for the @var{arguments}, only their values.
+These values are @emph{not} evaluated a second time in the act of
+calling @var{function}; the operation of @code{funcall} is like the
+normal procedure for calling a function, once its arguments have
+already been evaluated.
+
+The argument @var{function} must be either a Lisp function or a
+primitive function.  Special forms and macros are not allowed, because
+they make sense only when given the ``unevaluated'' argument
+expressions.  @code{funcall} cannot provide these because, as we saw
+above, it never knows them in the first place.
+
+@example
+@group
+(setq f 'list)
+     @result{} list
+@end group
+@group
+(funcall f 'x 'y 'z)
+     @result{} (x y z)
+@end group
+@group
+(funcall f 'x 'y '(z))
+     @result{} (x y (z))
+@end group
+@group
+(funcall 'and t nil)
+@error{} Invalid function: #<subr and>
+@end group
+@end example
+
+Compare these examples with the examples of @code{apply}.
+@end defun
+
+@defun apply function &rest arguments
+@code{apply} calls @var{function} with @var{arguments}, just like
+@code{funcall} but with one difference: the last of @var{arguments} is a
+list of objects, which are passed to @var{function} as separate
+arguments, rather than a single list.  We say that @code{apply}
+@dfn{spreads} this list so that each individual element becomes an
+argument.
+
+@code{apply} returns the result of calling @var{function}.  As with
+@code{funcall}, @var{function} must either be a Lisp function or a
+primitive function; special forms and macros do not make sense in
+@code{apply}.
+
+@example
+@group
+(setq f 'list)
+     @result{} list
+@end group
+@group
+(apply f 'x 'y 'z)
+@error{} Wrong type argument: listp, z
+@end group
+@group
+(apply '+ 1 2 '(3 4))
+     @result{} 10
+@end group
+@group
+(apply '+ '(1 2 3 4))
+     @result{} 10
+@end group
+
+@group
+(apply 'append '((a b c) nil (x y z) nil))
+     @result{} (a b c x y z)
+@end group
+@end example
+
+For an interesting example of using @code{apply}, see @ref{Definition
+of mapcar}.
+@end defun
+
+@cindex functionals
+  It is common for Lisp functions to accept functions as arguments or
+find them in data structures (especially in hook variables and property
+lists) and call them using @code{funcall} or @code{apply}.  Functions
+that accept function arguments are often called @dfn{functionals}.
+
+  Sometimes, when you call a functional, it is useful to supply a no-op
+function as the argument.  Here are two different kinds of no-op
+function:
+
+@defun identity arg
+This function returns @var{arg} and has no side effects.
+@end defun
+
+@defun ignore &rest args
+This function ignores any arguments and returns @code{nil}.
+@end defun
+
+@node Mapping Functions
+@section Mapping Functions
+@cindex mapping functions
+
+  A @dfn{mapping function} applies a given function (@emph{not} a
+special form or macro) to each element of a list or other collection.
+Emacs Lisp has several such functions; @code{mapcar} and
+@code{mapconcat}, which scan a list, are described here.
+@xref{Definition of mapatoms}, for the function @code{mapatoms} which
+maps over the symbols in an obarray.  @xref{Definition of maphash},
+for the function @code{maphash} which maps over key/value associations
+in a hash table.
+
+  These mapping functions do not allow char-tables because a char-table
+is a sparse array whose nominal range of indices is very large.  To map
+over a char-table in a way that deals properly with its sparse nature,
+use the function @code{map-char-table} (@pxref{Char-Tables}).
+
+@defun mapcar function sequence
+@anchor{Definition of mapcar}
+@code{mapcar} applies @var{function} to each element of @var{sequence}
+in turn, and returns a list of the results.
+
+The argument @var{sequence} can be any kind of sequence except a
+char-table; that is, a list, a vector, a bool-vector, or a string.  The
+result is always a list.  The length of the result is the same as the
+length of @var{sequence}.  For example:
+
+@smallexample
+@group
+(mapcar 'car '((a b) (c d) (e f)))
+     @result{} (a c e)
+(mapcar '1+ [1 2 3])
+     @result{} (2 3 4)
+(mapcar 'char-to-string "abc")
+     @result{} ("a" "b" "c")
+@end group
+
+@group
+;; @r{Call each function in @code{my-hooks}.}
+(mapcar 'funcall my-hooks)
+@end group
+
+@group
+(defun mapcar* (function &rest args)
+  "Apply FUNCTION to successive cars of all ARGS.
+Return the list of results."
+  ;; @r{If no list is exhausted,}
+  (if (not (memq nil args))
+      ;; @r{apply function to @sc{car}s.}
+      (cons (apply function (mapcar 'car args))
+            (apply 'mapcar* function
+                   ;; @r{Recurse for rest of elements.}
+                   (mapcar 'cdr args)))))
+@end group
+
+@group
+(mapcar* 'cons '(a b c) '(1 2 3 4))
+     @result{} ((a . 1) (b . 2) (c . 3))
+@end group
+@end smallexample
+@end defun
+
+@defun mapc function sequence
+@code{mapc} is like @code{mapcar} except that @var{function} is used for
+side-effects only---the values it returns are ignored, not collected
+into a list.  @code{mapc} always returns @var{sequence}.
+@end defun
+
+@defun mapconcat function sequence separator
+@code{mapconcat} applies @var{function} to each element of
+@var{sequence}: the results, which must be strings, are concatenated.
+Between each pair of result strings, @code{mapconcat} inserts the string
+@var{separator}.  Usually @var{separator} contains a space or comma or
+other suitable punctuation.
+
+The argument @var{function} must be a function that can take one
+argument and return a string.  The argument @var{sequence} can be any
+kind of sequence except a char-table; that is, a list, a vector, a
+bool-vector, or a string.
+
+@smallexample
+@group
+(mapconcat 'symbol-name
+           '(The cat in the hat)
+           " ")
+     @result{} "The cat in the hat"
+@end group
+
+@group
+(mapconcat (function (lambda (x) (format "%c" (1+ x))))
+           "HAL-8000"
+           "")
+     @result{} "IBM.9111"
+@end group
+@end smallexample
+@end defun
+
+@node Anonymous Functions
+@section Anonymous Functions
+@cindex anonymous function
+
+  In Lisp, a function is a list that starts with @code{lambda}, a
+byte-code function compiled from such a list, or alternatively a
+primitive subr-object; names are ``extra.''  Although usually functions
+are defined with @code{defun} and given names at the same time, it is
+occasionally more concise to use an explicit lambda expression---an
+anonymous function.  Such a list is valid wherever a function name is.
+
+  Any method of creating such a list makes a valid function.  Even this:
+
+@smallexample
+@group
+(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
+@result{} (lambda (x) (+ 12 x))
+@end group
+@end smallexample
+
+@noindent
+This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
+makes it the value (@emph{not} the function definition!) of
+@code{silly}.
+
+  Here is how we might call this function:
+
+@example
+@group
+(funcall silly 1)
+@result{} 13
+@end group
+@end example
+
+@noindent
+(It does @emph{not} work to write @code{(silly 1)}, because this function
+is not the @emph{function definition} of @code{silly}.  We have not given
+@code{silly} any function definition, just a value as a variable.)
+
+  Most of the time, anonymous functions are constants that appear in
+your program.  For example, you might want to pass one as an argument to
+the function @code{mapcar}, which applies any given function to each
+element of a list.
+
+  Here we define a function @code{change-property} which
+uses a function as its third argument:
+
+@example
+@group
+(defun change-property (symbol prop function)
+  (let ((value (get symbol prop)))
+    (put symbol prop (funcall function value))))
+@end group
+@end example
+
+@noindent
+Here we define a function that uses @code{change-property},
+passing it a function to double a number:
+
+@example
+@group
+(defun double-property (symbol prop)
+  (change-property symbol prop '(lambda (x) (* 2 x))))
+@end group
+@end example
+
+@noindent
+In such cases, we usually use the special form @code{function} instead
+of simple quotation to quote the anonymous function, like this:
+
+@example
+@group
+(defun double-property (symbol prop)
+  (change-property symbol prop
+                   (function (lambda (x) (* 2 x)))))
+@end group
+@end example
+
+Using @code{function} instead of @code{quote} makes a difference if you
+compile the function @code{double-property}.  For example, if you
+compile the second definition of @code{double-property}, the anonymous
+function is compiled as well.  By contrast, if you compile the first
+definition which uses ordinary @code{quote}, the argument passed to
+@code{change-property} is the precise list shown:
+
+@example
+(lambda (x) (* x 2))
+@end example
+
+@noindent
+The Lisp compiler cannot assume this list is a function, even though it
+looks like one, since it does not know what @code{change-property} will
+do with the list.  Perhaps it will check whether the @sc{car} of the third
+element is the symbol @code{*}!  Using @code{function} tells the
+compiler it is safe to go ahead and compile the constant function.
+
+  Nowadays it is possible to omit @code{function} entirely, like this:
+
+@example
+@group
+(defun double-property (symbol prop)
+  (change-property symbol prop (lambda (x) (* 2 x))))
+@end group
+@end example
+
+@noindent
+This is because @code{lambda} itself implies @code{function}.
+
+  We sometimes write @code{function} instead of @code{quote} when
+quoting the name of a function, but this usage is just a sort of
+comment:
+
+@example
+(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
+@end example
+
+@cindex @samp{#'} syntax
+  The read syntax @code{#'} is a short-hand for using @code{function}.
+For example,
+
+@example
+#'(lambda (x) (* x x))
+@end example
+
+@noindent
+is equivalent to
+
+@example
+(function (lambda (x) (* x x)))
+@end example
+
+@defspec function function-object
+@cindex function quoting
+This special form returns @var{function-object} without evaluating it.
+In this, it is equivalent to @code{quote}.  However, it serves as a
+note to the Emacs Lisp compiler that @var{function-object} is intended
+to be used only as a function, and therefore can safely be compiled.
+Contrast this with @code{quote}, in @ref{Quoting}.
+@end defspec
+
+  @xref{describe-symbols example}, for a realistic example using
+@code{function} and an anonymous function.
+
+@node Function Cells
+@section Accessing Function Cell Contents
+
+  The @dfn{function definition} of a symbol is the object stored in the
+function cell of the symbol.  The functions described here access, test,
+and set the function cell of symbols.
+
+  See also the function @code{indirect-function}.  @xref{Definition of
+indirect-function}.
+
+@defun symbol-function symbol
+@kindex void-function
+This returns the object in the function cell of @var{symbol}.  If the
+symbol's function cell is void, a @code{void-function} error is
+signaled.
+
+This function does not check that the returned object is a legitimate
+function.
+
+@example
+@group
+(defun bar (n) (+ n 2))
+     @result{} bar
+@end group
+@group
+(symbol-function 'bar)
+     @result{} (lambda (n) (+ n 2))
+@end group
+@group
+(fset 'baz 'bar)
+     @result{} bar
+@end group
+@group
+(symbol-function 'baz)
+     @result{} bar
+@end group
+@end example
+@end defun
+
+@cindex void function cell
+  If you have never given a symbol any function definition, we say that
+that symbol's function cell is @dfn{void}.  In other words, the function
+cell does not have any Lisp object in it.  If you try to call such a symbol
+as a function, it signals a @code{void-function} error.
+
+  Note that void is not the same as @code{nil} or the symbol
+@code{void}.  The symbols @code{nil} and @code{void} are Lisp objects,
+and can be stored into a function cell just as any other object can be
+(and they can be valid functions if you define them in turn with
+@code{defun}).  A void function cell contains no object whatsoever.
+
+  You can test the voidness of a symbol's function definition with
+@code{fboundp}.  After you have given a symbol a function definition, you
+can make it void once more using @code{fmakunbound}.
+
+@defun fboundp symbol
+This function returns @code{t} if the symbol has an object in its
+function cell, @code{nil} otherwise.  It does not check that the object
+is a legitimate function.
+@end defun
+
+@defun fmakunbound symbol
+This function makes @var{symbol}'s function cell void, so that a
+subsequent attempt to access this cell will cause a
+@code{void-function} error.  It returns @var{symbol}.  (See also
+@code{makunbound}, in @ref{Void Variables}.)
+
+@example
+@group
+(defun foo (x) x)
+     @result{} foo
+@end group
+@group
+(foo 1)
+     @result{}1
+@end group
+@group
+(fmakunbound 'foo)
+     @result{} foo
+@end group
+@group
+(foo 1)
+@error{} Symbol's function definition is void: foo
+@end group
+@end example
+@end defun
+
+@defun fset symbol definition
+This function stores @var{definition} in the function cell of
+@var{symbol}.  The result is @var{definition}.  Normally
+@var{definition} should be a function or the name of a function, but
+this is not checked.  The argument @var{symbol} is an ordinary evaluated
+argument.
+
+There are three normal uses of this function:
+
+@itemize @bullet
+@item
+Copying one symbol's function definition to another---in other words,
+making an alternate name for a function.  (If you think of this as the
+definition of the new name, you should use @code{defalias} instead of
+@code{fset}; see @ref{Definition of defalias}.)
+
+@item
+Giving a symbol a function definition that is not a list and therefore
+cannot be made with @code{defun}.  For example, you can use @code{fset}
+to give a symbol @code{s1} a function definition which is another symbol
+@code{s2}; then @code{s1} serves as an alias for whatever definition
+@code{s2} presently has.  (Once again use @code{defalias} instead of
+@code{fset} if you think of this as the definition of @code{s1}.)
+
+@item
+In constructs for defining or altering functions.  If @code{defun}
+were not a primitive, it could be written in Lisp (as a macro) using
+@code{fset}.
+@end itemize
+
+Here are examples of these uses:
+
+@example
+@group
+;; @r{Save @code{foo}'s definition in @code{old-foo}.}
+(fset 'old-foo (symbol-function 'foo))
+@end group
+
+@group
+;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
+;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
+(fset 'xfirst 'car)
+     @result{} car
+@end group
+@group
+(xfirst '(1 2 3))
+     @result{} 1
+@end group
+@group
+(symbol-function 'xfirst)
+     @result{} car
+@end group
+@group
+(symbol-function (symbol-function 'xfirst))
+     @result{} #<subr car>
+@end group
+
+@group
+;; @r{Define a named keyboard macro.}
+(fset 'kill-two-lines "\^u2\^k")
+     @result{} "\^u2\^k"
+@end group
+
+@group
+;; @r{Here is a function that alters other functions.}
+(defun copy-function-definition (new old)
+  "Define NEW with the same function definition as OLD."
+  (fset new (symbol-function old)))
+@end group
+@end example
+@end defun
+
+  @code{fset} is sometimes used to save the old definition of a
+function before redefining it.  That permits the new definition to
+invoke the old definition.  But it is unmodular and unclean for a Lisp
+file to redefine a function defined elsewhere.  If you want to modify
+a function defined by another package, it is cleaner to use
+@code{defadvice} (@pxref{Advising Functions}).
+
+@node Obsolete Functions
+@section Declaring Functions Obsolete
+
+You can use @code{make-obsolete} to declare a function obsolete.  This
+indicates that the function may be removed at some stage in the future.
+
+@defun make-obsolete obsolete-name current-name &optional when
+This function makes the byte compiler warn that the function
+@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol, the
+warning message says to use @var{current-name} instead of
+@var{obsolete-name}.  @var{current-name} does not need to be an alias for
+@var{obsolete-name}; it can be a different function with similar
+functionality.  If @var{current-name} is a string, it is the warning
+message.
+
+If provided, @var{when} should be a string indicating when the function
+was first made obsolete---for example, a date or a release number.
+@end defun
+
+You can define a function as an alias and declare it obsolete at the
+same time using the macro @code{define-obsolete-function-alias}.
+
+@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
+This macro marks the function @var{obsolete-name} obsolete and also
+defines it as an alias for the function @var{current-name}.  It is
+equivalent to the following:
+
+@example
+(defalias @var{obsolete-name} @var{current-name} @var{docstring})
+(make-obsolete @var{obsolete-name} @var{current-name} @var{when})
+@end example
+@end defmac
+
+@node Inline Functions
+@section Inline Functions
+@cindex inline functions
+
+@findex defsubst
+You can define an @dfn{inline function} by using @code{defsubst} instead
+of @code{defun}.  An inline function works just like an ordinary
+function except for one thing: when you compile a call to the function,
+the function's definition is open-coded into the caller.
+
+Making a function inline makes explicit calls run faster.  But it also
+has disadvantages.  For one thing, it reduces flexibility; if you
+change the definition of the function, calls already inlined still use
+the old definition until you recompile them.
+
+Another disadvantage is that making a large function inline can increase
+the size of compiled code both in files and in memory.  Since the speed
+advantage of inline functions is greatest for small functions, you
+generally should not make large functions inline.
+
+Also, inline functions do not behave well with respect to debugging,
+tracing, and advising (@pxref{Advising Functions}).  Since ease of
+debugging and the flexibility of redefining functions are important
+features of Emacs, you should not make a function inline, even if it's
+small, unless its speed is really crucial, and you've timed the code
+to verify that using @code{defun} actually has performance problems.
+
+It's possible to define a macro to expand into the same code that an
+inline function would execute.  (@xref{Macros}.)  But the macro would be
+limited to direct use in expressions---a macro cannot be called with
+@code{apply}, @code{mapcar} and so on.  Also, it takes some work to
+convert an ordinary function into a macro.  To convert it into an inline
+function is very easy; simply replace @code{defun} with @code{defsubst}.
+Since each argument of an inline function is evaluated exactly once, you
+needn't worry about how many times the body uses the arguments, as you
+do for macros.  (@xref{Argument Evaluation}.)
+
+Inline functions can be used and open-coded later on in the same file,
+following the definition, just like macros.
+
+@node Function Safety
+@section Determining whether a Function is Safe to Call
+@cindex function safety
+@cindex safety of functions
+
+Some major modes such as SES call functions that are stored in user
+files.  (@inforef{Top, ,ses}, for more information on SES.)  User
+files sometimes have poor pedigrees---you can get a spreadsheet from
+someone you've just met, or you can get one through email from someone
+you've never met.  So it is risky to call a function whose source code
+is stored in a user file until you have determined that it is safe.
+
+@defun unsafep form &optional unsafep-vars
+Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
+returns a list that describes why it might be unsafe.  The argument
+@var{unsafep-vars} is a list of symbols known to have temporary
+bindings at this point; it is mainly used for internal recursive
+calls.  The current buffer is an implicit argument, which provides a
+list of buffer-local bindings.
+@end defun
+
+Being quick and simple, @code{unsafep} does a very light analysis and
+rejects many Lisp expressions that are actually safe.  There are no
+known cases where @code{unsafep} returns @code{nil} for an unsafe
+expression.  However, a ``safe'' Lisp expression can return a string
+with a @code{display} property, containing an associated Lisp
+expression to be executed after the string is inserted into a buffer.
+This associated expression can be a virus.  In order to be safe, you
+must delete properties from all strings calculated by user code before
+inserting them into buffers.
+
+@ignore
+What is a safe Lisp expression?  Basically, it's an expression that
+calls only built-in functions with no side effects (or only innocuous
+ones).  Innocuous side effects include displaying messages and
+altering non-risky buffer-local variables (but not global variables).
+
+@table @dfn
+@item Safe expression
+@itemize
+@item
+An atom or quoted thing.
+@item
+A call to a safe function (see below), if all its arguments are
+safe expressions.
+@item
+One of the special forms @code{and}, @code{catch}, @code{cond},
+@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
+@code{while}, and @code{unwind-protect}], if all its arguments are
+safe.
+@item
+A form that creates temporary bindings (@code{condition-case},
+@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
+@code{let*}), if all args are safe and the symbols to be bound are not
+explicitly risky (see @pxref{File Local Variables}).
+@item
+An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
+@code{pop}, if all args are safe and the symbols to be assigned are
+not explicitly risky and they already have temporary or buffer-local
+bindings.
+@item
+One of [apply, mapc, mapcar, mapconcat] if the first argument is a
+safe explicit lambda and the other args are safe expressions.
+@end itemize
+
+@item Safe function
+@itemize
+@item
+A lambda containing safe expressions.
+@item
+A symbol on the list @code{safe-functions}, so the user says it's safe.
+@item
+A symbol with a non-@code{nil} @code{side-effect-free} property.
+@item
+A symbol with a non-@code{nil} @code{safe-function} property.  Value t
+indicates a function that is safe but has innocuous side effects.
+Other values will someday indicate functions with classes of side
+effects that are not always safe.
+@end itemize
+
+The @code{side-effect-free} and @code{safe-function} properties are
+provided for built-in functions and for low-level functions and macros
+defined in @file{subr.el}.  You can assign these properties for the
+functions you write.
+@end table
+@end ignore
+
+@node Related Topics
+@section Other Topics Related to Functions
+
+  Here is a table of several functions that do things related to
+function calling and function definitions.  They are documented
+elsewhere, but we provide cross references here.
+
+@table @code
+@item apply
+See @ref{Calling Functions}.
+
+@item autoload
+See @ref{Autoload}.
+
+@item call-interactively
+See @ref{Interactive Call}.
+
+@item commandp
+See @ref{Interactive Call}.
+
+@item documentation
+See @ref{Accessing Documentation}.
+
+@item eval
+See @ref{Eval}.
+
+@item funcall
+See @ref{Calling Functions}.
+
+@item function
+See @ref{Anonymous Functions}.
+
+@item ignore
+See @ref{Calling Functions}.
+
+@item indirect-function
+See @ref{Function Indirection}.
+
+@item interactive
+See @ref{Using Interactive}.
+
+@item interactive-p
+See @ref{Interactive Call}.
+
+@item mapatoms
+See @ref{Creating Symbols}.
+
+@item mapcar
+See @ref{Mapping Functions}.
+
+@item map-char-table
+See @ref{Char-Tables}.
+
+@item mapconcat
+See @ref{Mapping Functions}.
+
+@item undefined
+See @ref{Functions for Key Lookup}.
+@end table
+
+@ignore
+   arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2
+@end ignore
diff --git a/doc/lispref/gpl.texi b/doc/lispref/gpl.texi
new file mode 100644
index 00000000000..e9f7218ede9
--- /dev/null
+++ b/doc/lispref/gpl.texi
@@ -0,0 +1,727 @@
+@c -*-texinfo-*-
+@setfilename ../info/gpl
+
+@node GPL, Tips, GNU Free Documentation License, Top
+@comment  node-name,  next,  previous,  up
+@appendix GNU General Public License
+@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: d00ac830-e120-41fb-bbc5-7ca3eeaa227f
+@end ignore
diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
new file mode 100644
index 00000000000..c5b68e26d91
--- /dev/null
+++ b/doc/lispref/hash.texi
@@ -0,0 +1,337 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1999, 2001, 2002, 2003, 2004, 2005,
+@c   2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/hash
+@node Hash Tables, Symbols, Sequences Arrays Vectors, Top
+@chapter Hash Tables
+@cindex hash tables
+@cindex lookup tables
+
+  A hash table is a very fast kind of lookup table, somewhat like an
+alist (@pxref{Association Lists}) in that it maps keys to
+corresponding values.  It differs from an alist in these ways:
+
+@itemize @bullet
+@item
+Lookup in a hash table is extremely fast for large tables---in fact, the
+time required is essentially @emph{independent} of how many elements are
+stored in the table.  For smaller tables (a few tens of elements)
+alists may still be faster because hash tables have a more-or-less
+constant overhead.
+
+@item
+The correspondences in a hash table are in no particular order.
+
+@item
+There is no way to share structure between two hash tables,
+the way two alists can share a common tail.
+@end itemize
+
+  Emacs Lisp provides a general-purpose hash table data type, along
+with a series of functions for operating on them.  Hash tables have no
+read syntax, and print in hash notation, like this:
+
+@example
+(make-hash-table)
+     @result{} #<hash-table 'eql nil 0/65 0x83af980>
+@end example
+
+@noindent
+(The term ``hash notation'' refers to the initial @samp{#}
+character---@pxref{Printed Representation}---and has nothing to do with
+the term ``hash table.'')
+
+  Obarrays are also a kind of hash table, but they are a different type
+of object and are used only for recording interned symbols
+(@pxref{Creating Symbols}).
+
+@menu
+* Creating Hash::       Functions to create hash tables.
+* Hash Access::         Reading and writing the hash table contents.
+* Defining Hash::       Defining new comparison methods
+* Other Hash::          Miscellaneous.
+@end menu
+
+@node Creating Hash
+@section Creating Hash Tables
+@cindex creating hash tables
+
+  The principal function for creating a hash table is
+@code{make-hash-table}.
+
+@defun make-hash-table &rest keyword-args
+This function creates a new hash table according to the specified
+arguments.  The arguments should consist of alternating keywords
+(particular symbols recognized specially) and values corresponding to
+them.
+
+Several keywords make sense in @code{make-hash-table}, but the only two
+that you really need to know about are @code{:test} and @code{:weakness}.
+
+@table @code
+@item :test @var{test}
+This specifies the method of key lookup for this hash table.  The
+default is @code{eql}; @code{eq} and @code{equal} are other
+alternatives:
+
+@table @code
+@item eql
+Keys which are numbers are ``the same'' if they are @code{equal}, that
+is, if they are equal in value and either both are integers or both
+are floating point numbers; otherwise, two distinct objects are never
+``the same.''
+
+@item eq
+Any two distinct Lisp objects are ``different'' as keys.
+
+@item equal
+Two Lisp objects are ``the same,'' as keys, if they are equal
+according to @code{equal}.
+@end table
+
+You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to
+define additional possibilities for @var{test}.
+
+@item :weakness @var{weak}
+The weakness of a hash table specifies whether the presence of a key or
+value in the hash table preserves it from garbage collection.
+
+The value, @var{weak}, must be one of @code{nil}, @code{key},
+@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t}
+which is an alias for @code{key-and-value}.  If @var{weak} is @code{key}
+then the hash table does not prevent its keys from being collected as
+garbage (if they are not referenced anywhere else); if a particular key
+does get collected, the corresponding association is removed from the
+hash table.
+
+If @var{weak} is @code{value}, then the hash table does not prevent
+values from being collected as garbage (if they are not referenced
+anywhere else); if a particular value does get collected, the
+corresponding association is removed from the hash table.
+
+If @var{weak} is @code{key-and-value} or @code{t}, both the key and
+the value must be live in order to preserve the association.  Thus,
+the hash table does not protect either keys or values from garbage
+collection; if either one is collected as garbage, that removes the
+association.
+
+If @var{weak} is @code{key-or-value}, either the key or
+the value can preserve the association.  Thus, associations are
+removed from the hash table when both their key and value would be
+collected as garbage (if not for references from weak hash tables).
+
+The default for @var{weak} is @code{nil}, so that all keys and values
+referenced in the hash table are preserved from garbage collection.
+
+@item :size @var{size}
+This specifies a hint for how many associations you plan to store in the
+hash table.  If you know the approximate number, you can make things a
+little more efficient by specifying it this way.  If you specify too
+small a size, the hash table will grow automatically when necessary, but
+doing that takes some extra time.
+
+The default size is 65.
+
+@item :rehash-size @var{rehash-size}
+When you add an association to a hash table and the table is ``full,''
+it grows automatically.  This value specifies how to make the hash table
+larger, at that time.
+
+If @var{rehash-size} is an integer, it should be positive, and the hash
+table grows by adding that much to the nominal size.  If
+@var{rehash-size} is a floating point number, it had better be greater
+than 1, and the hash table grows by multiplying the old size by that
+number.
+
+The default value is 1.5.
+
+@item :rehash-threshold @var{threshold}
+This specifies the criterion for when the hash table is ``full'' (so
+it should be made larger).  The value, @var{threshold}, should be a
+positive floating point number, no greater than 1.  The hash table is
+``full'' whenever the actual number of entries exceeds this fraction
+of the nominal size.  The default for @var{threshold} is 0.8.
+@end table
+@end defun
+
+@defun makehash &optional test
+This is equivalent to @code{make-hash-table}, but with a different style
+argument list.  The argument @var{test} specifies the method
+of key lookup.
+
+This function is obsolete. Use @code{make-hash-table} instead.
+@end defun
+
+@node Hash Access
+@section Hash Table Access
+
+  This section describes the functions for accessing and storing
+associations in a hash table.  In general, any Lisp object can be used
+as a hash key, unless the comparison method imposes limits.  Any Lisp
+object can also be used as the value.
+
+@defun gethash key table &optional default
+This function looks up @var{key} in @var{table}, and returns its
+associated @var{value}---or @var{default}, if @var{key} has no
+association in @var{table}.
+@end defun
+
+@defun puthash key value table
+This function enters an association for @var{key} in @var{table}, with
+value @var{value}.  If @var{key} already has an association in
+@var{table}, @var{value} replaces the old associated value.
+@end defun
+
+@defun remhash key table
+This function removes the association for @var{key} from @var{table}, if
+there is one.  If @var{key} has no association, @code{remhash} does
+nothing.
+
+@b{Common Lisp note:} In Common Lisp, @code{remhash} returns
+non-@code{nil} if it actually removed an association and @code{nil}
+otherwise.  In Emacs Lisp, @code{remhash} always returns @code{nil}.
+@end defun
+
+@defun clrhash table
+This function removes all the associations from hash table @var{table},
+so that it becomes empty.  This is also called @dfn{clearing} the hash
+table.
+
+@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
+@var{table}.  In Emacs Lisp, it returns @code{nil}.
+@end defun
+
+@defun maphash function table
+@anchor{Definition of maphash}
+This function calls @var{function} once for each of the associations in
+@var{table}.  The function @var{function} should accept two
+arguments---a @var{key} listed in @var{table}, and its associated
+@var{value}.  @code{maphash} returns @code{nil}.
+@end defun
+
+@node Defining Hash
+@section Defining Hash Comparisons
+@cindex hash code
+@cindex define hash comparisons
+
+  You can define new methods of key lookup by means of
+@code{define-hash-table-test}.  In order to use this feature, you need
+to understand how hash tables work, and what a @dfn{hash code} means.
+
+  You can think of a hash table conceptually as a large array of many
+slots, each capable of holding one association.  To look up a key,
+@code{gethash} first computes an integer, the hash code, from the key.
+It reduces this integer modulo the length of the array, to produce an
+index in the array.  Then it looks in that slot, and if necessary in
+other nearby slots, to see if it has found the key being sought.
+
+  Thus, to define a new method of key lookup, you need to specify both a
+function to compute the hash code from a key, and a function to compare
+two keys directly.
+
+@defun define-hash-table-test name test-fn hash-fn
+This function defines a new hash table test, named @var{name}.
+
+After defining @var{name} in this way, you can use it as the @var{test}
+argument in @code{make-hash-table}.  When you do that, the hash table
+will use @var{test-fn} to compare key values, and @var{hash-fn} to compute
+a ``hash code'' from a key value.
+
+The function @var{test-fn} should accept two arguments, two keys, and
+return non-@code{nil} if they are considered ``the same.''
+
+The function @var{hash-fn} should accept one argument, a key, and return
+an integer that is the ``hash code'' of that key.  For good results, the
+function should use the whole range of integer values for hash codes,
+including negative integers.
+
+The specified functions are stored in the property list of @var{name}
+under the property @code{hash-table-test}; the property value's form is
+@code{(@var{test-fn} @var{hash-fn})}.
+@end defun
+
+@defun sxhash obj
+This function returns a hash code for Lisp object @var{obj}.
+This is an integer which reflects the contents of @var{obj}
+and the other Lisp objects it points to.
+
+If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
+@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
+
+If the two objects are not equal, the values returned by @code{sxhash}
+are usually different, but not always; once in a rare while, by luck,
+you will encounter two distinct-looking objects that give the same
+result from @code{sxhash}.
+@end defun
+
+  This example creates a hash table whose keys are strings that are
+compared case-insensitively.
+
+@example
+(defun case-fold-string= (a b)
+  (compare-strings a nil nil b nil nil t))
+(defun case-fold-string-hash (a)
+  (sxhash (upcase a)))
+
+(define-hash-table-test 'case-fold
+  'case-fold-string= 'case-fold-string-hash)
+
+(make-hash-table :test 'case-fold)
+@end example
+
+  Here is how you could define a hash table test equivalent to the
+predefined test value @code{equal}.  The keys can be any Lisp object,
+and equal-looking objects are considered the same key.
+
+@example
+(define-hash-table-test 'contents-hash 'equal 'sxhash)
+
+(make-hash-table :test 'contents-hash)
+@end example
+
+@node Other Hash
+@section Other Hash Table Functions
+
+  Here are some other functions for working with hash tables.
+
+@defun hash-table-p table
+This returns non-@code{nil} if @var{table} is a hash table object.
+@end defun
+
+@defun copy-hash-table table
+This function creates and returns a copy of @var{table}.  Only the table
+itself is copied---the keys and values are shared.
+@end defun
+
+@defun hash-table-count table
+This function returns the actual number of entries in @var{table}.
+@end defun
+
+@defun hash-table-test table
+This returns the @var{test} value that was given when @var{table} was
+created, to specify how to hash and compare keys.  See
+@code{make-hash-table} (@pxref{Creating Hash}).
+@end defun
+
+@defun hash-table-weakness table
+This function returns the @var{weak} value that was specified for hash
+table @var{table}.
+@end defun
+
+@defun hash-table-rehash-size table
+This returns the rehash size of @var{table}.
+@end defun
+
+@defun hash-table-rehash-threshold table
+This returns the rehash threshold of @var{table}.
+@end defun
+
+@defun hash-table-size table
+This returns the current nominal size of @var{table}.
+@end defun
+
+@ignore
+   arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e
+@end ignore
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
new file mode 100644
index 00000000000..dd56aa872b7
--- /dev/null
+++ b/doc/lispref/help.texi
@@ -0,0 +1,699 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/help
+@node Documentation, Files, Modes, Top
+@chapter Documentation
+@cindex documentation strings
+
+  GNU Emacs Lisp has convenient on-line help facilities, most of which
+derive their information from the documentation strings associated with
+functions and variables.  This chapter describes how to write good
+documentation strings for your Lisp programs, as well as how to write
+programs to access documentation.
+
+  Note that the documentation strings for Emacs are not the same thing
+as the Emacs manual.  Manuals have their own source files, written in
+the Texinfo language; documentation strings are specified in the
+definitions of the functions and variables they apply to.  A collection
+of documentation strings is not sufficient as a manual because a good
+manual is not organized in that fashion; it is organized in terms of
+topics of discussion.
+
+  For commands to display documentation strings, see @ref{Help, ,
+Help, emacs, The GNU Emacs Manual}.  For the conventions for writing
+documentation strings, see @ref{Documentation Tips}.
+
+@menu
+* Documentation Basics::      Good style for doc strings.
+                                Where to put them.  How Emacs stores them.
+* Accessing Documentation::   How Lisp programs can access doc strings.
+* Keys in Documentation::     Substituting current key bindings.
+* Describing Characters::     Making printable descriptions of
+                                non-printing characters and key sequences.
+* Help Functions::            Subroutines used by Emacs help facilities.
+@end menu
+
+@node Documentation Basics
+@comment  node-name,  next,  previous,  up
+@section Documentation Basics
+@cindex documentation conventions
+@cindex writing a documentation string
+@cindex string, writing a doc string
+
+  A documentation string is written using the Lisp syntax for strings,
+with double-quote characters surrounding the text of the string.  This
+is because it really is a Lisp string object.  The string serves as
+documentation when it is written in the proper place in the definition
+of a function or variable.  In a function definition, the documentation
+string follows the argument list.  In a variable definition, the
+documentation string follows the initial value of the variable.
+
+  When you write a documentation string, make the first line a
+complete sentence (or two complete sentences) since some commands,
+such as @code{apropos}, show only the first line of a multi-line
+documentation string.  Also, you should not indent the second line of
+a documentation string, if it has one, because that looks odd when you
+use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
+(@code{describe-variable}) to view the documentation string.  There
+are many other conventions for doc strings; see @ref{Documentation
+Tips}.
+
+  Documentation strings can contain several special substrings, which
+stand for key bindings to be looked up in the current keymaps when the
+documentation is displayed.  This allows documentation strings to refer
+to the keys for related commands and be accurate even when a user
+rearranges the key bindings.  (@xref{Keys in Documentation}.)
+
+@vindex emacs-lisp-docstring-fill-column
+  Emacs Lisp mode fills documentation strings to the width
+specified by @code{emacs-lisp-docstring-fill-column}.
+
+  In Emacs Lisp, a documentation string is accessible through the
+function or variable that it describes:
+
+@itemize @bullet
+@item
+@kindex function-documentation
+The documentation for a function is usually stored in the function
+definition itself (@pxref{Lambda Expressions}).  The function
+@code{documentation} knows how to extract it.  You can also put
+function documentation in the @code{function-documentation} property
+of the function name.  That is useful with definitions such as
+keyboard macros that can't hold a documentation string.
+
+@item
+@kindex variable-documentation
+The documentation for a variable is stored in the variable's property
+list under the property name @code{variable-documentation}.  The
+function @code{documentation-property} knows how to retrieve it.
+@end itemize
+
+@cindex @file{DOC-@var{version}} (documentation) file
+To save space, the documentation for preloaded functions and variables
+(including primitive functions and autoloaded functions) is stored in
+the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs.  The
+documentation strings for functions and variables loaded during the
+Emacs session from byte-compiled files are stored in those files
+(@pxref{Docs and Compilation}).
+
+The data structure inside Emacs has an integer offset into the file, or
+a list containing a file name and an integer, in place of the
+documentation string.  The functions @code{documentation} and
+@code{documentation-property} use that information to fetch the
+documentation string from the appropriate file; this is transparent to
+the user.
+
+@c Wordy to prevent overfull hbox.  --rjc 15mar92
+  The @file{emacs/lib-src} directory contains two utilities that you can
+use to print nice-looking hardcopy for the file
+@file{emacs/etc/DOC-@var{version}}.  These are @file{sorted-doc} and
+@file{digest-doc}.
+
+@node Accessing Documentation
+@section Access to Documentation Strings
+
+@defun documentation-property symbol property &optional verbatim
+This function returns the documentation string that is recorded in
+@var{symbol}'s property list under property @var{property}.  It
+retrieves the text from a file if the value calls for that.  If the
+property value isn't @code{nil}, isn't a string, and doesn't refer to
+text in a file, then it is evaluated to obtain a string.
+
+The last thing this function does is pass the string through
+@code{substitute-command-keys} to substitute actual key bindings,
+unless @var{verbatim} is non-@code{nil}.
+
+@smallexample
+@group
+(documentation-property 'command-line-processed
+   'variable-documentation)
+     @result{} "Non-nil once command line has been processed"
+@end group
+@group
+(symbol-plist 'command-line-processed)
+     @result{} (variable-documentation 188902)
+@end group
+@group
+(documentation-property 'emacs 'group-documentation)
+     @result{} "Customization of the One True Editor."
+@end group
+@end smallexample
+@end defun
+
+@defun documentation function &optional verbatim
+This function returns the documentation string of @var{function}.
+@code{documentation} handles macros, named keyboard macros, and
+special forms, as well as ordinary functions.
+
+If @var{function} is a symbol, this function first looks for the
+@code{function-documentation} property of that symbol; if that has a
+non-@code{nil} value, the documentation comes from that value (if the
+value is not a string, it is evaluated).  If @var{function} is not a
+symbol, or if it has no @code{function-documentation} property, then
+@code{documentation} extracts the documentation string from the actual
+function definition, reading it from a file if called for.
+
+Finally, unless @var{verbatim} is non-@code{nil}, it calls
+@code{substitute-command-keys} so as to return a value containing the
+actual (current) key bindings.
+
+The function @code{documentation} signals a @code{void-function} error
+if @var{function} has no function definition.  However, it is OK if
+the function definition has no documentation string.  In that case,
+@code{documentation} returns @code{nil}.
+@end defun
+
+@defun face-documentation face
+This function returns the documentation string of @var{face} as a
+face.
+@end defun
+
+@c Wordy to prevent overfull hboxes.  --rjc 15mar92
+Here is an example of using the two functions, @code{documentation} and
+@code{documentation-property}, to display the documentation strings for
+several symbols in a @samp{*Help*} buffer.
+
+@anchor{describe-symbols example}
+@smallexample
+@group
+(defun describe-symbols (pattern)
+  "Describe the Emacs Lisp symbols matching PATTERN.
+All symbols that have PATTERN in their name are described
+in the `*Help*' buffer."
+  (interactive "sDescribe symbols matching: ")
+  (let ((describe-func
+         (function
+          (lambda (s)
+@end group
+@group
+            ;; @r{Print description of symbol.}
+            (if (fboundp s)             ; @r{It is a function.}
+                (princ
+                 (format "%s\t%s\n%s\n\n" s
+                   (if (commandp s)
+                       (let ((keys (where-is-internal s)))
+                         (if keys
+                             (concat
+                              "Keys: "
+                              (mapconcat 'key-description
+                                         keys " "))
+                           "Keys: none"))
+                     "Function")
+@end group
+@group
+                   (or (documentation s)
+                       "not documented"))))
+
+            (if (boundp s)              ; @r{It is a variable.}
+@end group
+@group
+                (princ
+                 (format "%s\t%s\n%s\n\n" s
+                   (if (user-variable-p s)
+                       "Option " "Variable")
+@end group
+@group
+                   (or (documentation-property
+                         s 'variable-documentation)
+                       "not documented")))))))
+        sym-list)
+@end group
+
+@group
+    ;; @r{Build a list of symbols that match pattern.}
+    (mapatoms (function
+               (lambda (sym)
+                 (if (string-match pattern (symbol-name sym))
+                     (setq sym-list (cons sym sym-list))))))
+@end group
+
+@group
+    ;; @r{Display the data.}
+    (with-output-to-temp-buffer "*Help*"
+      (mapcar describe-func (sort sym-list 'string<))
+      (print-help-return-message))))
+@end group
+@end smallexample
+
+  The @code{describe-symbols} function works like @code{apropos},
+but provides more information.
+
+@smallexample
+@group
+(describe-symbols "goal")
+
+---------- Buffer: *Help* ----------
+goal-column     Option
+*Semipermanent goal column for vertical motion, as set by @dots{}
+@end group
+@c Do not blithely break or fill these lines.
+@c That makes them incorrect.
+
+@group
+set-goal-column Keys: C-x C-n
+Set the current horizontal position as a goal for C-n and C-p.
+@end group
+@c DO NOT put a blank line here!  That is factually inaccurate!
+@group
+Those commands will move to this position in the line moved to
+rather than trying to keep the same horizontal position.
+With a non-nil argument, clears out the goal column
+so that C-n and C-p resume vertical motion.
+The goal column is stored in the variable `goal-column'.
+@end group
+
+@group
+temporary-goal-column   Variable
+Current goal column for vertical motion.
+It is the column where point was
+at the start of current run of vertical motion commands.
+When the `track-eol' feature is doing its job, the value is 9999.
+---------- Buffer: *Help* ----------
+@end group
+@end smallexample
+
+The asterisk @samp{*} as the first character of a variable's doc string,
+as shown above for the @code{goal-column} variable, means that it is a
+user option; see the description of @code{defvar} in @ref{Defining
+Variables}.
+
+@defun Snarf-documentation filename
+@anchor{Definition of Snarf-documentation}
+This function is used only during Emacs initialization, just before
+the runnable Emacs is dumped.  It finds the file offsets of the
+documentation strings stored in the file @var{filename}, and records
+them in the in-core function definitions and variable property lists in
+place of the actual strings.  @xref{Building Emacs}.
+
+Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
+When the dumped Emacs is later executed, the same file will be looked
+for in the directory @code{doc-directory}.  Usually @var{filename} is
+@code{"DOC-@var{version}"}.
+@end defun
+
+@c Emacs 19 feature
+@defvar doc-directory
+This variable holds the name of the directory which should contain the
+file @code{"DOC-@var{version}"} that contains documentation strings for
+built-in and preloaded functions and variables.
+
+In most cases, this is the same as @code{data-directory}.  They may be
+different when you run Emacs from the directory where you built it,
+without actually installing it.  @xref{Definition of data-directory}.
+
+In older Emacs versions, @code{exec-directory} was used for this.
+@end defvar
+
+@node Keys in Documentation
+@section Substituting Key Bindings in Documentation
+@cindex documentation, keys in
+@cindex keys in documentation strings
+@cindex substituting keys in documentation
+
+  When documentation strings refer to key sequences, they should use the
+current, actual key bindings.  They can do so using certain special text
+sequences described below.  Accessing documentation strings in the usual
+way substitutes current key binding information for these special
+sequences.  This works by calling @code{substitute-command-keys}.  You
+can also call that function yourself.
+
+  Here is a list of the special sequences and what they mean:
+
+@table @code
+@item \[@var{command}]
+stands for a key sequence that will invoke @var{command}, or @samp{M-x
+@var{command}} if @var{command} has no key bindings.
+
+@item \@{@var{mapvar}@}
+stands for a summary of the keymap which is the value of the variable
+@var{mapvar}.  The summary is made using @code{describe-bindings}.
+
+@item \<@var{mapvar}>
+stands for no text itself.  It is used only for a side effect: it
+specifies @var{mapvar}'s value as the keymap for any following
+@samp{\[@var{command}]} sequences in this documentation string.
+
+@item \=
+quotes the following character and is discarded; thus, @samp{\=\[} puts
+@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
+output.
+@end table
+
+@strong{Please note:} Each @samp{\} must be doubled when written in a
+string in Emacs Lisp.
+
+@defun substitute-command-keys string
+This function scans @var{string} for the above special sequences and
+replaces them by what they stand for, returning the result as a string.
+This permits display of documentation that refers accurately to the
+user's own customized key bindings.
+@end defun
+
+  Here are examples of the special sequences:
+
+@smallexample
+@group
+(substitute-command-keys
+   "To abort recursive edit, type: \\[abort-recursive-edit]")
+@result{} "To abort recursive edit, type: C-]"
+@end group
+
+@group
+(substitute-command-keys
+   "The keys that are defined for the minibuffer here are:
+  \\@{minibuffer-local-must-match-map@}")
+@result{} "The keys that are defined for the minibuffer here are:
+@end group
+
+?               minibuffer-completion-help
+SPC             minibuffer-complete-word
+TAB             minibuffer-complete
+C-j             minibuffer-complete-and-exit
+RET             minibuffer-complete-and-exit
+C-g             abort-recursive-edit
+"
+
+@group
+(substitute-command-keys
+   "To abort a recursive edit from the minibuffer, type\
+\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
+@result{} "To abort a recursive edit from the minibuffer, type C-g."
+@end group
+@end smallexample
+
+  There are other special conventions for the text in documentation
+strings---for instance, you can refer to functions, variables, and
+sections of this manual.  @xref{Documentation Tips}, for details.
+
+@node Describing Characters
+@section Describing Characters for Help Messages
+@cindex describe characters and events
+
+  These functions convert events, key sequences, or characters to
+textual descriptions.  These descriptions are useful for including
+arbitrary text characters or key sequences in messages, because they
+convert non-printing and whitespace characters to sequences of printing
+characters.  The description of a non-whitespace printing character is
+the character itself.
+
+@defun key-description sequence &optional prefix
+@cindex Emacs event standard notation
+This function returns a string containing the Emacs standard notation
+for the input events in @var{sequence}.  If @var{prefix} is
+non-@code{nil}, it is a sequence of input events leading up to
+@var{sequence} and is included in the return value.  Both arguments
+may be strings, vectors or lists.  @xref{Input Events}, for more
+information about valid events.
+
+@smallexample
+@group
+(key-description [?\M-3 delete])
+     @result{} "M-3 <delete>"
+@end group
+@group
+(key-description [delete] "\M-3")
+     @result{} "M-3 <delete>"
+@end group
+@end smallexample
+
+  See also the examples for @code{single-key-description}, below.
+@end defun
+
+@defun single-key-description event &optional no-angles
+@cindex event printing
+@cindex character printing
+@cindex control character printing
+@cindex meta character printing
+This function returns a string describing @var{event} in the standard
+Emacs notation for keyboard input.  A normal printing character
+appears as itself, but a control character turns into a string
+starting with @samp{C-}, a meta character turns into a string starting
+with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
+@samp{TAB}, etc.  A function key symbol appears inside angle brackets
+@samp{<@dots{}>}.  An event that is a list appears as the name of the
+symbol in the @sc{car} of the list, inside angle brackets.
+
+If the optional argument @var{no-angles} is non-@code{nil}, the angle
+brackets around function keys and event symbols are omitted; this is
+for compatibility with old versions of Emacs which didn't use the
+brackets.
+
+@smallexample
+@group
+(single-key-description ?\C-x)
+     @result{} "C-x"
+@end group
+@group
+(key-description "\C-x \M-y \n \t \r \f123")
+     @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
+@end group
+@group
+(single-key-description 'delete)
+     @result{} "<delete>"
+@end group
+@group
+(single-key-description 'C-mouse-1)
+     @result{} "<C-mouse-1>"
+@end group
+@group
+(single-key-description 'C-mouse-1 t)
+     @result{} "C-mouse-1"
+@end group
+@end smallexample
+@end defun
+
+@defun text-char-description character
+This function returns a string describing @var{character} in the
+standard Emacs notation for characters that appear in text---like
+@code{single-key-description}, except that control characters are
+represented with a leading caret (which is how control characters in
+Emacs buffers are usually displayed).  Another difference is that
+@code{text-char-description} recognizes the 2**7 bit as the Meta
+character, whereas @code{single-key-description} uses the 2**27 bit
+for Meta.
+
+@smallexample
+@group
+(text-char-description ?\C-c)
+     @result{} "^C"
+@end group
+@group
+(text-char-description ?\M-m)
+     @result{} "\xed"
+@end group
+@group
+(text-char-description ?\C-\M-m)
+     @result{} "\x8d"
+@end group
+@group
+(text-char-description (+ 128 ?m))
+     @result{} "M-m"
+@end group
+@group
+(text-char-description (+ 128 ?\C-m))
+     @result{} "M-^M"
+@end group
+@end smallexample
+@end defun
+
+@defun read-kbd-macro string &optional need-vector
+This function is used mainly for operating on keyboard macros, but it
+can also be used as a rough inverse for @code{key-description}.  You
+call it with a string containing key descriptions, separated by spaces;
+it returns a string or vector containing the corresponding events.
+(This may or may not be a single valid key sequence, depending on what
+events you use; @pxref{Key Sequences}.)  If @var{need-vector} is
+non-@code{nil}, the return value is always a vector.
+@end defun
+
+@node Help Functions
+@section Help Functions
+
+  Emacs provides a variety of on-line help functions, all accessible to
+the user as subcommands of the prefix @kbd{C-h}.  For more information
+about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}.  Here
+we describe some program-level interfaces to the same information.
+
+@deffn Command apropos pattern &optional do-all
+This function finds all ``meaningful'' symbols whose names contain a
+match for the apropos pattern @var{pattern}.  An apropos pattern is
+either a word to match, a space-separated list of words of which at
+least two must match, or a regular expression (if any special regular
+expression characters occur).  A symbol is ``meaningful'' if it has a
+definition as a function, variable, or face, or has properties.
+
+The function returns a list of elements that look like this:
+
+@example
+(@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
+ @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
+@end example
+
+Here, @var{score} is an integer measure of how important the symbol
+seems to be as a match, and the remaining elements are documentation
+strings for @var{symbol}'s various roles (or @code{nil}).
+
+It also displays the symbols in a buffer named @samp{*Apropos*}, each
+with a one-line description taken from the beginning of its
+documentation string.
+
+@c Emacs 19 feature
+If @var{do-all} is non-@code{nil}, or if the user option
+@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also
+shows key bindings for the functions that are found; it also shows
+@emph{all} interned symbols, not just meaningful ones (and it lists
+them in the return value as well).
+@end deffn
+
+@defvar help-map
+The value of this variable is a local keymap for characters following the
+Help key, @kbd{C-h}.
+@end defvar
+
+@deffn {Prefix Command} help-command
+This symbol is not a function; its function definition cell holds the
+keymap known as @code{help-map}.  It is defined in @file{help.el} as
+follows:
+
+@smallexample
+@group
+(define-key global-map (char-to-string help-char) 'help-command)
+(fset 'help-command help-map)
+@end group
+@end smallexample
+@end deffn
+
+@defun print-help-return-message &optional function
+This function builds a string that explains how to restore the previous
+state of the windows after a help command.  After building the message,
+it applies @var{function} to it if @var{function} is non-@code{nil}.
+Otherwise it calls @code{message} to display it in the echo area.
+
+This function expects to be called inside a
+@code{with-output-to-temp-buffer} special form, and expects
+@code{standard-output} to have the value bound by that special form.
+For an example of its use, see the long example in @ref{Accessing
+Documentation}.
+@end defun
+
+@defvar help-char
+The value of this variable is the help character---the character that
+Emacs recognizes as meaning Help.  By default, its value is 8, which
+stands for @kbd{C-h}.  When Emacs reads this character, if
+@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
+expression, and displays the result in a window if it is a string.
+
+Usually the value of @code{help-form} is @code{nil}.  Then the
+help character has no special meaning at the level of command input, and
+it becomes part of a key sequence in the normal way.  The standard key
+binding of @kbd{C-h} is a prefix key for several general-purpose help
+features.
+
+The help character is special after prefix keys, too.  If it has no
+binding as a subcommand of the prefix key, it runs
+@code{describe-prefix-bindings}, which displays a list of all the
+subcommands of the prefix key.
+@end defvar
+
+@defvar help-event-list
+The value of this variable is a list of event types that serve as
+alternative ``help characters.''  These events are handled just like the
+event specified by @code{help-char}.
+@end defvar
+
+@defvar help-form
+If this variable is non-@code{nil}, its value is a form to evaluate
+whenever the character @code{help-char} is read.  If evaluating the form
+produces a string, that string is displayed.
+
+A command that calls @code{read-event} or @code{read-char} probably
+should bind @code{help-form} to a non-@code{nil} expression while it
+does input.  (The time when you should not do this is when @kbd{C-h} has
+some other meaning.)  Evaluating this expression should result in a
+string that explains what the input is for and how to enter it properly.
+
+Entry to the minibuffer binds this variable to the value of
+@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
+@end defvar
+
+@defvar prefix-help-command
+This variable holds a function to print help for a prefix key.  The
+function is called when the user types a prefix key followed by the help
+character, and the help character has no binding after that prefix.  The
+variable's default value is @code{describe-prefix-bindings}.
+@end defvar
+
+@defun describe-prefix-bindings
+This function calls @code{describe-bindings} to display a list of all
+the subcommands of the prefix key of the most recent key sequence.  The
+prefix described consists of all but the last event of that key
+sequence.  (The last event is, presumably, the help character.)
+@end defun
+
+  The following two functions are meant for modes that want to provide
+help without relinquishing control, such as the ``electric'' modes.
+Their names begin with @samp{Helper} to distinguish them from the
+ordinary help functions.
+
+@deffn Command Helper-describe-bindings
+This command pops up a window displaying a help buffer containing a
+listing of all of the key bindings from both the local and global keymaps.
+It works by calling @code{describe-bindings}.
+@end deffn
+
+@deffn Command Helper-help
+This command provides help for the current mode.  It prompts the user
+in the minibuffer with the message @samp{Help (Type ? for further
+options)}, and then provides assistance in finding out what the key
+bindings are, and what the mode is intended for.  It returns @code{nil}.
+
+This can be customized by changing the map @code{Helper-help-map}.
+@end deffn
+
+@c Emacs 19 feature
+@defvar data-directory
+@anchor{Definition of data-directory}
+This variable holds the name of the directory in which Emacs finds
+certain documentation and text files that come with Emacs.  In older
+Emacs versions, @code{exec-directory} was used for this.
+@end defvar
+
+@c Emacs 19 feature
+@defmac make-help-screen fname help-line help-text help-map
+This macro defines a help command named @var{fname} that acts like a
+prefix key that shows a list of the subcommands it offers.
+
+When invoked, @var{fname} displays @var{help-text} in a window, then
+reads and executes a key sequence according to @var{help-map}.  The
+string @var{help-text} should describe the bindings available in
+@var{help-map}.
+
+The command @var{fname} is defined to handle a few events itself, by
+scrolling the display of @var{help-text}.  When @var{fname} reads one of
+those special events, it does the scrolling and then reads another
+event.  When it reads an event that is not one of those few, and which
+has a binding in @var{help-map}, it executes that key's binding and
+then returns.
+
+The argument @var{help-line} should be a single-line summary of the
+alternatives in @var{help-map}.  In the current version of Emacs, this
+argument is used only if you set the option @code{three-step-help} to
+@code{t}.
+
+This macro is used in the command @code{help-for-help} which is the
+binding of @kbd{C-h C-h}.
+@end defmac
+
+@defopt three-step-help
+If this variable is non-@code{nil}, commands defined with
+@code{make-help-screen} display their @var{help-line} strings in the
+echo area at first, and display the longer @var{help-text} strings only
+if the user types the help character again.
+@end defopt
+
+@ignore
+   arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
+@end ignore
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
new file mode 100644
index 00000000000..572d3b79d93
--- /dev/null
+++ b/doc/lispref/hooks.texi
@@ -0,0 +1,338 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/hooks
+@node Standard Hooks, Index, Standard Keymaps, Top
+@appendix Standard Hooks
+@cindex standard hooks
+@cindex hook variables, list of
+
+The following is a list of hook variables that let you provide
+functions to be called from within Emacs on suitable occasions.
+
+Most of these variables have names ending with @samp{-hook}.  They are
+@dfn{normal hooks}, run by means of @code{run-hooks}.  The value of such
+a hook is a list of functions; the functions are called with no
+arguments and their values are completely ignored.  The recommended way
+to put a new function on such a hook is to call @code{add-hook}.
+@xref{Hooks}, for more information about using hooks.
+
+Every major mode defines a mode hook named
+@samp{@var{modename}-mode-hook}.  The major mode command runs this
+normal hook with @code{run-mode-hooks} as the very last thing it does.
+@xref{Mode Hooks}.  Most minor modes have mode hooks too.  Mode hooks
+are omitted in the list below.
+
+The variables whose names end in @samp{-hooks} or @samp{-functions} are
+usually @dfn{abnormal hooks}; their values are lists of functions, but
+these functions are called in a special way (they are passed arguments,
+or their values are used). The variables whose names end in
+@samp{-function} have single functions as their values.
+
+@c We need to xref to where each hook is documented or else document
+@c it here.
+
+@table @code
+@item activate-mark-hook
+@xref{The Mark}.
+
+@item after-change-functions
+@xref{Change Hooks}.
+
+@item after-change-major-mode-hook
+@xref{Mode Hooks}.
+
+@item after-init-hook
+@xref{Init File}.
+
+@item after-insert-file-functions
+@xref{Format Conversion}.
+
+@item after-make-frame-functions
+@xref{Creating Frames}.
+
+@item after-revert-hook
+@xref{Reverting}.
+
+@item after-save-hook
+@xref{Saving Buffers}.
+
+@item auto-fill-function
+@xref{Auto Filling}.
+
+@item auto-save-hook
+@xref{Auto-Saving}.
+
+@item before-change-functions
+@xref{Change Hooks}.
+
+@item before-init-hook
+@xref{Init File}.
+
+@item before-make-frame-hook
+@xref{Creating Frames}.
+
+@item before-revert-hook
+@xref{Reverting}.
+
+@item before-save-hook
+@xref{Saving Buffers}.
+
+@item blink-paren-function
+@xref{Blinking}.
+
+@item buffer-access-fontify-functions
+@xref{Lazy Properties}.
+
+@item calendar-load-hook
+@iftex
+@inforef{Calendar Customizing,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Calendar Customizing,,, emacs}.
+@end ifnottex
+
+
+@item change-major-mode-hook
+@xref{Creating Buffer-Local}.
+
+@item command-line-functions
+@xref{Command-Line Arguments}.
+
+@item comment-indent-function
+@xref{Options for Comments,, Options Controlling Comments, emacs, the
+GNU Emacs Manual}.
+
+@item compilation-finish-functions
+Functions to call when a compilation process finishes.
+
+@item custom-define-hook
+Hook called after defining each customize option.
+
+@item deactivate-mark-hook
+@xref{The Mark}.
+
+@item desktop-after-read-hook
+Normal hook run after a successful @code{desktop-read}.  May be used
+to show a buffer list.  @xref{Saving Emacs Sessions,, Saving Emacs
+Sessions, emacs, the GNU Emacs Manual}.
+
+@item desktop-no-desktop-file-hook
+Normal hook run when @code{desktop-read} can't find a desktop file.
+May be used to show a dired buffer.  @xref{Saving Emacs Sessions,,
+Saving Emacs Sessions, emacs, the GNU Emacs Manual}.
+
+@item desktop-save-hook
+Normal hook run before the desktop is saved in a desktop file.  This
+is useful for truncating history lists, for example.  @xref{Saving
+Emacs Sessions,, Saving Emacs Sessions, emacs, the GNU Emacs Manual}.
+
+@item diary-display-hook
+@iftex
+@inforef{Fancy Diary Display,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Fancy Diary Display,,, emacs}.
+@end ifnottex
+
+@item diary-hook
+List of functions called after the display of the diary.  Can be used
+for appointment notification.
+
+@item disabled-command-function
+@xref{Disabling Commands}.
+
+@item echo-area-clear-hook
+@xref{Echo Area Customization}.
+
+@item emacs-startup-hook
+@xref{Init File}.
+
+@item find-file-hook
+@xref{Visiting Functions}.
+
+@item find-file-not-found-functions
+@xref{Visiting Functions}.
+
+@item first-change-hook
+@xref{Change Hooks}.
+
+@item font-lock-beginning-of-syntax-function
+@xref{Syntactic Font Lock}.
+
+@item font-lock-fontify-buffer-function
+@xref{Other Font Lock Variables}.
+
+@item font-lock-fontify-region-function
+@xref{Other Font Lock Variables}.
+
+@item font-lock-mark-block-function
+@xref{Other Font Lock Variables}.
+
+@item font-lock-syntactic-face-function
+@xref{Syntactic Font Lock}.
+
+@item font-lock-unfontify-buffer-function
+@xref{Other Font Lock Variables}.
+
+@item font-lock-unfontify-region-function
+@xref{Other Font Lock Variables}.
+
+@item initial-calendar-window-hook
+@iftex
+@inforef{Calendar Customizing,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Calendar Customizing,,, emacs}.
+@end ifnottex
+
+@item kbd-macro-termination-hook
+@xref{Keyboard Macros}.
+
+@item kill-buffer-hook
+@xref{Killing Buffers}.
+
+@item kill-buffer-query-functions
+@xref{Killing Buffers}.
+
+@item kill-emacs-hook
+@xref{Killing Emacs}.
+
+@item kill-emacs-query-functions
+@xref{Killing Emacs}.
+
+@item lisp-indent-function
+
+@item list-diary-entries-hook
+@iftex
+@inforef{Fancy Diary Display,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Fancy Diary Display,,, emacs}.
+@end ifnottex
+
+@item mail-setup-hook
+@xref{Mail Mode Misc,, Mail Mode Miscellany, emacs, the GNU Emacs
+Manual}.
+
+@item mark-diary-entries-hook
+@iftex
+@inforef{Fancy Diary Display,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Fancy Diary Display,,, emacs}.
+@end ifnottex
+
+@item menu-bar-update-hook
+@xref{Menu Bar}.
+
+@item minibuffer-setup-hook
+@xref{Minibuffer Misc}.
+
+@item minibuffer-exit-hook
+@xref{Minibuffer Misc}.
+
+@item mouse-position-function
+@xref{Mouse Position}.
+
+@item nongregorian-diary-listing-hook
+@iftex
+@inforef{Hebrew/Islamic Entries,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Hebrew/Islamic Entries,,, emacs}.
+@end ifnottex
+
+@item nongregorian-diary-marking-hook
+@iftex
+@inforef{Hebrew/Islamic Entries,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Hebrew/Islamic Entries,,, emacs}.
+@end ifnottex
+
+@item occur-hook
+
+@item post-command-hook
+@xref{Command Overview}.
+
+@item pre-abbrev-expand-hook
+@xref{Abbrev Expansion}.
+
+@item pre-command-hook
+@xref{Command Overview}.
+
+@item print-diary-entries-hook
+@iftex
+@inforef{Diary Customizing,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Diary Customizing,,, emacs}.
+@end ifnottex
+
+@item redisplay-end-trigger-functions
+@xref{Window Hooks}.
+
+@item scheme-indent-function
+
+@item suspend-hook
+@xref{Suspending Emacs}.
+
+@item suspend-resume-hook
+@xref{Suspending Emacs}.
+
+@item temp-buffer-setup-hook
+@xref{Temporary Displays}.
+
+@item temp-buffer-show-function
+@xref{Temporary Displays}.
+
+@item temp-buffer-show-hook
+@xref{Temporary Displays}.
+
+@item term-setup-hook
+@xref{Terminal-Specific}.
+
+@item today-visible-calendar-hook
+@iftex
+@inforef{Calendar Customizing,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Calendar Customizing,,, emacs}.
+@end ifnottex
+
+@item today-invisible-calendar-hook
+@iftex
+@inforef{Calendar Customizing,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Calendar Customizing,,, emacs}.
+@end ifnottex
+
+@item window-configuration-change-hook
+@xref{Window Hooks}.
+
+@item window-scroll-functions
+@xref{Window Hooks}.
+
+@item window-setup-hook
+@xref{Window Systems}.
+
+@item window-size-change-functions
+@xref{Window Hooks}.
+
+@item write-contents-functions
+@xref{Saving Buffers}.
+
+@item write-file-functions
+@xref{Saving Buffers}.
+
+@item write-region-annotate-functions
+@xref{Format Conversion}.
+@end table
+
+@ignore
+   arch-tag: 55fd0296-d906-4551-b300-979d3846aa88
+@end ignore
diff --git a/doc/lispref/index.texi b/doc/lispref/index.texi
new file mode 100644
index 00000000000..cfa8f25e126
--- /dev/null
+++ b/doc/lispref/index.texi
@@ -0,0 +1,29 @@
+@c -*-texinfo-*-
+@setfilename ../info/index
+
+@c Indexing guidelines
+
+@c I assume that all indexes will be combined.
+@c Therefore, if a generated findex and permutations
+@c cover the ways an index user would look up the entry,
+@c then no cindex is added.
+@c Concept index (cindex) entries will also be permuted.  Therefore, they
+@c have no commas and few irrelevant connectives in them.
+
+@c I tried to include words in a cindex that give the context of the entry,
+@c particularly if there is more than one entry for the same concept.
+@c For example, "nil in keymap"
+@c Similarly for explicit findex and vindex entries, e.g. "print example".
+
+@c Error codes are given cindex entries, e.g. "end-of-file error".
+
+@c pindex is used for .el files and Unix programs
+
+@node Index, , Standard Hooks, Top
+@unnumbered Index
+
+@c Print the indices
+
+@printindex fn
+
+
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
new file mode 100644
index 00000000000..3cd42ed69ff
--- /dev/null
+++ b/doc/lispref/internals.texi
@@ -0,0 +1,1522 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2001, 2002, 2003,
+@c   2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/internals
+@node GNU Emacs Internals, Standard Errors, Tips, Top
+@comment  node-name,  next,  previous,  up
+@appendix GNU Emacs Internals
+
+This chapter describes how the runnable Emacs executable is dumped with
+the preloaded Lisp libraries in it, how storage is allocated, and some
+internal aspects of GNU Emacs that may be of interest to C programmers.
+
+@menu
+* Building Emacs::      How the dumped Emacs is made.
+* Pure Storage::        A kludge to make preloaded Lisp functions sharable.
+* Garbage Collection::  Reclaiming space for Lisp objects no longer used.
+* Memory Usage::        Info about total size of Lisp objects made so far.
+* Writing Emacs Primitives::   Writing C code for Emacs.
+* Object Internals::    Data formats of buffers, windows, processes.
+@end menu
+
+@node Building Emacs
+@appendixsec Building Emacs
+@cindex building Emacs
+@pindex temacs
+
+  This section explains the steps involved in building the Emacs
+executable.  You don't have to know this material to build and install
+Emacs, since the makefiles do all these things automatically.  This
+information is pertinent to Emacs maintenance.
+
+   Compilation of the C source files in the @file{src} directory
+produces an executable file called @file{temacs}, also called a
+@dfn{bare impure Emacs}.  It contains the Emacs Lisp interpreter and I/O
+routines, but not the editing commands.
+
+@cindex @file{loadup.el}
+  The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
+the real runnable Emacs executable.  These arguments direct
+@file{temacs} to evaluate the Lisp files specified in the file
+@file{loadup.el}.  These files set up the normal Emacs editing
+environment, resulting in an Emacs that is still impure but no longer
+bare.
+
+@cindex dumping Emacs
+  It takes a substantial time to load the standard Lisp files.  Luckily,
+you don't have to do this each time you run Emacs; @file{temacs} can
+dump out an executable program called @file{emacs} that has these files
+preloaded.  @file{emacs} starts more quickly because it does not need to
+load the files.  This is the Emacs executable that is normally
+installed.
+
+  To create @file{emacs}, use the command @samp{temacs -batch -l loadup
+dump}.  The purpose of @samp{-batch} here is to prevent @file{temacs}
+from trying to initialize any of its data on the terminal; this ensures
+that the tables of terminal information are empty in the dumped Emacs.
+The argument @samp{dump} tells @file{loadup.el} to dump a new executable
+named @file{emacs}.
+
+  Some operating systems don't support dumping.  On those systems, you
+must start Emacs with the @samp{temacs -l loadup} command each time you
+use it.  This takes a substantial time, but since you need to start
+Emacs once a day at most---or once a week if you never log out---the
+extra time is not too severe a problem.
+
+@cindex @file{site-load.el}
+
+  You can specify additional files to preload by writing a library named
+@file{site-load.el} that loads them.  You may need to add a definition
+
+@example
+#define SITELOAD_PURESIZE_EXTRA @var{n}
+@end example
+
+@noindent
+to make @var{n} added bytes of pure space to hold the additional files.
+(Try adding increments of 20000 until it is big enough.)  However, the
+advantage of preloading additional files decreases as machines get
+faster.  On modern machines, it is usually not advisable.
+
+  After @file{loadup.el} reads @file{site-load.el}, it finds the
+documentation strings for primitive and preloaded functions (and
+variables) in the file @file{etc/DOC} where they are stored, by
+calling @code{Snarf-documentation} (@pxref{Definition of
+Snarf-documentation,, Accessing Documentation}).
+
+@cindex @file{site-init.el}
+@cindex preloading additional functions and variables
+  You can specify other Lisp expressions to execute just before dumping
+by putting them in a library named @file{site-init.el}.  This file is
+executed after the documentation strings are found.
+
+  If you want to preload function or variable definitions, there are
+three ways you can do this and make their documentation strings
+accessible when you subsequently run Emacs:
+
+@itemize @bullet
+@item
+Arrange to scan these files when producing the @file{etc/DOC} file,
+and load them with @file{site-load.el}.
+
+@item
+Load the files with @file{site-init.el}, then copy the files into the
+installation directory for Lisp files when you install Emacs.
+
+@item
+Specify a non-@code{nil} value for
+@code{byte-compile-dynamic-docstrings} as a local variable in each of these
+files, and load them with either @file{site-load.el} or
+@file{site-init.el}.  (This method has the drawback that the
+documentation strings take up space in Emacs all the time.)
+@end itemize
+
+  It is not advisable to put anything in @file{site-load.el} or
+@file{site-init.el} that would alter any of the features that users
+expect in an ordinary unmodified Emacs.  If you feel you must override
+normal features for your site, do it with @file{default.el}, so that
+users can override your changes if they wish.  @xref{Startup Summary}.
+
+  In a package that can be preloaded, it is sometimes useful to
+specify a computation to be done when Emacs subsequently starts up.
+For this, use @code{eval-at-startup}:
+
+@defmac eval-at-startup body@dots{}
+This evaluates the @var{body} forms, either immediately if running in
+an Emacs that has already started up, or later when Emacs does start
+up.  Since the value of the @var{body} forms is not necessarily
+available when the @code{eval-at-startup} form is run, that form
+always returns @code{nil}.
+@end defmac
+
+@defun dump-emacs to-file from-file
+@cindex unexec
+This function dumps the current state of Emacs into an executable file
+@var{to-file}.  It takes symbols from @var{from-file} (this is normally
+the executable file @file{temacs}).
+
+If you want to use this function in an Emacs that was already dumped,
+you must run Emacs with @samp{-batch}.
+@end defun
+
+@node Pure Storage
+@appendixsec Pure Storage
+@cindex pure storage
+
+  Emacs Lisp uses two kinds of storage for user-created Lisp objects:
+@dfn{normal storage} and @dfn{pure storage}.  Normal storage is where
+all the new data created during an Emacs session are kept; see the
+following section for information on normal storage.  Pure storage is
+used for certain data in the preloaded standard Lisp files---data that
+should never change during actual use of Emacs.
+
+  Pure storage is allocated only while @file{temacs} is loading the
+standard preloaded Lisp libraries.  In the file @file{emacs}, it is
+marked as read-only (on operating systems that permit this), so that
+the memory space can be shared by all the Emacs jobs running on the
+machine at once.  Pure storage is not expandable; a fixed amount is
+allocated when Emacs is compiled, and if that is not sufficient for
+the preloaded libraries, @file{temacs} allocates dynamic memory for
+the part that didn't fit.  If that happens, you should increase the
+compilation parameter @code{PURESIZE} in the file
+@file{src/puresize.h} and rebuild Emacs, even though the resulting
+image will work: garbage collection is disabled in this situation,
+causing a memory leak.  Such an overflow normally won't happen unless you
+try to preload additional libraries or add features to the standard
+ones.  Emacs will display a warning about the overflow when it
+starts.
+
+@defun purecopy object
+This function makes a copy in pure storage of @var{object}, and returns
+it.  It copies a string by simply making a new string with the same
+characters, but without text properties, in pure storage.  It
+recursively copies the contents of vectors and cons cells.  It does
+not make copies of other objects such as symbols, but just returns
+them unchanged.  It signals an error if asked to copy markers.
+
+This function is a no-op except while Emacs is being built and dumped;
+it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
+a few packages call it just in case you decide to preload them.
+@end defun
+
+@defvar pure-bytes-used
+The value of this variable is the number of bytes of pure storage
+allocated so far.  Typically, in a dumped Emacs, this number is very
+close to the total amount of pure storage available---if it were not,
+we would preallocate less.
+@end defvar
+
+@defvar purify-flag
+This variable determines whether @code{defun} should make a copy of the
+function definition in pure storage.  If it is non-@code{nil}, then the
+function definition is copied into pure storage.
+
+This flag is @code{t} while loading all of the basic functions for
+building Emacs initially (allowing those functions to be sharable and
+non-collectible).  Dumping Emacs as an executable always writes
+@code{nil} in this variable, regardless of the value it actually has
+before and after dumping.
+
+You should not change this flag in a running Emacs.
+@end defvar
+
+@node Garbage Collection
+@appendixsec Garbage Collection
+@cindex garbage collection
+
+@cindex memory allocation
+  When a program creates a list or the user defines a new function (such
+as by loading a library), that data is placed in normal storage.  If
+normal storage runs low, then Emacs asks the operating system to
+allocate more memory in blocks of 1k bytes.  Each block is used for one
+type of Lisp object, so symbols, cons cells, markers, etc., are
+segregated in distinct blocks in memory.  (Vectors, long strings,
+buffers and certain other editing types, which are fairly large, are
+allocated in individual blocks, one per object, while small strings are
+packed into blocks of 8k bytes.)
+
+  It is quite common to use some storage for a while, then release it by
+(for example) killing a buffer or deleting the last pointer to an
+object.  Emacs provides a @dfn{garbage collector} to reclaim this
+abandoned storage.  (This name is traditional, but ``garbage recycler''
+might be a more intuitive metaphor for this facility.)
+
+  The garbage collector operates by finding and marking all Lisp objects
+that are still accessible to Lisp programs.  To begin with, it assumes
+all the symbols, their values and associated function definitions, and
+any data presently on the stack, are accessible.  Any objects that can
+be reached indirectly through other accessible objects are also
+accessible.
+
+  When marking is finished, all objects still unmarked are garbage.  No
+matter what the Lisp program or the user does, it is impossible to refer
+to them, since there is no longer a way to reach them.  Their space
+might as well be reused, since no one will miss them.  The second
+(``sweep'') phase of the garbage collector arranges to reuse them.
+
+@c ??? Maybe add something describing weak hash tables here?
+
+@cindex free list
+  The sweep phase puts unused cons cells onto a @dfn{free list}
+for future allocation; likewise for symbols and markers.  It compacts
+the accessible strings so they occupy fewer 8k blocks; then it frees the
+other 8k blocks.  Vectors, buffers, windows, and other large objects are
+individually allocated and freed using @code{malloc} and @code{free}.
+
+@cindex CL note---allocate more storage
+@quotation
+@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not
+call the garbage collector when the free list is empty.  Instead, it
+simply requests the operating system to allocate more storage, and
+processing continues until @code{gc-cons-threshold} bytes have been
+used.
+
+This means that you can make sure that the garbage collector will not
+run during a certain portion of a Lisp program by calling the garbage
+collector explicitly just before it (provided that portion of the
+program does not use so much space as to force a second garbage
+collection).
+@end quotation
+
+@deffn Command garbage-collect
+This command runs a garbage collection, and returns information on
+the amount of space in use.  (Garbage collection can also occur
+spontaneously if you use more than @code{gc-cons-threshold} bytes of
+Lisp data since the previous garbage collection.)
+
+@code{garbage-collect} returns a list containing the following
+information:
+
+@example
+@group
+((@var{used-conses} . @var{free-conses})
+ (@var{used-syms} . @var{free-syms})
+@end group
+ (@var{used-miscs} . @var{free-miscs})
+ @var{used-string-chars}
+ @var{used-vector-slots}
+ (@var{used-floats} . @var{free-floats})
+ (@var{used-intervals} . @var{free-intervals})
+ (@var{used-strings} . @var{free-strings}))
+@end example
+
+Here is an example:
+
+@example
+@group
+(garbage-collect)
+     @result{} ((106886 . 13184) (9769 . 0)
+                (7731 . 4651) 347543 121628
+                (31 . 94) (1273 . 168)
+                (25474 . 3569))
+@end group
+@end example
+
+Here is a table explaining each element:
+
+@table @var
+@item used-conses
+The number of cons cells in use.
+
+@item free-conses
+The number of cons cells for which space has been obtained from the
+operating system, but that are not currently being used.
+
+@item used-syms
+The number of symbols in use.
+
+@item free-syms
+The number of symbols for which space has been obtained from the
+operating system, but that are not currently being used.
+
+@item used-miscs
+The number of miscellaneous objects in use.  These include markers and
+overlays, plus certain objects not visible to users.
+
+@item free-miscs
+The number of miscellaneous objects for which space has been obtained
+from the operating system, but that are not currently being used.
+
+@item used-string-chars
+The total size of all strings, in characters.
+
+@item used-vector-slots
+The total number of elements of existing vectors.
+
+@item used-floats
+@c Emacs 19 feature
+The number of floats in use.
+
+@item free-floats
+@c Emacs 19 feature
+The number of floats for which space has been obtained from the
+operating system, but that are not currently being used.
+
+@item used-intervals
+The number of intervals in use.  Intervals are an internal
+data structure used for representing text properties.
+
+@item free-intervals
+The number of intervals for which space has been obtained
+from the operating system, but that are not currently being used.
+
+@item used-strings
+The number of strings in use.
+
+@item free-strings
+The number of string headers for which the space was obtained from the
+operating system, but which are currently not in use.  (A string
+object consists of a header and the storage for the string text
+itself; the latter is only allocated when the string is created.)
+@end table
+
+If there was overflow in pure space (see the previous section),
+@code{garbage-collect} returns @code{nil}, because a real garbage
+collection can not be done in this situation.
+@end deffn
+
+@defopt garbage-collection-messages
+If this variable is non-@code{nil}, Emacs displays a message at the
+beginning and end of garbage collection.  The default value is
+@code{nil}, meaning there are no such messages.
+@end defopt
+
+@defvar post-gc-hook
+This is a normal hook that is run at the end of garbage collection.
+Garbage collection is inhibited while the hook functions run, so be
+careful writing them.
+@end defvar
+
+@defopt gc-cons-threshold
+The value of this variable is the number of bytes of storage that must
+be allocated for Lisp objects after one garbage collection in order to
+trigger another garbage collection.  A cons cell counts as eight bytes,
+a string as one byte per character plus a few bytes of overhead, and so
+on; space allocated to the contents of buffers does not count.  Note
+that the subsequent garbage collection does not happen immediately when
+the threshold is exhausted, but only the next time the Lisp evaluator is
+called.
+
+The initial threshold value is 400,000.  If you specify a larger
+value, garbage collection will happen less often.  This reduces the
+amount of time spent garbage collecting, but increases total memory use.
+You may want to do this when running a program that creates lots of
+Lisp data.
+
+You can make collections more frequent by specifying a smaller value,
+down to 10,000.  A value less than 10,000 will remain in effect only
+until the subsequent garbage collection, at which time
+@code{garbage-collect} will set the threshold back to 10,000.
+@end defopt
+
+@defopt gc-cons-percentage
+The value of this variable specifies the amount of consing before a
+garbage collection occurs, as a fraction of the current heap size.
+This criterion and @code{gc-cons-threshold} apply in parallel, and
+garbage collection occurs only when both criteria are satisfied.
+
+As the heap size increases, the time to perform a garbage collection
+increases.  Thus, it can be desirable to do them less frequently in
+proportion.
+@end defopt
+
+  The value returned by @code{garbage-collect} describes the amount of
+memory used by Lisp data, broken down by data type.  By contrast, the
+function @code{memory-limit} provides information on the total amount of
+memory Emacs is currently using.
+
+@c Emacs 19 feature
+@defun memory-limit
+This function returns the address of the last byte Emacs has allocated,
+divided by 1024.  We divide the value by 1024 to make sure it fits in a
+Lisp integer.
+
+You can use this to get a general idea of how your actions affect the
+memory usage.
+@end defun
+
+@defvar memory-full
+This variable is @code{t} if Emacs is close to out of memory for Lisp
+objects, and @code{nil} otherwise.
+@end defvar
+
+@defun memory-use-counts
+This returns a list of numbers that count the number of objects
+created in this Emacs session.  Each of these counters increments for
+a certain kind of object.  See the documentation string for details.
+@end defun
+
+@defvar gcs-done
+This variable contains the total number of garbage collections
+done so far in this Emacs session.
+@end defvar
+
+@defvar gc-elapsed
+This variable contains the total number of seconds of elapsed time
+during garbage collection so far in this Emacs session, as a floating
+point number.
+@end defvar
+
+@node Memory Usage
+@section Memory Usage
+@cindex memory usage
+
+  These functions and variables give information about the total amount
+of memory allocation that Emacs has done, broken down by data type.
+Note the difference between these and the values returned by
+@code{(garbage-collect)}; those count objects that currently exist, but
+these count the number or size of all allocations, including those for
+objects that have since been freed.
+
+@defvar cons-cells-consed
+The total number of cons cells that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar floats-consed
+The total number of floats that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar vector-cells-consed
+The total number of vector cells that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar symbols-consed
+The total number of symbols that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar string-chars-consed
+The total number of string characters that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar misc-objects-consed
+The total number of miscellaneous objects that have been allocated so
+far in this Emacs session.  These include markers and overlays, plus
+certain objects not visible to users.
+@end defvar
+
+@defvar intervals-consed
+The total number of intervals that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar strings-consed
+The total number of strings that have been allocated so far in this
+Emacs session.
+@end defvar
+
+@node Writing Emacs Primitives
+@appendixsec Writing Emacs Primitives
+@cindex primitive function internals
+@cindex writing Emacs primitives
+
+  Lisp primitives are Lisp functions implemented in C.  The details of
+interfacing the C function so that Lisp can call it are handled by a few
+C macros.  The only way to really understand how to write new C code is
+to read the source, but we can explain some things here.
+
+  An example of a special form is the definition of @code{or}, from
+@file{eval.c}.  (An ordinary function would have the same general
+appearance.)
+
+@cindex garbage collection protection
+@smallexample
+@group
+DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
+  doc: /* Eval args until one of them yields non-nil, then return that
+value. The remaining args are not evalled at all.
+If all args return nil, return nil.
+@end group
+@group
+usage: (or CONDITIONS ...)  */)
+  (args)
+     Lisp_Object args;
+@{
+  register Lisp_Object val = Qnil;
+  struct gcpro gcpro1;
+@end group
+
+@group
+  GCPRO1 (args);
+@end group
+
+@group
+  while (CONSP (args))
+    @{
+      val = Feval (XCAR (args));
+      if (!NILP (val))
+        break;
+      args = XCDR (args);
+    @}
+@end group
+
+@group
+  UNGCPRO;
+  return val;
+@}
+@end group
+@end smallexample
+
+@cindex @code{DEFUN}, C macro to define Lisp primitives
+  Let's start with a precise explanation of the arguments to the
+@code{DEFUN} macro.  Here is a template for them:
+
+@example
+DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc})
+@end example
+
+@table @var
+@item lname
+This is the name of the Lisp symbol to define as the function name; in
+the example above, it is @code{or}.
+
+@item fname
+This is the C function name for this function.  This is
+the name that is used in C code for calling the function.  The name is,
+by convention, @samp{F} prepended to the Lisp name, with all dashes
+(@samp{-}) in the Lisp name changed to underscores.  Thus, to call this
+function from C code, call @code{For}.  Remember that the arguments must
+be of type @code{Lisp_Object}; various macros and functions for creating
+values of type @code{Lisp_Object} are declared in the file
+@file{lisp.h}.
+
+@item sname
+This is a C variable name to use for a structure that holds the data for
+the subr object that represents the function in Lisp.  This structure
+conveys the Lisp symbol name to the initialization routine that will
+create the symbol and store the subr object as its definition.  By
+convention, this name is always @var{fname} with @samp{F} replaced with
+@samp{S}.
+
+@item min
+This is the minimum number of arguments that the function requires.  The
+function @code{or} allows a minimum of zero arguments.
+
+@item max
+This is the maximum number of arguments that the function accepts, if
+there is a fixed maximum.  Alternatively, it can be @code{UNEVALLED},
+indicating a special form that receives unevaluated arguments, or
+@code{MANY}, indicating an unlimited number of evaluated arguments (the
+equivalent of @code{&rest}).  Both @code{UNEVALLED} and @code{MANY} are
+macros.  If @var{max} is a number, it may not be less than @var{min} and
+it may not be greater than eight.
+
+@item interactive
+This is an interactive specification, a string such as might be used as
+the argument of @code{interactive} in a Lisp function.  In the case of
+@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be
+called interactively.  A value of @code{""} indicates a function that
+should receive no arguments when called interactively.
+
+@item doc
+This is the documentation string.  It uses C comment syntax rather
+than C string syntax because comment syntax requires nothing special
+to include multiple lines.  The @samp{doc:} identifies the comment
+that follows as the documentation string.  The @samp{/*} and @samp{*/}
+delimiters that begin and end the comment are not part of the
+documentation string.
+
+If the last line of the documentation string begins with the keyword
+@samp{usage:}, the rest of the line is treated as the argument list
+for documentation purposes.  This way, you can use different argument
+names in the documentation string from the ones used in the C code.
+@samp{usage:} is required if the function has an unlimited number of
+arguments.
+
+All the usual rules for documentation strings in Lisp code
+(@pxref{Documentation Tips}) apply to C code documentation strings
+too.
+@end table
+
+  After the call to the @code{DEFUN} macro, you must write the argument
+name list that every C function must have, followed by ordinary C
+declarations for the arguments.  For a function with a fixed maximum
+number of arguments, declare a C argument for each Lisp argument, and
+give them all type @code{Lisp_Object}.  When a Lisp function has no
+upper limit on the number of arguments, its implementation in C actually
+receives exactly two arguments: the first is the number of Lisp
+arguments, and the second is the address of a block containing their
+values.  They have types @code{int} and @w{@code{Lisp_Object *}}.
+
+@cindex @code{GCPRO} and @code{UNGCPRO}
+@cindex protect C variables from garbage collection
+  Within the function @code{For} itself, note the use of the macros
+@code{GCPRO1} and @code{UNGCPRO}.  @code{GCPRO1} is used to
+``protect'' a variable from garbage collection---to inform the garbage
+collector that it must look in that variable and regard its contents
+as an accessible object.  GC protection is necessary whenever you call
+@code{Feval} or anything that can directly or indirectly call
+@code{Feval}.  At such a time, any Lisp object that this function may
+refer to again must be protected somehow.
+
+  It suffices to ensure that at least one pointer to each object is
+GC-protected; that way, the object cannot be recycled, so all pointers
+to it remain valid.  Thus, a particular local variable can do without
+protection if it is certain that the object it points to will be
+preserved by some other pointer (such as another local variable which
+has a @code{GCPRO})@footnote{Formerly, strings were a special
+exception; in older Emacs versions, every local variable that might
+point to a string needed a @code{GCPRO}.}.  Otherwise, the local
+variable needs a @code{GCPRO}.
+
+  The macro @code{GCPRO1} protects just one local variable.  If you
+want to protect two variables, use @code{GCPRO2} instead; repeating
+@code{GCPRO1} will not work.  Macros @code{GCPRO3}, @code{GCPRO4},
+@code{GCPRO5}, and @code{GCPRO6} also exist.  All these macros
+implicitly use local variables such as @code{gcpro1}; you must declare
+these explicitly, with type @code{struct gcpro}.  Thus, if you use
+@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
+Alas, we can't explain all the tricky details here.
+
+  @code{UNGCPRO} cancels the protection of the variables that are
+protected in the current function.  It is necessary to do this
+explicitly.
+
+  Built-in functions that take a variable number of arguments actually
+accept two arguments at the C level: the number of Lisp arguments, and
+a @code{Lisp_Object *} pointer to a C vector containing those Lisp
+arguments.  This C vector may be part of a Lisp vector, but it need
+not be.  The responsibility for using @code{GCPRO} to protect the Lisp
+arguments from GC if necessary rests with the caller in this case,
+since the caller allocated or found the storage for them.
+
+  You must not use C initializers for static or global variables unless
+the variables are never written once Emacs is dumped.  These variables
+with initializers are allocated in an area of memory that becomes
+read-only (on certain operating systems) as a result of dumping Emacs.
+@xref{Pure Storage}.
+
+  Do not use static variables within functions---place all static
+variables at top level in the file.  This is necessary because Emacs on
+some operating systems defines the keyword @code{static} as a null
+macro.  (This definition is used because those systems put all variables
+declared static in a place that becomes read-only after dumping, whether
+they have initializers or not.)
+
+@cindex @code{defsubr}, Lisp symbol for a primitive
+  Defining the C function is not enough to make a Lisp primitive
+available; you must also create the Lisp symbol for the primitive and
+store a suitable subr object in its function cell.  The code looks like
+this:
+
+@example
+defsubr (&@var{subr-structure-name});
+@end example
+
+@noindent
+Here @var{subr-structure-name} is the name you used as the third
+argument to @code{DEFUN}.
+
+  If you add a new primitive to a file that already has Lisp primitives
+defined in it, find the function (near the end of the file) named
+@code{syms_of_@var{something}}, and add the call to @code{defsubr}
+there.  If the file doesn't have this function, or if you create a new
+file, add to it a @code{syms_of_@var{filename}} (e.g.,
+@code{syms_of_myfile}).  Then find the spot in @file{emacs.c} where all
+of these functions are called, and add a call to
+@code{syms_of_@var{filename}} there.
+
+@anchor{Defining Lisp variables in C}
+@vindex byte-boolean-vars
+@cindex defining Lisp variables in C
+@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}
+  The function @code{syms_of_@var{filename}} is also the place to define
+any C variables that are to be visible as Lisp variables.
+@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
+in Lisp.  @code{DEFVAR_INT} makes a C variable of type @code{int}
+visible in Lisp with a value that is always an integer.
+@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
+with a value that is either @code{t} or @code{nil}.  Note that variables
+defined with @code{DEFVAR_BOOL} are automatically added to the list
+@code{byte-boolean-vars} used by the byte compiler.
+
+@cindex @code{staticpro}, protection from GC
+  If you define a file-scope C variable of type @code{Lisp_Object},
+you must protect it from garbage-collection by calling @code{staticpro}
+in @code{syms_of_@var{filename}}, like this:
+
+@example
+staticpro (&@var{variable});
+@end example
+
+  Here is another example function, with more complicated arguments.
+This comes from the code in @file{window.c}, and it demonstrates the use
+of macros and functions to manipulate Lisp objects.
+
+@smallexample
+@group
+DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
+  Scoordinates_in_window_p, 2, 2,
+  "xSpecify coordinate pair: \nXExpression which evals to window: ",
+  "Return non-nil if COORDINATES is in WINDOW.\n\
+COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
+...
+@end group
+@group
+If they are on the border between WINDOW and its right sibling,\n\
+   `vertical-line' is returned.")
+  (coordinates, window)
+     register Lisp_Object coordinates, window;
+@{
+  int x, y;
+@end group
+
+@group
+  CHECK_LIVE_WINDOW (window, 0);
+  CHECK_CONS (coordinates, 1);
+  x = XINT (Fcar (coordinates));
+  y = XINT (Fcdr (coordinates));
+@end group
+
+@group
+  switch (coordinates_in_window (XWINDOW (window), &x, &y))
+    @{
+    case 0:			/* NOT in window at all. */
+      return Qnil;
+@end group
+
+@group
+    case 1:			/* In text part of window. */
+      return Fcons (make_number (x), make_number (y));
+@end group
+
+@group
+    case 2:			/* In mode line of window. */
+      return Qmode_line;
+@end group
+
+@group
+    case 3:			/* On right border of window.  */
+      return Qvertical_line;
+@end group
+
+@group
+    default:
+      abort ();
+    @}
+@}
+@end group
+@end smallexample
+
+  Note that C code cannot call functions by name unless they are defined
+in C.  The way to call a function written in Lisp is to use
+@code{Ffuncall}, which embodies the Lisp function @code{funcall}.  Since
+the Lisp function @code{funcall} accepts an unlimited number of
+arguments, in C it takes two: the number of Lisp-level arguments, and a
+one-dimensional array containing their values.  The first Lisp-level
+argument is the Lisp function to call, and the rest are the arguments to
+pass to it.  Since @code{Ffuncall} can call the evaluator, you must
+protect pointers from garbage collection around the call to
+@code{Ffuncall}.
+
+  The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
+provide handy ways to call a Lisp function conveniently with a fixed
+number of arguments.  They work by calling @code{Ffuncall}.
+
+  @file{eval.c} is a very good file to look through for examples;
+@file{lisp.h} contains the definitions for some important macros and
+functions.
+
+  If you define a function which is side-effect free, update the code
+in @file{byte-opt.el} which binds @code{side-effect-free-fns} and
+@code{side-effect-and-error-free-fns} so that the compiler optimizer
+knows about it.
+
+@node Object Internals
+@appendixsec Object Internals
+@cindex object internals
+
+  GNU Emacs Lisp manipulates many different types of data.  The actual
+data are stored in a heap and the only access that programs have to it
+is through pointers.  Pointers are thirty-two bits wide in most
+implementations.  Depending on the operating system and type of machine
+for which you compile Emacs, twenty-nine bits are used to address the
+object, and the remaining three bits are used for the tag that
+identifies the object's type.
+
+  Because Lisp objects are represented as tagged pointers, it is always
+possible to determine the Lisp data type of any object.  The C data type
+@code{Lisp_Object} can hold any Lisp object of any data type.  Ordinary
+variables have type @code{Lisp_Object}, which means they can hold any
+type of Lisp value; you can determine the actual data type only at run
+time.  The same is true for function arguments; if you want a function
+to accept only a certain type of argument, you must check the type
+explicitly using a suitable predicate (@pxref{Type Predicates}).
+@cindex type checking internals
+
+@menu
+* Buffer Internals::    Components of a buffer structure.
+* Window Internals::    Components of a window structure.
+* Process Internals::   Components of a process structure.
+@end menu
+
+@node Buffer Internals
+@appendixsubsec Buffer Internals
+@cindex internals, of buffer
+@cindex buffer internals
+
+  Buffers contain fields not directly accessible by the Lisp programmer.
+We describe them here, naming them by the names used in the C code.
+Many are accessible indirectly in Lisp programs via Lisp primitives.
+
+Two structures are used to represent buffers in C.  The
+@code{buffer_text} structure contains fields describing the text of a
+buffer; the @code{buffer} structure holds other fields.  In the case
+of indirect buffers, two or more @code{buffer} structures reference
+the same @code{buffer_text} structure.
+
+Here is a list of the @code{struct buffer_text} fields:
+
+@table @code
+@item beg
+This field contains the actual address of the buffer contents.
+
+@item gpt
+This holds the character position of the gap in the buffer.
+@xref{Buffer Gap}.
+
+@item z
+This field contains the character position of the end of the buffer
+text.
+
+@item gpt_byte
+Contains the byte position of the gap.
+
+@item z_byte
+Holds the byte position of the end of the buffer text.
+
+@item gap_size
+Contains the size of buffer's gap.  @xref{Buffer Gap}.
+
+@item modiff
+This field counts buffer-modification events for this buffer.  It is
+incremented for each such event, and never otherwise changed.
+
+@item save_modiff
+Contains the previous value of @code{modiff}, as of the last time a
+buffer was visited or saved in a file.
+
+@item overlay_modiff
+Counts modifications to overlays analogous to @code{modiff}.
+
+@item beg_unchanged
+Holds the number of characters at the start of the text that are known
+to be unchanged since the last redisplay that finished.
+
+@item end_unchanged
+Holds the number of characters at the end of the text that are known to
+be unchanged since the last redisplay that finished.
+
+@item unchanged_modified
+Contains the value of @code{modiff} at the time of the last redisplay
+that finished.  If this value matches @code{modiff},
+@code{beg_unchanged} and @code{end_unchanged} contain no useful
+information.
+
+@item overlay_unchanged_modified
+Contains the value of @code{overlay_modiff} at the time of the last
+redisplay that finished.  If this value matches @code{overlay_modiff},
+@code{beg_unchanged} and @code{end_unchanged} contain no useful
+information.
+
+@item markers
+The markers that refer to this buffer.  This is actually a single
+marker, and successive elements in its marker @code{chain} are the other
+markers referring to this buffer text.
+
+@item intervals
+Contains the interval tree which records the text properties of this
+buffer.
+@end table
+
+The fields of @code{struct buffer} are:
+
+@table @code
+@item next
+Points to the next buffer, in the chain of all buffers including killed
+buffers.  This chain is used only for garbage collection, in order to
+collect killed buffers properly.  Note that vectors, and most kinds of
+objects allocated as vectors, are all on one chain, but buffers are on a
+separate chain of their own.
+
+@item own_text
+This is a @code{struct buffer_text} structure.  In an ordinary buffer,
+it holds the buffer contents.  In indirect buffers, this field is not
+used.
+
+@item text
+This points to the @code{buffer_text} structure that is used for this
+buffer.  In an ordinary buffer, this is the @code{own_text} field above.
+In an indirect buffer, this is the @code{own_text} field of the base
+buffer.
+
+@item pt
+Contains the character position of point in a buffer.
+
+@item pt_byte
+Contains the byte position of point in a buffer.
+
+@item begv
+This field contains the character position of the beginning of the
+accessible range of text in the buffer.
+
+@item begv_byte
+This field contains the byte position of the beginning of the
+accessible range of text in the buffer.
+
+@item zv
+This field contains the character position of the end of the
+accessible range of text in the buffer.
+
+@item zv_byte
+This field contains the byte position of the end of the
+accessible range of text in the buffer.
+
+@item base_buffer
+In an indirect buffer, this points to the base buffer.  In an ordinary
+buffer, it is null.
+
+@item local_var_flags
+This field contains flags indicating that certain variables are local in
+this buffer.  Such variables are declared in the C code using
+@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored in
+fields in the buffer structure itself.  (Some of these fields are
+described in this table.)
+
+@item modtime
+This field contains the modification time of the visited file.  It is
+set when the file is written or read.  Before writing the buffer into a
+file, this field is compared to the modification time of the file to see
+if the file has changed on disk.  @xref{Buffer Modification}.
+
+@item auto_save_modified
+This field contains the time when the buffer was last auto-saved.
+
+@item auto_save_failure_time
+The time at which we detected a failure to auto-save, or -1 if we didn't
+have a failure.
+
+@item last_window_start
+This field contains the @code{window-start} position in the buffer as of
+the last time the buffer was displayed in a window.
+
+@item clip_changed
+This flag is set when narrowing changes in a buffer.
+
+@item prevent_redisplay_optimizations_p
+this flag indicates that redisplay optimizations should not be used
+to display this buffer.
+
+@item undo_list
+This field points to the buffer's undo list.  @xref{Undo}.
+
+@item name
+The buffer name is a string that names the buffer.  It is guaranteed to
+be unique.  @xref{Buffer Names}.
+
+@item filename
+The name of the file visited in this buffer, or @code{nil}.
+
+@item directory
+The directory for expanding relative file names.
+
+@item save_length
+Length of the file this buffer is visiting, when last read or saved.
+This and other fields concerned with saving are not kept in the
+@code{buffer_text} structure because indirect buffers are never saved.
+
+@item auto_save_file_name
+File name used for auto-saving this buffer.  This is not in the
+@code{buffer_text} because it's not used in indirect buffers at all.
+
+@item read_only
+Non-@code{nil} means this buffer is read-only.
+
+@item mark
+This field contains the mark for the buffer.  The mark is a marker,
+hence it is also included on the list @code{markers}.  @xref{The Mark}.
+
+@item local_var_alist
+This field contains the association list describing the buffer-local
+variable bindings of this buffer, not including the built-in
+buffer-local bindings that have special slots in the buffer object.
+(Those slots are omitted from this table.)  @xref{Buffer-Local
+Variables}.
+
+@item major_mode
+Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}.
+
+@item mode_name
+Pretty name of major mode, e.g., @code{"Lisp"}.
+
+@item mode_line_format
+Mode line element that controls the format of the mode line.  If this
+is @code{nil}, no mode line will be displayed.
+
+@item header_line_format
+This field is analogous to @code{mode_line_format} for the mode
+line displayed at the top of windows.
+
+@item keymap
+This field holds the buffer's local keymap.  @xref{Keymaps}.
+
+@item abbrev_table
+This buffer's local abbrevs.
+
+@item syntax_table
+This field contains the syntax table for the buffer.  @xref{Syntax Tables}.
+
+@item category_table
+This field contains the category table for the buffer.
+
+@item case_fold_search
+The value of @code{case-fold-search} in this buffer.
+
+@item tab_width
+The value of @code{tab-width} in this buffer.
+
+@item fill_column
+The value of @code{fill-column} in this buffer.
+
+@item left_margin
+The value of @code{left-margin} in this buffer.
+
+@item auto_fill_function
+The value of @code{auto-fill-function} in this buffer.
+
+@item downcase_table
+This field contains the conversion table for converting text to lower case.
+@xref{Case Tables}.
+
+@item upcase_table
+This field contains the conversion table for converting text to upper case.
+@xref{Case Tables}.
+
+@item case_canon_table
+This field contains the conversion table for canonicalizing text for
+case-folding search.  @xref{Case Tables}.
+
+@item case_eqv_table
+This field contains the equivalence table for case-folding search.
+@xref{Case Tables}.
+
+@item truncate_lines
+The value of @code{truncate-lines} in this buffer.
+
+@item ctl_arrow
+The value of @code{ctl-arrow} in this buffer.
+
+@item selective_display
+The value of @code{selective-display} in this buffer.
+
+@item selective_display_ellipsis
+The value of @code{selective-display-ellipsis} in this buffer.
+
+@item minor_modes
+An alist of the minor modes of this buffer.
+
+@item overwrite_mode
+The value of @code{overwrite_mode} in this buffer.
+
+@item abbrev_mode
+The value of @code{abbrev-mode} in this buffer.
+
+@item display_table
+This field contains the buffer's display table, or @code{nil} if it doesn't
+have one.  @xref{Display Tables}.
+
+@item save_modified
+This field contains the time when the buffer was last saved, as an integer.
+@xref{Buffer Modification}.
+
+@item mark_active
+This field is non-@code{nil} if the buffer's mark is active.
+
+@item overlays_before
+This field holds a list of the overlays in this buffer that end at or
+before the current overlay center position.  They are sorted in order of
+decreasing end position.
+
+@item overlays_after
+This field holds a list of the overlays in this buffer that end after
+the current overlay center position.  They are sorted in order of
+increasing beginning position.
+
+@item overlay_center
+This field holds the current overlay center position.  @xref{Overlays}.
+
+@item enable_multibyte_characters
+This field holds the buffer's local value of
+@code{enable-multibyte-characters}---either @code{t} or @code{nil}.
+
+@item buffer_file_coding_system
+The value of @code{buffer-file-coding-system} in this buffer.
+
+@item file_format
+The value of @code{buffer-file-format} in this buffer.
+
+@item auto_save_file_format
+The value of @code{buffer-auto-save-file-format} in this buffer.
+
+@item pt_marker
+In an indirect buffer, or a buffer that is the base of an indirect
+buffer, this holds a marker that records point for this buffer when the
+buffer is not current.
+
+@item begv_marker
+In an indirect buffer, or a buffer that is the base of an indirect
+buffer, this holds a marker that records @code{begv} for this buffer
+when the buffer is not current.
+
+@item zv_marker
+In an indirect buffer, or a buffer that is the base of an indirect
+buffer, this holds a marker that records @code{zv} for this buffer when
+the buffer is not current.
+
+@item file_truename
+The truename of the visited file, or @code{nil}.
+
+@item invisibility_spec
+The value of @code{buffer-invisibility-spec} in this buffer.
+
+@item last_selected_window
+This is the last window that was selected with this buffer in it, or @code{nil}
+if that window no longer displays this buffer.
+
+@item display_count
+This field is incremented each time the buffer is displayed in a window.
+
+@item left_margin_width
+The value of @code{left-margin-width} in this buffer.
+
+@item right_margin_width
+The value of @code{right-margin-width} in this buffer.
+
+@item indicate_empty_lines
+Non-@code{nil} means indicate empty lines (lines with no text) with a
+small bitmap in the fringe, when using a window system that can do it.
+
+@item display_time
+This holds a time stamp that is updated each time this buffer is
+displayed in a window.
+
+@item scroll_up_aggressively
+The value of @code{scroll-up-aggressively} in this buffer.
+
+@item scroll_down_aggressively
+The value of @code{scroll-down-aggressively} in this buffer.
+@end table
+
+@node Window Internals
+@appendixsubsec Window Internals
+@cindex internals, of window
+@cindex window internals
+
+  Windows have the following accessible fields:
+
+@table @code
+@item frame
+The frame that this window is on.
+
+@item mini_p
+Non-@code{nil} if this window is a minibuffer window.
+
+@item parent
+Internally, Emacs arranges windows in a tree; each group of siblings has
+a parent window whose area includes all the siblings.  This field points
+to a window's parent.
+
+Parent windows do not display buffers, and play little role in display
+except to shape their child windows.  Emacs Lisp programs usually have
+no access to the parent windows; they operate on the windows at the
+leaves of the tree, which actually display buffers.
+
+The following four fields also describe the window tree structure.
+
+@item hchild
+In a window subdivided horizontally by child windows, the leftmost child.
+Otherwise, @code{nil}.
+
+@item vchild
+In a window subdivided vertically by child windows, the topmost child.
+Otherwise, @code{nil}.
+
+@item next
+The next sibling of this window.  It is @code{nil} in a window that is
+the rightmost or bottommost of a group of siblings.
+
+@item prev
+The previous sibling of this window.  It is @code{nil} in a window that
+is the leftmost or topmost of a group of siblings.
+
+@item left
+This is the left-hand edge of the window, measured in columns.  (The
+leftmost column on the screen is @w{column 0}.)
+
+@item top
+This is the top edge of the window, measured in lines.  (The top line on
+the screen is @w{line 0}.)
+
+@item height
+The height of the window, measured in lines.
+
+@item width
+The width of the window, measured in columns.  This width includes the
+scroll bar and fringes, and/or the separator line on the right of the
+window (if any).
+
+@item buffer
+The buffer that the window is displaying.  This may change often during
+the life of the window.
+
+@item start
+The position in the buffer that is the first character to be displayed
+in the window.
+
+@item pointm
+@cindex window point internals
+This is the value of point in the current buffer when this window is
+selected; when it is not selected, it retains its previous value.
+
+@item force_start
+If this flag is non-@code{nil}, it says that the window has been
+scrolled explicitly by the Lisp program.  This affects what the next
+redisplay does if point is off the screen: instead of scrolling the
+window to show the text around point, it moves point to a location that
+is on the screen.
+
+@item frozen_window_start_p
+This field is set temporarily to 1 to indicate to redisplay that
+@code{start} of this window should not be changed, even if point
+gets invisible.
+
+@item start_at_line_beg
+Non-@code{nil} means current value of @code{start} was the beginning of a line
+when it was chosen.
+
+@item too_small_ok
+Non-@code{nil} means don't delete this window for becoming ``too small.''
+
+@item height_fixed_p
+This field is temporarily set to 1 to fix the height of the selected
+window when the echo area is resized.
+
+@item use_time
+This is the last time that the window was selected.  The function
+@code{get-lru-window} uses this field.
+
+@item sequence_number
+A unique number assigned to this window when it was created.
+
+@item last_modified
+The @code{modiff} field of the window's buffer, as of the last time
+a redisplay completed in this window.
+
+@item last_overlay_modified
+The @code{overlay_modiff} field of the window's buffer, as of the last
+time a redisplay completed in this window.
+
+@item last_point
+The buffer's value of point, as of the last time a redisplay completed
+in this window.
+
+@item last_had_star
+A non-@code{nil} value means the window's buffer was ``modified'' when the
+window was last updated.
+
+@item vertical_scroll_bar
+This window's vertical scroll bar.
+
+@item left_margin_width
+The width of the left margin in this window, or @code{nil} not to
+specify it (in which case the buffer's value of @code{left-margin-width}
+is used.
+
+@item right_margin_width
+Likewise for the right margin.
+
+@ignore
+@item last_mark_x
+@item last_mark_y
+???Not used.
+@end ignore
+
+@item window_end_pos
+This is computed as @code{z} minus the buffer position of the last glyph
+in the current matrix of the window.  The value is only valid if
+@code{window_end_valid} is not @code{nil}.
+
+@item window_end_bytepos
+The byte position corresponding to @code{window_end_pos}.
+
+@item window_end_vpos
+The window-relative vertical position of the line containing
+@code{window_end_pos}.
+
+@item window_end_valid
+This field is set to a non-@code{nil} value if @code{window_end_pos} is truly
+valid.  This is @code{nil} if nontrivial redisplay is preempted since in that
+case the display that @code{window_end_pos} was computed for did not get
+onto the screen.
+
+@item redisplay_end_trigger
+If redisplay in this window goes beyond this buffer position, it runs
+the @code{redisplay-end-trigger-hook}.
+
+@ignore
+@item orig_height
+@item orig_top
+??? Are temporary storage areas.
+@end ignore
+
+@item cursor
+A structure describing where the cursor is in this window.
+
+@item last_cursor
+The value of @code{cursor} as of the last redisplay that finished.
+
+@item phys_cursor
+A structure describing where the cursor of this window physically is.
+
+@item phys_cursor_type
+The type of cursor that was last displayed on this window.
+
+@item phys_cursor_on_p
+This field is non-zero if the cursor is physically on.
+
+@item cursor_off_p
+Non-zero means the cursor in this window is logically on.
+
+@item last_cursor_off_p
+This field contains the value of @code{cursor_off_p} as of the time of
+the last redisplay.
+
+@item must_be_updated_p
+This is set to 1 during redisplay when this window must be updated.
+
+@item hscroll
+This is the number of columns that the display in the window is scrolled
+horizontally to the left.  Normally, this is 0.
+
+@item vscroll
+Vertical scroll amount, in pixels.  Normally, this is 0.
+
+@item dedicated
+Non-@code{nil} if this window is dedicated to its buffer.
+
+@item display_table
+The window's display table, or @code{nil} if none is specified for it.
+
+@item update_mode_line
+Non-@code{nil} means this window's mode line needs to be updated.
+
+@item base_line_number
+The line number of a certain position in the buffer, or @code{nil}.
+This is used for displaying the line number of point in the mode line.
+
+@item base_line_pos
+The position in the buffer for which the line number is known, or
+@code{nil} meaning none is known.
+
+@item region_showing
+If the region (or part of it) is highlighted in this window, this field
+holds the mark position that made one end of that region.  Otherwise,
+this field is @code{nil}.
+
+@item column_number_displayed
+The column number currently displayed in this window's mode line, or @code{nil}
+if column numbers are not being displayed.
+
+@item current_matrix
+A glyph matrix describing the current display of this window.
+
+@item desired_matrix
+A glyph matrix describing the desired display of this window.
+@end table
+
+@node Process Internals
+@appendixsubsec Process Internals
+@cindex internals, of process
+@cindex process internals
+
+  The fields of a process are:
+
+@table @code
+@item name
+A string, the name of the process.
+
+@item command
+A list containing the command arguments that were used to start this
+process.
+
+@item filter
+A function used to accept output from the process instead of a buffer,
+or @code{nil}.
+
+@item sentinel
+A function called whenever the process receives a signal, or @code{nil}.
+
+@item buffer
+The associated buffer of the process.
+
+@item pid
+An integer, the operating system's process @acronym{ID}.
+
+@item childp
+A flag, non-@code{nil} if this is really a child process.
+It is @code{nil} for a network connection.
+
+@item mark
+A marker indicating the position of the end of the last output from this
+process inserted into the buffer.  This is often but not always the end
+of the buffer.
+
+@item kill_without_query
+If this is non-@code{nil}, killing Emacs while this process is still
+running does not ask for confirmation about killing the process.
+
+@item raw_status_low
+@itemx raw_status_high
+These two fields record 16 bits each of the process status returned by
+the @code{wait} system call.
+
+@item status
+The process status, as @code{process-status} should return it.
+
+@item tick
+@itemx update_tick
+If these two fields are not equal, a change in the status of the process
+needs to be reported, either by running the sentinel or by inserting a
+message in the process buffer.
+
+@item pty_flag
+Non-@code{nil} if communication with the subprocess uses a @acronym{PTY};
+@code{nil} if it uses a pipe.
+
+@item infd
+The file descriptor for input from the process.
+
+@item outfd
+The file descriptor for output to the process.
+
+@item subtty
+The file descriptor for the terminal that the subprocess is using.  (On
+some systems, there is no need to record this, so the value is
+@code{nil}.)
+
+@item tty_name
+The name of the terminal that the subprocess is using,
+or @code{nil} if it is using pipes.
+
+@item decode_coding_system
+Coding-system for decoding the input from this process.
+
+@item decoding_buf
+A working buffer for decoding.
+
+@item decoding_carryover
+Size of carryover in decoding.
+
+@item encode_coding_system
+Coding-system for encoding the output to this process.
+
+@item encoding_buf
+A working buffer for encoding.
+
+@item encoding_carryover
+Size of carryover in encoding.
+
+@item inherit_coding_system_flag
+Flag to set @code{coding-system} of the process buffer from the
+coding system used to decode process output.
+@end table
+
+@ignore
+   arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e
+@end ignore
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
new file mode 100644
index 00000000000..ed0fd1c0699
--- /dev/null
+++ b/doc/lispref/intro.texi
@@ -0,0 +1,560 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/intro
+
+@node Introduction, Lisp Data Types, Top, Top
+@comment  node-name,  next,  previous,  up
+@chapter Introduction
+
+  Most of the GNU Emacs text editor is written in the programming
+language called Emacs Lisp.  You can write new code in Emacs Lisp and
+install it as an extension to the editor.  However, Emacs Lisp is more
+than a mere ``extension language''; it is a full computer programming
+language in its own right.  You can use it as you would any other
+programming language.
+
+  Because Emacs Lisp is designed for use in an editor, it has special
+features for scanning and parsing text as well as features for handling
+files, buffers, displays, subprocesses, and so on.  Emacs Lisp is
+closely integrated with the editing facilities; thus, editing commands
+are functions that can also conveniently be called from Lisp programs,
+and parameters for customization are ordinary Lisp variables.
+
+  This manual attempts to be a full description of Emacs Lisp.  For a
+beginner's introduction to Emacs Lisp, see @cite{An Introduction to
+Emacs Lisp Programming}, by Bob Chassell, also published by the Free
+Software Foundation.  This manual presumes considerable familiarity with
+the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this
+basic information.
+
+  Generally speaking, the earlier chapters describe features of Emacs
+Lisp that have counterparts in many programming languages, and later
+chapters describe features that are peculiar to Emacs Lisp or relate
+specifically to editing.
+
+  This is edition @value{VERSION} of the GNU Emacs Lisp Reference
+Manual, corresponding to Emacs version @value{EMACSVER}.
+
+@menu
+* Caveats::             Flaws and a request for help.
+* Lisp History::        Emacs Lisp is descended from Maclisp.
+* Conventions::         How the manual is formatted.
+* Version Info::        Which Emacs version is running?
+* Acknowledgements::    The authors, editors, and sponsors of this manual.
+@end menu
+
+@node Caveats
+@section Caveats
+@cindex bugs in this manual
+
+  This manual has gone through numerous drafts.  It is nearly complete
+but not flawless.  There are a few topics that are not covered, either
+because we consider them secondary (such as most of the individual
+modes) or because they are yet to be written.  Because we are not able
+to deal with them completely, we have left out several parts
+intentionally.  This includes most information about usage on VMS.
+
+  The manual should be fully correct in what it does cover, and it is
+therefore open to criticism on anything it says---from specific examples
+and descriptive text, to the ordering of chapters and sections.  If
+something is confusing, or you find that you have to look at the sources
+or experiment to learn something not covered in the manual, then perhaps
+the manual should be fixed.  Please let us know.
+
+@iftex
+  As you use this manual, we ask that you mark pages with corrections so
+you can later look them up and send them to us.  If you think of a simple,
+real-life example for a function or group of functions, please make an
+effort to write it up and send it in.  Please reference any comments to
+the chapter name, section name, and function name, as appropriate, since
+page numbers and chapter and section numbers will change and we may have
+trouble finding the text you are talking about.  Also state the number
+of the edition you are criticizing.
+@end iftex
+@ifnottex
+
+As you use this manual, we ask that you send corrections as soon as you
+find them.  If you think of a simple, real life example for a function
+or group of functions, please make an effort to write it up and send it
+in.  Please reference any comments to the node name and function or
+variable name, as appropriate.  Also state the number of the edition
+you are criticizing.
+@end ifnottex
+
+@cindex bugs
+@cindex suggestions
+Please mail comments and corrections to
+
+@example
+bug-lisp-manual@@gnu.org
+@end example
+
+@noindent
+We let mail to this list accumulate unread until someone decides to
+apply the corrections.  Months, and sometimes years, go by between
+updates.  So please attach no significance to the lack of a reply---your
+mail @emph{will} be acted on in due time.  If you want to contact the
+Emacs maintainers more quickly, send mail to
+@code{bug-gnu-emacs@@gnu.org}.
+
+@node Lisp History
+@section Lisp History
+@cindex Lisp history
+
+  Lisp (LISt Processing language) was first developed in the late 1950s
+at the Massachusetts Institute of Technology for research in artificial
+intelligence.  The great power of the Lisp language makes it ideal
+for other purposes as well, such as writing editing commands.
+
+@cindex Maclisp
+@cindex Common Lisp
+  Dozens of Lisp implementations have been built over the years, each
+with its own idiosyncrasies.  Many of them were inspired by Maclisp,
+which was written in the 1960s at MIT's Project MAC.  Eventually the
+implementors of the descendants of Maclisp came together and developed a
+standard for Lisp systems, called Common Lisp.  In the meantime, Gerry
+Sussman and Guy Steele at MIT developed a simplified but very powerful
+dialect of Lisp, called Scheme.
+
+  GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
+Lisp.  If you know Common Lisp, you will notice many similarities.
+However, many features of Common Lisp have been omitted or
+simplified in order to reduce the memory requirements of GNU Emacs.
+Sometimes the simplifications are so drastic that a Common Lisp user
+might be very confused.  We will occasionally point out how GNU Emacs
+Lisp differs from Common Lisp.  If you don't know Common Lisp, don't
+worry about it; this manual is self-contained.
+
+@pindex cl
+  A certain amount of Common Lisp emulation is available via the
+@file{cl} library.  @inforef{Top, Overview, cl}.
+
+  Emacs Lisp is not at all influenced by Scheme; but the GNU project has
+an implementation of Scheme, called Guile.  We use Guile in all new GNU
+software that calls for extensibility.
+
+@node Conventions
+@section Conventions
+
+This section explains the notational conventions that are used in this
+manual.  You may want to skip this section and refer back to it later.
+
+@menu
+* Some Terms::               Explanation of terms we use in this manual.
+* nil and t::                How the symbols @code{nil} and @code{t} are used.
+* Evaluation Notation::      The format we use for examples of evaluation.
+* Printing Notation::        The format we use when examples print text.
+* Error Messages::           The format we use for examples of errors.
+* Buffer Text Notation::     The format we use for buffer contents in examples.
+* Format of Descriptions::   Notation for describing functions, variables, etc.
+@end menu
+
+@node Some Terms
+@subsection Some Terms
+
+  Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
+printer'' refer to those routines in Lisp that convert textual
+representations of Lisp objects into actual Lisp objects, and vice
+versa.  @xref{Printed Representation}, for more details.  You, the
+person reading this manual, are thought of as ``the programmer'' and are
+addressed as ``you.''  ``The user'' is the person who uses Lisp
+programs, including those you write.
+
+@cindex fonts in this manual
+  Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
+Names that represent metasyntactic variables, or arguments to a function
+being described, are formatted like this: @var{first-number}.
+
+@node nil and t
+@subsection @code{nil} and @code{t}
+@cindex truth value
+@cindex boolean
+
+@cindex @code{nil}
+@cindex false
+  In Lisp, the symbol @code{nil} has three separate meanings: it
+is a symbol with the name @samp{nil}; it is the logical truth value
+@var{false}; and it is the empty list---the list of zero elements.
+When used as a variable, @code{nil} always has the value @code{nil}.
+
+  As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are
+identical: they stand for the same object, the symbol @code{nil}.  The
+different ways of writing the symbol are intended entirely for human
+readers.  After the Lisp reader has read either @samp{()} or @samp{nil},
+there is no way to determine which representation was actually written
+by the programmer.
+
+  In this manual, we write @code{()} when we wish to emphasize that it
+means the empty list, and we write @code{nil} when we wish to emphasize
+that it means the truth value @var{false}.  That is a good convention to use
+in Lisp programs also.
+
+@example
+(cons 'foo ())                ; @r{Emphasize the empty list}
+(setq foo-flag nil)           ; @r{Emphasize the truth value @var{false}}
+@end example
+
+@cindex @code{t}
+@cindex true
+  In contexts where a truth value is expected, any non-@code{nil} value
+is considered to be @var{true}.  However, @code{t} is the preferred way
+to represent the truth value @var{true}.  When you need to choose a
+value which represents @var{true}, and there is no other basis for
+choosing, use @code{t}.  The symbol @code{t} always has the value
+@code{t}.
+
+  In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
+evaluate to themselves.  This is so that you do not need to quote them
+to use them as constants in a program.  An attempt to change their
+values results in a @code{setting-constant} error.  @xref{Constant
+Variables}.
+
+@defun booleanp object
+Return non-nil if @var{object} is one of the two canonical boolean
+values: @code{t} or @code{nil}.
+@end defun
+
+@node Evaluation Notation
+@subsection Evaluation Notation
+@cindex evaluation notation
+@cindex documentation notation
+@cindex notation
+
+  A Lisp expression that you can evaluate is called a @dfn{form}.
+Evaluating a form always produces a result, which is a Lisp object.  In
+the examples in this manual, this is indicated with @samp{@result{}}:
+
+@example
+(car '(1 2))
+     @result{} 1
+@end example
+
+@noindent
+You can read this as ``@code{(car '(1 2))} evaluates to 1.''
+
+  When a form is a macro call, it expands into a new form for Lisp to
+evaluate.  We show the result of the expansion with
+@samp{@expansion{}}.  We may or may not show the result of the
+evaluation of the expanded form.
+
+@example
+(third '(a b c))
+     @expansion{} (car (cdr (cdr '(a b c))))
+     @result{} c
+@end example
+
+  Sometimes to help describe one form we show another form that
+produces identical results.  The exact equivalence of two forms is
+indicated with @samp{@equiv{}}.
+
+@example
+(make-sparse-keymap) @equiv{} (list 'keymap)
+@end example
+
+@node Printing Notation
+@subsection Printing Notation
+@cindex printing notation
+
+  Many of the examples in this manual print text when they are
+evaluated.  If you execute example code in a Lisp Interaction buffer
+(such as the buffer @samp{*scratch*}), the printed text is inserted into
+the buffer.  If you execute the example by other means (such as by
+evaluating the function @code{eval-region}), the printed text is
+displayed in the echo area.
+
+  Examples in this manual indicate printed text with @samp{@print{}},
+irrespective of where that text goes.  The value returned by
+evaluating the form (here @code{bar}) follows on a separate line with
+@samp{@result{}}.
+
+@example
+@group
+(progn (prin1 'foo) (princ "\n") (prin1 'bar))
+     @print{} foo
+     @print{} bar
+     @result{} bar
+@end group
+@end example
+
+@node Error Messages
+@subsection Error Messages
+@cindex error message notation
+
+  Some examples signal errors.  This normally displays an error message
+in the echo area.  We show the error message on a line starting with
+@samp{@error{}}.  Note that @samp{@error{}} itself does not appear in
+the echo area.
+
+@example
+(+ 23 'x)
+@error{} Wrong type argument: number-or-marker-p, x
+@end example
+
+@node Buffer Text Notation
+@subsection Buffer Text Notation
+@cindex buffer text notation
+
+  Some examples describe modifications to the contents of a buffer, by
+showing the ``before'' and ``after'' versions of the text.  These
+examples show the contents of the buffer in question between two lines
+of dashes containing the buffer name.  In addition, @samp{@point{}}
+indicates the location of point.  (The symbol for point, of course, is
+not part of the text in the buffer; it indicates the place
+@emph{between} two characters where point is currently located.)
+
+@example
+---------- Buffer: foo ----------
+This is the @point{}contents of foo.
+---------- Buffer: foo ----------
+
+(insert "changed ")
+     @result{} nil
+---------- Buffer: foo ----------
+This is the changed @point{}contents of foo.
+---------- Buffer: foo ----------
+@end example
+
+@node Format of Descriptions
+@subsection Format of Descriptions
+@cindex description format
+
+  Functions, variables, macros, commands, user options, and special
+forms are described in this manual in a uniform format.  The first
+line of a description contains the name of the item followed by its
+arguments, if any.
+@ifnottex
+The category---function, variable, or whatever---appears at the
+beginning of the line.
+@end ifnottex
+@iftex
+The category---function, variable, or whatever---is printed next to the
+right margin.
+@end iftex
+The description follows on succeeding lines, sometimes with examples.
+
+@menu
+* A Sample Function Description::       A description of an imaginary
+                                          function, @code{foo}.
+* A Sample Variable Description::       A description of an imaginary
+                                          variable,
+                                          @code{electric-future-map}.
+@end menu
+
+@node A Sample Function Description
+@subsubsection A Sample Function Description
+@cindex function descriptions
+@cindex command descriptions
+@cindex macro descriptions
+@cindex special form descriptions
+
+  In a function description, the name of the function being described
+appears first.  It is followed on the same line by a list of argument
+names.  These names are also used in the body of the description, to
+stand for the values of the arguments.
+
+  The appearance of the keyword @code{&optional} in the argument list
+indicates that the subsequent arguments may be omitted (omitted
+arguments default to @code{nil}).  Do not write @code{&optional} when
+you call the function.
+
+  The keyword @code{&rest} (which must be followed by a single
+argument name) indicates that any number of arguments can follow.  The
+single argument name following @code{&rest} will receive, as its
+value, a list of all the remaining arguments passed to the function.
+Do not write @code{&rest} when you call the function.
+
+  Here is a description of an imaginary function @code{foo}:
+
+@defun foo integer1 &optional integer2 &rest integers
+The function @code{foo} subtracts @var{integer1} from @var{integer2},
+then adds all the rest of the arguments to the result.  If @var{integer2}
+is not supplied, then the number 19 is used by default.
+
+@example
+(foo 1 5 3 9)
+     @result{} 16
+(foo 5)
+     @result{} 14
+@end example
+
+@need 1500
+More generally,
+
+@example
+(foo @var{w} @var{x} @var{y}@dots{})
+@equiv{}
+(+ (- @var{x} @var{w}) @var{y}@dots{})
+@end example
+@end defun
+
+  Any argument whose name contains the name of a type (e.g.,
+@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
+type.  A plural of a type (such as @var{buffers}) often means a list of
+objects of that type.  Arguments named @var{object} may be of any type.
+(@xref{Lisp Data Types}, for a list of Emacs object types.)  Arguments
+with other sorts of names (e.g., @var{new-file}) are discussed
+specifically in the description of the function.  In some sections,
+features common to the arguments of several functions are described at
+the beginning.
+
+  @xref{Lambda Expressions}, for a more complete description of optional
+and rest arguments.
+
+  Command, macro, and special form descriptions have the same format,
+but the word `Function' is replaced by `Command', `Macro', or `Special
+Form', respectively.  Commands are simply functions that may be called
+interactively; macros process their arguments differently from functions
+(the arguments are not evaluated), but are presented the same way.
+
+  Special form descriptions use a more complex notation to specify
+optional and repeated arguments because they can break the argument
+list down into separate arguments in more complicated ways.
+@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
+optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
+arguments.  Parentheses are used when several arguments are grouped into
+additional levels of list structure.  Here is an example:
+
+@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
+This imaginary special form implements a loop that executes the
+@var{body} forms and then increments the variable @var{var} on each
+iteration.  On the first iteration, the variable has the value
+@var{from}; on subsequent iterations, it is incremented by one (or by
+@var{inc} if that is given).  The loop exits before executing @var{body}
+if @var{var} equals @var{to}.  Here is an example:
+
+@example
+(count-loop (i 0 10)
+  (prin1 i) (princ " ")
+  (prin1 (aref vector i))
+  (terpri))
+@end example
+
+If @var{from} and @var{to} are omitted, @var{var} is bound to
+@code{nil} before the loop begins, and the loop exits if @var{var} is
+non-@code{nil} at the beginning of an iteration.  Here is an example:
+
+@example
+(count-loop (done)
+  (if (pending)
+      (fixit)
+    (setq done t)))
+@end example
+
+In this special form, the arguments @var{from} and @var{to} are
+optional, but must both be present or both absent.  If they are present,
+@var{inc} may optionally be specified as well.  These arguments are
+grouped with the argument @var{var} into a list, to distinguish them
+from @var{body}, which includes all remaining elements of the form.
+@end defspec
+
+@node A Sample Variable Description
+@subsubsection A Sample Variable Description
+@cindex variable descriptions
+@cindex option descriptions
+
+  A @dfn{variable} is a name that can hold a value.  Although nearly
+all variables can be set by the user, certain variables exist
+specifically so that users can change them; these are called @dfn{user
+options}.  Ordinary variables and user options are described using a
+format like that for functions except that there are no arguments.
+
+  Here is a description of the imaginary @code{electric-future-map}
+variable.@refill
+
+@defvar electric-future-map
+The value of this variable is a full keymap used by Electric Command
+Future mode.  The functions in this map allow you to edit commands you
+have not yet thought about executing.
+@end defvar
+
+  User option descriptions have the same format, but `Variable' is
+replaced by `User Option'.
+
+@node Version Info
+@section Version Information
+
+  These facilities provide information about which version of Emacs is
+in use.
+
+@deffn Command emacs-version &optional here
+This function returns a string describing the version of Emacs that is
+running.  It is useful to include this string in bug reports.
+
+@smallexample
+@group
+(emacs-version)
+  @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
+ of Sat Feb 14 1998 on psilocin.gnu.org"
+@end group
+@end smallexample
+
+If @var{here} is non-@code{nil}, it inserts the text in the buffer
+before point, and returns @code{nil}.  Called interactively, the
+function prints the same information in the echo area, but giving a
+prefix argument makes @var{here} non-@code{nil}.
+@end deffn
+
+@defvar emacs-build-time
+The value of this variable indicates the time at which Emacs was built
+at the local site.  It is a list of three integers, like the value
+of @code{current-time} (@pxref{Time of Day}).
+
+@example
+@group
+emacs-build-time
+     @result{} (13623 62065 344633)
+@end group
+@end example
+@end defvar
+
+@defvar emacs-version
+The value of this variable is the version of Emacs being run.  It is a
+string such as @code{"20.3.1"}.  The last number in this string is not
+really part of the Emacs release version number; it is incremented each
+time you build Emacs in any given directory.  A value with four numeric
+components, such as @code{"20.3.9.1"}, indicates an unreleased test
+version.
+@end defvar
+
+  The following two variables have existed since Emacs version 19.23:
+
+@defvar emacs-major-version
+The major version number of Emacs, as an integer.  For Emacs version
+20.3, the value is 20.
+@end defvar
+
+@defvar emacs-minor-version
+The minor version number of Emacs, as an integer.  For Emacs version
+20.3, the value is 3.
+@end defvar
+
+@node Acknowledgements
+@section Acknowledgements
+
+  This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte,
+Richard@tie{}M. Stallman and Chris Welty, the volunteers of the GNU
+manual group, in an effort extending over several years.
+Robert@tie{}J. Chassell helped to review and edit the manual, with the
+support of the Defense Advanced Research Projects Agency, ARPA Order
+6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic,
+Inc.
+
+  Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom,
+Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence
+R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly
+Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea,
+Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki
+Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe
+Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland
+McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson,
+Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul
+Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp,
+Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty,
+Dale Worley, Rusty Wright, and David D. Zuhn.
+
+@ignore
+   arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa
+@end ignore
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
new file mode 100644
index 00000000000..bf20680dd81
--- /dev/null
+++ b/doc/lispref/keymaps.texi
@@ -0,0 +1,2785 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/keymaps
+@node Keymaps, Modes, Command Loop, Top
+@chapter Keymaps
+@cindex keymap
+
+  The command bindings of input events are recorded in data structures
+called @dfn{keymaps}.  Each entry in a keymap associates (or
+@dfn{binds}) an individual event type, either to another keymap or to
+a command.  When an event type is bound to a keymap, that keymap is
+used to look up the next input event; this continues until a command
+is found.  The whole process is called @dfn{key lookup}.
+
+@menu
+* Key Sequences::        	Key sequences as Lisp objects.
+* Keymap Basics::               Basic concepts of keymaps.
+* Format of Keymaps::		What a keymap looks like as a Lisp object.
+* Creating Keymaps:: 		Functions to create and copy keymaps.
+* Inheritance and Keymaps::	How one keymap can inherit the bindings
+				   of another keymap.
+* Prefix Keys::                 Defining a key with a keymap as its definition.
+* Active Keymaps::              How Emacs searches the active keymaps
+                                   for a key binding.
+* Searching Keymaps::           A pseudo-Lisp summary of searching active maps.
+* Controlling Active Maps::     Each buffer has a local keymap
+                                   to override the standard (global) bindings.
+				   A minor mode can also override them.
+* Key Lookup::                  Finding a key's binding in one keymap.
+* Functions for Key Lookup::    How to request key lookup.
+* Changing Key Bindings::       Redefining a key in a keymap.
+* Remapping Commands::          A keymap can translate one command to another.
+* Translation Keymaps::         Keymaps for translating sequences of events.
+* Key Binding Commands::        Interactive interfaces for redefining keys.
+* Scanning Keymaps::            Looking through all keymaps, for printing help.
+* Menu Keymaps::		Defining a menu as a keymap.
+@end menu
+
+@node Key Sequences
+@section Key Sequences
+@cindex key
+@cindex keystroke
+@cindex key sequence
+
+  A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
+or more input events that form a unit.  Input events include
+characters, function keys, and mouse actions (@pxref{Input Events}).
+The Emacs Lisp representation for a key sequence is a string or
+vector.  Unless otherwise stated, any Emacs Lisp function that accepts
+a key sequence as an argument can handle both representations.
+
+  In the string representation, alphanumeric characters ordinarily
+stand for themselves; for example, @code{"a"} represents @kbd{a}
+and @code{"2"} represents @kbd{2}.  Control character events are
+prefixed by the substring @code{"\C-"}, and meta characters by
+@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
+In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events
+are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and
+@code{"\d"} respectively.  The string representation of a complete key
+sequence is the concatenation of the string representations of the
+constituent events; thus, @code{"\C-xl"} represents the key sequence
+@kbd{C-x l}.
+
+  Key sequences containing function keys, mouse button events, or
+non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
+represented as strings; they have to be represented as vectors.
+
+  In the vector representation, each element of the vector represents
+an input event, in its Lisp form.  @xref{Input Events}.  For example,
+the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}.
+
+  For examples of key sequences written in string and vector
+representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}.
+
+@defmac kbd keyseq-text
+This macro converts the text @var{keyseq-text} (a string constant)
+into a key sequence (a string or vector constant).  The contents of
+@var{keyseq-text} should describe the key sequence using almost the same
+syntax used in this manual.  More precisely, it uses the same syntax
+that Edit Macro mode uses for editing keyboard macros (@pxref{Edit
+Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround
+function key names with @samp{<@dots{}>}.
+
+@example
+(kbd "C-x") @result{} "\C-x"
+(kbd "C-x C-f") @result{} "\C-x\C-f"
+(kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
+(kbd "X") @result{} "X"
+(kbd "RET") @result{} "\^M"
+(kbd "C-c SPC") @result{} "\C-c@ "
+(kbd "<f1> SPC") @result{} [f1 32]
+(kbd "C-M-<down>") @result{} [C-M-down]
+@end example
+
+This macro is not meant for use with arguments that vary---only
+with string constants.
+@end defmac
+
+@node Keymap Basics
+@section Keymap Basics
+@cindex key binding
+@cindex binding of a key
+@cindex complete key
+@cindex undefined key
+
+  A keymap is a Lisp data structure that specifies @dfn{key bindings}
+for various key sequences.
+
+  A single keymap directly specifies definitions for individual
+events.  When a key sequence consists of a single event, its binding
+in a keymap is the keymap's definition for that event.  The binding of
+a longer key sequence is found by an iterative process: first find the
+definition of the first event (which must itself be a keymap); then
+find the second event's definition in that keymap, and so on until all
+the events in the key sequence have been processed.
+
+  If the binding of a key sequence is a keymap, we call the key sequence
+a @dfn{prefix key}.  Otherwise, we call it a @dfn{complete key} (because
+no more events can be added to it).  If the binding is @code{nil},
+we call the key @dfn{undefined}.  Examples of prefix keys are @kbd{C-c},
+@kbd{C-x}, and @kbd{C-x 4}.  Examples of defined complete keys are
+@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}.  Examples of undefined complete
+keys are @kbd{C-x C-g}, and @kbd{C-c 3}.  @xref{Prefix Keys}, for more
+details.
+
+  The rule for finding the binding of a key sequence assumes that the
+intermediate bindings (found for the events before the last) are all
+keymaps; if this is not so, the sequence of events does not form a
+unit---it is not really one key sequence.  In other words, removing one
+or more events from the end of any valid key sequence must always yield
+a prefix key.  For example, @kbd{C-f C-n} is not a key sequence;
+@kbd{C-f} is not a prefix key, so a longer sequence starting with
+@kbd{C-f} cannot be a key sequence.
+
+  The set of possible multi-event key sequences depends on the bindings
+for prefix keys; therefore, it can be different for different keymaps,
+and can change when bindings are changed.  However, a one-event sequence
+is always a key sequence, because it does not depend on any prefix keys
+for its well-formedness.
+
+  At any time, several primary keymaps are @dfn{active}---that is, in
+use for finding key bindings.  These are the @dfn{global map}, which is
+shared by all buffers; the @dfn{local keymap}, which is usually
+associated with a specific major mode; and zero or more @dfn{minor mode
+keymaps}, which belong to currently enabled minor modes.  (Not all minor
+modes have keymaps.)  The local keymap bindings shadow (i.e., take
+precedence over) the corresponding global bindings.  The minor mode
+keymaps shadow both local and global keymaps.  @xref{Active Keymaps},
+for details.
+
+@node Format of Keymaps
+@section Format of Keymaps
+@cindex format of keymaps
+@cindex keymap format
+@cindex full keymap
+@cindex sparse keymap
+
+  Each keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
+remaining elements of the list define the key bindings of the keymap.
+A symbol whose function definition is a keymap is also a keymap.  Use
+the function @code{keymapp} (see below) to test whether an object is a
+keymap.
+
+  Several kinds of elements may appear in a keymap, after the symbol
+@code{keymap} that begins it:
+
+@table @code
+@item (@var{type} .@: @var{binding})
+This specifies one binding, for events of type @var{type}.  Each
+ordinary binding applies to events of a particular @dfn{event type},
+which is always a character or a symbol.  @xref{Classifying Events}.
+In this kind of binding, @var{binding} is a command.
+
+@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding})
+This specifies a binding which is also a simple menu item that
+displays as @var{item-name} in the menu.  @var{cache}, if present,
+caches certain information for display in the menu.  @xref{Simple Menu
+Items}.
+
+@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding})
+This is a simple menu item with help string @var{help-string}.
+
+@item (@var{type} menu-item .@: @var{details})
+This specifies a binding which is also an extended menu item.  This
+allows use of other features.  @xref{Extended Menu Items}.
+
+@item (t .@: @var{binding})
+@cindex default key binding
+This specifies a @dfn{default key binding}; any event not bound by other
+elements of the keymap is given @var{binding} as its binding.  Default
+bindings allow a keymap to bind all possible event types without having
+to enumerate all of them.  A keymap that has a default binding
+completely masks any lower-precedence keymap, except for events
+explicitly bound to @code{nil} (see below).
+
+@item @var{char-table}
+If an element of a keymap is a char-table, it counts as holding
+bindings for all character events with no modifier bits
+(@pxref{modifier bits}): element @var{n} is the binding for the
+character with code @var{n}.  This is a compact way to record lots of
+bindings.  A keymap with such a char-table is called a @dfn{full
+keymap}.  Other keymaps are called @dfn{sparse keymaps}.
+
+@item @var{string}
+@cindex keymap prompt string
+@cindex overall prompt string
+@cindex prompt string of keymap
+Aside from elements that specify bindings for keys, a keymap can also
+have a string as an element.  This is called the @dfn{overall prompt
+string} and makes it possible to use the keymap as a menu.
+@xref{Defining Menus}.
+@end table
+
+When the binding is @code{nil}, it doesn't constitute a definition
+but it does take precedence over a default binding or a binding in the
+parent keymap.  On the other hand, a binding of @code{nil} does
+@emph{not} override lower-precedence keymaps; thus, if the local map
+gives a binding of @code{nil}, Emacs uses the binding from the
+global map.
+
+@cindex meta characters lookup
+  Keymaps do not directly record bindings for the meta characters.
+Instead, meta characters are regarded for purposes of key lookup as
+sequences of two characters, the first of which is @key{ESC} (or
+whatever is currently the value of @code{meta-prefix-char}).  Thus, the
+key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its
+global binding is found at the slot for @kbd{a} in @code{esc-map}
+(@pxref{Prefix Keys}).
+
+  This conversion applies only to characters, not to function keys or
+other input events; thus, @kbd{M-@key{end}} has nothing to do with
+@kbd{@key{ESC} @key{end}}.
+
+  Here as an example is the local keymap for Lisp mode, a sparse
+keymap.  It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
+C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
+
+@example
+@group
+lisp-mode-map
+@result{}
+@end group
+@group
+(keymap
+ (3 keymap
+    ;; @kbd{C-c C-z}
+    (26 . run-lisp))
+@end group
+@group
+ (27 keymap
+     ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
+     (24 . lisp-send-defun)
+     keymap
+     ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
+     (17 . indent-sexp))
+@end group
+@group
+ ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
+ keymap
+ ;; @key{DEL}
+ (127 . backward-delete-char-untabify)
+@end group
+@group
+ (27 keymap
+     ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
+     (17 . indent-sexp))
+ (9 . lisp-indent-line))
+@end group
+@end example
+
+@defun keymapp object
+This function returns @code{t} if @var{object} is a keymap, @code{nil}
+otherwise.  More precisely, this function tests for a list whose
+@sc{car} is @code{keymap}, or for a symbol whose function definition
+satisfies @code{keymapp}.
+
+@example
+@group
+(keymapp '(keymap))
+    @result{} t
+@end group
+@group
+(fset 'foo '(keymap))
+(keymapp 'foo)
+    @result{} t
+@end group
+@group
+(keymapp (current-global-map))
+    @result{} t
+@end group
+@end example
+@end defun
+
+@node Creating Keymaps
+@section Creating Keymaps
+@cindex creating keymaps
+
+  Here we describe the functions for creating keymaps.
+
+@defun make-sparse-keymap &optional prompt
+This function creates and returns a new sparse keymap with no entries.
+(A sparse keymap is the kind of keymap you usually want.)  The new
+keymap does not contain a char-table, unlike @code{make-keymap}, and
+does not bind any events.
+
+@example
+@group
+(make-sparse-keymap)
+    @result{} (keymap)
+@end group
+@end example
+
+If you specify @var{prompt}, that becomes the overall prompt string
+for the keymap.  You should specify this only for menu keymaps
+(@pxref{Defining Menus}).  A keymap with an overall prompt string will
+always present a mouse menu or a keyboard menu if it is active for
+looking up the next input event.  Don't specify an overall prompt string
+for the main map of a major or minor mode, because that would cause
+the command loop to present a keyboard menu every time.
+@end defun
+
+@defun make-keymap &optional prompt
+This function creates and returns a new full keymap.  That keymap
+contains a char-table (@pxref{Char-Tables}) with slots for all
+characters without modifiers.  The new keymap initially binds all
+these characters to @code{nil}, and does not bind any other kind of
+event.  The argument @var{prompt} specifies a
+prompt string, as in @code{make-sparse-keymap}.
+
+@example
+@group
+(make-keymap)
+    @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
+@end group
+@end example
+
+A full keymap is more efficient than a sparse keymap when it holds
+lots of bindings; for just a few, the sparse keymap is better.
+@end defun
+
+@defun copy-keymap keymap
+This function returns a copy of @var{keymap}.  Any keymaps that
+appear directly as bindings in @var{keymap} are also copied recursively,
+and so on to any number of levels.  However, recursive copying does not
+take place when the definition of a character is a symbol whose function
+definition is a keymap; the same symbol appears in the new copy.
+@c Emacs 19 feature
+
+@example
+@group
+(setq map (copy-keymap (current-local-map)))
+@result{} (keymap
+@end group
+@group
+     ;; @r{(This implements meta characters.)}
+     (27 keymap
+         (83 . center-paragraph)
+         (115 . center-line))
+     (9 . tab-to-tab-stop))
+@end group
+
+@group
+(eq map (current-local-map))
+    @result{} nil
+@end group
+@group
+(equal map (current-local-map))
+    @result{} t
+@end group
+@end example
+@end defun
+
+@node Inheritance and Keymaps
+@section Inheritance and Keymaps
+@cindex keymap inheritance
+@cindex inheriting a keymap's bindings
+
+  A keymap can inherit the bindings of another keymap, which we call the
+@dfn{parent keymap}.  Such a keymap looks like this:
+
+@example
+(keymap @var{elements}@dots{} . @var{parent-keymap})
+@end example
+
+@noindent
+The effect is that this keymap inherits all the bindings of
+@var{parent-keymap}, whatever they may be at the time a key is looked up,
+but can add to them or override them with @var{elements}.
+
+If you change the bindings in @var{parent-keymap} using
+@code{define-key} or other key-binding functions, these changed
+bindings are visible in the inheriting keymap, unless shadowed by the
+bindings made by @var{elements}.  The converse is not true: if you use
+@code{define-key} to change bindings in the inheriting keymap, these
+changes are recorded in @var{elements}, but have no effect on
+@var{parent-keymap}.
+
+The proper way to construct a keymap with a parent is to use
+@code{set-keymap-parent}; if you have code that directly constructs a
+keymap with a parent, please convert the program to use
+@code{set-keymap-parent} instead.
+
+@defun keymap-parent keymap
+This returns the parent keymap of @var{keymap}.  If @var{keymap}
+has no parent, @code{keymap-parent} returns @code{nil}.
+@end defun
+
+@defun set-keymap-parent keymap parent
+This sets the parent keymap of @var{keymap} to @var{parent}, and returns
+@var{parent}.  If @var{parent} is @code{nil}, this function gives
+@var{keymap} no parent at all.
+
+If @var{keymap} has submaps (bindings for prefix keys), they too receive
+new parent keymaps that reflect what @var{parent} specifies for those
+prefix keys.
+@end defun
+
+   Here is an example showing how to make a keymap that inherits
+from @code{text-mode-map}:
+
+@example
+(let ((map (make-sparse-keymap)))
+  (set-keymap-parent map text-mode-map)
+  map)
+@end example
+
+  A non-sparse keymap can have a parent too, but this is not very
+useful.  A non-sparse keymap always specifies something as the binding
+for every numeric character code without modifier bits, even if it is
+@code{nil}, so these character's bindings are never inherited from
+the parent keymap.
+
+@node Prefix Keys
+@section Prefix Keys
+@cindex prefix key
+
+  A @dfn{prefix key} is a key sequence whose binding is a keymap.  The
+keymap defines what to do with key sequences that extend the prefix key.
+For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
+also stored in the variable @code{ctl-x-map}.  This keymap defines
+bindings for key sequences starting with @kbd{C-x}.
+
+  Some of the standard Emacs prefix keys use keymaps that are
+also found in Lisp variables:
+
+@itemize @bullet
+@item
+@vindex esc-map
+@findex ESC-prefix
+@code{esc-map} is the global keymap for the @key{ESC} prefix key.  Thus,
+the global definitions of all meta characters are actually found here.
+This map is also the function definition of @code{ESC-prefix}.
+
+@item
+@cindex @kbd{C-h}
+@code{help-map} is the global keymap for the @kbd{C-h} prefix key.
+
+@item
+@cindex @kbd{C-c}
+@vindex mode-specific-map
+@code{mode-specific-map} is the global keymap for the prefix key
+@kbd{C-c}.  This map is actually global, not mode-specific, but its name
+provides useful information about @kbd{C-c} in the output of @kbd{C-h b}
+(@code{display-bindings}), since the main use of this prefix key is for
+mode-specific bindings.
+
+@item
+@cindex @kbd{C-x}
+@vindex ctl-x-map
+@findex Control-X-prefix
+@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
+This map is found via the function cell of the symbol
+@code{Control-X-prefix}.
+
+@item
+@cindex @kbd{C-x @key{RET}}
+@vindex mule-keymap
+@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
+prefix key.
+
+@item
+@cindex @kbd{C-x 4}
+@vindex ctl-x-4-map
+@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
+key.
+
+@c Emacs 19 feature
+@item
+@cindex @kbd{C-x 5}
+@vindex ctl-x-5-map
+@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
+key.
+
+@c Emacs 19 feature
+@item
+@cindex @kbd{C-x 6}
+@vindex 2C-mode-map
+@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
+key.
+
+@item
+@cindex @kbd{C-x v}
+@vindex vc-prefix-map
+@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
+key.
+
+@item
+@cindex @kbd{M-o}
+@vindex facemenu-keymap
+@code{facemenu-keymap} is the global keymap used for the @kbd{M-o}
+prefix key.
+
+@c Emacs 19 feature
+@item
+The other Emacs prefix keys are @kbd{M-g}, @kbd{C-x @@}, @kbd{C-x a i},
+@kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}.  They use keymaps
+that have no special names.
+@end itemize
+
+  The keymap binding of a prefix key is used for looking up the event
+that follows the prefix key.  (It may instead be a symbol whose function
+definition is a keymap.  The effect is the same, but the symbol serves
+as a name for the prefix key.)  Thus, the binding of @kbd{C-x} is the
+symbol @code{Control-X-prefix}, whose function cell holds the keymap
+for @kbd{C-x} commands.  (The same keymap is also the value of
+@code{ctl-x-map}.)
+
+  Prefix key definitions can appear in any active keymap.  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.  Major and minor modes can redefine a key as a prefix by
+putting a prefix key definition for it in the local map or the minor
+mode's map.  @xref{Active Keymaps}.
+
+  If a key is defined as a prefix in more than one active map, then its
+various definitions are in effect merged: the commands defined in the
+minor mode keymaps come first, followed by those in the local map's
+prefix definition, and then by those from the global map.
+
+  In the following example, we make @kbd{C-p} a prefix key in the local
+keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}.  Then
+the binding for @kbd{C-p C-f} is the function @code{find-file}, just
+like @kbd{C-x C-f}.  The key sequence @kbd{C-p 6} is not found in any
+active keymap.
+
+@example
+@group
+(use-local-map (make-sparse-keymap))
+    @result{} nil
+@end group
+@group
+(local-set-key "\C-p" ctl-x-map)
+    @result{} nil
+@end group
+@group
+(key-binding "\C-p\C-f")
+    @result{} find-file
+@end group
+
+@group
+(key-binding "\C-p6")
+    @result{} nil
+@end group
+@end example
+
+@defun define-prefix-command symbol &optional mapvar prompt
+@cindex prefix command
+@anchor{Definition of define-prefix-command}
+This function prepares @var{symbol} for use as a prefix key's binding:
+it creates a sparse keymap and stores it as @var{symbol}'s function
+definition.  Subsequently binding a key sequence to @var{symbol} will
+make that key sequence into a prefix key.  The return value is @code{symbol}.
+
+This function also sets @var{symbol} as a variable, with the keymap as
+its value.  But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
+as a variable instead.
+
+If @var{prompt} is non-@code{nil}, that becomes the overall prompt
+string for the keymap.  The prompt string should be given for menu keymaps
+(@pxref{Defining Menus}).
+@end defun
+
+@node Active Keymaps
+@section Active Keymaps
+@cindex active keymap
+@cindex global keymap
+@cindex local keymap
+
+  Emacs normally contains many keymaps; at any given time, just a few
+of them are @dfn{active}, meaning that they participate in the
+interpretation of user input.  All the active keymaps are used
+together to determine what command to execute when a key is entered.
+
+  Normally the active keymaps are the @code{keymap} property keymap,
+the keymaps of any enabled minor modes, the current buffer's local
+keymap, and the global keymap, in that order.  Emacs searches for each
+input key sequence in all these keymaps.  @xref{Searching Keymaps},
+for more details of this procedure.
+
+  When the key sequence starts with a mouse event (optionally preceded
+by a symbolic prefix), the active keymaps are determined based on the
+position in that event.  If the event happened on a string embedded
+with a @code{display}, @code{before-string}, or @code{after-string}
+property (@pxref{Special Properties}), the non-@code{nil} map
+properties of the string override those of the buffer.
+
+  The @dfn{global keymap} holds the bindings of keys that are defined
+regardless of the current buffer, such as @kbd{C-f}.  The variable
+@code{global-map} holds this keymap, which is always active.
+
+  Each buffer may have another keymap, its @dfn{local keymap}, which
+may contain new or overriding definitions for keys.  The current
+buffer's local keymap is always active except when
+@code{overriding-local-map} overrides it.  The @code{local-map} text
+or overlay property can specify an alternative local keymap for certain
+parts of the buffer; see @ref{Special Properties}.
+
+  Each minor mode can have a keymap; if it does, the keymap is active
+when the minor mode is enabled.  Modes for emulation can specify
+additional active keymaps through the variable
+@code{emulation-mode-map-alists}.
+
+  The highest precedence normal keymap comes from the @code{keymap}
+text or overlay property.  If that is non-@code{nil}, it is the first
+keymap to be processed, in normal circumstances.
+
+  However, there are also special ways for programs to substitute
+other keymaps for some of those.  The variable
+@code{overriding-local-map}, if non-@code{nil}, specifies a keymap
+that replaces all the usual active keymaps except the global keymap.
+Another way to do this is with @code{overriding-terminal-local-map};
+it operates on a per-terminal basis.  These variables are documented
+below.
+
+@cindex major mode keymap
+  Since every buffer that uses the same major mode normally uses the
+same local keymap, you can think of the keymap as local to the mode.  A
+change to the local keymap of a buffer (using @code{local-set-key}, for
+example) is seen also in the other buffers that share that keymap.
+
+  The local keymaps that are used for Lisp mode and some other major
+modes exist even if they have not yet been used.  These local keymaps are
+the values of variables such as @code{lisp-mode-map}.  For most major
+modes, which are less frequently used, the local keymap is constructed
+only when the mode is used for the first time in a session.
+
+  The minibuffer has local keymaps, too; they contain various completion
+and exit commands.  @xref{Intro to Minibuffers}.
+
+  Emacs has other keymaps that are used in a different way---translating
+events within @code{read-key-sequence}.  @xref{Translation Keymaps}.
+
+  @xref{Standard Keymaps}, for a list of standard keymaps.
+
+@defun current-active-maps &optional olp position
+This returns the list of active keymaps that would be used by the
+command loop in the current circumstances to look up a key sequence.
+Normally it ignores @code{overriding-local-map} and
+@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil}
+then it pays attention to them.  @var{position} can optionally be either
+an event position as returned by @code{event-start} or a buffer
+position, and may change the keymaps as described for
+@code{key-binding}.
+@end defun
+
+@defun key-binding key &optional accept-defaults no-remap position
+This function returns the binding for @var{key} according to the
+current active keymaps.  The result is @code{nil} if @var{key} is
+undefined in the keymaps.
+
+The argument @var{accept-defaults} controls checking for default
+bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}).
+
+When commands are remapped (@pxref{Remapping Commands}),
+@code{key-binding} normally processes command remappings so as to
+returns the remapped command that will actually be executed.  However,
+if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
+remappings and returns the binding directly specified for @var{key}.
+
+If @var{key} starts with a mouse event (perhaps following a prefix
+event), the maps to be consulted are determined based on the event's
+position.  Otherwise, they are determined based on the value of point.
+However, you can override either of them by specifying @var{position}.
+If @var{position} is non-@code{nil}, it should be either a buffer
+position or an event position like the value of @code{event-start}.
+Then the maps consulted are determined based on @var{position}.
+
+An error is signaled if @var{key} is not a string or a vector.
+
+@example
+@group
+(key-binding "\C-x\C-f")
+    @result{} find-file
+@end group
+@end example
+@end defun
+
+@node Searching Keymaps
+@section Searching the Active Keymaps
+@cindex searching active keymaps for keys
+
+  After translation of event subsequences (@pxref{Translation
+Keymaps}) Emacs looks for them in the active keymaps.  Here is a
+pseudo-Lisp description of the order and conditions for searching
+them:
+
+@lisp
+(or (if overriding-terminal-local-map
+        (@var{find-in} overriding-terminal-local-map)
+      (if overriding-local-map
+          (@var{find-in} overriding-local-map)
+        (or (@var{find-in} (get-char-property (point) 'keymap))
+            (@var{find-in-any} emulation-mode-map-alists)
+            (@var{find-in-any} minor-mode-overriding-map-alist)
+            (@var{find-in-any} minor-mode-map-alist)
+            (if (get-text-property (point) 'local-map)
+                (@var{find-in} (get-char-property (point) 'local-map))
+              (@var{find-in} (current-local-map))))))
+    (@var{find-in} (current-global-map)))
+@end lisp
+
+@noindent
+The @var{find-in} and @var{find-in-any} are pseudo functions that
+search in one keymap and in an alist of keymaps, respectively.
+(Searching a single keymap for a binding is called @dfn{key lookup};
+see @ref{Key Lookup}.)  If the key sequence starts with a mouse event,
+or a symbolic prefix event followed by a mouse event, that event's
+position is used instead of point and the current buffer.  Mouse
+events on an embedded string use non-@code{nil} text properties from
+that string instead of the buffer.
+
+@enumerate
+@item
+The function finally found may be remapped
+(@pxref{Remapping Commands}).
+
+@item
+Characters that are bound to @code{self-insert-command} are translated
+according to @code{translation-table-for-input} before insertion.
+
+@item
+@code{current-active-maps} returns a list of the
+currently active keymaps at point.
+
+@item
+When a match is found (@pxref{Key Lookup}), if the binding in the
+keymap is a function, the search is over.  However if the keymap entry
+is a symbol with a value or a string, Emacs replaces the input key
+sequences with the variable's value or the string, and restarts the
+search of the active keymaps.
+@end enumerate
+
+@node Controlling Active Maps
+@section Controlling the Active Keymaps
+
+@defvar global-map
+This variable contains the default global keymap that maps Emacs
+keyboard input to commands.  The global keymap is normally this
+keymap.  The default global keymap is a full keymap that binds
+@code{self-insert-command} to all of the printing characters.
+
+It is normal practice to change the bindings in the global keymap, but you
+should not assign this variable any value other than the keymap it starts
+out with.
+@end defvar
+
+@defun current-global-map
+This function returns the current global keymap.  This is the
+same as the value of @code{global-map} unless you change one or the
+other.
+
+@example
+@group
+(current-global-map)
+@result{} (keymap [set-mark-command beginning-of-line @dots{}
+            delete-backward-char])
+@end group
+@end example
+@end defun
+
+@defun current-local-map
+This function returns the current buffer's local keymap, or @code{nil}
+if it has none.  In the following example, the keymap for the
+@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
+in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
+keymap.
+
+@example
+@group
+(current-local-map)
+@result{} (keymap
+    (10 . eval-print-last-sexp)
+    (9 . lisp-indent-line)
+    (127 . backward-delete-char-untabify)
+@end group
+@group
+    (27 keymap
+        (24 . eval-defun)
+        (17 . indent-sexp)))
+@end group
+@end example
+@end defun
+
+@defun current-minor-mode-maps
+This function returns a list of the keymaps of currently enabled minor modes.
+@end defun
+
+@defun use-global-map keymap
+This function makes @var{keymap} the new current global keymap.  It
+returns @code{nil}.
+
+It is very unusual to change the global keymap.
+@end defun
+
+@defun use-local-map keymap
+This function makes @var{keymap} the new local keymap of the current
+buffer.  If @var{keymap} is @code{nil}, then the buffer has no local
+keymap.  @code{use-local-map} returns @code{nil}.  Most major mode
+commands use this function.
+@end defun
+
+@c Emacs 19 feature
+@defvar minor-mode-map-alist
+@anchor{Definition of minor-mode-map-alist}
+This variable is an alist describing keymaps that may or may not be
+active according to the values of certain variables.  Its elements look
+like this:
+
+@example
+(@var{variable} . @var{keymap})
+@end example
+
+The keymap @var{keymap} is active whenever @var{variable} has a
+non-@code{nil} value.  Typically @var{variable} is the variable that
+enables or disables a minor mode.  @xref{Keymaps and Minor Modes}.
+
+Note that elements of @code{minor-mode-map-alist} do not have the same
+structure as elements of @code{minor-mode-alist}.  The map must be the
+@sc{cdr} of the element; a list with the map as the second element will
+not do.  The @sc{cdr} can be either a keymap (a list) or a symbol whose
+function definition is a keymap.
+
+When more than one minor mode keymap is active, the earlier one in
+@code{minor-mode-map-alist} takes priority.  But you should design
+minor modes so that they don't interfere with each other.  If you do
+this properly, the order will not matter.
+
+See @ref{Keymaps and Minor Modes}, for more information about minor
+modes.  See also @code{minor-mode-key-binding} (@pxref{Functions for Key
+Lookup}).
+@end defvar
+
+@defvar minor-mode-overriding-map-alist
+This variable allows major modes to override the key bindings for
+particular minor modes.  The elements of this alist look like the
+elements of @code{minor-mode-map-alist}: @code{(@var{variable}
+. @var{keymap})}.
+
+If a variable appears as an element of
+@code{minor-mode-overriding-map-alist}, the map specified by that
+element totally replaces any map specified for the same variable in
+@code{minor-mode-map-alist}.
+
+@code{minor-mode-overriding-map-alist} is automatically buffer-local in
+all buffers.
+@end defvar
+
+@defvar overriding-local-map
+If non-@code{nil}, this variable holds a keymap to use instead of the
+buffer's local keymap, any text property or overlay keymaps, and any
+minor mode keymaps.  This keymap, if specified, overrides all other
+maps that would have been active, except for the current global map.
+@end defvar
+
+@defvar overriding-terminal-local-map
+If non-@code{nil}, this variable holds a keymap to use instead of
+@code{overriding-local-map}, the buffer's local keymap, text property
+or overlay keymaps, and all the minor mode keymaps.
+
+This variable is always local to the current terminal and cannot be
+buffer-local.  @xref{Multiple Displays}.  It is used to implement
+incremental search mode.
+@end defvar
+
+@defvar overriding-local-map-menu-flag
+If this variable is non-@code{nil}, the value of
+@code{overriding-local-map} or @code{overriding-terminal-local-map} can
+affect the display of the menu bar.  The default value is @code{nil}, so
+those map variables have no effect on the menu bar.
+
+Note that these two map variables do affect the execution of key
+sequences entered using the menu bar, even if they do not affect the
+menu bar display.  So if a menu bar key sequence comes in, you should
+clear the variables before looking up and executing that key sequence.
+Modes that use the variables would typically do this anyway; normally
+they respond to events that they do not handle by ``unreading'' them and
+exiting.
+@end defvar
+
+@defvar special-event-map
+This variable holds a keymap for special events.  If an event type has a
+binding in this keymap, then it is special, and the binding for the
+event is run directly by @code{read-event}.  @xref{Special Events}.
+@end defvar
+
+@defvar emulation-mode-map-alists
+This variable holds a list of keymap alists to use for emulations
+modes.  It is intended for modes or packages using multiple minor-mode
+keymaps.  Each element is a keymap alist which has the same format and
+meaning as @code{minor-mode-map-alist}, or a symbol with a variable
+binding which is such an alist.  The ``active'' keymaps in each alist
+are used before @code{minor-mode-map-alist} and
+@code{minor-mode-overriding-map-alist}.
+@end defvar
+
+@node Key Lookup
+@section Key Lookup
+@cindex key lookup
+@cindex keymap entry
+
+  @dfn{Key lookup} is the process of finding the binding of a key
+sequence from a given keymap.  The execution or use of the binding is
+not part of key lookup.
+
+  Key lookup uses just the event type of each event in the key sequence;
+the rest of the event is ignored.  In fact, a key sequence used for key
+lookup may designate a mouse event with just its types (a symbol)
+instead of the entire event (a list).  @xref{Input Events}.  Such
+a ``key sequence'' is insufficient for @code{command-execute} to run,
+but it is sufficient for looking up or rebinding a key.
+
+  When the key sequence consists of multiple events, key lookup
+processes the events sequentially: the binding of the first event is
+found, and must be a keymap; then the second event's binding is found in
+that keymap, and so on until all the events in the key sequence are used
+up.  (The binding thus found for the last event may or may not be a
+keymap.)  Thus, the process of key lookup is defined in terms of a
+simpler process for looking up a single event in a keymap.  How that is
+done depends on the type of object associated with the event in that
+keymap.
+
+  Let's use the term @dfn{keymap entry} to describe the value found by
+looking up an event type in a keymap.  (This doesn't include the item
+string and other extra elements in a keymap element for a menu item, because
+@code{lookup-key} and other key lookup functions don't include them in
+the returned value.)  While any Lisp object may be stored in a keymap
+as a keymap entry, not all make sense for key lookup.  Here is a table
+of the meaningful types of keymap entries:
+
+@table @asis
+@item @code{nil}
+@cindex @code{nil} in keymap
+@code{nil} means that the events used so far in the lookup form an
+undefined key.  When a keymap fails to mention an event type at all, and
+has no default binding, that is equivalent to a binding of @code{nil}
+for that event type.
+
+@item @var{command}
+@cindex command in keymap
+The events used so far in the lookup form a complete key,
+and @var{command} is its binding.  @xref{What Is a Function}.
+
+@item @var{array}
+@cindex string in keymap
+The array (either a string or a vector) is a keyboard macro.  The events
+used so far in the lookup form a complete key, and the array is its
+binding.  See @ref{Keyboard Macros}, for more information.
+
+@item @var{keymap}
+@cindex keymap in keymap
+The events used so far in the lookup form a prefix key.  The next
+event of the key sequence is looked up in @var{keymap}.
+
+@item @var{list}
+@cindex list in keymap
+The meaning of a list depends on what it contains:
+
+@itemize @bullet
+@item
+If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
+is a keymap, and is treated as a keymap (see above).
+
+@item
+@cindex @code{lambda} in keymap
+If the @sc{car} of @var{list} is @code{lambda}, then the list is a
+lambda expression.  This is presumed to be a function, and is treated
+as such (see above).  In order to execute properly as a key binding,
+this function must be a command---it must have an @code{interactive}
+specification.  @xref{Defining Commands}.
+
+@item
+If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
+type, then this is an @dfn{indirect entry}:
+
+@example
+(@var{othermap} . @var{othertype})
+@end example
+
+When key lookup encounters an indirect entry, it looks up instead the
+binding of @var{othertype} in @var{othermap} and uses that.
+
+This feature permits you to define one key as an alias for another key.
+For example, an entry whose @sc{car} is the keymap called @code{esc-map}
+and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
+binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
+@end itemize
+
+@item @var{symbol}
+@cindex symbol in keymap
+The function definition of @var{symbol} is used in place of
+@var{symbol}.  If that too is a symbol, then this process is repeated,
+any number of times.  Ultimately this should lead to an object that is
+a keymap, a command, or a keyboard macro.  A list is allowed if it is a
+keymap or a command, but indirect entries are not understood when found
+via symbols.
+
+Note that keymaps and keyboard macros (strings and vectors) are not
+valid functions, so a symbol with a keymap, string, or vector as its
+function definition is invalid as a function.  It is, however, valid as
+a key binding.  If the definition is a keyboard macro, then the symbol
+is also valid as an argument to @code{command-execute}
+(@pxref{Interactive Call}).
+
+@cindex @code{undefined} in keymap
+The symbol @code{undefined} is worth special mention: it means to treat
+the key as undefined.  Strictly speaking, the key is defined, and its
+binding is the command @code{undefined}; but that command does the same
+thing that is done automatically for an undefined key: it rings the bell
+(by calling @code{ding}) but does not signal an error.
+
+@cindex preventing prefix key
+@code{undefined} is used in local keymaps to override a global key
+binding and make the key ``undefined'' locally.  A local binding of
+@code{nil} would fail to do this because it would not override the
+global binding.
+
+@item @var{anything else}
+If any other type of object is found, the events used so far in the
+lookup form a complete key, and the object is its binding, but the
+binding is not executable as a command.
+@end table
+
+  In short, a keymap entry may be a keymap, a command, a keyboard macro,
+a symbol that leads to one of them, or an indirection or @code{nil}.
+Here is an example of a sparse keymap with two characters bound to
+commands and one bound to another keymap.  This map is the normal value
+of @code{emacs-lisp-mode-map}.  Note that 9 is the code for @key{TAB},
+127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
+@kbd{C-x}.
+
+@example
+@group
+(keymap (9 . lisp-indent-line)
+        (127 . backward-delete-char-untabify)
+        (27 keymap (17 . indent-sexp) (24 . eval-defun)))
+@end group
+@end example
+
+@node Functions for Key Lookup
+@section Functions for Key Lookup
+
+  Here are the functions and variables pertaining to key lookup.
+
+@defun lookup-key keymap key &optional accept-defaults
+This function returns the definition of @var{key} in @var{keymap}.  All
+the other functions described in this chapter that look up keys use
+@code{lookup-key}.  Here are examples:
+
+@example
+@group
+(lookup-key (current-global-map) "\C-x\C-f")
+    @result{} find-file
+@end group
+@group
+(lookup-key (current-global-map) (kbd "C-x C-f"))
+    @result{} find-file
+@end group
+@group
+(lookup-key (current-global-map) "\C-x\C-f12345")
+    @result{} 2
+@end group
+@end example
+
+If the string or vector @var{key} is not a valid key sequence according
+to the prefix keys specified in @var{keymap}, it must be ``too long''
+and have extra events at the end that do not fit into a single key
+sequence.  Then the value is a number, the number of events at the front
+of @var{key} that compose a complete key.
+
+@c Emacs 19 feature
+If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
+considers default bindings as well as bindings for the specific events
+in @var{key}.  Otherwise, @code{lookup-key} reports only bindings for
+the specific sequence @var{key}, ignoring default bindings except when
+you explicitly ask about them.  (To do this, supply @code{t} as an
+element of @var{key}; see @ref{Format of Keymaps}.)
+
+If @var{key} contains a meta character (not a function key), that
+character is implicitly replaced by a two-character sequence: the value
+of @code{meta-prefix-char}, followed by the corresponding non-meta
+character.  Thus, the first example below is handled by conversion into
+the second example.
+
+@example
+@group
+(lookup-key (current-global-map) "\M-f")
+    @result{} forward-word
+@end group
+@group
+(lookup-key (current-global-map) "\ef")
+    @result{} forward-word
+@end group
+@end example
+
+Unlike @code{read-key-sequence}, this function does not modify the
+specified events in ways that discard information (@pxref{Key Sequence
+Input}).  In particular, it does not convert letters to lower case and
+it does not change drag events to clicks.
+@end defun
+
+@deffn Command undefined
+Used in keymaps to undefine keys.  It calls @code{ding}, but does
+not cause an error.
+@end deffn
+
+@defun local-key-binding key &optional accept-defaults
+This function returns the binding for @var{key} in the current
+local keymap, or @code{nil} if it is undefined there.
+
+@c Emacs 19 feature
+The argument @var{accept-defaults} controls checking for default bindings,
+as in @code{lookup-key} (above).
+@end defun
+
+@defun global-key-binding key &optional accept-defaults
+This function returns the binding for command @var{key} in the
+current global keymap, or @code{nil} if it is undefined there.
+
+@c Emacs 19 feature
+The argument @var{accept-defaults} controls checking for default bindings,
+as in @code{lookup-key} (above).
+@end defun
+
+@c Emacs 19 feature
+@defun minor-mode-key-binding key &optional accept-defaults
+This function returns a list of all the active minor mode bindings of
+@var{key}.  More precisely, it returns an alist of pairs
+@code{(@var{modename} . @var{binding})}, where @var{modename} is the
+variable that enables the minor mode, and @var{binding} is @var{key}'s
+binding in that mode.  If @var{key} has no minor-mode bindings, the
+value is @code{nil}.
+
+If the first binding found is not a prefix definition (a keymap or a
+symbol defined as a keymap), all subsequent bindings from other minor
+modes are omitted, since they would be completely shadowed.  Similarly,
+the list omits non-prefix bindings that follow prefix bindings.
+
+The argument @var{accept-defaults} controls checking for default
+bindings, as in @code{lookup-key} (above).
+@end defun
+
+@defvar meta-prefix-char
+@cindex @key{ESC}
+This variable is the meta-prefix character code.  It is used for
+translating a meta character to a two-character sequence so it can be
+looked up in a keymap.  For useful results, the value should be a
+prefix event (@pxref{Prefix Keys}).  The default value is 27, which is
+the @acronym{ASCII} code for @key{ESC}.
+
+As long as the value of @code{meta-prefix-char} remains 27, key lookup
+translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined
+as the @code{backward-word} command.  However, if you were to set
+@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
+translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
+@code{switch-to-buffer} command.  (Don't actually do this!)  Here is an
+illustration of what would happen:
+
+@smallexample
+@group
+meta-prefix-char                    ; @r{The default value.}
+     @result{} 27
+@end group
+@group
+(key-binding "\M-b")
+     @result{} backward-word
+@end group
+@group
+?\C-x                               ; @r{The print representation}
+     @result{} 24                          ;   @r{of a character.}
+@end group
+@group
+(setq meta-prefix-char 24)
+     @result{} 24
+@end group
+@group
+(key-binding "\M-b")
+     @result{} switch-to-buffer            ; @r{Now, typing @kbd{M-b} is}
+                                    ;   @r{like typing @kbd{C-x b}.}
+
+(setq meta-prefix-char 27)          ; @r{Avoid confusion!}
+     @result{} 27                          ; @r{Restore the default value!}
+@end group
+@end smallexample
+
+This translation of one event into two happens only for characters, not
+for other kinds of input events.  Thus, @kbd{M-@key{F1}}, a function
+key, is not converted into @kbd{@key{ESC} @key{F1}}.
+@end defvar
+
+@node Changing Key Bindings
+@section Changing Key Bindings
+@cindex changing key bindings
+@cindex rebinding
+
+  The way to rebind a key is to change its entry in a keymap.  If you
+change a binding in the global keymap, the change is effective in all
+buffers (though it has no direct effect in buffers that shadow the
+global binding with a local one).  If you change the current buffer's
+local map, that usually affects all buffers using the same major mode.
+The @code{global-set-key} and @code{local-set-key} functions are
+convenient interfaces for these operations (@pxref{Key Binding
+Commands}).  You can also use @code{define-key}, a more general
+function; then you must specify explicitly the map to change.
+
+  When choosing the key sequences for Lisp programs to rebind, please
+follow the Emacs conventions for use of various keys (@pxref{Key
+Binding Conventions}).
+
+@cindex meta character key constants
+@cindex control character key constants
+  In writing the key sequence to rebind, it is good to use the special
+escape sequences for control and meta characters (@pxref{String Type}).
+The syntax @samp{\C-} means that the following character is a control
+character and @samp{\M-} means that the following character is a meta
+character.  Thus, the string @code{"\M-x"} is read as containing a
+single @kbd{M-x}, @code{"\C-f"} is read as containing a single
+@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
+containing a single @kbd{C-M-x}.  You can also use this escape syntax in
+vectors, as well as others that aren't allowed in strings; one example
+is @samp{[?\C-\H-x home]}.  @xref{Character Type}.
+
+  The key definition and lookup functions accept an alternate syntax for
+event types in a key sequence that is a vector: you can use a list
+containing modifier names plus one base event (a character or function
+key name).  For example, @code{(control ?a)} is equivalent to
+@code{?\C-a} and @code{(hyper control left)} is equivalent to
+@code{C-H-left}.  One advantage of such lists is that the precise
+numeric codes for the modifier bits don't appear in compiled files.
+
+  The functions below signal an error if @var{keymap} is not a keymap,
+or if @var{key} is not a string or vector representing a key sequence.
+You can use event types (symbols) as shorthand for events that are
+lists.  The @code{kbd} macro (@pxref{Key Sequences}) is a convenient
+way to specify the key sequence.
+
+@defun define-key keymap key binding
+This function sets the binding for @var{key} in @var{keymap}.  (If
+@var{key} is more than one event long, the change is actually made
+in another keymap reached from @var{keymap}.)  The argument
+@var{binding} can be any Lisp object, but only certain types are
+meaningful.  (For a list of meaningful types, see @ref{Key Lookup}.)
+The value returned by @code{define-key} is @var{binding}.
+
+If @var{key} is @code{[t]}, this sets the default binding in
+@var{keymap}.  When an event has no binding of its own, the Emacs
+command loop uses the keymap's default binding, if there is one.
+
+@cindex invalid prefix key error
+@cindex key sequence error
+Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
+or undefined; otherwise an error is signaled.  If some prefix of
+@var{key} is undefined, then @code{define-key} defines it as a prefix
+key so that the rest of @var{key} can be defined as specified.
+
+If there was previously no binding for @var{key} in @var{keymap}, the
+new binding is added at the beginning of @var{keymap}.  The order of
+bindings in a keymap makes no difference for keyboard input, but it
+does matter for menu keymaps (@pxref{Menu Keymaps}).
+@end defun
+
+  This example creates a sparse keymap and makes a number of
+bindings in it:
+
+@smallexample
+@group
+(setq map (make-sparse-keymap))
+    @result{} (keymap)
+@end group
+@group
+(define-key map "\C-f" 'forward-char)
+    @result{} forward-char
+@end group
+@group
+map
+    @result{} (keymap (6 . forward-char))
+@end group
+
+@group
+;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
+(define-key map (kbd "C-x f") 'forward-word)
+    @result{} forward-word
+@end group
+@group
+map
+@result{} (keymap
+    (24 keymap                ; @kbd{C-x}
+        (102 . forward-word)) ;      @kbd{f}
+    (6 . forward-char))       ; @kbd{C-f}
+@end group
+
+@group
+;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
+(define-key map (kbd "C-p") ctl-x-map)
+;; @code{ctl-x-map}
+@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
+@end group
+
+@group
+;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
+(define-key map (kbd "C-p C-f") 'foo)
+@result{} 'foo
+@end group
+@group
+map
+@result{} (keymap     ; @r{Note @code{foo} in @code{ctl-x-map}.}
+    (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
+    (24 keymap
+        (102 . forward-word))
+    (6 . forward-char))
+@end group
+@end smallexample
+
+@noindent
+Note that storing a new binding for @kbd{C-p C-f} actually works by
+changing an entry in @code{ctl-x-map}, and this has the effect of
+changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
+default global map.
+
+  The function @code{substitute-key-definition} scans a keymap for
+keys that have a certain binding and rebinds them with a different
+binding.  Another feature which is cleaner and can often produce the
+same results to remap one command into another (@pxref{Remapping
+Commands}).
+
+@defun substitute-key-definition olddef newdef keymap &optional oldmap
+@cindex replace bindings
+This function replaces @var{olddef} with @var{newdef} for any keys in
+@var{keymap} that were bound to @var{olddef}.  In other words,
+@var{olddef} is replaced with @var{newdef} wherever it appears.  The
+function returns @code{nil}.
+
+For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
+standard bindings:
+
+@smallexample
+@group
+(substitute-key-definition
+ 'find-file 'find-file-read-only (current-global-map))
+@end group
+@end smallexample
+
+@c Emacs 19 feature
+If @var{oldmap} is non-@code{nil}, that changes the behavior of
+@code{substitute-key-definition}: the bindings in @var{oldmap} determine
+which keys to rebind.  The rebindings still happen in @var{keymap}, not
+in @var{oldmap}.  Thus, you can change one map under the control of the
+bindings in another.  For example,
+
+@smallexample
+(substitute-key-definition
+  'delete-backward-char 'my-funny-delete
+  my-map global-map)
+@end smallexample
+
+@noindent
+puts the special deletion command in @code{my-map} for whichever keys
+are globally bound to the standard deletion command.
+
+Here is an example showing a keymap before and after substitution:
+
+@smallexample
+@group
+(setq map '(keymap
+            (?1 . olddef-1)
+            (?2 . olddef-2)
+            (?3 . olddef-1)))
+@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
+@end group
+
+@group
+(substitute-key-definition 'olddef-1 'newdef map)
+@result{} nil
+@end group
+@group
+map
+@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
+@end group
+@end smallexample
+@end defun
+
+@defun suppress-keymap keymap &optional nodigits
+@cindex @code{self-insert-command} override
+This function changes the contents of the full keymap @var{keymap} by
+remapping @code{self-insert-command} to the command @code{undefined}
+(@pxref{Remapping Commands}).  This has the effect of undefining all
+printing characters, thus making ordinary insertion of text impossible.
+@code{suppress-keymap} returns @code{nil}.
+
+If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
+digits to run @code{digit-argument}, and @kbd{-} to run
+@code{negative-argument}.  Otherwise it makes them undefined like the
+rest of the printing characters.
+
+@cindex yank suppression
+@cindex @code{quoted-insert} suppression
+The @code{suppress-keymap} function does not make it impossible to
+modify a buffer, as it does not suppress commands such as @code{yank}
+and @code{quoted-insert}.  To prevent any modification of a buffer, make
+it read-only (@pxref{Read Only Buffers}).
+
+Since this function modifies @var{keymap}, you would normally use it
+on a newly created keymap.  Operating on an existing keymap
+that is used for some other purpose is likely to cause trouble; for
+example, suppressing @code{global-map} would make it impossible to use
+most of Emacs.
+
+Most often, @code{suppress-keymap} is used to initialize local
+keymaps of modes such as Rmail and Dired where insertion of text is not
+desirable and the buffer is read-only.  Here is an example taken from
+the file @file{emacs/lisp/dired.el}, showing how the local keymap for
+Dired mode is set up:
+
+@smallexample
+@group
+(setq dired-mode-map (make-keymap))
+(suppress-keymap dired-mode-map)
+(define-key dired-mode-map "r" 'dired-rename-file)
+(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
+(define-key dired-mode-map "d" 'dired-flag-file-deleted)
+(define-key dired-mode-map "v" 'dired-view-file)
+(define-key dired-mode-map "e" 'dired-find-file)
+(define-key dired-mode-map "f" 'dired-find-file)
+@dots{}
+@end group
+@end smallexample
+@end defun
+
+@node Remapping Commands
+@section Remapping Commands
+@cindex remapping commands
+
+  A special kind of key binding, using a special ``key sequence''
+which includes a command name, has the effect of @dfn{remapping} that
+command into another.  Here's how it works.  You make a key binding
+for a key sequence that starts with the dummy event @code{remap},
+followed by the command name you want to remap.  Specify the remapped
+definition as the definition in this binding.  The remapped definition
+is usually a command name, but it can be any valid definition for
+a key binding.
+
+  Here's an example.  Suppose that My mode uses special commands
+@code{my-kill-line} and @code{my-kill-word}, which should be invoked
+instead of @code{kill-line} and @code{kill-word}.  It can establish
+this by making these two command-remapping bindings in its keymap:
+
+@smallexample
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap kill-word] 'my-kill-word)
+@end smallexample
+
+Whenever @code{my-mode-map} is an active keymap, if the user types
+@kbd{C-k}, Emacs will find the standard global binding of
+@code{kill-line} (assuming nobody has changed it).  But
+@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
+so instead of running @code{kill-line}, Emacs runs
+@code{my-kill-line}.
+
+Remapping only works through a single level.  In other words,
+
+@smallexample
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
+@end smallexample
+
+@noindent
+does not have the effect of remapping @code{kill-line} into
+@code{my-other-kill-line}.  If an ordinary key binding specifies
+@code{kill-line}, this keymap will remap it to @code{my-kill-line};
+if an ordinary binding specifies @code{my-kill-line}, this keymap will
+remap it to @code{my-other-kill-line}.
+
+@defun command-remapping command &optional position keymaps
+This function returns the remapping for @var{command} (a symbol),
+given the current active keymaps.  If @var{command} is not remapped
+(which is the usual situation), or not a symbol, the function returns
+@code{nil}.  @code{position} can optionally specify a buffer position
+or an event position to determine the keymaps to use, as in
+@code{key-binding}.
+
+If the optional argument @code{keymaps} is non-@code{nil}, it
+specifies a list of keymaps to search in.  This argument is ignored if
+@code{position} is non-@code{nil}.
+@end defun
+
+@node Translation Keymaps
+@section Keymaps for Translating Sequences of Events
+@cindex keymaps for translating events
+
+  This section describes keymaps that are used during reading a key
+sequence, to translate certain event sequences into others.
+@code{read-key-sequence} checks every subsequence of the key sequence
+being read, as it is read, against @code{function-key-map} and then
+against @code{key-translation-map}.
+
+@defvar function-key-map
+This variable holds a keymap that describes the character sequences sent
+by function keys on an ordinary character terminal.  This keymap has the
+same structure as other keymaps, but is used differently: it specifies
+translations to make while reading key sequences, rather than bindings
+for key sequences.
+
+If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
+@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
+key sequence, it is replaced with the events in @var{v}.
+
+For example, VT100 terminals send @kbd{@key{ESC} O P} when the
+keypad @key{PF1} key is pressed.  Therefore, we want Emacs to translate
+that sequence of events into the single event @code{pf1}.  We accomplish
+this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
+@code{function-key-map}, when using a VT100.
+
+Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
+@key{ESC} O P}; later the function @code{read-key-sequence} translates
+this back into @kbd{C-c @key{PF1}}, which it returns as the vector
+@code{[?\C-c pf1]}.
+
+Entries in @code{function-key-map} are ignored if they conflict with
+bindings made in the minor mode, local, or global keymaps.  The intent
+is that the character sequences that function keys send should not have
+command bindings in their own right---but if they do, the ordinary
+bindings take priority.
+
+The value of @code{function-key-map} is usually set up automatically
+according to the terminal's Terminfo or Termcap entry, but sometimes
+those need help from terminal-specific Lisp files.  Emacs comes with
+terminal-specific files for many common terminals; their main purpose is
+to make entries in @code{function-key-map} beyond those that can be
+deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.
+@end defvar
+
+@defvar key-translation-map
+This variable is another keymap used just like @code{function-key-map}
+to translate input events into other events.  It differs from
+@code{function-key-map} in two ways:
+
+@itemize @bullet
+@item
+@code{key-translation-map} goes to work after @code{function-key-map} is
+finished; it receives the results of translation by
+@code{function-key-map}.
+
+@item
+Non-prefix bindings in @code{key-translation-map} override actual key
+bindings.  For example, if @kbd{C-x f} has a non-prefix binding in
+@code{key-translation-map}, that translation takes effect even though
+@kbd{C-x f} also has a key binding in the global map.
+@end itemize
+
+Note however that actual key bindings can have an effect on
+@code{key-translation-map}, even though they are overridden by it.
+Indeed, actual key bindings override @code{function-key-map} and thus
+may alter the key sequence that @code{key-translation-map} receives.
+Clearly, it is better to avoid this type of situation.
+
+The intent of @code{key-translation-map} is for users to map one
+character set to another, including ordinary characters normally bound
+to @code{self-insert-command}.
+@end defvar
+
+@cindex key translation function
+You can use @code{function-key-map} or @code{key-translation-map} for
+more than simple aliases, by using a function, instead of a key
+sequence, as the ``translation'' of a key.  Then this function is called
+to compute the translation of that key.
+
+The key translation function receives one argument, which is the prompt
+that was specified in @code{read-key-sequence}---or @code{nil} if the
+key sequence is being read by the editor command loop.  In most cases
+you can ignore the prompt value.
+
+If the function reads input itself, it can have the effect of altering
+the event that follows.  For example, here's how to define @kbd{C-c h}
+to turn the character that follows into a Hyper character:
+
+@example
+@group
+(defun hyperify (prompt)
+  (let ((e (read-event)))
+    (vector (if (numberp e)
+                (logior (lsh 1 24) e)
+              (if (memq 'hyper (event-modifiers e))
+                  e
+                (add-event-modifier "H-" e))))))
+
+(defun add-event-modifier (string e)
+  (let ((symbol (if (symbolp e) e (car e))))
+    (setq symbol (intern (concat string
+                                 (symbol-name symbol))))
+@end group
+@group
+    (if (symbolp e)
+        symbol
+      (cons symbol (cdr e)))))
+
+(define-key function-key-map "\C-ch" 'hyperify)
+@end group
+@end example
+
+  If you have enabled keyboard character set decoding using
+@code{set-keyboard-coding-system}, decoding is done after the
+translations listed above.  @xref{Terminal I/O Encoding}.  However, in
+future Emacs versions, character set decoding may be done at an
+earlier stage.
+
+@node Key Binding Commands
+@section Commands for Binding Keys
+
+  This section describes some convenient interactive interfaces for
+changing key bindings.  They work by calling @code{define-key}.
+
+  People often use @code{global-set-key} in their init files
+(@pxref{Init File}) for simple customization.  For example,
+
+@smallexample
+(global-set-key (kbd "C-x C-\\") 'next-line)
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+(global-set-key [?\C-x ?\C-\\] 'next-line)
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+(global-set-key [(control ?x) (control ?\\)] 'next-line)
+@end smallexample
+
+@noindent
+redefines @kbd{C-x C-\} to move down a line.
+
+@smallexample
+(global-set-key [M-mouse-1] 'mouse-set-point)
+@end smallexample
+
+@noindent
+redefines the first (leftmost) mouse button, entered with the Meta key, to
+set point where you click.
+
+@cindex non-@acronym{ASCII} text in keybindings
+  Be careful when using non-@acronym{ASCII} text characters in Lisp
+specifications of keys to bind.  If these are read as multibyte text, as
+they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
+must type the keys as multibyte too.  For instance, if you use this:
+
+@smallexample
+(global-set-key "@"o" 'my-function) ; bind o-umlaut
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+(global-set-key ?@"o 'my-function) ; bind o-umlaut
+@end smallexample
+
+@noindent
+and your language environment is multibyte Latin-1, these commands
+actually bind the multibyte character with code 2294, not the unibyte
+Latin-1 character with code 246 (@kbd{M-v}).  In order to use this
+binding, you need to enter the multibyte Latin-1 character as keyboard
+input.  One way to do this is by using an appropriate input method
+(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).
+
+  If you want to use a unibyte character in the key binding, you can
+construct the key sequence string using @code{multibyte-char-to-unibyte}
+or @code{string-make-unibyte} (@pxref{Converting Representations}).
+
+@deffn Command global-set-key key binding
+This function sets the binding of @var{key} in the current global map
+to @var{binding}.
+
+@smallexample
+@group
+(global-set-key @var{key} @var{binding})
+@equiv{}
+(define-key (current-global-map) @var{key} @var{binding})
+@end group
+@end smallexample
+@end deffn
+
+@deffn Command global-unset-key key
+@cindex unbinding keys
+This function removes the binding of @var{key} from the current
+global map.
+
+One use of this function is in preparation for defining a longer key
+that uses @var{key} as a prefix---which would not be allowed if
+@var{key} has a non-prefix binding.  For example:
+
+@smallexample
+@group
+(global-unset-key "\C-l")
+    @result{} nil
+@end group
+@group
+(global-set-key "\C-l\C-l" 'redraw-display)
+    @result{} nil
+@end group
+@end smallexample
+
+This function is implemented simply using @code{define-key}:
+
+@smallexample
+@group
+(global-unset-key @var{key})
+@equiv{}
+(define-key (current-global-map) @var{key} nil)
+@end group
+@end smallexample
+@end deffn
+
+@deffn Command local-set-key key binding
+This function sets the binding of @var{key} in the current local
+keymap to @var{binding}.
+
+@smallexample
+@group
+(local-set-key @var{key} @var{binding})
+@equiv{}
+(define-key (current-local-map) @var{key} @var{binding})
+@end group
+@end smallexample
+@end deffn
+
+@deffn Command local-unset-key key
+This function removes the binding of @var{key} from the current
+local map.
+
+@smallexample
+@group
+(local-unset-key @var{key})
+@equiv{}
+(define-key (current-local-map) @var{key} nil)
+@end group
+@end smallexample
+@end deffn
+
+@node Scanning Keymaps
+@section Scanning Keymaps
+
+  This section describes functions used to scan all the current keymaps
+for the sake of printing help information.
+
+@defun accessible-keymaps keymap &optional prefix
+This function returns a list of all the keymaps that can be reached (via
+zero or more prefix keys) from @var{keymap}.  The value is an
+association list with elements of the form @code{(@var{key} .@:
+@var{map})}, where @var{key} is a prefix key whose definition in
+@var{keymap} is @var{map}.
+
+The elements of the alist are ordered so that the @var{key} increases
+in length.  The first element is always @code{([] .@: @var{keymap})},
+because the specified keymap is accessible from itself with a prefix of
+no events.
+
+If @var{prefix} is given, it should be a prefix key sequence; then
+@code{accessible-keymaps} includes only the submaps whose prefixes start
+with @var{prefix}.  These elements look just as they do in the value of
+@code{(accessible-keymaps)}; the only difference is that some elements
+are omitted.
+
+In the example below, the returned alist indicates that the key
+@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
+definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
+(115 .@: foo))}.
+
+@smallexample
+@group
+(accessible-keymaps (current-local-map))
+@result{}(([] keymap
+      (27 keymap   ; @r{Note this keymap for @key{ESC} is repeated below.}
+          (83 . center-paragraph)
+          (115 . center-line))
+      (9 . tab-to-tab-stop))
+@end group
+
+@group
+   ("^[" keymap
+    (83 . center-paragraph)
+    (115 . foo)))
+@end group
+@end smallexample
+
+In the following example, @kbd{C-h} is a prefix key that uses a sparse
+keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
+Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of
+the variable @code{ctl-x-4-map}.  The event @code{mode-line} is one of
+several dummy events used as prefixes for mouse actions in special parts
+of a window.
+
+@smallexample
+@group
+(accessible-keymaps (current-global-map))
+@result{} (([] keymap [set-mark-command beginning-of-line @dots{}
+                   delete-backward-char])
+@end group
+@group
+    ("^H" keymap (118 . describe-variable) @dots{}
+     (8 . help-for-help))
+@end group
+@group
+    ("^X" keymap [x-flush-mouse-queue @dots{}
+     backward-kill-sentence])
+@end group
+@group
+    ("^[" keymap [mark-sexp backward-sexp @dots{}
+     backward-kill-word])
+@end group
+    ("^X4" keymap (15 . display-buffer) @dots{})
+@group
+    ([mode-line] keymap
+     (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
+@end group
+@end smallexample
+
+@noindent
+These are not all the keymaps you would see in actuality.
+@end defun
+
+@defun map-keymap function keymap
+The function @code{map-keymap} calls @var{function} once
+for each binding in @var{keymap}.  It passes two arguments,
+the event type and the value of the binding.  If @var{keymap}
+has a parent, the parent's bindings are included as well.
+This works recursively: if the parent has itself a parent, then the
+grandparent's bindings are also included and so on.
+
+This function is the cleanest way to examine all the bindings
+in a keymap.
+@end defun
+
+@defun where-is-internal command &optional keymap firstonly noindirect no-remap
+This function is a subroutine used by the @code{where-is} command
+(@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list
+of all key sequences (of any length) that are bound to @var{command} in a
+set of keymaps.
+
+The argument @var{command} can be any object; it is compared with all
+keymap entries using @code{eq}.
+
+If @var{keymap} is @code{nil}, then the maps used are the current active
+keymaps, disregarding @code{overriding-local-map} (that is, pretending
+its value is @code{nil}).  If @var{keymap} is a keymap, then the
+maps searched are @var{keymap} and the global keymap.  If @var{keymap}
+is a list of keymaps, only those keymaps are searched.
+
+Usually it's best to use @code{overriding-local-map} as the expression
+for @var{keymap}.  Then @code{where-is-internal} searches precisely the
+keymaps that are active.  To search only the global map, pass
+@code{(keymap)} (an empty keymap) as @var{keymap}.
+
+If @var{firstonly} is @code{non-ascii}, then the value is a single
+vector representing the first key sequence found, rather than a list of
+all possible key sequences.  If @var{firstonly} is @code{t}, then the
+value is the first key sequence, except that key sequences consisting
+entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
+characters) are preferred to all other key sequences and that the
+return value can never be a menu binding.
+
+If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
+follow indirect keymap bindings.  This makes it possible to search for
+an indirect definition itself.
+
+When command remapping is in effect (@pxref{Remapping Commands}),
+@code{where-is-internal} figures out when a command will be run due to
+remapping and reports keys accordingly.  It also returns @code{nil} if
+@var{command} won't really be run because it has been remapped to some
+other command.  However, if @var{no-remap} is non-@code{nil}.
+@code{where-is-internal} ignores remappings.
+
+@smallexample
+@group
+(where-is-internal 'describe-function)
+    @result{} ([8 102] [f1 102] [help 102]
+         [menu-bar help-menu describe describe-function])
+@end group
+@end smallexample
+@end defun
+
+@deffn Command describe-bindings &optional prefix buffer-or-name
+This function creates a listing of all current key bindings, and
+displays it in a buffer named @samp{*Help*}.  The text is grouped by
+modes---minor modes first, then the major mode, then global bindings.
+
+If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
+listing includes only keys that start with @var{prefix}.
+
+The listing describes meta characters as @key{ESC} followed by the
+corresponding non-meta character.
+
+When several characters with consecutive @acronym{ASCII} codes have the
+same definition, they are shown together, as
+@samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to
+know the @acronym{ASCII} codes to understand which characters this means.
+For example, in the default global map, the characters @samp{@key{SPC}
+..@: ~} are described by a single line.  @key{SPC} is @acronym{ASCII} 32,
+@kbd{~} is @acronym{ASCII} 126, and the characters between them include all
+the normal printing characters, (e.g., letters, digits, punctuation,
+etc.@:); all these characters are bound to @code{self-insert-command}.
+
+If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
+buffer name.  Then @code{describe-bindings} lists that buffer's bindings,
+instead of the current buffer's.
+@end deffn
+
+@node Menu Keymaps
+@section Menu Keymaps
+@cindex menu keymaps
+
+A keymap can operate as a menu as well as defining bindings for
+keyboard keys and mouse buttons.  Menus are usually actuated with the
+mouse, but they can function with the keyboard also.  If a menu keymap
+is active for the next input event, that activates the keyboard menu
+feature.
+
+@menu
+* Defining Menus::		How to make a keymap that defines a menu.
+* Mouse Menus::			How users actuate the menu with the mouse.
+* Keyboard Menus::		How users actuate the menu with the keyboard.
+* Menu Example::		Making a simple menu.
+* Menu Bar::			How to customize the menu bar.
+* Tool Bar::                    A tool bar is a row of images.
+* Modifying Menus::             How to add new items to a menu.
+@end menu
+
+@node Defining Menus
+@subsection Defining Menus
+@cindex defining menus
+@cindex menu prompt string
+@cindex prompt string (of menu)
+
+A keymap acts as a menu if it has an @dfn{overall prompt string},
+which is a string that appears as an element of the keymap.
+(@xref{Format of Keymaps}.)  The string should describe the purpose of
+the menu's commands.  Emacs displays the overall prompt string as the
+menu title in some cases, depending on the toolkit (if any) used for
+displaying menus.@footnote{It is required for menus which do not use a
+toolkit, e.g.@: under MS-DOS.}  Keyboard menus also display the
+overall prompt string.
+
+The easiest way to construct a keymap with a prompt string is to
+specify the string as an argument when you call @code{make-keymap},
+@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or
+@code{define-prefix-command} (@pxref{Definition of
+define-prefix-command}).  If you do not want the keymap to operate as
+a menu, don't specify a prompt string for it.
+
+@defun keymap-prompt keymap
+This function returns the overall prompt string of @var{keymap},
+or @code{nil} if it has none.
+@end defun
+
+The menu's items are the bindings in the keymap.  Each binding
+associates an event type to a definition, but the event types have no
+significance for the menu appearance.  (Usually we use pseudo-events,
+symbols that the keyboard cannot generate, as the event types for menu
+item bindings.)  The menu is generated entirely from the bindings that
+correspond in the keymap to these events.
+
+The order of items in the menu is the same as the order of bindings in
+the keymap.  Since @code{define-key} puts new bindings at the front, you
+should define the menu items starting at the bottom of the menu and
+moving to the top, if you care about the order.  When you add an item to
+an existing menu, you can specify its position in the menu using
+@code{define-key-after} (@pxref{Modifying Menus}).
+
+@menu
+* Simple Menu Items::       A simple kind of menu key binding,
+                              limited in capabilities.
+* Extended Menu Items::     More powerful menu item definitions
+                              let you specify keywords to enable
+                              various features.
+* Menu Separators::         Drawing a horizontal line through a menu.
+* Alias Menu Items::        Using command aliases in menu items.
+@end menu
+
+@node Simple Menu Items
+@subsubsection Simple Menu Items
+
+  The simpler (and original) way to define a menu item is to bind some
+event type (it doesn't matter what event type) to a binding like this:
+
+@example
+(@var{item-string} . @var{real-binding})
+@end example
+
+@noindent
+The @sc{car}, @var{item-string}, is the string to be displayed in the
+menu.  It should be short---preferably one to three words.  It should
+describe the action of the command it corresponds to.  Note that it is
+not generally possible to display non-@acronym{ASCII} text in menus.  It will
+work for keyboard menus and will work to a large extent when Emacs is
+built with the Gtk+ toolkit.@footnote{In this case, the text is first
+encoded using the @code{utf-8} coding system and then rendered by the
+toolkit as it sees fit.}
+
+  You can also supply a second string, called the help string, as follows:
+
+@example
+(@var{item-string} @var{help} . @var{real-binding})
+@end example
+
+@noindent
+@var{help} specifies a ``help-echo'' string to display while the mouse
+is on that item in the same way as @code{help-echo} text properties
+(@pxref{Help display}).
+
+  As far as @code{define-key} is concerned, @var{item-string} and
+@var{help-string} are part of the event's binding.  However,
+@code{lookup-key} returns just @var{real-binding}, and only
+@var{real-binding} is used for executing the key.
+
+  If @var{real-binding} is @code{nil}, then @var{item-string} appears in
+the menu but cannot be selected.
+
+  If @var{real-binding} is a symbol and has a non-@code{nil}
+@code{menu-enable} property, that property is an expression that
+controls whether the menu item is enabled.  Every time the keymap is
+used to display a menu, Emacs evaluates the expression, and it enables
+the menu item only if the expression's value is non-@code{nil}.  When a
+menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
+cannot be selected.
+
+  The menu bar does not recalculate which items are enabled every time you
+look at a menu.  This is because the X toolkit requires the whole tree
+of menus in advance.  To force recalculation of the menu bar, call
+@code{force-mode-line-update} (@pxref{Mode Line Format}).
+
+  You've probably noticed that menu items show the equivalent keyboard key
+sequence (if any) to invoke the same command.  To save time on
+recalculation, menu display caches this information in a sublist in the
+binding, like this:
+
+@c This line is not too long--rms.
+@example
+(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding})
+@end example
+
+@noindent
+Don't put these sublists in the menu item yourself; menu display
+calculates them automatically.  Don't mention keyboard equivalents in
+the item strings themselves, since that is redundant.
+
+@node Extended Menu Items
+@subsubsection Extended Menu Items
+@kindex menu-item
+
+  An extended-format menu item is a more flexible and also cleaner
+alternative to the simple format.  You define an event type with a
+binding that's a list starting with the symbol @code{menu-item}.
+For a non-selectable string, the binding looks like this:
+
+@example
+(menu-item @var{item-name})
+@end example
+
+@noindent
+A string starting with two or more dashes specifies a separator line;
+see @ref{Menu Separators}.
+
+  To define a real menu item which can be selected, the extended format
+binding looks like this:
+
+@example
+(menu-item @var{item-name} @var{real-binding}
+    . @var{item-property-list})
+@end example
+
+@noindent
+Here, @var{item-name} is an expression which evaluates to the menu item
+string.  Thus, the string need not be a constant.  The third element,
+@var{real-binding}, is the command to execute.  The tail of the list,
+@var{item-property-list}, has the form of a property list which contains
+other information.
+
+  When an equivalent keyboard key binding is cached, the extended menu
+item binding looks like this:
+
+@example
+(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
+    . @var{item-property-list})
+@end example
+
+  Here is a table of the properties that are supported:
+
+@table @code
+@item :enable @var{form}
+The result of evaluating @var{form} determines whether the item is
+enabled (non-@code{nil} means yes).  If the item is not enabled,
+you can't really click on it.
+
+@item :visible @var{form}
+The result of evaluating @var{form} determines whether the item should
+actually appear in the menu (non-@code{nil} means yes).  If the item
+does not appear, then the menu is displayed as if this item were
+not defined at all.
+
+@item :help @var{help}
+The value of this property, @var{help}, specifies a ``help-echo'' string
+to display while the mouse is on that item.  This is displayed in the
+same way as @code{help-echo} text properties (@pxref{Help display}).
+Note that this must be a constant string, unlike the @code{help-echo}
+property for text and overlays.
+
+@item :button (@var{type} . @var{selected})
+This property provides a way to define radio buttons and toggle buttons.
+The @sc{car}, @var{type}, says which: it should be @code{:toggle} or
+@code{:radio}.  The @sc{cdr}, @var{selected}, should be a form; the
+result of evaluating it says whether this button is currently selected.
+
+A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
+according to the value of @var{selected}.  The command itself should
+toggle @var{selected}, setting it to @code{t} if it is @code{nil},
+and to @code{nil} if it is @code{t}.  Here is how the menu item
+to toggle the @code{debug-on-error} flag is defined:
+
+@example
+(menu-item "Debug on Error" toggle-debug-on-error
+           :button (:toggle
+                    . (and (boundp 'debug-on-error)
+                           debug-on-error)))
+@end example
+
+@noindent
+This works because @code{toggle-debug-on-error} is defined as a command
+which toggles the variable @code{debug-on-error}.
+
+@dfn{Radio buttons} are a group of menu items, in which at any time one
+and only one is ``selected.''  There should be a variable whose value
+says which one is selected at any time.  The @var{selected} form for
+each radio button in the group should check whether the variable has the
+right value for selecting that button.  Clicking on the button should
+set the variable so that the button you clicked on becomes selected.
+
+@item :key-sequence @var{key-sequence}
+This property specifies which key sequence is likely to be bound to the
+same command invoked by this menu item.  If you specify the right key
+sequence, that makes preparing the menu for display run much faster.
+
+If you specify the wrong key sequence, it has no effect; before Emacs
+displays @var{key-sequence} in the menu, it verifies that
+@var{key-sequence} is really equivalent to this menu item.
+
+@item :key-sequence nil
+This property indicates that there is normally no key binding which is
+equivalent to this menu item.  Using this property saves time in
+preparing the menu for display, because Emacs does not need to search
+the keymaps for a keyboard equivalent for this menu item.
+
+However, if the user has rebound this item's definition to a key
+sequence, Emacs ignores the @code{:keys} property and finds the keyboard
+equivalent anyway.
+
+@item :keys @var{string}
+This property specifies that @var{string} is the string to display
+as the keyboard equivalent for this menu item.  You can use
+the @samp{\\[...]} documentation construct in @var{string}.
+
+@item :filter @var{filter-fn}
+This property provides a way to compute the menu item dynamically.
+The property value @var{filter-fn} should be a function of one argument;
+when it is called, its argument will be @var{real-binding}.  The
+function should return the binding to use instead.
+
+Emacs can call this function at any time that it does redisplay or
+operates on menu data structures, so you should write it so it can
+safely be called at any time.
+@end table
+
+@node Menu Separators
+@subsubsection Menu Separators
+@cindex menu separators
+
+  A menu separator is a kind of menu item that doesn't display any
+text---instead, it divides the menu into subparts with a horizontal line.
+A separator looks like this in the menu keymap:
+
+@example
+(menu-item @var{separator-type})
+@end example
+
+@noindent
+where @var{separator-type} is a string starting with two or more dashes.
+
+  In the simplest case, @var{separator-type} consists of only dashes.
+That specifies the default kind of separator.  (For compatibility,
+@code{""} and @code{-} also count as separators.)
+
+  Certain other values of @var{separator-type} specify a different
+style of separator.  Here is a table of them:
+
+@table @code
+@item "--no-line"
+@itemx "--space"
+An extra vertical space, with no actual line.
+
+@item "--single-line"
+A single line in the menu's foreground color.
+
+@item "--double-line"
+A double line in the menu's foreground color.
+
+@item "--single-dashed-line"
+A single dashed line in the menu's foreground color.
+
+@item "--double-dashed-line"
+A double dashed line in the menu's foreground color.
+
+@item "--shadow-etched-in"
+A single line with a 3D sunken appearance.  This is the default,
+used separators consisting of dashes only.
+
+@item "--shadow-etched-out"
+A single line with a 3D raised appearance.
+
+@item "--shadow-etched-in-dash"
+A single dashed line with a 3D sunken appearance.
+
+@item "--shadow-etched-out-dash"
+A single dashed line with a 3D raised appearance.
+
+@item "--shadow-double-etched-in"
+Two lines with a 3D sunken appearance.
+
+@item "--shadow-double-etched-out"
+Two lines with a 3D raised appearance.
+
+@item "--shadow-double-etched-in-dash"
+Two dashed lines with a 3D sunken appearance.
+
+@item "--shadow-double-etched-out-dash"
+Two dashed lines with a 3D raised appearance.
+@end table
+
+  You can also give these names in another style, adding a colon after
+the double-dash and replacing each single dash with capitalization of
+the following word.  Thus, @code{"--:singleLine"}, is equivalent to
+@code{"--single-line"}.
+
+  Some systems and display toolkits don't really handle all of these
+separator types.  If you use a type that isn't supported, the menu
+displays a similar kind of separator that is supported.
+
+@node Alias Menu Items
+@subsubsection Alias Menu Items
+
+  Sometimes it is useful to make menu items that use the ``same''
+command but with different enable conditions.  The best way to do this
+in Emacs now is with extended menu items; before that feature existed,
+it could be done by defining alias commands and using them in menu
+items.  Here's an example that makes two aliases for
+@code{toggle-read-only} and gives them different enable conditions:
+
+@example
+(defalias 'make-read-only 'toggle-read-only)
+(put 'make-read-only 'menu-enable '(not buffer-read-only))
+(defalias 'make-writable 'toggle-read-only)
+(put 'make-writable 'menu-enable 'buffer-read-only)
+@end example
+
+When using aliases in menus, often it is useful to display the
+equivalent key bindings for the ``real'' command name, not the aliases
+(which typically don't have any key bindings except for the menu
+itself).  To request this, give the alias symbol a non-@code{nil}
+@code{menu-alias} property.  Thus,
+
+@example
+(put 'make-read-only 'menu-alias t)
+(put 'make-writable 'menu-alias t)
+@end example
+
+@noindent
+causes menu items for @code{make-read-only} and @code{make-writable} to
+show the keyboard bindings for @code{toggle-read-only}.
+
+@node Mouse Menus
+@subsection Menus and the Mouse
+
+  The usual way to make a menu keymap produce a menu is to make it the
+definition of a prefix key.  (A Lisp program can explicitly pop up a
+menu and receive the user's choice---see @ref{Pop-Up Menus}.)
+
+  If the prefix key ends with a mouse event, Emacs handles the menu keymap
+by popping up a visible menu, so that the user can select a choice with
+the mouse.  When the user clicks on a menu item, the event generated is
+whatever character or symbol has the binding that brought about that
+menu item.  (A menu item may generate a series of events if the menu has
+multiple levels or comes from the menu bar.)
+
+  It's often best to use a button-down event to trigger the menu.  Then
+the user can select a menu item by releasing the button.
+
+  A single keymap can appear as multiple menu panes, if you explicitly
+arrange for this.  The way to do this is to make a keymap for each pane,
+then create a binding for each of those maps in the main keymap of the
+menu.  Give each of these bindings an item string that starts with
+@samp{@@}.  The rest of the item string becomes the name of the pane.
+See the file @file{lisp/mouse.el} for an example of this.  Any ordinary
+bindings with @samp{@@}-less item strings are grouped into one pane,
+which appears along with the other panes explicitly created for the
+submaps.
+
+  X toolkit menus don't have panes; instead, they can have submenus.
+Every nested keymap becomes a submenu, whether the item string starts
+with @samp{@@} or not.  In a toolkit version of Emacs, the only thing
+special about @samp{@@} at the beginning of an item string is that the
+@samp{@@} doesn't appear in the menu item.
+
+  Multiple keymaps that define the same menu prefix key produce
+separate panes or separate submenus.
+
+@node Keyboard Menus
+@subsection Menus and the Keyboard
+
+  When a prefix key ending with a keyboard event (a character or
+function key) has a definition that is a menu keymap, the keymap
+operates as a keyboard menu; the user specifies the next event by
+choosing a menu item with the keyboard.
+
+  Emacs displays the keyboard menu with the map's overall prompt
+string, followed by the alternatives (the item strings of the map's
+bindings), in the echo area.  If the bindings don't all fit at once,
+the user can type @key{SPC} to see the next line of alternatives.
+Successive uses of @key{SPC} eventually get to the end of the menu and
+then cycle around to the beginning.  (The variable
+@code{menu-prompt-more-char} specifies which character is used for
+this; @key{SPC} is the default.)
+
+  When the user has found the desired alternative from the menu, he or
+she should type the corresponding character---the one whose binding is
+that alternative.
+
+@ignore
+In a menu intended for keyboard use, each menu item must clearly
+indicate what character to type.  The best convention to use is to make
+the character the first letter of the item string---that is something
+users will understand without being told.  We plan to change this; by
+the time you read this manual, keyboard menus may explicitly name the
+key for each alternative.
+@end ignore
+
+  This way of using menus in an Emacs-like editor was inspired by the
+Hierarkey system.
+
+@defvar menu-prompt-more-char
+This variable specifies the character to use to ask to see
+the next line of a menu.  Its initial value is 32, the code
+for @key{SPC}.
+@end defvar
+
+@node Menu Example
+@subsection Menu Example
+@cindex menu definition example
+
+  Here is a complete example of defining a menu keymap.  It is the
+definition of the @samp{Replace} submenu in the @samp{Edit} menu in
+the menu bar, and it uses the extended menu item format
+(@pxref{Extended Menu Items}).  First we create the keymap, and give
+it a name:
+
+@smallexample
+(defvar menu-bar-replace-menu (make-sparse-keymap "Replace"))
+@end smallexample
+
+@noindent
+Next we define the menu items:
+
+@smallexample
+(define-key menu-bar-replace-menu [tags-repl-continue]
+  '(menu-item "Continue Replace" tags-loop-continue
+	      :help "Continue last tags replace operation"))
+(define-key menu-bar-replace-menu [tags-repl]
+  '(menu-item "Replace in tagged files" tags-query-replace
+	      :help "Interactively replace a regexp in all tagged files"))
+(define-key menu-bar-replace-menu [separator-replace-tags]
+  '(menu-item "--"))
+;; @r{@dots{}}
+@end smallexample
+
+@noindent
+Note the symbols which the bindings are ``made for''; these appear
+inside square brackets, in the key sequence being defined.  In some
+cases, this symbol is the same as the command name; sometimes it is
+different.  These symbols are treated as ``function keys,'' but they are
+not real function keys on the keyboard.  They do not affect the
+functioning of the menu itself, but they are ``echoed'' in the echo area
+when the user selects from the menu, and they appear in the output of
+@code{where-is} and @code{apropos}.
+
+  The menu in this example is intended for use with the mouse.  If a
+menu is intended for use with the keyboard, that is, if it is bound to
+a key sequence ending with a keyboard event, then the menu items
+should be bound to characters or ``real'' function keys, that can be
+typed with the keyboard.
+
+  The binding whose definition is @code{("--")} is a separator line.
+Like a real menu item, the separator has a key symbol, in this case
+@code{separator-replace-tags}.  If one menu has two separators, they
+must have two different key symbols.
+
+  Here is how we make this menu appear as an item in the parent menu:
+
+@example
+(define-key menu-bar-edit-menu [replace]
+  (list 'menu-item "Replace" menu-bar-replace-menu))
+@end example
+
+@noindent
+Note that this incorporates the submenu keymap, which is the value of
+the variable @code{menu-bar-replace-menu}, rather than the symbol
+@code{menu-bar-replace-menu} itself.  Using that symbol in the parent
+menu item would be meaningless because @code{menu-bar-replace-menu} is
+not a command.
+
+  If you wanted to attach the same replace menu to a mouse click, you
+can do it this way:
+
+@example
+(define-key global-map [C-S-down-mouse-1]
+   menu-bar-replace-menu)
+@end example
+
+@node Menu Bar
+@subsection The Menu Bar
+@cindex menu bar
+
+  Most window systems allow each frame to have a @dfn{menu bar}---a
+permanently displayed menu stretching horizontally across the top of the
+frame.  The items of the menu bar are the subcommands of the fake
+``function key'' @code{menu-bar}, as defined in the active keymaps.
+
+  To add an item to the menu bar, invent a fake ``function key'' of your
+own (let's call it @var{key}), and make a binding for the key sequence
+@code{[menu-bar @var{key}]}.  Most often, the binding is a menu keymap,
+so that pressing a button on the menu bar item leads to another menu.
+
+  When more than one active keymap defines the same fake function key
+for the menu bar, the item appears just once.  If the user clicks on
+that menu bar item, it brings up a single, combined menu containing
+all the subcommands of that item---the global subcommands, the local
+subcommands, and the minor mode subcommands.
+
+  The variable @code{overriding-local-map} is normally ignored when
+determining the menu bar contents.  That is, the menu bar is computed
+from the keymaps that would be active if @code{overriding-local-map}
+were @code{nil}.  @xref{Active Keymaps}.
+
+  In order for a frame to display a menu bar, its @code{menu-bar-lines}
+parameter must be greater than zero.  Emacs uses just one line for the
+menu bar itself; if you specify more than one line, the other lines
+serve to separate the menu bar from the windows in the frame.  We
+recommend 1 or 2 as the value of @code{menu-bar-lines}.  @xref{Layout
+Parameters}.
+
+  Here's an example of setting up a menu bar item:
+
+@example
+@group
+(modify-frame-parameters (selected-frame)
+                         '((menu-bar-lines . 2)))
+@end group
+
+@group
+;; @r{Make a menu keymap (with a prompt string)}
+;; @r{and make it the menu bar item's definition.}
+(define-key global-map [menu-bar words]
+  (cons "Words" (make-sparse-keymap "Words")))
+@end group
+
+@group
+;; @r{Define specific subcommands in this menu.}
+(define-key global-map
+  [menu-bar words forward]
+  '("Forward word" . forward-word))
+@end group
+@group
+(define-key global-map
+  [menu-bar words backward]
+  '("Backward word" . backward-word))
+@end group
+@end example
+
+  A local keymap can cancel a menu bar item made by the global keymap by
+rebinding the same fake function key with @code{undefined} as the
+binding.  For example, this is how Dired suppresses the @samp{Edit} menu
+bar item:
+
+@example
+(define-key dired-mode-map [menu-bar edit] 'undefined)
+@end example
+
+@noindent
+@code{edit} is the fake function key used by the global map for the
+@samp{Edit} menu bar item.  The main reason to suppress a global
+menu bar item is to regain space for mode-specific items.
+
+@defvar menu-bar-final-items
+Normally the menu bar shows global items followed by items defined by the
+local maps.
+
+This variable holds a list of fake function keys for items to display at
+the end of the menu bar rather than in normal sequence.  The default
+value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
+at the end of the menu bar, following local menu items.
+@end defvar
+
+@defvar menu-bar-update-hook
+This normal hook is run by redisplay to update the menu bar contents,
+before redisplaying the menu bar.  You can use it to update submenus
+whose contents should vary.  Since this hook is run frequently, we
+advise you to ensure that the functions it calls do not take much time
+in the usual case.
+@end defvar
+
+@node Tool Bar
+@subsection Tool bars
+@cindex tool bar
+
+  A @dfn{tool bar} is a row of icons at the top of a frame, that execute
+commands when you click on them---in effect, a kind of graphical menu
+bar.
+
+  The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
+controls how many lines' worth of height to reserve for the tool bar.  A
+zero value suppresses the tool bar.  If the value is nonzero, and
+@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
+contracts automatically as needed to hold the specified contents.
+
+  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, the user has to redraw the frame by entering
+@kbd{C-l}.
+
+  The tool bar contents are controlled by a menu keymap attached to a
+fake ``function key'' called @code{tool-bar} (much like the way the menu
+bar is controlled).  So you define a tool bar item using
+@code{define-key}, like this:
+
+@example
+(define-key global-map [tool-bar @var{key}] @var{item})
+@end example
+
+@noindent
+where @var{key} is a fake ``function key'' to distinguish this item from
+other items, and @var{item} is a menu item key binding (@pxref{Extended
+Menu Items}), which says how to display this item and how it behaves.
+
+  The usual menu keymap item properties, @code{:visible},
+@code{:enable}, @code{:button}, and @code{:filter}, are useful in
+tool bar bindings and have their normal meanings.  The @var{real-binding}
+in the item must be a command, not a keymap; in other words, it does not
+work to define a tool bar icon as a prefix key.
+
+  The @code{:help} property specifies a ``help-echo'' string to display
+while the mouse is on that item.  This is displayed in the same way as
+@code{help-echo} text properties (@pxref{Help display}).
+
+  In addition, you should use the @code{:image} property;
+this is how you specify the image to display in the tool bar:
+
+@table @code
+@item :image @var{image}
+@var{images} is either a single image specification or a vector of four
+image specifications.  If you use a vector of four,
+one of them is used, depending on circumstances:
+
+@table @asis
+@item item 0
+Used when the item is enabled and selected.
+@item item 1
+Used when the item is enabled and deselected.
+@item item 2
+Used when the item is disabled and selected.
+@item item 3
+Used when the item is disabled and deselected.
+@end table
+@end table
+
+If @var{image} is a single image specification, Emacs draws the tool bar
+button in disabled state by applying an edge-detection algorithm to the
+image.
+
+The default tool bar is defined so that items specific to editing do not
+appear for major modes whose command symbol has a @code{mode-class}
+property of @code{special} (@pxref{Major Mode Conventions}).  Major
+modes may add items to the global bar by binding @code{[tool-bar
+@var{foo}]} in their local map.  It makes sense for some major modes to
+replace the default tool bar items completely, since not many can be
+accommodated conveniently, and the default bindings make this easy by
+using an indirection through @code{tool-bar-map}.
+
+@defvar tool-bar-map
+By default, the global map binds @code{[tool-bar]} as follows:
+@example
+(global-set-key [tool-bar]
+		'(menu-item "tool bar" ignore
+			    :filter (lambda (ignore) tool-bar-map)))
+@end example
+@noindent
+Thus the tool bar map is derived dynamically from the value of variable
+@code{tool-bar-map} and you should normally adjust the default (global)
+tool bar by changing that map.  Major modes may replace the global bar
+completely by making @code{tool-bar-map} buffer-local and set to a
+keymap containing only the desired items.  Info mode provides an
+example.
+@end defvar
+
+There are two convenience functions for defining tool bar items, as
+follows.
+
+@defun tool-bar-add-item icon def key &rest props
+This function adds an item to the tool bar by modifying
+@code{tool-bar-map}.  The image to use is defined by @var{icon}, which
+is the base name of an XPM, XBM or PBM image file to be located by
+@code{find-image}.  Given a value @samp{"exit"}, say, @file{exit.xpm},
+@file{exit.pbm} and @file{exit.xbm} would be searched for in that order
+on a color display.  On a monochrome display, the search order is
+@samp{.pbm}, @samp{.xbm} and @samp{.xpm}.  The binding to use is the
+command @var{def}, and @var{key} is the fake function key symbol in the
+prefix keymap.  The remaining arguments @var{props} are additional
+property list elements to add to the menu item specification.
+
+To define items in some local map, bind @code{tool-bar-map} with
+@code{let} around calls of this function:
+@example
+(defvar foo-tool-bar-map
+  (let ((tool-bar-map (make-sparse-keymap)))
+    (tool-bar-add-item @dots{})
+    @dots{}
+    tool-bar-map))
+@end example
+@end defun
+
+@defun tool-bar-add-item-from-menu command icon &optional map &rest props
+This function is a convenience for defining tool bar items which are
+consistent with existing menu bar bindings.  The binding of
+@var{command} is looked up in the menu bar in @var{map} (default
+@code{global-map}) and modified to add an image specification for
+@var{icon}, which is found in the same way as by
+@code{tool-bar-add-item}.  The resulting binding is then placed in
+@code{tool-bar-map}, so use this function only for global tool bar
+items.
+
+@var{map} must contain an appropriate keymap bound to
+@code{[menu-bar]}.  The remaining arguments @var{props} are additional
+property list elements to add to the menu item specification.
+@end defun
+
+@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
+This function is used for making non-global tool bar items.  Use it
+like @code{tool-bar-add-item-from-menu} except that @var{in-map}
+specifies the local map to make the definition in.  The argument
+@var{from-map} is like the @var{map} argument of
+@code{tool-bar-add-item-from-menu}.
+@end defun
+
+@defvar auto-resize-tool-bar
+If this variable is non-@code{nil}, the tool bar automatically resizes to
+show all defined tool bar items---but not larger than a quarter of the
+frame's height.
+
+If the value is @code{grow-only}, the tool bar expands automatically,
+but does not contract automatically.  To contract the tool bar, the
+user has to redraw the frame by entering @kbd{C-l}.
+@end defvar
+
+@defvar auto-raise-tool-bar-buttons
+If this variable is non-@code{nil}, tool bar items display
+in raised form when the mouse moves over them.
+@end defvar
+
+@defvar tool-bar-button-margin
+This variable specifies an extra margin to add around tool bar items.
+The value is an integer, a number of pixels.  The default is 4.
+@end defvar
+
+@defvar tool-bar-button-relief
+This variable specifies the shadow width for tool bar items.
+The value is an integer, a number of pixels.  The default is 1.
+@end defvar
+
+@defvar tool-bar-border
+This variable specifies the height of the border drawn below the tool
+bar area.  An integer value specifies height as a number of pixels.
+If the value is one of @code{internal-border-width} (the default) or
+@code{border-width}, the tool bar border height corresponds to the
+corresponding frame parameter.
+@end defvar
+
+  You can define a special meaning for clicking on a tool bar item with
+the shift, control, meta, etc., modifiers.  You do this by setting up
+additional items that relate to the original item through the fake
+function keys.  Specifically, the additional items should use the
+modified versions of the same fake function key used to name the
+original item.
+
+  Thus, if the original item was defined this way,
+
+@example
+(define-key global-map [tool-bar shell]
+  '(menu-item "Shell" shell
+              :image (image :type xpm :file "shell.xpm")))
+@end example
+
+@noindent
+then here is how you can define clicking on the same tool bar image with
+the shift modifier:
+
+@example
+(define-key global-map [tool-bar S-shell] 'some-command)
+@end example
+
+@xref{Function Keys}, for more information about how to add modifiers to
+function keys.
+
+@node Modifying Menus
+@subsection Modifying Menus
+
+  When you insert a new item in an existing menu, you probably want to
+put it in a particular place among the menu's existing items.  If you
+use @code{define-key} to add the item, it normally goes at the front of
+the menu.  To put it elsewhere in the menu, use @code{define-key-after}:
+
+@defun define-key-after map key binding &optional after
+Define a binding in @var{map} for @var{key}, with value @var{binding},
+just like @code{define-key}, but position the binding in @var{map} after
+the binding for the event @var{after}.  The argument @var{key} should be
+of length one---a vector or string with just one element.  But
+@var{after} should be a single event type---a symbol or a character, not
+a sequence.  The new binding goes after the binding for @var{after}.  If
+@var{after} is @code{t} or is omitted, then the new binding goes last, at
+the end of the keymap.  However, new bindings are added before any
+inherited keymap.
+
+Here is an example:
+
+@example
+(define-key-after my-menu [drink]
+  '("Drink" . drink-command) 'eat)
+@end example
+
+@noindent
+makes a binding for the fake function key @key{DRINK} and puts it
+right after the binding for @key{EAT}.
+
+Here is how to insert an item called @samp{Work} in the @samp{Signals}
+menu of Shell mode, after the item @code{break}:
+
+@example
+(define-key-after
+  (lookup-key shell-mode-map [menu-bar signals])
+  [work] '("Work" . work-command) 'break)
+@end example
+@end defun
+
+@ignore
+   arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
+@end ignore
diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi
new file mode 100644
index 00000000000..1677058d7ca
--- /dev/null
+++ b/doc/lispref/lay-flat.texi
@@ -0,0 +1,48 @@
+\input texinfo    @c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
+@c   Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@c
+@comment %**start of header
+@setfilename inner-covers.info
+@settitle Inner Covers
+@smallbook
+@comment %**end of header
+
+@headings off
+
+@w{ }
+@sp 4
+@tex
+\center {\secfonts \rm Lay-Flat Binding}
+@end tex
+@sp 2
+
+We have bound this manual using a new @dfn{lay-flat} binding
+technology.  This type of binding allows you to open a soft cover book
+so that it ``lays flat'' on a table without creasing the binding.
+
+In order to make the book lay flat properly, you need to ``crack'' the
+binding.  To do this, divide the book into two sections and bend it so
+that the front and back covers meet.  Do not worry; the pages are
+sewn and glued to the binding, and will not fall out easily.
+The outer cardboard binding itself is designed so that it will not
+break or crease as an ordinary paperback binding will.  Bend the book
+several times in this manner, dividing it in a different place each
+time and pressing the pages flat and open.  With use, the binding will
+become flexible and the pages will lay flat without needing to be
+pushed or held down.
+
+@page
+
+
+@tex
+\center {\secfonts \rm Notes}
+@end tex
+
+@bye
+
+@ignore
+   arch-tag: 9e03a1c7-6f62-4346-85d9-ed5b79386e07
+@end ignore
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
new file mode 100644
index 00000000000..ffe4df2413d
--- /dev/null
+++ b/doc/lispref/lists.texi
@@ -0,0 +1,1904 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/lists
+@node Lists, Sequences Arrays Vectors, Strings and Characters, Top
+@chapter Lists
+@cindex lists
+@cindex element (of list)
+
+  A @dfn{list} represents a sequence of zero or more elements (which may
+be any Lisp objects).  The important difference between lists and
+vectors is that two or more lists can share part of their structure; in
+addition, you can insert or delete elements in a list without copying
+the whole list.
+
+@menu
+* Cons Cells::          How lists are made out of cons cells.
+* List-related Predicates::        Is this object a list?  Comparing two lists.
+* List Elements::       Extracting the pieces of a list.
+* Building Lists::      Creating list structure.
+* List Variables::      Modifying lists stored in variables.
+* Modifying Lists::     Storing new pieces into an existing list.
+* Sets And Lists::      A list can represent a finite mathematical set.
+* Association Lists::   A list can represent a finite relation or mapping.
+* Rings::               Managing a fixed-size ring of objects.
+@end menu
+
+@node Cons Cells
+@section Lists and Cons Cells
+@cindex lists and cons cells
+
+  Lists in Lisp are not a primitive data type; they are built up from
+@dfn{cons cells}.  A cons cell is a data object that represents an
+ordered pair.  That is, it has two slots, and each slot @dfn{holds}, or
+@dfn{refers to}, some Lisp object.  One slot is known as the @sc{car},
+and the other is known as the @sc{cdr}.  (These names are traditional;
+see @ref{Cons Cell Type}.)  @sc{cdr} is pronounced ``could-er.''
+
+  We say that ``the @sc{car} of this cons cell is'' whatever object
+its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
+
+  A list is a series of cons cells ``chained together,'' so that each
+cell refers to the next one.  There is one cons cell for each element of
+the list.  By convention, the @sc{car}s of the cons cells hold the
+elements of the list, and the @sc{cdr}s are used to chain the list: the
+@sc{cdr} slot of each cons cell refers to the following cons cell.  The
+@sc{cdr} of the last cons cell is @code{nil}.  This asymmetry between
+the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the
+level of cons cells, the @sc{car} and @sc{cdr} slots have the same
+characteristics.
+
+@cindex true list
+  Since @code{nil} is the conventional value to put in the @sc{cdr} of
+the last cons cell in the list, we call that case a @dfn{true list}.
+
+  In Lisp, we consider the symbol @code{nil} a list as well as a
+symbol; it is the list with no elements.  For convenience, the symbol
+@code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
+as its @sc{car}).  Therefore, the @sc{cdr} of a true list is always a
+true list.
+
+@cindex dotted list
+@cindex circular list
+  If the @sc{cdr} of a list's last cons cell is some other value,
+neither @code{nil} nor another cons cell, we call the structure a
+@dfn{dotted list}, since its printed representation would use
+@samp{.}.  There is one other possibility: some cons cell's @sc{cdr}
+could point to one of the previous cons cells in the list.  We call
+that structure a @dfn{circular list}.
+
+  For some purposes, it does not matter whether a list is true,
+circular or dotted.  If the program doesn't look far enough down the
+list to see the @sc{cdr} of the final cons cell, it won't care.
+However, some functions that operate on lists demand true lists and
+signal errors if given a dotted list.  Most functions that try to find
+the end of a list enter infinite loops if given a circular list.
+
+@cindex list structure
+  Because most cons cells are used as part of lists, the phrase
+@dfn{list structure} has come to mean any structure made out of cons
+cells.
+
+  The @sc{cdr} of any nonempty true list @var{l} is a list containing all the
+elements of @var{l} except the first.
+
+  @xref{Cons Cell Type}, for the read and print syntax of cons cells and
+lists, and for ``box and arrow'' illustrations of lists.
+
+@node List-related Predicates
+@section Predicates on Lists
+
+  The following predicates test whether a Lisp object is an atom,
+whether it is a cons cell or is a list, or whether it is the
+distinguished object @code{nil}.  (Many of these predicates can be
+defined in terms of the others, but they are used so often that it is
+worth having all of them.)
+
+@defun consp object
+This function returns @code{t} if @var{object} is a cons cell, @code{nil}
+otherwise.  @code{nil} is not a cons cell, although it @emph{is} a list.
+@end defun
+
+@defun atom object
+This function returns @code{t} if @var{object} is an atom, @code{nil}
+otherwise.  All objects except cons cells are atoms.  The symbol
+@code{nil} is an atom and is also a list; it is the only Lisp object
+that is both.
+
+@example
+(atom @var{object}) @equiv{} (not (consp @var{object}))
+@end example
+@end defun
+
+@defun listp object
+This function returns @code{t} if @var{object} is a cons cell or
+@code{nil}.  Otherwise, it returns @code{nil}.
+
+@example
+@group
+(listp '(1))
+     @result{} t
+@end group
+@group
+(listp '())
+     @result{} t
+@end group
+@end example
+@end defun
+
+@defun nlistp object
+This function is the opposite of @code{listp}: it returns @code{t} if
+@var{object} is not a list.  Otherwise, it returns @code{nil}.
+
+@example
+(listp @var{object}) @equiv{} (not (nlistp @var{object}))
+@end example
+@end defun
+
+@defun null object
+This function returns @code{t} if @var{object} is @code{nil}, and
+returns @code{nil} otherwise.  This function is identical to @code{not},
+but as a matter of clarity we use @code{null} when @var{object} is
+considered a list and @code{not} when it is considered a truth value
+(see @code{not} in @ref{Combining Conditions}).
+
+@example
+@group
+(null '(1))
+     @result{} nil
+@end group
+@group
+(null '())
+     @result{} t
+@end group
+@end example
+@end defun
+
+
+@node List Elements
+@section Accessing Elements of Lists
+@cindex list elements
+
+@defun car cons-cell
+This function returns the value referred to by the first slot of the
+cons cell @var{cons-cell}.  Expressed another way, this function
+returns the @sc{car} of @var{cons-cell}.
+
+As a special case, if @var{cons-cell} is @code{nil}, then @code{car}
+is defined to return @code{nil}; therefore, any list is a valid argument
+for @code{car}.  An error is signaled if the argument is not a cons cell
+or @code{nil}.
+
+@example
+@group
+(car '(a b c))
+     @result{} a
+@end group
+@group
+(car '())
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun cdr cons-cell
+This function returns the value referred to by the second slot of
+the cons cell @var{cons-cell}.  Expressed another way, this function
+returns the @sc{cdr} of @var{cons-cell}.
+
+As a special case, if @var{cons-cell} is @code{nil}, then @code{cdr}
+is defined to return @code{nil}; therefore, any list is a valid argument
+for @code{cdr}.  An error is signaled if the argument is not a cons cell
+or @code{nil}.
+
+@example
+@group
+(cdr '(a b c))
+     @result{} (b c)
+@end group
+@group
+(cdr '())
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun car-safe object
+This function lets you take the @sc{car} of a cons cell while avoiding
+errors for other data types.  It returns the @sc{car} of @var{object} if
+@var{object} is a cons cell, @code{nil} otherwise.  This is in contrast
+to @code{car}, which signals an error if @var{object} is not a list.
+
+@example
+@group
+(car-safe @var{object})
+@equiv{}
+(let ((x @var{object}))
+  (if (consp x)
+      (car x)
+    nil))
+@end group
+@end example
+@end defun
+
+@defun cdr-safe object
+This function lets you take the @sc{cdr} of a cons cell while
+avoiding errors for other data types.  It returns the @sc{cdr} of
+@var{object} if @var{object} is a cons cell, @code{nil} otherwise.
+This is in contrast to @code{cdr}, which signals an error if
+@var{object} is not a list.
+
+@example
+@group
+(cdr-safe @var{object})
+@equiv{}
+(let ((x @var{object}))
+  (if (consp x)
+      (cdr x)
+    nil))
+@end group
+@end example
+@end defun
+
+@defmac pop listname
+This macro is a way of examining the @sc{car} of a list,
+and taking it off the list, all at once.
+
+It operates on the list which is stored in the symbol @var{listname}.
+It removes this element from the list by setting @var{listname}
+to the @sc{cdr} of its old value---but it also returns the @sc{car}
+of that list, which is the element being removed.
+
+@example
+x
+     @result{} (a b c)
+(pop x)
+     @result{} a
+x
+     @result{} (b c)
+@end example
+@end defmac
+
+@defun nth n list
+@anchor{Definition of nth}
+This function returns the @var{n}th element of @var{list}.  Elements
+are numbered starting with zero, so the @sc{car} of @var{list} is
+element number zero.  If the length of @var{list} is @var{n} or less,
+the value is @code{nil}.
+
+If @var{n} is negative, @code{nth} returns the first element of
+@var{list}.
+
+@example
+@group
+(nth 2 '(1 2 3 4))
+     @result{} 3
+@end group
+@group
+(nth 10 '(1 2 3 4))
+     @result{} nil
+@end group
+@group
+(nth -3 '(1 2 3 4))
+     @result{} 1
+
+(nth n x) @equiv{} (car (nthcdr n x))
+@end group
+@end example
+
+The function @code{elt} is similar, but applies to any kind of sequence.
+For historical reasons, it takes its arguments in the opposite order.
+@xref{Sequence Functions}.
+@end defun
+
+@defun nthcdr n list
+This function returns the @var{n}th @sc{cdr} of @var{list}.  In other
+words, it skips past the first @var{n} links of @var{list} and returns
+what follows.
+
+If @var{n} is zero or negative, @code{nthcdr} returns all of
+@var{list}.  If the length of @var{list} is @var{n} or less,
+@code{nthcdr} returns @code{nil}.
+
+@example
+@group
+(nthcdr 1 '(1 2 3 4))
+     @result{} (2 3 4)
+@end group
+@group
+(nthcdr 10 '(1 2 3 4))
+     @result{} nil
+@end group
+@group
+(nthcdr -3 '(1 2 3 4))
+     @result{} (1 2 3 4)
+@end group
+@end example
+@end defun
+
+@defun last list &optional n
+This function returns the last link of @var{list}.  The @code{car} of
+this link is the list's last element.  If @var{list} is null,
+@code{nil} is returned.  If @var{n} is non-@code{nil}, the
+@var{n}th-to-last link is returned instead, or the whole of @var{list}
+if @var{n} is bigger than @var{list}'s length.
+@end defun
+
+@defun safe-length list
+@anchor{Definition of safe-length}
+This function returns the length of @var{list}, with no risk of either
+an error or an infinite loop.  It generally returns the number of
+distinct cons cells in the list.  However, for circular lists,
+the value is just an upper bound; it is often too large.
+
+If @var{list} is not @code{nil} or a cons cell, @code{safe-length}
+returns 0.
+@end defun
+
+  The most common way to compute the length of a list, when you are not
+worried that it may be circular, is with @code{length}.  @xref{Sequence
+Functions}.
+
+@defun caar cons-cell
+This is the same as @code{(car (car @var{cons-cell}))}.
+@end defun
+
+@defun cadr cons-cell
+This is the same as @code{(car (cdr @var{cons-cell}))}
+or @code{(nth 1 @var{cons-cell})}.
+@end defun
+
+@defun cdar cons-cell
+This is the same as @code{(cdr (car @var{cons-cell}))}.
+@end defun
+
+@defun cddr cons-cell
+This is the same as @code{(cdr (cdr @var{cons-cell}))}
+or @code{(nthcdr 2 @var{cons-cell})}.
+@end defun
+
+@defun butlast x &optional n
+This function returns the list @var{x} with the last element,
+or the last @var{n} elements, removed.  If @var{n} is greater
+than zero it makes a copy of the list so as not to damage the
+original list.  In general, @code{(append (butlast @var{x} @var{n})
+(last @var{x} @var{n}))} will return a list equal to @var{x}.
+@end defun
+
+@defun nbutlast x &optional n
+This is a version of @code{butlast} that works by destructively
+modifying the @code{cdr} of the appropriate element, rather than
+making a copy of the list.
+@end defun
+
+@node Building Lists
+@comment  node-name,  next,  previous,  up
+@section Building Cons Cells and Lists
+@cindex cons cells
+@cindex building lists
+
+  Many functions build lists, as lists reside at the very heart of Lisp.
+@code{cons} is the fundamental list-building function; however, it is
+interesting to note that @code{list} is used more times in the source
+code for Emacs than @code{cons}.
+
+@defun cons object1 object2
+This function is the most basic function for building new list
+structure.  It creates a new cons cell, making @var{object1} the
+@sc{car}, and @var{object2} the @sc{cdr}.  It then returns the new
+cons cell.  The arguments @var{object1} and @var{object2} may be any
+Lisp objects, but most often @var{object2} is a list.
+
+@example
+@group
+(cons 1 '(2))
+     @result{} (1 2)
+@end group
+@group
+(cons 1 '())
+     @result{} (1)
+@end group
+@group
+(cons 1 2)
+     @result{} (1 . 2)
+@end group
+@end example
+
+@cindex consing
+@code{cons} is often used to add a single element to the front of a
+list.  This is called @dfn{consing the element onto the list}.
+@footnote{There is no strictly equivalent way to add an element to
+the end of a list.  You can use @code{(append @var{listname} (list
+@var{newelt}))}, which creates a whole new list by copying @var{listname}
+and adding @var{newelt} to its end.  Or you can use @code{(nconc
+@var{listname} (list @var{newelt}))}, which modifies @var{listname}
+by following all the @sc{cdr}s and then replacing the terminating
+@code{nil}.  Compare this to adding an element to the beginning of a
+list with @code{cons}, which neither copies nor modifies the list.}
+For example:
+
+@example
+(setq list (cons newelt list))
+@end example
+
+Note that there is no conflict between the variable named @code{list}
+used in this example and the function named @code{list} described below;
+any symbol can serve both purposes.
+@end defun
+
+@defun list &rest objects
+This function creates a list with @var{objects} as its elements.  The
+resulting list is always @code{nil}-terminated.  If no @var{objects}
+are given, the empty list is returned.
+
+@example
+@group
+(list 1 2 3 4 5)
+     @result{} (1 2 3 4 5)
+@end group
+@group
+(list 1 2 '(3 4 5) 'foo)
+     @result{} (1 2 (3 4 5) foo)
+@end group
+@group
+(list)
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun make-list length object
+This function creates a list of @var{length} elements, in which each
+element is @var{object}.  Compare @code{make-list} with
+@code{make-string} (@pxref{Creating Strings}).
+
+@example
+@group
+(make-list 3 'pigs)
+     @result{} (pigs pigs pigs)
+@end group
+@group
+(make-list 0 'pigs)
+     @result{} nil
+@end group
+@group
+(setq l (make-list 3 '(a b))
+     @result{} ((a b) (a b) (a b))
+(eq (car l) (cadr l))
+     @result{} t
+@end group
+@end example
+@end defun
+
+@defun append &rest sequences
+@cindex copying lists
+This function returns a list containing all the elements of
+@var{sequences}.  The @var{sequences} may be lists, vectors,
+bool-vectors, or strings, but the last one should usually be a list.
+All arguments except the last one are copied, so none of the arguments
+is altered.  (See @code{nconc} in @ref{Rearrangement}, for a way to join
+lists with no copying.)
+
+More generally, the final argument to @code{append} may be any Lisp
+object.  The final argument is not copied or converted; it becomes the
+@sc{cdr} of the last cons cell in the new list.  If the final argument
+is itself a list, then its elements become in effect elements of the
+result list.  If the final element is not a list, the result is a
+dotted list since its final @sc{cdr} is not @code{nil} as required
+in a true list.
+
+In Emacs 20 and before, the @code{append} function also allowed
+integers as (non last) arguments.  It converted them to strings of
+digits, making up the decimal print representation of the integer, and
+then used the strings instead of the original integers.  This obsolete
+usage no longer works.  The proper way to convert an integer to a
+decimal number in this way is with @code{format} (@pxref{Formatting
+Strings}) or @code{number-to-string} (@pxref{String Conversion}).
+@end defun
+
+  Here is an example of using @code{append}:
+
+@example
+@group
+(setq trees '(pine oak))
+     @result{} (pine oak)
+(setq more-trees (append '(maple birch) trees))
+     @result{} (maple birch pine oak)
+@end group
+
+@group
+trees
+     @result{} (pine oak)
+more-trees
+     @result{} (maple birch pine oak)
+@end group
+@group
+(eq trees (cdr (cdr more-trees)))
+     @result{} t
+@end group
+@end example
+
+  You can see how @code{append} works by looking at a box diagram.  The
+variable @code{trees} is set to the list @code{(pine oak)} and then the
+variable @code{more-trees} is set to the list @code{(maple birch pine
+oak)}.  However, the variable @code{trees} continues to refer to the
+original list:
+
+@smallexample
+@group
+more-trees                trees
+|                           |
+|     --- ---      --- ---   -> --- ---      --- ---
+ --> |   |   |--> |   |   |--> |   |   |--> |   |   |--> nil
+      --- ---      --- ---      --- ---      --- ---
+       |            |            |            |
+       |            |            |            |
+        --> maple    -->birch     --> pine     --> oak
+@end group
+@end smallexample
+
+  An empty sequence contributes nothing to the value returned by
+@code{append}.  As a consequence of this, a final @code{nil} argument
+forces a copy of the previous argument:
+
+@example
+@group
+trees
+     @result{} (pine oak)
+@end group
+@group
+(setq wood (append trees nil))
+     @result{} (pine oak)
+@end group
+@group
+wood
+     @result{} (pine oak)
+@end group
+@group
+(eq wood trees)
+     @result{} nil
+@end group
+@end example
+
+@noindent
+This once was the usual way to copy a list, before the function
+@code{copy-sequence} was invented.  @xref{Sequences Arrays Vectors}.
+
+  Here we show the use of vectors and strings as arguments to @code{append}:
+
+@example
+@group
+(append [a b] "cd" nil)
+     @result{} (a b 99 100)
+@end group
+@end example
+
+  With the help of @code{apply} (@pxref{Calling Functions}), we can append
+all the lists in a list of lists:
+
+@example
+@group
+(apply 'append '((a b c) nil (x y z) nil))
+     @result{} (a b c x y z)
+@end group
+@end example
+
+  If no @var{sequences} are given, @code{nil} is returned:
+
+@example
+@group
+(append)
+     @result{} nil
+@end group
+@end example
+
+  Here are some examples where the final argument is not a list:
+
+@example
+(append '(x y) 'z)
+     @result{} (x y . z)
+(append '(x y) [z])
+     @result{} (x y . [z])
+@end example
+
+@noindent
+The second example shows that when the final argument is a sequence but
+not a list, the sequence's elements do not become elements of the
+resulting list.  Instead, the sequence becomes the final @sc{cdr}, like
+any other non-list final argument.
+
+@defun reverse list
+This function creates a new list whose elements are the elements of
+@var{list}, but in reverse order.  The original argument @var{list} is
+@emph{not} altered.
+
+@example
+@group
+(setq x '(1 2 3 4))
+     @result{} (1 2 3 4)
+@end group
+@group
+(reverse x)
+     @result{} (4 3 2 1)
+x
+     @result{} (1 2 3 4)
+@end group
+@end example
+@end defun
+
+@defun copy-tree tree &optional vecp
+This function returns a copy of the tree @code{tree}.  If @var{tree} is a
+cons cell, this makes a new cons cell with the same @sc{car} and
+@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
+same way.
+
+Normally, when @var{tree} is anything other than a cons cell,
+@code{copy-tree} simply returns @var{tree}.  However, if @var{vecp} is
+non-@code{nil}, it copies vectors too (and operates recursively on
+their elements).
+@end defun
+
+@defun number-sequence from &optional to separation
+This returns a list of numbers starting with @var{from} and
+incrementing by @var{separation}, and ending at or just before
+@var{to}.  @var{separation} can be positive or negative and defaults
+to 1.  If @var{to} is @code{nil} or numerically equal to @var{from},
+the value is the one-element list @code{(@var{from})}.  If @var{to} is
+less than @var{from} with a positive @var{separation}, or greater than
+@var{from} with a negative @var{separation}, the value is @code{nil}
+because those arguments specify an empty sequence.
+
+If @var{separation} is 0 and @var{to} is neither @code{nil} nor
+numerically equal to @var{from}, @code{number-sequence} signals an
+error, since those arguments specify an infinite sequence.
+
+All arguments can be integers or floating point numbers.  However,
+floating point arguments can be tricky, because floating point
+arithmetic is inexact.  For instance, depending on the machine, it may
+quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
+the one element list @code{(0.4)}, whereas
+@code{(number-sequence 0.4 0.8 0.2)} returns a list with three
+elements.  The @var{n}th element of the list is computed by the exact
+formula @code{(+ @var{from} (* @var{n} @var{separation}))}.  Thus, if
+one wants to make sure that @var{to} is included in the list, one can
+pass an expression of this exact type for @var{to}.  Alternatively,
+one can replace @var{to} with a slightly larger value (or a slightly
+more negative value if @var{separation} is negative).
+
+Some examples:
+
+@example
+(number-sequence 4 9)
+     @result{} (4 5 6 7 8 9)
+(number-sequence 9 4 -1)
+     @result{} (9 8 7 6 5 4)
+(number-sequence 9 4 -2)
+     @result{} (9 7 5)
+(number-sequence 8)
+     @result{} (8)
+(number-sequence 8 5)
+     @result{} nil
+(number-sequence 5 8 -1)
+     @result{} nil
+(number-sequence 1.5 6 2)
+     @result{} (1.5 3.5 5.5)
+@end example
+@end defun
+
+@node List Variables
+@section Modifying List Variables
+
+  These functions, and one macro, provide convenient ways
+to modify a list which is stored in a variable.
+
+@defmac push newelt listname
+This macro provides an alternative way to write
+@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
+
+@example
+(setq l '(a b))
+     @result{} (a b)
+(push 'c l)
+     @result{} (c a b)
+l
+     @result{} (c a b)
+@end example
+@end defmac
+
+  Two functions modify lists that are the values of variables.
+
+@defun add-to-list symbol element &optional append compare-fn
+This function sets the variable @var{symbol} by consing @var{element}
+onto the old value, if @var{element} is not already a member of that
+value.  It returns the resulting list, whether updated or not.  The
+value of @var{symbol} had better be a list already before the call.
+@code{add-to-list} uses @var{compare-fn} to compare @var{element}
+against existing list members; if @var{compare-fn} is @code{nil}, it
+uses @code{equal}.
+
+Normally, if @var{element} is added, it is added to the front of
+@var{symbol}, but if the optional argument @var{append} is
+non-@code{nil}, it is added at the end.
+
+The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
+is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
+the argument yourself if that is what you want.
+@end defun
+
+Here's a scenario showing how to use @code{add-to-list}:
+
+@example
+(setq foo '(a b))
+     @result{} (a b)
+
+(add-to-list 'foo 'c)     ;; @r{Add @code{c}.}
+     @result{} (c a b)
+
+(add-to-list 'foo 'b)     ;; @r{No effect.}
+     @result{} (c a b)
+
+foo                       ;; @r{@code{foo} was changed.}
+     @result{} (c a b)
+@end example
+
+  An equivalent expression for @code{(add-to-list '@var{var}
+@var{value})} is this:
+
+@example
+(or (member @var{value} @var{var})
+    (setq @var{var} (cons @var{value} @var{var})))
+@end example
+
+@defun add-to-ordered-list symbol element &optional order
+This function sets the variable @var{symbol} by inserting
+@var{element} into the old value, which must be a list, at the
+position specified by @var{order}.  If @var{element} is already a
+member of the list, its position in the list is adjusted according
+to @var{order}.  Membership is tested using @code{eq}.
+This function returns the resulting list, whether updated or not.
+
+The @var{order} is typically a number (integer or float), and the
+elements of the list are sorted in non-decreasing numerical order.
+
+@var{order} may also be omitted or @code{nil}.  Then the numeric order
+of @var{element} stays unchanged if it already has one; otherwise,
+@var{element} has no numeric order.  Elements without a numeric list
+order are placed at the end of the list, in no particular order.
+
+Any other value for @var{order} removes the numeric order of @var{element}
+if it already has one; otherwise, it is equivalent to @code{nil}.
+
+The argument @var{symbol} is not implicitly quoted;
+@code{add-to-ordered-list} is an ordinary function, like @code{set}
+and unlike @code{setq}.  Quote the argument yourself if that is what
+you want.
+
+The ordering information is stored in a hash table on @var{symbol}'s
+@code{list-order} property.
+@end defun
+
+Here's a scenario showing how to use @code{add-to-ordered-list}:
+
+@example
+(setq foo '())
+     @result{} nil
+
+(add-to-ordered-list 'foo 'a 1)     ;; @r{Add @code{a}.}
+     @result{} (a)
+
+(add-to-ordered-list 'foo 'c 3)     ;; @r{Add @code{c}.}
+     @result{} (a c)
+
+(add-to-ordered-list 'foo 'b 2)     ;; @r{Add @code{b}.}
+     @result{} (a b c)
+
+(add-to-ordered-list 'foo 'b 4)     ;; @r{Move @code{b}.}
+     @result{} (a c b)
+
+(add-to-ordered-list 'foo 'd)       ;; @r{Append @code{d}.}
+     @result{} (a c b d)
+
+(add-to-ordered-list 'foo 'e)       ;; @r{Add @code{e}}.
+     @result{} (a c b e d)
+
+foo                       ;; @r{@code{foo} was changed.}
+     @result{} (a c b e d)
+@end example
+
+@node Modifying Lists
+@section Modifying Existing List Structure
+@cindex destructive list operations
+
+  You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
+primitives @code{setcar} and @code{setcdr}.  We call these ``destructive''
+operations because they change existing list structure.
+
+@cindex CL note---@code{rplaca} vs @code{setcar}
+@quotation
+@findex rplaca
+@findex rplacd
+@b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and
+@code{rplacd} to alter list structure; they change structure the same
+way as @code{setcar} and @code{setcdr}, but the Common Lisp functions
+return the cons cell while @code{setcar} and @code{setcdr} return the
+new @sc{car} or @sc{cdr}.
+@end quotation
+
+@menu
+* Setcar::          Replacing an element in a list.
+* Setcdr::          Replacing part of the list backbone.
+                      This can be used to remove or add elements.
+* Rearrangement::   Reordering the elements in a list; combining lists.
+@end menu
+
+@node Setcar
+@subsection Altering List Elements with @code{setcar}
+
+  Changing the @sc{car} of a cons cell is done with @code{setcar}.  When
+used on a list, @code{setcar} replaces one element of a list with a
+different element.
+
+@defun setcar cons object
+This function stores @var{object} as the new @sc{car} of @var{cons},
+replacing its previous @sc{car}.  In other words, it changes the
+@sc{car} slot of @var{cons} to refer to @var{object}.  It returns the
+value @var{object}.  For example:
+
+@example
+@group
+(setq x '(1 2))
+     @result{} (1 2)
+@end group
+@group
+(setcar x 4)
+     @result{} 4
+@end group
+@group
+x
+     @result{} (4 2)
+@end group
+@end example
+@end defun
+
+  When a cons cell is part of the shared structure of several lists,
+storing a new @sc{car} into the cons changes one element of each of
+these lists.  Here is an example:
+
+@example
+@group
+;; @r{Create two lists that are partly shared.}
+(setq x1 '(a b c))
+     @result{} (a b c)
+(setq x2 (cons 'z (cdr x1)))
+     @result{} (z b c)
+@end group
+
+@group
+;; @r{Replace the @sc{car} of a shared link.}
+(setcar (cdr x1) 'foo)
+     @result{} foo
+x1                           ; @r{Both lists are changed.}
+     @result{} (a foo c)
+x2
+     @result{} (z foo c)
+@end group
+
+@group
+;; @r{Replace the @sc{car} of a link that is not shared.}
+(setcar x1 'baz)
+     @result{} baz
+x1                           ; @r{Only one list is changed.}
+     @result{} (baz foo c)
+x2
+     @result{} (z foo c)
+@end group
+@end example
+
+  Here is a graphical depiction of the shared structure of the two lists
+in the variables @code{x1} and @code{x2}, showing why replacing @code{b}
+changes them both:
+
+@example
+@group
+        --- ---        --- ---      --- ---
+x1---> |   |   |----> |   |   |--> |   |   |--> nil
+        --- ---        --- ---      --- ---
+         |        -->   |            |
+         |       |      |            |
+          --> a  |       --> b        --> c
+                 |
+       --- ---   |
+x2--> |   |   |--
+       --- ---
+        |
+        |
+         --> z
+@end group
+@end example
+
+  Here is an alternative form of box diagram, showing the same relationship:
+
+@example
+@group
+x1:
+ --------------       --------------       --------------
+| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
+|   a   |   o------->|   b   |   o------->|   c   |  nil |
+|       |      |  -->|       |      |     |       |      |
+ --------------  |    --------------       --------------
+                 |
+x2:              |
+ --------------  |
+| car   | cdr  | |
+|   z   |   o----
+|       |      |
+ --------------
+@end group
+@end example
+
+@node Setcdr
+@subsection Altering the CDR of a List
+
+  The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
+
+@defun setcdr cons object
+This function stores @var{object} as the new @sc{cdr} of @var{cons},
+replacing its previous @sc{cdr}.  In other words, it changes the
+@sc{cdr} slot of @var{cons} to refer to @var{object}.  It returns the
+value @var{object}.
+@end defun
+
+  Here is an example of replacing the @sc{cdr} of a list with a
+different list.  All but the first element of the list are removed in
+favor of a different sequence of elements.  The first element is
+unchanged, because it resides in the @sc{car} of the list, and is not
+reached via the @sc{cdr}.
+
+@example
+@group
+(setq x '(1 2 3))
+     @result{} (1 2 3)
+@end group
+@group
+(setcdr x '(4))
+     @result{} (4)
+@end group
+@group
+x
+     @result{} (1 4)
+@end group
+@end example
+
+  You can delete elements from the middle of a list by altering the
+@sc{cdr}s of the cons cells in the list.  For example, here we delete
+the second element, @code{b}, from the list @code{(a b c)}, by changing
+the @sc{cdr} of the first cons cell:
+
+@example
+@group
+(setq x1 '(a b c))
+     @result{} (a b c)
+(setcdr x1 (cdr (cdr x1)))
+     @result{} (c)
+x1
+     @result{} (a c)
+@end group
+@end example
+
+  Here is the result in box notation:
+
+@smallexample
+@group
+                   --------------------
+                  |                    |
+ --------------   |   --------------   |    --------------
+| car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
+|   a   |   o-----   |   b   |   o-------->|   c   |  nil |
+|       |      |     |       |      |      |       |      |
+ --------------       --------------        --------------
+@end group
+@end smallexample
+
+@noindent
+The second cons cell, which previously held the element @code{b}, still
+exists and its @sc{car} is still @code{b}, but it no longer forms part
+of this list.
+
+  It is equally easy to insert a new element by changing @sc{cdr}s:
+
+@example
+@group
+(setq x1 '(a b c))
+     @result{} (a b c)
+(setcdr x1 (cons 'd (cdr x1)))
+     @result{} (d b c)
+x1
+     @result{} (a d b c)
+@end group
+@end example
+
+  Here is this result in box notation:
+
+@smallexample
+@group
+ --------------        -------------       -------------
+| car  | cdr   |      | car  | cdr  |     | car  | cdr  |
+|   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
+|      |   |   |  |   |      |      |     |      |      |
+ --------- | --   |    -------------       -------------
+           |      |
+     -----         --------
+    |                      |
+    |    ---------------   |
+    |   | car   | cdr   |  |
+     -->|   d   |   o------
+        |       |       |
+         ---------------
+@end group
+@end smallexample
+
+@node Rearrangement
+@subsection Functions that Rearrange Lists
+@cindex rearrangement of lists
+@cindex modification of lists
+
+  Here are some functions that rearrange lists ``destructively'' by
+modifying the @sc{cdr}s of their component cons cells.  We call these
+functions ``destructive'' because they chew up the original lists passed
+to them as arguments, relinking their cons cells to form a new list that
+is the returned value.
+
+@ifnottex
+  See @code{delq}, in @ref{Sets And Lists}, for another function
+that modifies cons cells.
+@end ifnottex
+@iftex
+   The function @code{delq} in the following section is another example
+of destructive list manipulation.
+@end iftex
+
+@defun nconc &rest lists
+@cindex concatenating lists
+@cindex joining lists
+This function returns a list containing all the elements of @var{lists}.
+Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
+@emph{not} copied.  Instead, the last @sc{cdr} of each of the
+@var{lists} is changed to refer to the following list.  The last of the
+@var{lists} is not altered.  For example:
+
+@example
+@group
+(setq x '(1 2 3))
+     @result{} (1 2 3)
+@end group
+@group
+(nconc x '(4 5))
+     @result{} (1 2 3 4 5)
+@end group
+@group
+x
+     @result{} (1 2 3 4 5)
+@end group
+@end example
+
+   Since the last argument of @code{nconc} is not itself modified, it is
+reasonable to use a constant list, such as @code{'(4 5)}, as in the
+above example.  For the same reason, the last argument need not be a
+list:
+
+@example
+@group
+(setq x '(1 2 3))
+     @result{} (1 2 3)
+@end group
+@group
+(nconc x 'z)
+     @result{} (1 2 3 . z)
+@end group
+@group
+x
+     @result{} (1 2 3 . z)
+@end group
+@end example
+
+However, the other arguments (all but the last) must be lists.
+
+A common pitfall is to use a quoted constant list as a non-last
+argument to @code{nconc}.  If you do this, your program will change
+each time you run it!  Here is what happens:
+
+@smallexample
+@group
+(defun add-foo (x)            ; @r{We want this function to add}
+  (nconc '(foo) x))           ;   @r{@code{foo} to the front of its arg.}
+@end group
+
+@group
+(symbol-function 'add-foo)
+     @result{} (lambda (x) (nconc (quote (foo)) x))
+@end group
+
+@group
+(setq xx (add-foo '(1 2)))    ; @r{It seems to work.}
+     @result{} (foo 1 2)
+@end group
+@group
+(setq xy (add-foo '(3 4)))    ; @r{What happened?}
+     @result{} (foo 1 2 3 4)
+@end group
+@group
+(eq xx xy)
+     @result{} t
+@end group
+
+@group
+(symbol-function 'add-foo)
+     @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
+@end group
+@end smallexample
+@end defun
+
+@defun nreverse list
+@cindex reversing a list
+  This function reverses the order of the elements of @var{list}.
+Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
+the @sc{cdr}s in the cons cells forming the list.  The cons cell that
+used to be the last one in @var{list} becomes the first cons cell of the
+value.
+
+  For example:
+
+@example
+@group
+(setq x '(a b c))
+     @result{} (a b c)
+@end group
+@group
+x
+     @result{} (a b c)
+(nreverse x)
+     @result{} (c b a)
+@end group
+@group
+;; @r{The cons cell that was first is now last.}
+x
+     @result{} (a)
+@end group
+@end example
+
+  To avoid confusion, we usually store the result of @code{nreverse}
+back in the same variable which held the original list:
+
+@example
+(setq x (nreverse x))
+@end example
+
+  Here is the @code{nreverse} of our favorite example, @code{(a b c)},
+presented graphically:
+
+@smallexample
+@group
+@r{Original list head:}                       @r{Reversed list:}
+ -------------        -------------        ------------
+| car  | cdr  |      | car  | cdr  |      | car | cdr  |
+|   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
+|      |      |   |  |      |   |  |   |  |     |   |  |
+ -------------    |   --------- | -    |   -------- | -
+                  |             |      |            |
+                   -------------        ------------
+@end group
+@end smallexample
+@end defun
+
+@defun sort list predicate
+@cindex stable sort
+@cindex sorting lists
+This function sorts @var{list} stably, though destructively, and
+returns the sorted list.  It compares elements using @var{predicate}.  A
+stable sort is one in which elements with equal sort keys maintain their
+relative order before and after the sort.  Stability is important when
+successive sorts are used to order elements according to different
+criteria.
+
+The argument @var{predicate} must be a function that accepts two
+arguments.  It is called with two elements of @var{list}.  To get an
+increasing order sort, the @var{predicate} should return non-@code{nil} if the
+first element is ``less than'' the second, or @code{nil} if not.
+
+The comparison function @var{predicate} must give reliable results for
+any given pair of arguments, at least within a single call to
+@code{sort}.  It must be @dfn{antisymmetric}; that is, if @var{a} is
+less than @var{b}, @var{b} must not be less than @var{a}.  It must be
+@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
+is less than @var{c}, then @var{a} must be less than @var{c}.  If you
+use a comparison function which does not meet these requirements, the
+result of @code{sort} is unpredictable.
+
+The destructive aspect of @code{sort} is that it rearranges the cons
+cells forming @var{list} by changing @sc{cdr}s.  A nondestructive sort
+function would create new cons cells to store the elements in their
+sorted order.  If you wish to make a sorted copy without destroying the
+original, copy it first with @code{copy-sequence} and then sort.
+
+Sorting does not change the @sc{car}s of the cons cells in @var{list};
+the cons cell that originally contained the element @code{a} in
+@var{list} still has @code{a} in its @sc{car} after sorting, but it now
+appears in a different position in the list due to the change of
+@sc{cdr}s.  For example:
+
+@example
+@group
+(setq nums '(1 3 2 6 5 4 0))
+     @result{} (1 3 2 6 5 4 0)
+@end group
+@group
+(sort nums '<)
+     @result{} (0 1 2 3 4 5 6)
+@end group
+@group
+nums
+     @result{} (1 2 3 4 5 6)
+@end group
+@end example
+
+@noindent
+@strong{Warning}: Note that the list in @code{nums} no longer contains
+0; this is the same cons cell that it was before, but it is no longer
+the first one in the list.  Don't assume a variable that formerly held
+the argument now holds the entire sorted list!  Instead, save the result
+of @code{sort} and use that.  Most often we store the result back into
+the variable that held the original list:
+
+@example
+(setq nums (sort nums '<))
+@end example
+
+@xref{Sorting}, for more functions that perform sorting.
+See @code{documentation} in @ref{Accessing Documentation}, for a
+useful example of @code{sort}.
+@end defun
+
+@node Sets And Lists
+@section Using Lists as Sets
+@cindex lists as sets
+@cindex sets
+
+  A list can represent an unordered mathematical set---simply consider a
+value an element of a set if it appears in the list, and ignore the
+order of the list.  To form the union of two sets, use @code{append} (as
+long as you don't mind having duplicate elements).  You can remove
+@code{equal} duplicates using @code{delete-dups}.  Other useful
+functions for sets include @code{memq} and @code{delq}, and their
+@code{equal} versions, @code{member} and @code{delete}.
+
+@cindex CL note---lack @code{union}, @code{intersection}
+@quotation
+@b{Common Lisp note:} Common Lisp has functions @code{union} (which
+avoids duplicate elements) and @code{intersection} for set operations,
+but GNU Emacs Lisp does not have them.  You can write them in Lisp if
+you wish.
+@end quotation
+
+@defun memq object list
+@cindex membership in a list
+This function tests to see whether @var{object} is a member of
+@var{list}.  If it is, @code{memq} returns a list starting with the
+first occurrence of @var{object}.  Otherwise, it returns @code{nil}.
+The letter @samp{q} in @code{memq} says that it uses @code{eq} to
+compare @var{object} against the elements of the list.  For example:
+
+@example
+@group
+(memq 'b '(a b c b a))
+     @result{} (b c b a)
+@end group
+@group
+(memq '(2) '((1) (2)))    ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun delq object list
+@cindex deleting list elements
+This function destructively removes all elements @code{eq} to
+@var{object} from @var{list}.  The letter @samp{q} in @code{delq} says
+that it uses @code{eq} to compare @var{object} against the elements of
+the list, like @code{memq} and @code{remq}.
+@end defun
+
+When @code{delq} deletes elements from the front of the list, it does so
+simply by advancing down the list and returning a sublist that starts
+after those elements:
+
+@example
+@group
+(delq 'a '(a b c)) @equiv{} (cdr '(a b c))
+@end group
+@end example
+
+When an element to be deleted appears in the middle of the list,
+removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
+
+@example
+@group
+(setq sample-list '(a b c (4)))
+     @result{} (a b c (4))
+@end group
+@group
+(delq 'a sample-list)
+     @result{} (b c (4))
+@end group
+@group
+sample-list
+     @result{} (a b c (4))
+@end group
+@group
+(delq 'c sample-list)
+     @result{} (a b (4))
+@end group
+@group
+sample-list
+     @result{} (a b (4))
+@end group
+@end example
+
+Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to
+splice out the third element, but @code{(delq 'a sample-list)} does not
+splice anything---it just returns a shorter list.  Don't assume that a
+variable which formerly held the argument @var{list} now has fewer
+elements, or that it still holds the original list!  Instead, save the
+result of @code{delq} and use that.  Most often we store the result back
+into the variable that held the original list:
+
+@example
+(setq flowers (delq 'rose flowers))
+@end example
+
+In the following example, the @code{(4)} that @code{delq} attempts to match
+and the @code{(4)} in the @code{sample-list} are not @code{eq}:
+
+@example
+@group
+(delq '(4) sample-list)
+     @result{} (a c (4))
+@end group
+
+If you want to delete elements that are @code{equal} to a given value,
+use @code{delete} (see below).
+@end example
+
+@defun remq object list
+This function returns a copy of @var{list}, with all elements removed
+which are @code{eq} to @var{object}.  The letter @samp{q} in @code{remq}
+says that it uses @code{eq} to compare @var{object} against the elements
+of @code{list}.
+
+@example
+@group
+(setq sample-list '(a b c a b c))
+     @result{} (a b c a b c)
+@end group
+@group
+(remq 'a sample-list)
+     @result{} (b c b c)
+@end group
+@group
+sample-list
+     @result{} (a b c a b c)
+@end group
+@end example
+@end defun
+
+@defun memql object list
+The function @code{memql} tests to see whether @var{object} is a member
+of @var{list}, comparing members with @var{object} using @code{eql},
+so floating point elements are compared by value.
+If @var{object} is a member, @code{memql} returns a list starting with
+its first occurrence in @var{list}.  Otherwise, it returns @code{nil}.
+
+Compare this with @code{memq}:
+
+@example
+@group
+(memql 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} are @code{eql}.}
+     @result{} (1.2 1.3)
+@end group
+@group
+(memq 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} are not @code{eq}.}
+     @result{} nil
+@end group
+@end example
+@end defun
+
+The following three functions are like @code{memq}, @code{delq} and
+@code{remq}, but use @code{equal} rather than @code{eq} to compare
+elements.  @xref{Equality Predicates}.
+
+@defun member object list
+The function @code{member} tests to see whether @var{object} is a member
+of @var{list}, comparing members with @var{object} using @code{equal}.
+If @var{object} is a member, @code{member} returns a list starting with
+its first occurrence in @var{list}.  Otherwise, it returns @code{nil}.
+
+Compare this with @code{memq}:
+
+@example
+@group
+(member '(2) '((1) (2)))  ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
+     @result{} ((2))
+@end group
+@group
+(memq '(2) '((1) (2)))    ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
+     @result{} nil
+@end group
+@group
+;; @r{Two strings with the same contents are @code{equal}.}
+(member "foo" '("foo" "bar"))
+     @result{} ("foo" "bar")
+@end group
+@end example
+@end defun
+
+@defun delete object sequence
+If @code{sequence} is a list, this function destructively removes all
+elements @code{equal} to @var{object} from @var{sequence}.  For lists,
+@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it
+uses @code{equal} to compare elements with @var{object}, like
+@code{member}; when it finds an element that matches, it cuts the
+element out just as @code{delq} would.
+
+If @code{sequence} is a vector or string, @code{delete} returns a copy
+of @code{sequence} with all elements @code{equal} to @code{object}
+removed.
+
+For example:
+
+@example
+@group
+(setq l '((2) (1) (2)))
+(delete '(2) l)
+     @result{} ((1))
+l
+     @result{} ((2) (1))
+;; @r{If you want to change @code{l} reliably,}
+;; @r{write @code{(setq l (delete elt l))}.}
+@end group
+@group
+(setq l '((2) (1) (2)))
+(delete '(1) l)
+     @result{} ((2) (2))
+l
+     @result{} ((2) (2))
+;; @r{In this case, it makes no difference whether you set @code{l},}
+;; @r{but you should do so for the sake of the other case.}
+@end group
+@group
+(delete '(2) [(2) (1) (2)])
+     @result{} [(1)]
+@end group
+@end example
+@end defun
+
+@defun remove object sequence
+This function is the non-destructive counterpart of @code{delete}.  It
+returns a copy of @code{sequence}, a list, vector, or string, with
+elements @code{equal} to @code{object} removed.  For example:
+
+@example
+@group
+(remove '(2) '((2) (1) (2)))
+     @result{} ((1))
+@end group
+@group
+(remove '(2) [(2) (1) (2)])
+     @result{} [(1)]
+@end group
+@end example
+@end defun
+
+@quotation
+@b{Common Lisp note:} The functions @code{member}, @code{delete} and
+@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common
+Lisp.  The Common Lisp versions do not use @code{equal} to compare
+elements.
+@end quotation
+
+@defun member-ignore-case object list
+This function is like @code{member}, except that @var{object} should
+be a string and that it ignores differences in letter-case and text
+representation: upper-case and lower-case letters are treated as
+equal, and unibyte strings are converted to multibyte prior to
+comparison.
+@end defun
+
+@defun delete-dups list
+This function destructively removes all @code{equal} duplicates from
+@var{list}, stores the result in @var{list} and returns it.  Of
+several @code{equal} occurrences of an element in @var{list},
+@code{delete-dups} keeps the first one.
+@end defun
+
+  See also the function @code{add-to-list}, in @ref{List Variables},
+for a way to add an element to a list stored in a variable and used as a
+set.
+
+@node Association Lists
+@section Association Lists
+@cindex association list
+@cindex alist
+
+  An @dfn{association list}, or @dfn{alist} for short, records a mapping
+from keys to values.  It is a list of cons cells called
+@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the
+@sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key''
+is not related to the term ``key sequence''; it means a value used to
+look up an item in a table.  In this case, the table is the alist, and
+the alist associations are the items.}
+
+  Here is an example of an alist.  The key @code{pine} is associated with
+the value @code{cones}; the key @code{oak} is associated with
+@code{acorns}; and the key @code{maple} is associated with @code{seeds}.
+
+@example
+@group
+((pine . cones)
+ (oak . acorns)
+ (maple . seeds))
+@end group
+@end example
+
+  Both the values and the keys in an alist may be any Lisp objects.
+For example, in the following alist, the symbol @code{a} is
+associated with the number @code{1}, and the string @code{"b"} is
+associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of
+the alist element:
+
+@example
+((a . 1) ("b" 2 3))
+@end example
+
+  Sometimes it is better to design an alist to store the associated
+value in the @sc{car} of the @sc{cdr} of the element.  Here is an
+example of such an alist:
+
+@example
+((rose red) (lily white) (buttercup yellow))
+@end example
+
+@noindent
+Here we regard @code{red} as the value associated with @code{rose}.  One
+advantage of this kind of alist is that you can store other related
+information---even a list of other items---in the @sc{cdr} of the
+@sc{cdr}.  One disadvantage is that you cannot use @code{rassq} (see
+below) to find the element containing a given value.  When neither of
+these considerations is important, the choice is a matter of taste, as
+long as you are consistent about it for any given alist.
+
+  The same alist shown above could be regarded as having the
+associated value in the @sc{cdr} of the element; the value associated
+with @code{rose} would be the list @code{(red)}.
+
+  Association lists are often used to record information that you might
+otherwise keep on a stack, since new associations may be added easily to
+the front of the list.  When searching an association list for an
+association with a given key, the first one found is returned, if there
+is more than one.
+
+  In Emacs Lisp, it is @emph{not} an error if an element of an
+association list is not a cons cell.  The alist search functions simply
+ignore such elements.  Many other versions of Lisp signal errors in such
+cases.
+
+  Note that property lists are similar to association lists in several
+respects.  A property list behaves like an association list in which
+each key can occur only once.  @xref{Property Lists}, for a comparison
+of property lists and association lists.
+
+@defun assoc key alist
+This function returns the first association for @var{key} in
+@var{alist}, comparing @var{key} against the alist elements using
+@code{equal} (@pxref{Equality Predicates}).  It returns @code{nil} if no
+association in @var{alist} has a @sc{car} @code{equal} to @var{key}.
+For example:
+
+@smallexample
+(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+     @result{} ((pine . cones) (oak . acorns) (maple . seeds))
+(assoc 'oak trees)
+     @result{} (oak . acorns)
+(cdr (assoc 'oak trees))
+     @result{} acorns
+(assoc 'birch trees)
+     @result{} nil
+@end smallexample
+
+Here is another example, in which the keys and values are not symbols:
+
+@smallexample
+(setq needles-per-cluster
+      '((2 "Austrian Pine" "Red Pine")
+        (3 "Pitch Pine")
+        (5 "White Pine")))
+
+(cdr (assoc 3 needles-per-cluster))
+     @result{} ("Pitch Pine")
+(cdr (assoc 2 needles-per-cluster))
+     @result{} ("Austrian Pine" "Red Pine")
+@end smallexample
+@end defun
+
+  The function @code{assoc-string} is much like @code{assoc} except
+that it ignores certain differences between strings.  @xref{Text
+Comparison}.
+
+@defun rassoc value alist
+This function returns the first association with value @var{value} in
+@var{alist}.  It returns @code{nil} if no association in @var{alist} has
+a @sc{cdr} @code{equal} to @var{value}.
+
+@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
+each @var{alist} association instead of the @sc{car}.  You can think of
+this as ``reverse @code{assoc},'' finding the key for a given value.
+@end defun
+
+@defun assq key alist
+This function is like @code{assoc} in that it returns the first
+association for @var{key} in @var{alist}, but it makes the comparison
+using @code{eq} instead of @code{equal}.  @code{assq} returns @code{nil}
+if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}.
+This function is used more often than @code{assoc}, since @code{eq} is
+faster than @code{equal} and most alists use symbols as keys.
+@xref{Equality Predicates}.
+
+@smallexample
+(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+     @result{} ((pine . cones) (oak . acorns) (maple . seeds))
+(assq 'pine trees)
+     @result{} (pine . cones)
+@end smallexample
+
+On the other hand, @code{assq} is not usually useful in alists where the
+keys may not be symbols:
+
+@smallexample
+(setq leaves
+      '(("simple leaves" . oak)
+        ("compound leaves" . horsechestnut)))
+
+(assq "simple leaves" leaves)
+     @result{} nil
+(assoc "simple leaves" leaves)
+     @result{} ("simple leaves" . oak)
+@end smallexample
+@end defun
+
+@defun rassq value alist
+This function returns the first association with value @var{value} in
+@var{alist}.  It returns @code{nil} if no association in @var{alist} has
+a @sc{cdr} @code{eq} to @var{value}.
+
+@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of
+each @var{alist} association instead of the @sc{car}.  You can think of
+this as ``reverse @code{assq},'' finding the key for a given value.
+
+For example:
+
+@smallexample
+(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+
+(rassq 'acorns trees)
+     @result{} (oak . acorns)
+(rassq 'spores trees)
+     @result{} nil
+@end smallexample
+
+@code{rassq} cannot search for a value stored in the @sc{car}
+of the @sc{cdr} of an element:
+
+@smallexample
+(setq colors '((rose red) (lily white) (buttercup yellow)))
+
+(rassq 'white colors)
+     @result{} nil
+@end smallexample
+
+In this case, the @sc{cdr} of the association @code{(lily white)} is not
+the symbol @code{white}, but rather the list @code{(white)}.  This
+becomes clearer if the association is written in dotted pair notation:
+
+@smallexample
+(lily white) @equiv{} (lily . (white))
+@end smallexample
+@end defun
+
+@defun assoc-default key alist &optional test default
+This function searches @var{alist} for a match for @var{key}.  For each
+element of @var{alist}, it compares the element (if it is an atom) or
+the element's @sc{car} (if it is a cons) against @var{key}, by calling
+@var{test} with two arguments: the element or its @sc{car}, and
+@var{key}.  The arguments are passed in that order so that you can get
+useful results using @code{string-match} with an alist that contains
+regular expressions (@pxref{Regexp Search}).  If @var{test} is omitted
+or @code{nil}, @code{equal} is used for comparison.
+
+If an alist element matches @var{key} by this criterion,
+then @code{assoc-default} returns a value based on this element.
+If the element is a cons, then the value is the element's @sc{cdr}.
+Otherwise, the return value is @var{default}.
+
+If no alist element matches @var{key}, @code{assoc-default} returns
+@code{nil}.
+@end defun
+
+@defun copy-alist alist
+@cindex copying alists
+This function returns a two-level deep copy of @var{alist}: it creates a
+new copy of each association, so that you can alter the associations of
+the new alist without changing the old one.
+
+@smallexample
+@group
+(setq needles-per-cluster
+      '((2 . ("Austrian Pine" "Red Pine"))
+        (3 . ("Pitch Pine"))
+@end group
+        (5 . ("White Pine"))))
+@result{}
+((2 "Austrian Pine" "Red Pine")
+ (3 "Pitch Pine")
+ (5 "White Pine"))
+
+(setq copy (copy-alist needles-per-cluster))
+@result{}
+((2 "Austrian Pine" "Red Pine")
+ (3 "Pitch Pine")
+ (5 "White Pine"))
+
+(eq needles-per-cluster copy)
+     @result{} nil
+(equal needles-per-cluster copy)
+     @result{} t
+(eq (car needles-per-cluster) (car copy))
+     @result{} nil
+(cdr (car (cdr needles-per-cluster)))
+     @result{} ("Pitch Pine")
+@group
+(eq (cdr (car (cdr needles-per-cluster)))
+    (cdr (car (cdr copy))))
+     @result{} t
+@end group
+@end smallexample
+
+  This example shows how @code{copy-alist} makes it possible to change
+the associations of one copy without affecting the other:
+
+@smallexample
+@group
+(setcdr (assq 3 copy) '("Martian Vacuum Pine"))
+(cdr (assq 3 needles-per-cluster))
+     @result{} ("Pitch Pine")
+@end group
+@end smallexample
+@end defun
+
+@defun assq-delete-all key alist
+This function deletes from @var{alist} all the elements whose @sc{car}
+is @code{eq} to @var{key}, much as if you used @code{delq} to delete
+each such element one by one.  It returns the shortened alist, and
+often modifies the original list structure of @var{alist}.  For
+correct results, use the return value of @code{assq-delete-all} rather
+than looking at the saved value of @var{alist}.
+
+@example
+(setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
+     @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
+(assq-delete-all 'foo alist)
+     @result{} ((bar 2) (lose 4))
+alist
+     @result{} ((foo 1) (bar 2) (lose 4))
+@end example
+@end defun
+
+@defun rassq-delete-all value alist
+This function deletes from @var{alist} all the elements whose @sc{cdr}
+is @code{eq} to @var{value}.  It returns the shortened alist, and
+often modifies the original list structure of @var{alist}.
+@code{rassq-delete-all} is like @code{assq-delete-all} except that it
+compares the @sc{cdr} of each @var{alist} association instead of the
+@sc{car}.
+@end defun
+
+@node Rings
+@section Managing a Fixed-Size Ring of Objects
+
+@cindex ring data structure
+  This section describes functions for operating on rings.  A
+@dfn{ring} is a fixed-size data structure that supports insertion,
+deletion, rotation, and modulo-indexed reference and traversal.
+
+@defun make-ring size
+This returns a new ring capable of holding @var{size} objects.
+@var{size} should be an integer.
+@end defun
+
+@defun ring-p object
+This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
+@end defun
+
+@defun ring-size ring
+This returns the maximum capacity of the @var{ring}.
+@end defun
+
+@defun ring-length ring
+This returns the number of objects that @var{ring} currently contains.
+The value will never exceed that returned by @code{ring-size}.
+@end defun
+
+@defun ring-elements ring
+This returns a list of the objects in @var{ring}, in order, newest first.
+@end defun
+
+@defun ring-copy ring
+This returns a new ring which is a copy of @var{ring}.
+The new ring contains the same (@code{eq}) objects as @var{ring}.
+@end defun
+
+@defun ring-empty-p ring
+This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
+@end defun
+
+  The newest element in the ring always has index 0.  Higher indices
+correspond to older elements.  Indices are computed modulo the ring
+length.  Index @minus{}1 corresponds to the oldest element, @minus{}2
+to the next-oldest, and so forth.
+
+@defun ring-ref ring index
+This returns the object in @var{ring} found at index @var{index}.
+@var{index} may be negative or greater than the ring length.  If
+@var{ring} is empty, @code{ring-ref} signals an error.
+@end defun
+
+@defun ring-insert ring object
+This inserts @var{object} into @var{ring}, making it the newest
+element, and returns @var{object}.
+
+If the ring is full, insertion removes the oldest element to
+make room for the new element.
+@end defun
+
+@defun ring-remove ring &optional index
+Remove an object from @var{ring}, and return that object.  The
+argument @var{index} specifies which item to remove; if it is
+@code{nil}, that means to remove the oldest item.  If @var{ring} is
+empty, @code{ring-remove} signals an error.
+@end defun
+
+@defun ring-insert-at-beginning ring object
+This inserts @var{object} into @var{ring}, treating it as the oldest
+element.  The return value is not significant.
+
+If the ring is full, this function removes the newest element to make
+room for the inserted element.
+@end defun
+
+@cindex fifo data structure
+  If you are careful not to exceed the ring size, you can
+use the ring as a first-in-first-out queue.  For example:
+
+@lisp
+(let ((fifo (make-ring 5)))
+  (mapc (lambda (obj) (ring-insert fifo obj))
+        '(0 one "two"))
+  (list (ring-remove fifo) t
+        (ring-remove fifo) t
+        (ring-remove fifo)))
+     @result{} (0 t one t "two")
+@end lisp
+
+@ignore
+   arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
+@end ignore
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
new file mode 100644
index 00000000000..058ed9c8984
--- /dev/null
+++ b/doc/lispref/loading.texi
@@ -0,0 +1,968 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/loading
+@node Loading, Byte Compilation, Customization, Top
+@chapter Loading
+@cindex loading
+@cindex library
+@cindex Lisp library
+
+  Loading a file of Lisp code means bringing its contents into the Lisp
+environment in the form of Lisp objects.  Emacs finds and opens the
+file, reads the text, evaluates each form, and then closes the file.
+
+  The load functions evaluate all the expressions in a file just
+as the @code{eval-buffer} function evaluates all the
+expressions in a buffer.  The difference is that the load functions
+read and evaluate the text in the file as found on disk, not the text
+in an Emacs buffer.
+
+@cindex top-level form
+  The loaded file must contain Lisp expressions, either as source code
+or as byte-compiled code.  Each form in the file is called a
+@dfn{top-level form}.  There is no special format for the forms in a
+loadable file; any form in a file may equally well be typed directly
+into a buffer and evaluated there.  (Indeed, most code is tested this
+way.)  Most often, the forms are function definitions and variable
+definitions.
+
+  A file containing Lisp code is often called a @dfn{library}.  Thus,
+the ``Rmail library'' is a file containing code for Rmail mode.
+Similarly, a ``Lisp library directory'' is a directory of files
+containing Lisp code.
+
+@menu
+* How Programs Do Loading:: The @code{load} function and others.
+* Load Suffixes::           Details about the suffixes that @code{load} tries.
+* Library Search::          Finding a library to load.
+* Loading Non-ASCII::       Non-@acronym{ASCII} characters in Emacs Lisp files.
+* Autoload::                Setting up a function to autoload.
+* Repeated Loading::        Precautions about loading a file twice.
+* Named Features::          Loading a library if it isn't already loaded.
+* Where Defined::           Finding which file defined a certain symbol.
+* Unloading::		    How to "unload" a library that was loaded.
+* Hooks for Loading::	    Providing code to be run when
+			      particular libraries are loaded.
+@end menu
+
+@node How Programs Do Loading
+@section How Programs Do Loading
+
+  Emacs Lisp has several interfaces for loading.  For example,
+@code{autoload} creates a placeholder object for a function defined in a
+file; trying to call the autoloading function loads the file to get the
+function's real definition (@pxref{Autoload}).  @code{require} loads a
+file if it isn't already loaded (@pxref{Named Features}).  Ultimately,
+all these facilities call the @code{load} function to do the work.
+
+@defun load filename &optional missing-ok nomessage nosuffix must-suffix
+This function finds and opens a file of Lisp code, evaluates all the
+forms in it, and closes the file.
+
+To find the file, @code{load} first looks for a file named
+@file{@var{filename}.elc}, that is, for a file whose name is
+@var{filename} with the extension @samp{.elc} appended.  If such a
+file exists, it is loaded.  If there is no file by that name, then
+@code{load} looks for a file named @file{@var{filename}.el}.  If that
+file exists, it is loaded.  Finally, if neither of those names is
+found, @code{load} looks for a file named @var{filename} with nothing
+appended, and loads it if it exists.  (The @code{load} function is not
+clever about looking at @var{filename}.  In the perverse case of a
+file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
+indeed find it.)
+
+If Auto Compression mode is enabled, as it is by default, then if
+@code{load} can not find a file, it searches for a compressed version
+of the file before trying other file names.  It decompresses and loads
+it if it exists.  It looks for compressed versions by appending each
+of the suffixes in @code{jka-compr-load-suffixes} to the file name.
+The value of this variable must be a list of strings. Its standard
+value is @code{(".gz")}.
+
+If the optional argument @var{nosuffix} is non-@code{nil}, then
+@code{load} does not try the suffixes @samp{.elc} and @samp{.el}.  In
+this case, you must specify the precise file name you want, except
+that, if Auto Compression mode is enabled, @code{load} will still use
+@code{jka-compr-load-suffixes} to find compressed versions.  By
+specifying the precise file name and using @code{t} for
+@var{nosuffix}, you can prevent perverse file names such as
+@file{foo.el.el} from being tried.
+
+If the optional argument @var{must-suffix} is non-@code{nil}, then
+@code{load} insists that the file name used must end in either
+@samp{.el} or @samp{.elc} (possibly extended with a compression
+suffix), unless it contains an explicit directory name.
+
+If @var{filename} is a relative file name, such as @file{foo} or
+@file{baz/foo.bar}, @code{load} searches for the file using the variable
+@code{load-path}.  It appends @var{filename} to each of the directories
+listed in @code{load-path}, and loads the first file it finds whose name
+matches.  The current default directory is tried only if it is specified
+in @code{load-path}, where @code{nil} stands for the default directory.
+@code{load} tries all three possible suffixes in the first directory in
+@code{load-path}, then all three suffixes in the second directory, and
+so on.  @xref{Library Search}.
+
+If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
+means you should consider recompiling @file{foo.el}.  @xref{Byte
+Compilation}.
+
+When loading a source file (not compiled), @code{load} performs
+character set translation just as Emacs would do when visiting the file.
+@xref{Coding Systems}.
+
+Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
+in the echo area during loading unless @var{nomessage} is
+non-@code{nil}.
+
+@cindex load errors
+Any unhandled errors while loading a file terminate loading.  If the
+load was done for the sake of @code{autoload}, any function definitions
+made during the loading are undone.
+
+@kindex file-error
+If @code{load} can't find the file to load, then normally it signals the
+error @code{file-error} (with @samp{Cannot open load file
+@var{filename}}).  But if @var{missing-ok} is non-@code{nil}, then
+@code{load} just returns @code{nil}.
+
+You can use the variable @code{load-read-function} to specify a function
+for @code{load} to use instead of @code{read} for reading expressions.
+See below.
+
+@code{load} returns @code{t} if the file loads successfully.
+@end defun
+
+@deffn Command load-file filename
+This command loads the file @var{filename}.  If @var{filename} is a
+relative file name, then the current default directory is assumed.
+This command does not use @code{load-path}, and does not append
+suffixes.  However, it does look for compressed versions (if Auto
+Compression Mode is enabled).  Use this command if you wish to specify
+precisely the file name to load.
+@end deffn
+
+@deffn Command load-library library
+This command loads the library named @var{library}.  It is equivalent to
+@code{load}, except in how it reads its argument interactively.
+@end deffn
+
+@defvar load-in-progress
+This variable is non-@code{nil} if Emacs is in the process of loading a
+file, and it is @code{nil} otherwise.
+@end defvar
+
+@defvar load-read-function
+@anchor{Definition of load-read-function}
+@c do not allow page break at anchor; work around Texinfo deficiency.
+This variable specifies an alternate expression-reading function for
+@code{load} and @code{eval-region} to use instead of @code{read}.
+The function should accept one argument, just as @code{read} does.
+
+Normally, the variable's value is @code{nil}, which means those
+functions should use @code{read}.
+
+Instead of using this variable, it is cleaner to use another, newer
+feature: to pass the function as the @var{read-function} argument to
+@code{eval-region}.  @xref{Definition of eval-region,, Eval}.
+@end defvar
+
+  For information about how @code{load} is used in building Emacs, see
+@ref{Building Emacs}.
+
+@node Load Suffixes
+@section Load Suffixes
+We now describe some technical details about the exact suffixes that
+@code{load} tries.
+
+@defvar load-suffixes
+This is a list of suffixes indicating (compiled or source) Emacs Lisp
+files.  It should not include the empty string.  @code{load} uses
+these suffixes in order when it appends Lisp suffixes to the specified
+file name.  The standard value is @code{(".elc" ".el")} which produces
+the behavior described in the previous section.
+@end defvar
+
+@defvar load-file-rep-suffixes
+This is a list of suffixes that indicate representations of the same
+file.  This list should normally start with the empty string.
+When @code{load} searches for a file it appends the suffixes in this
+list, in order, to the file name, before searching for another file.
+
+Enabling Auto Compression mode appends the suffixes in
+@code{jka-compr-load-suffixes} to this list and disabling Auto
+Compression mode removes them again.  The standard value of
+@code{load-file-rep-suffixes} if Auto Compression mode is disabled is
+@code{("")}.  Given that the standard value of
+@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
+of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
+is @code{("" ".gz")}.
+@end defvar
+
+@defun get-load-suffixes
+This function returns the list of all suffixes that @code{load} should
+try, in order, when its @var{must-suffix} argument is non-@code{nil}.
+This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
+into account.  If @code{load-suffixes}, @code{jka-compr-load-suffixes}
+and @code{load-file-rep-suffixes} all have their standard values, this
+function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
+Compression mode is enabled and @code{(".elc" ".el")} if Auto
+Compression mode is disabled.
+@end defun
+
+To summarize, @code{load} normally first tries the suffixes in the
+value of @code{(get-load-suffixes)} and then those in
+@code{load-file-rep-suffixes}.  If @var{nosuffix} is non-@code{nil},
+it skips the former group, and if @var{must-suffix} is non-@code{nil},
+it skips the latter group.
+
+@node Library Search
+@section Library Search
+@cindex library search
+@cindex find library
+
+  When Emacs loads a Lisp library, it searches for the library
+in a list of directories specified by the variable @code{load-path}.
+
+@defopt load-path
+@cindex @code{EMACSLOADPATH} environment variable
+The value of this variable is a list of directories to search when
+loading files with @code{load}.  Each element is a string (which must be
+a directory name) or @code{nil} (which stands for the current working
+directory).
+@end defopt
+
+  The value of @code{load-path} is initialized from the environment
+variable @code{EMACSLOADPATH}, if that exists; otherwise its default
+value is specified in @file{emacs/src/epaths.h} when Emacs is built.
+Then the list is expanded by adding subdirectories of the directories
+in the list.
+
+  The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
+@samp{:} (or @samp{;}, according to the operating system) separates
+directory names, and @samp{.} is used for the current default directory.
+Here is an example of how to set your @code{EMACSLOADPATH} variable from
+a @code{csh} @file{.login} file:
+
+@smallexample
+setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
+@end smallexample
+
+  Here is how to set it using @code{sh}:
+
+@smallexample
+export EMACSLOADPATH
+EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
+@end smallexample
+
+  Here is an example of code you can place in your init file (@pxref{Init
+File}) to add several directories to the front of your default
+@code{load-path}:
+
+@smallexample
+@group
+(setq load-path
+      (append (list nil "/user/bil/emacs"
+                    "/usr/local/lisplib"
+                    "~/emacs")
+              load-path))
+@end group
+@end smallexample
+
+@c Wordy to rid us of an overfull hbox.  --rjc 15mar92
+@noindent
+In this example, the path searches the current working directory first,
+followed then by the @file{/user/bil/emacs} directory, the
+@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
+which are then followed by the standard directories for Lisp code.
+
+  Dumping Emacs uses a special value of @code{load-path}.  If the value of
+@code{load-path} at the end of dumping is unchanged (that is, still the
+same special value), the dumped Emacs switches to the ordinary
+@code{load-path} value when it starts up, as described above.  But if
+@code{load-path} has any other value at the end of dumping, that value
+is used for execution of the dumped Emacs also.
+
+  Therefore, if you want to change @code{load-path} temporarily for
+loading a few libraries in @file{site-init.el} or @file{site-load.el},
+you should bind @code{load-path} locally with @code{let} around the
+calls to @code{load}.
+
+  The default value of @code{load-path}, when running an Emacs which has
+been installed on the system, includes two special directories (and
+their subdirectories as well):
+
+@smallexample
+"/usr/local/share/emacs/@var{version}/site-lisp"
+@end smallexample
+
+@noindent
+and
+
+@smallexample
+"/usr/local/share/emacs/site-lisp"
+@end smallexample
+
+@noindent
+The first one is for locally installed packages for a particular Emacs
+version; the second is for locally installed packages meant for use with
+all installed Emacs versions.
+
+  There are several reasons why a Lisp package that works well in one
+Emacs version can cause trouble in another.  Sometimes packages need
+updating for incompatible changes in Emacs; sometimes they depend on
+undocumented internal Emacs data that can change without notice;
+sometimes a newer Emacs version incorporates a version of the package,
+and should be used only with that version.
+
+  Emacs finds these directories' subdirectories and adds them to
+@code{load-path} when it starts up.  Both immediate subdirectories and
+subdirectories multiple levels down are added to @code{load-path}.
+
+  Not all subdirectories are included, though.  Subdirectories whose
+names do not start with a letter or digit are excluded.  Subdirectories
+named @file{RCS} or @file{CVS} are excluded.  Also, a subdirectory which
+contains a file named @file{.nosearch} is excluded.  You can use these
+methods to prevent certain subdirectories of the @file{site-lisp}
+directories from being searched.
+
+  If you run Emacs from the directory where it was built---that is, an
+executable that has not been formally installed---then @code{load-path}
+normally contains two additional directories.  These are the @code{lisp}
+and @code{site-lisp} subdirectories of the main build directory.  (Both
+are represented as absolute file names.)
+
+@deffn Command locate-library library &optional nosuffix path interactive-call
+This command finds the precise file name for library @var{library}.  It
+searches for the library in the same way @code{load} does, and the
+argument @var{nosuffix} has the same meaning as in @code{load}: don't
+add suffixes @samp{.elc} or @samp{.el} to the specified name
+@var{library}.
+
+If the @var{path} is non-@code{nil}, that list of directories is used
+instead of @code{load-path}.
+
+When @code{locate-library} is called from a program, it returns the file
+name as a string.  When the user runs @code{locate-library}
+interactively, the argument @var{interactive-call} is @code{t}, and this
+tells @code{locate-library} to display the file name in the echo area.
+@end deffn
+
+@node Loading Non-ASCII
+@section Loading Non-@acronym{ASCII} Characters
+
+  When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
+characters, these can be represented within Emacs either as unibyte
+strings or as multibyte strings (@pxref{Text Representations}).  Which
+representation is used depends on how the file is read into Emacs.  If
+it is read with decoding into multibyte representation, the text of the
+Lisp program will be multibyte text, and its string constants will be
+multibyte strings.  If a file containing Latin-1 characters (for
+example) is read without decoding, the text of the program will be
+unibyte text, and its string constants will be unibyte strings.
+@xref{Coding Systems}.
+
+  To make the results more predictable, Emacs always performs decoding
+into the multibyte representation when loading Lisp files, even if it
+was started with the @samp{--unibyte} option.  This means that string
+constants with non-@acronym{ASCII} characters translate into multibyte
+strings.  The only exception is when a particular file specifies no
+decoding.
+
+  The reason Emacs is designed this way is so that Lisp programs give
+predictable results, regardless of how Emacs was started.  In addition,
+this enables programs that depend on using multibyte text to work even
+in a unibyte Emacs.  Of course, such programs should be designed to
+notice whether the user prefers unibyte or multibyte text, by checking
+@code{default-enable-multibyte-characters}, and convert representations
+appropriately.
+
+  In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
+multibyte strings should not be noticeable, since inserting them in
+unibyte buffers converts them to unibyte automatically.  However, if
+this does make a difference, you can force a particular Lisp file to be
+interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
+comment on the file's first line.  With that designator, the file will
+unconditionally be interpreted as unibyte, even in an ordinary
+multibyte Emacs session.  This can matter when making keybindings to
+non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
+
+@node Autoload
+@section Autoload
+@cindex autoload
+
+  The @dfn{autoload} facility allows you to make a function or macro
+known in Lisp, but put off loading the file that defines it.  The first
+call to the function automatically reads the proper file to install the
+real definition and other associated code, then runs the real definition
+as if it had been loaded all along.
+
+  There are two ways to set up an autoloaded function: by calling
+@code{autoload}, and by writing a special ``magic'' comment in the
+source before the real definition.  @code{autoload} is the low-level
+primitive for autoloading; any Lisp program can call @code{autoload} at
+any time.  Magic comments are the most convenient way to make a function
+autoload, for packages installed along with Emacs.  These comments do
+nothing on their own, but they serve as a guide for the command
+@code{update-file-autoloads}, which constructs calls to @code{autoload}
+and arranges to execute them when Emacs is built.
+
+@defun autoload function filename &optional docstring interactive type
+This function defines the function (or macro) named @var{function} so as
+to load automatically from @var{filename}.  The string @var{filename}
+specifies the file to load to get the real definition of @var{function}.
+
+If @var{filename} does not contain either a directory name, or the
+suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
+one of these suffixes, and it will not load from a file whose name is
+just @var{filename} with no added suffix.  (The variable
+@code{load-suffixes} specifies the exact required suffixes.)
+
+The argument @var{docstring} is the documentation string for the
+function.  Specifying the documentation string in the call to
+@code{autoload} makes it possible to look at the documentation without
+loading the function's real definition.  Normally, this should be
+identical to the documentation string in the function definition
+itself.  If it isn't, the function definition's documentation string
+takes effect when it is loaded.
+
+If @var{interactive} is non-@code{nil}, that says @var{function} can be
+called interactively.  This lets completion in @kbd{M-x} work without
+loading @var{function}'s real definition.  The complete interactive
+specification is not given here; it's not needed unless the user
+actually calls @var{function}, and when that happens, it's time to load
+the real definition.
+
+You can autoload macros and keymaps as well as ordinary functions.
+Specify @var{type} as @code{macro} if @var{function} is really a macro.
+Specify @var{type} as @code{keymap} if @var{function} is really a
+keymap.  Various parts of Emacs need to know this information without
+loading the real definition.
+
+An autoloaded keymap loads automatically during key lookup when a prefix
+key's binding is the symbol @var{function}.  Autoloading does not occur
+for other kinds of access to the keymap.  In particular, it does not
+happen when a Lisp program gets the keymap from the value of a variable
+and calls @code{define-key}; not even if the variable name is the same
+symbol @var{function}.
+
+@cindex function cell in autoload
+If @var{function} already has a non-void function definition that is not
+an autoload object, @code{autoload} does nothing and returns @code{nil}.
+If the function cell of @var{function} is void, or is already an autoload
+object, then it is defined as an autoload object like this:
+
+@example
+(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
+@end example
+
+For example,
+
+@example
+@group
+(symbol-function 'run-prolog)
+     @result{} (autoload "prolog" 169681 t nil)
+@end group
+@end example
+
+@noindent
+In this case, @code{"prolog"} is the name of the file to load, 169681
+refers to the documentation string in the
+@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
+@code{t} means the function is interactive, and @code{nil} that it is
+not a macro or a keymap.
+@end defun
+
+@cindex autoload errors
+  The autoloaded file usually contains other definitions and may require
+or provide one or more features.  If the file is not completely loaded
+(due to an error in the evaluation of its contents), any function
+definitions or @code{provide} calls that occurred during the load are
+undone.  This is to ensure that the next attempt to call any function
+autoloading from this file will try again to load the file.  If not for
+this, then some of the functions in the file might be defined by the
+aborted load, but fail to work properly for the lack of certain
+subroutines not loaded successfully because they come later in the file.
+
+  If the autoloaded file fails to define the desired Lisp function or
+macro, then an error is signaled with data @code{"Autoloading failed to
+define function @var{function-name}"}.
+
+@findex update-file-autoloads
+@findex update-directory-autoloads
+@cindex magic autoload comment
+@cindex autoload cookie
+@anchor{autoload cookie}
+  A magic autoload comment (often called an @dfn{autoload cookie})
+consists of @samp{;;;###autoload}, on a line by itself,
+just before the real definition of the function in its
+autoloadable source file.  The command @kbd{M-x update-file-autoloads}
+writes a corresponding @code{autoload} call into @file{loaddefs.el}.
+Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
+@kbd{M-x update-directory-autoloads} is even more powerful; it updates
+autoloads for all files in the current directory.
+
+  The same magic comment can copy any kind of form into
+@file{loaddefs.el}.  If the form following the magic comment is not a
+function-defining form or a @code{defcustom} form, it is copied
+verbatim.  ``Function-defining forms'' include @code{define-skeleton},
+@code{define-derived-mode}, @code{define-generic-mode} and
+@code{define-minor-mode} as well as @code{defun} and
+@code{defmacro}.  To save space, a @code{defcustom} form is converted to
+a @code{defvar} in @file{loaddefs.el}, with some additional information
+if it uses @code{:require}.
+
+  You can also use a magic comment to execute a form at build time
+@emph{without} executing it when the file itself is loaded.  To do this,
+write the form @emph{on the same line} as the magic comment.  Since it
+is in a comment, it does nothing when you load the source file; but
+@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
+it is executed while building Emacs.
+
+  The following example shows how @code{doctor} is prepared for
+autoloading with a magic comment:
+
+@smallexample
+;;;###autoload
+(defun doctor ()
+  "Switch to *doctor* buffer and start giving psychotherapy."
+  (interactive)
+  (switch-to-buffer "*doctor*")
+  (doctor-mode))
+@end smallexample
+
+@noindent
+Here's what that produces in @file{loaddefs.el}:
+
+@smallexample
+(autoload (quote doctor) "doctor" "\
+Switch to *doctor* buffer and start giving psychotherapy.
+
+\(fn)" t nil)
+@end smallexample
+
+@noindent
+@cindex @code{fn} in function's documentation string
+The backslash and newline immediately following the double-quote are a
+convention used only in the preloaded uncompiled Lisp files such as
+@file{loaddefs.el}; they tell @code{make-docfile} to put the
+documentation string in the @file{etc/DOC} file.  @xref{Building Emacs}.
+See also the commentary in @file{lib-src/make-docfile.c}.  @samp{(fn)}
+in the usage part of the documentation string is replaced with the
+function's name when the various help functions (@pxref{Help
+Functions}) display it.
+
+  If you write a function definition with an unusual macro that is not
+one of the known and recognized function definition methods, use of an
+ordinary magic autoload comment would copy the whole definition into
+@code{loaddefs.el}.  That is not desirable.  You can put the desired
+@code{autoload} call into @code{loaddefs.el} instead by writing this:
+
+@smallexample
+;;;###autoload (autoload 'foo "myfile")
+(mydefunmacro foo
+  ...)
+@end smallexample
+
+@node Repeated Loading
+@section Repeated Loading
+@cindex repeated loading
+
+  You can load a given file more than once in an Emacs session.  For
+example, after you have rewritten and reinstalled a function definition
+by editing it in a buffer, you may wish to return to the original
+version; you can do this by reloading the file it came from.
+
+  When you load or reload files, bear in mind that the @code{load} and
+@code{load-library} functions automatically load a byte-compiled file
+rather than a non-compiled file of similar name.  If you rewrite a file
+that you intend to save and reinstall, you need to byte-compile the new
+version; otherwise Emacs will load the older, byte-compiled file instead
+of your newer, non-compiled file!  If that happens, the message
+displayed when loading the file includes, @samp{(compiled; note, source is
+newer)}, to remind you to recompile it.
+
+  When writing the forms in a Lisp library file, keep in mind that the
+file might be loaded more than once.  For example, think about whether
+each variable should be reinitialized when you reload the library;
+@code{defvar} does not change the value if the variable is already
+initialized.  (@xref{Defining Variables}.)
+
+  The simplest way to add an element to an alist is like this:
+
+@example
+(push '(leif-mode " Leif") minor-mode-alist)
+@end example
+
+@noindent
+But this would add multiple elements if the library is reloaded.
+To avoid the problem, write this:
+
+@example
+(or (assq 'leif-mode minor-mode-alist)
+    (push '(leif-mode " Leif") minor-mode-alist))
+@end example
+
+@noindent
+or this:
+
+@example
+(add-to-list '(leif-mode " Leif") minor-mode-alist)
+@end example
+
+  Occasionally you will want to test explicitly whether a library has
+already been loaded.  Here's one way to test, in a library, whether it
+has been loaded before:
+
+@example
+(defvar foo-was-loaded nil)
+
+(unless foo-was-loaded
+  @var{execute-first-time-only}
+  (setq foo-was-loaded t))
+@end example
+
+@noindent
+If the library uses @code{provide} to provide a named feature, you can
+use @code{featurep} earlier in the file to test whether the
+@code{provide} call has been executed before.
+@ifnottex
+@xref{Named Features}.
+@end ifnottex
+
+@node Named Features
+@section Features
+@cindex features
+@cindex requiring features
+@cindex providing features
+
+  @code{provide} and @code{require} are an alternative to
+@code{autoload} for loading files automatically.  They work in terms of
+named @dfn{features}.  Autoloading is triggered by calling a specific
+function, but a feature is loaded the first time another program asks
+for it by name.
+
+  A feature name is a symbol that stands for a collection of functions,
+variables, etc.  The file that defines them should @dfn{provide} the
+feature.  Another program that uses them may ensure they are defined by
+@dfn{requiring} the feature.  This loads the file of definitions if it
+hasn't been loaded already.
+
+  To require the presence of a feature, call @code{require} with the
+feature name as argument.  @code{require} looks in the global variable
+@code{features} to see whether the desired feature has been provided
+already.  If not, it loads the feature from the appropriate file.  This
+file should call @code{provide} at the top level to add the feature to
+@code{features}; if it fails to do so, @code{require} signals an error.
+@cindex load error with require
+
+  For example, in @file{emacs/lisp/prolog.el},
+the definition for @code{run-prolog} includes the following code:
+
+@smallexample
+(defun run-prolog ()
+  "Run an inferior Prolog process, with I/O via buffer *prolog*."
+  (interactive)
+  (require 'comint)
+  (switch-to-buffer (make-comint "prolog" prolog-program-name))
+  (inferior-prolog-mode))
+@end smallexample
+
+@noindent
+The expression @code{(require 'comint)} loads the file @file{comint.el}
+if it has not yet been loaded.  This ensures that @code{make-comint} is
+defined.  Features are normally named after the files that provide them,
+so that @code{require} need not be given the file name.
+
+The @file{comint.el} file contains the following top-level expression:
+
+@smallexample
+(provide 'comint)
+@end smallexample
+
+@noindent
+This adds @code{comint} to the global @code{features} list, so that
+@code{(require 'comint)} will henceforth know that nothing needs to be
+done.
+
+@cindex byte-compiling @code{require}
+  When @code{require} is used at top level in a file, it takes effect
+when you byte-compile that file (@pxref{Byte Compilation}) as well as
+when you load it.  This is in case the required package contains macros
+that the byte compiler must know about.  It also avoids byte-compiler
+warnings for functions and variables defined in the file loaded with
+@code{require}.
+
+  Although top-level calls to @code{require} are evaluated during
+byte compilation, @code{provide} calls are not.  Therefore, you can
+ensure that a file of definitions is loaded before it is byte-compiled
+by including a @code{provide} followed by a @code{require} for the same
+feature, as in the following example.
+
+@smallexample
+@group
+(provide 'my-feature)  ; @r{Ignored by byte compiler,}
+                       ;   @r{evaluated by @code{load}.}
+(require 'my-feature)  ; @r{Evaluated by byte compiler.}
+@end group
+@end smallexample
+
+@noindent
+The compiler ignores the @code{provide}, then processes the
+@code{require} by loading the file in question.  Loading the file does
+execute the @code{provide} call, so the subsequent @code{require} call
+does nothing when the file is loaded.
+
+@defun provide feature &optional subfeatures
+This function announces that @var{feature} is now loaded, or being
+loaded, into the current Emacs session.  This means that the facilities
+associated with @var{feature} are or will be available for other Lisp
+programs.
+
+The direct effect of calling @code{provide} is to add @var{feature} to
+the front of the list @code{features} if it is not already in the list.
+The argument @var{feature} must be a symbol.  @code{provide} returns
+@var{feature}.
+
+If provided, @var{subfeatures} should be a list of symbols indicating
+a set of specific subfeatures provided by this version of
+@var{feature}.  You can test the presence of a subfeature using
+@code{featurep}.  The idea of subfeatures is that you use them when a
+package (which is one @var{feature}) is complex enough to make it
+useful to give names to various parts or functionalities of the
+package, which might or might not be loaded, or might or might not be
+present in a given version.  @xref{Network Feature Testing}, for
+an example.
+
+@smallexample
+features
+     @result{} (bar bish)
+
+(provide 'foo)
+     @result{} foo
+features
+     @result{} (foo bar bish)
+@end smallexample
+
+When a file is loaded to satisfy an autoload, and it stops due to an
+error in the evaluation of its contents, any function definitions or
+@code{provide} calls that occurred during the load are undone.
+@xref{Autoload}.
+@end defun
+
+@defun require feature &optional filename noerror
+This function checks whether @var{feature} is present in the current
+Emacs session (using @code{(featurep @var{feature})}; see below).  The
+argument @var{feature} must be a symbol.
+
+If the feature is not present, then @code{require} loads @var{filename}
+with @code{load}.  If @var{filename} is not supplied, then the name of
+the symbol @var{feature} is used as the base file name to load.
+However, in this case, @code{require} insists on finding @var{feature}
+with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
+a compression suffix); a file whose name is just @var{feature} won't
+be used.  (The variable @code{load-suffixes} specifies the exact
+required Lisp suffixes.)
+
+If @var{noerror} is non-@code{nil}, that suppresses errors from actual
+loading of the file.  In that case, @code{require} returns @code{nil}
+if loading the file fails.  Normally, @code{require} returns
+@var{feature}.
+
+If loading the file succeeds but does not provide @var{feature},
+@code{require} signals an error, @samp{Required feature @var{feature}
+was not provided}.
+@end defun
+
+@defun featurep feature &optional subfeature
+This function returns @code{t} if @var{feature} has been provided in
+the current Emacs session (i.e.@:, if @var{feature} is a member of
+@code{features}.)  If @var{subfeature} is non-@code{nil}, then the
+function returns @code{t} only if that subfeature is provided as well
+(i.e.@: if @var{subfeature} is a member of the @code{subfeature}
+property of the @var{feature} symbol.)
+@end defun
+
+@defvar features
+The value of this variable is a list of symbols that are the features
+loaded in the current Emacs session.  Each symbol was put in this list
+with a call to @code{provide}.  The order of the elements in the
+@code{features} list is not significant.
+@end defvar
+
+@node Where Defined
+@section Which File Defined a Certain Symbol
+
+@defun symbol-file symbol &optional type
+This function returns the name of the file that defined @var{symbol}.
+If @var{type} is @code{nil}, then any kind of definition is
+acceptable.  If @var{type} is @code{defun} or @code{defvar}, that
+specifies function definition only or variable definition only.
+
+The value is normally an absolute file name.  It can also be
+@code{nil}, if the definition is not associated with any file.
+@end defun
+
+  The basis for @code{symbol-file} is the data in the variable
+@code{load-history}.
+
+@defvar load-history
+This variable's value is an alist connecting library file names with the
+names of functions and variables they define, the features they provide,
+and the features they require.
+
+Each element is a list and describes one library.  The @sc{car} of the
+list is the absolute file name of the library, as a string.  The rest
+of the list elements have these forms:
+
+@table @code
+@item @var{var}
+The symbol @var{var} was defined as a variable.
+@item (defun . @var{fun})
+The function @var{fun} was defined.
+@item (t . @var{fun})
+The function @var{fun} was previously an autoload before this library
+redefined it as a function.  The following element is always
+@code{(defun . @var{fun})}, which represents defining @var{fun} as a
+function.
+@item (autoload . @var{fun})
+The function @var{fun} was defined as an autoload.
+@item (require . @var{feature})
+The feature @var{feature} was required.
+@item (provide . @var{feature})
+The feature @var{feature} was provided.
+@end table
+
+The value of @code{load-history} may have one element whose @sc{car} is
+@code{nil}.  This element describes definitions made with
+@code{eval-buffer} on a buffer that is not visiting a file.
+@end defvar
+
+  The command @code{eval-region} updates @code{load-history}, but does so
+by adding the symbols defined to the element for the file being visited,
+rather than replacing that element.  @xref{Eval}.
+
+@node Unloading
+@section Unloading
+@cindex unloading packages
+
+@c Emacs 19 feature
+  You can discard the functions and variables loaded by a library to
+reclaim memory for other Lisp objects.  To do this, use the function
+@code{unload-feature}:
+
+@deffn Command unload-feature feature &optional force
+This command unloads the library that provided feature @var{feature}.
+It undefines all functions, macros, and variables defined in that
+library with @code{defun}, @code{defalias}, @code{defsubst},
+@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
+It then restores any autoloads formerly associated with those symbols.
+(Loading saves these in the @code{autoload} property of the symbol.)
+
+@vindex unload-feature-special-hooks
+Before restoring the previous definitions, @code{unload-feature} runs
+@code{remove-hook} to remove functions in the library from certain
+hooks.  These hooks include variables whose names end in @samp{hook}
+or @samp{-hooks}, plus those listed in
+@code{unload-feature-special-hooks}.  This is to prevent Emacs from
+ceasing to function because important hooks refer to functions that
+are no longer defined.
+
+@vindex @var{feature}-unload-hook
+If these measures are not sufficient to prevent malfunction, a library
+can define an explicit unload hook.  If @code{@var{feature}-unload-hook}
+is defined, it is run as a normal hook before restoring the previous
+definitions, @emph{instead of} the usual hook-removing actions.  The
+unload hook ought to undo all the global state changes made by the
+library that might cease to work once the library is unloaded.
+@code{unload-feature} can cause problems with libraries that fail to do
+this, so it should be used with caution.
+
+Ordinarily, @code{unload-feature} refuses to unload a library on which
+other loaded libraries depend.  (A library @var{a} depends on library
+@var{b} if @var{a} contains a @code{require} for @var{b}.)  If the
+optional argument @var{force} is non-@code{nil}, dependencies are
+ignored and you can unload any library.
+@end deffn
+
+  The @code{unload-feature} function is written in Lisp; its actions are
+based on the variable @code{load-history}.
+
+@defvar unload-feature-special-hooks
+This variable holds a list of hooks to be scanned before unloading a
+library, to remove functions defined in the library.
+@end defvar
+
+@node Hooks for Loading
+@section Hooks for Loading
+@cindex loading hooks
+@cindex hooks for loading
+
+You can ask for code to be executed if and when a particular library is
+loaded, by calling @code{eval-after-load}.
+
+@defun eval-after-load library form
+This function arranges to evaluate @var{form} at the end of loading
+the file @var{library}, each time @var{library} is loaded.  If
+@var{library} is already loaded, it evaluates @var{form} right away.
+Don't forget to quote @var{form}!
+
+You don't need to give a directory or extension in the file name
+@var{library}---normally you just give a bare file name, like this:
+
+@example
+(eval-after-load "edebug" '(def-edebug-spec c-point t))
+@end example
+
+To restrict which files can trigger the evaluation, include a
+directory or an extension or both in @var{library}.  Only a file whose
+absolute true name (i.e., the name with all symbolic links chased out)
+matches all the given name components will match.  In the following
+example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
+@code{..../foo/bar} will trigger the evaluation, but not
+@file{my_inst.el}:
+
+@example
+(eval-after-load "foo/bar/my_inst.elc" @dots{})
+@end example
+
+@var{library} can also be a feature (i.e.@: a symbol), in which case
+@var{form} is evaluated when @code{(provide @var{library})} is called.
+
+An error in @var{form} does not undo the load, but does prevent
+execution of the rest of @var{form}.
+@end defun
+
+In general, well-designed Lisp programs should not use this feature.
+The clean and modular ways to interact with a Lisp library are (1)
+examine and set the library's variables (those which are meant for
+outside use), and (2) call the library's functions.  If you wish to
+do (1), you can do it immediately---there is no need to wait for when
+the library is loaded.  To do (2), you must load the library (preferably
+with @code{require}).
+
+But it is OK to use @code{eval-after-load} in your personal
+customizations if you don't feel they must meet the design standards for
+programs meant for wider use.
+
+@defvar after-load-alist
+This variable, an alist built by @code{eval-after-load}, holds the
+expressions to evaluate when particular libraries are loaded.  Each
+element looks like this:
+
+@example
+(@var{regexp-or-feature} @var{forms}@dots{})
+@end example
+
+The key @var{regexp-or-feature} is either a regular expression or a
+symbol, and the value is a list of forms.  The forms are evaluated when
+the key matches the absolute true name of the file being
+@code{load}ed or the symbol being @code{provide}d.
+@end defvar
+
+@ignore
+   arch-tag: df731f89-0900-4389-a436-9105241b6f7a
+@end ignore
diff --git a/doc/lispref/locals.texi b/doc/lispref/locals.texi
new file mode 100644
index 00000000000..4edbc2a815f
--- /dev/null
+++ b/doc/lispref/locals.texi
@@ -0,0 +1,232 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/locals
+@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top
+@appendix Buffer-Local Variables
+@c The title "Standard Buffer-Local Variables" is too long for
+@c smallbook. --rjc 30mar92
+@cindex buffer-local variables, general-purpose
+@cindex standard buffer-local variables
+
+  The table below lists the general-purpose Emacs variables that
+automatically become buffer-local in each buffer.  Most become
+buffer-local only when set; a few of them are always local in every
+buffer.  Many Lisp packages define such variables for their internal
+use, but we don't try to list them all here.
+
+  Every buffer-specific minor mode defines a buffer-local variable
+named @samp{@var{modename}-mode}.  @xref{Minor Mode Conventions}.
+Minor mode variables will not be listed here.
+
+@table @code
+@item auto-fill-function
+@xref{Auto Filling}.
+
+@item buffer-auto-save-file-format
+@xref{Format Conversion}.
+
+@item buffer-auto-save-file-name
+@xref{Auto-Saving}.
+
+@item buffer-backed-up
+@xref{Making Backups}.
+
+@item buffer-display-count
+@xref{Buffers and Windows}.
+
+@item buffer-display-table
+@xref{Active Display Table}.
+
+@item buffer-display-time
+@xref{Buffers and Windows}.
+
+@item buffer-file-coding-system
+@xref{Encoding and I/O}.
+
+@item buffer-file-format
+@xref{Format Conversion}.
+
+@item buffer-file-name
+@xref{Buffer File Name}.
+
+@item buffer-file-number
+@xref{Buffer File Name}.
+
+@item buffer-file-truename
+@xref{Buffer File Name}.
+
+@item buffer-file-type
+@xref{MS-DOS File Types}.
+
+@item buffer-invisibility-spec
+@xref{Invisible Text}.
+
+@item buffer-offer-save
+@xref{Killing Buffers}.
+
+@item buffer-save-without-query
+@xref{Killing Buffers}.
+
+@item buffer-read-only
+@xref{Read Only Buffers}.
+
+@item buffer-saved-size
+@xref{Auto-Saving}.
+
+@item buffer-undo-list
+@xref{Undo}.
+
+@item cache-long-line-scans
+@xref{Truncation}.
+
+@item case-fold-search
+@xref{Searching and Case}.
+
+@item ctl-arrow
+@xref{Usual Display}.
+
+@item cursor-type
+@xref{Cursor Parameters}.
+
+@item cursor-in-non-selected-windows
+@xref{Basic Windows}.
+
+@item comment-column
+@xref{Comments,,, emacs, The GNU Emacs Manual}.
+
+@item default-directory
+@xref{File Name Expansion}.
+
+@item defun-prompt-regexp
+@xref{List Motion}.
+
+@item desktop-save-buffer
+@xref{Desktop Save Mode}.
+
+@ignore
+@item direction-reversed
+Does not work yet.
+@end ignore
+
+@item enable-multibyte-characters
+@ref{Text Representations}.
+
+@item fill-column
+@xref{Margins}.
+
+@item fill-prefix
+@xref{Margins}.
+
+@item font-lock-defaults
+@xref{Font Lock Basics}.
+
+@item fringe-cursor-alist
+@xref{Fringe Cursors}.
+
+@item fringe-indicator-alist
+@xref{Fringe Indicators}.
+
+@item fringes-outside-margins
+@xref{Fringes}.
+
+@item goal-column
+@xref{Moving Point,,, emacs, The GNU Emacs Manual}.
+
+@item header-line-format
+@xref{Header Lines}.
+
+@item indicate-buffer-boundaries
+@xref{Usual Display}.
+
+@item indicate-empty-lines
+@xref{Usual Display}.
+
+@item left-fringe-width
+@xref{Fringe Size/Pos}.
+
+@item left-margin
+@xref{Margins}.
+
+@item left-margin-width
+@xref{Display Margins}.
+
+@item line-spacing
+@xref{Line Height}.
+
+@item local-abbrev-table
+@xref{Standard Abbrev Tables}.
+
+@item major-mode
+@xref{Mode Help}.
+
+@item mark-active
+@xref{The Mark}.
+
+@item mark-ring
+@xref{The Mark}.
+
+@item mode-line-buffer-identification
+@xref{Mode Line Variables}.
+
+@item mode-line-format
+@xref{Mode Line Data}.
+
+@item mode-line-modified
+@xref{Mode Line Variables}.
+
+@item mode-line-process
+@xref{Mode Line Variables}.
+
+@item mode-name
+@xref{Mode Line Variables}.
+
+@item point-before-scroll
+Used for communication between mouse commands and scroll-bar commands.
+
+@item right-fringe-width
+@xref{Fringe Size/Pos}.
+
+@item right-margin-width
+@xref{Display Margins}.
+
+@item save-buffer-coding-system
+@xref{Encoding and I/O}.
+
+@item scroll-bar-width
+@xref{Scroll Bars}.
+
+@item scroll-down-aggressively
+@xref{Textual Scrolling}.
+
+@item scroll-up-aggressively
+@xref{Textual Scrolling}.
+
+@item selective-display
+@xref{Selective Display}.
+
+@item selective-display-ellipses
+@xref{Selective Display}.
+
+@item tab-width
+@xref{Usual Display}.
+
+@item truncate-lines
+@xref{Truncation}.
+
+@item vertical-scroll-bar
+@xref{Scroll Bars}.
+
+@item window-size-fixed
+@xref{Resizing Windows}.
+
+@item write-contents-functions
+@xref{Saving Buffers}.
+@end table
+
+
+@ignore
+   arch-tag: 6baae835-b667-4447-91e2-9829ae1cf543
+@end ignore
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
new file mode 100644
index 00000000000..b62c8b99d74
--- /dev/null
+++ b/doc/lispref/macros.texi
@@ -0,0 +1,752 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/macros
+@node Macros, Customization, Functions, Top
+@chapter Macros
+@cindex macros
+
+  @dfn{Macros} enable you to define new control constructs and other
+language features.  A macro is defined much like a function, but instead
+of telling how to compute a value, it tells how to compute another Lisp
+expression which will in turn compute the value.  We call this
+expression the @dfn{expansion} of the macro.
+
+  Macros can do this because they operate on the unevaluated expressions
+for the arguments, not on the argument values as functions do.  They can
+therefore construct an expansion containing these argument expressions
+or parts of them.
+
+  If you are using a macro to do something an ordinary function could
+do, just for the sake of speed, consider using an inline function
+instead.  @xref{Inline Functions}.
+
+@menu
+* Simple Macro::            A basic example.
+* Expansion::               How, when and why macros are expanded.
+* Compiling Macros::        How macros are expanded by the compiler.
+* Defining Macros::         How to write a macro definition.
+* Backquote::               Easier construction of list structure.
+* Problems with Macros::    Don't evaluate the macro arguments too many times.
+                              Don't hide the user's variables.
+* Indenting Macros::        Specifying how to indent macro calls.
+@end menu
+
+@node Simple Macro
+@section A Simple Example of a Macro
+
+  Suppose we would like to define a Lisp construct to increment a
+variable value, much like the @code{++} operator in C.  We would like to
+write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
+Here's a macro definition that does the job:
+
+@findex inc
+@example
+@group
+(defmacro inc (var)
+   (list 'setq var (list '1+ var)))
+@end group
+@end example
+
+  When this is called with @code{(inc x)}, the argument @var{var} is the
+symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would
+be in a function.  The body of the macro uses this to construct the
+expansion, which is @code{(setq x (1+ x))}.  Once the macro definition
+returns this expansion, Lisp proceeds to evaluate it, thus incrementing
+@code{x}.
+
+@node Expansion
+@section Expansion of a Macro Call
+@cindex expansion of macros
+@cindex macro call
+
+  A macro call looks just like a function call in that it is a list which
+starts with the name of the macro.  The rest of the elements of the list
+are the arguments of the macro.
+
+  Evaluation of the macro call begins like evaluation of a function call
+except for one crucial difference: the macro arguments are the actual
+expressions appearing in the macro call.  They are not evaluated before
+they are given to the macro definition.  By contrast, the arguments of a
+function are results of evaluating the elements of the function call
+list.
+
+  Having obtained the arguments, Lisp invokes the macro definition just
+as a function is invoked.  The argument variables of the macro are bound
+to the argument values from the macro call, or to a list of them in the
+case of a @code{&rest} argument.  And the macro body executes and
+returns its value just as a function body does.
+
+  The second crucial difference between macros and functions is that the
+value returned by the macro body is not the value of the macro call.
+Instead, it is an alternate expression for computing that value, also
+known as the @dfn{expansion} of the macro.  The Lisp interpreter
+proceeds to evaluate the expansion as soon as it comes back from the
+macro.
+
+  Since the expansion is evaluated in the normal manner, it may contain
+calls to other macros.  It may even be a call to the same macro, though
+this is unusual.
+
+  You can see the expansion of a given macro call by calling
+@code{macroexpand}.
+
+@defun macroexpand form &optional environment
+@cindex macro expansion
+This function expands @var{form}, if it is a macro call.  If the result
+is another macro call, it is expanded in turn, until something which is
+not a macro call results.  That is the value returned by
+@code{macroexpand}.  If @var{form} is not a macro call to begin with, it
+is returned as given.
+
+Note that @code{macroexpand} does not look at the subexpressions of
+@var{form} (although some macro definitions may do so).  Even if they
+are macro calls themselves, @code{macroexpand} does not expand them.
+
+The function @code{macroexpand} does not expand calls to inline functions.
+Normally there is no need for that, since a call to an inline function is
+no harder to understand than a call to an ordinary function.
+
+If @var{environment} is provided, it specifies an alist of macro
+definitions that shadow the currently defined macros.  Byte compilation
+uses this feature.
+
+@smallexample
+@group
+(defmacro inc (var)
+    (list 'setq var (list '1+ var)))
+     @result{} inc
+@end group
+
+@group
+(macroexpand '(inc r))
+     @result{} (setq r (1+ r))
+@end group
+
+@group
+(defmacro inc2 (var1 var2)
+    (list 'progn (list 'inc var1) (list 'inc var2)))
+     @result{} inc2
+@end group
+
+@group
+(macroexpand '(inc2 r s))
+     @result{} (progn (inc r) (inc s))  ; @r{@code{inc} not expanded here.}
+@end group
+@end smallexample
+@end defun
+
+
+@defun macroexpand-all form &optional environment
+@code{macroexpand-all} expands macros like @code{macroexpand}, but
+will look for and expand all macros in @var{form}, not just at the
+top-level.  If no macros are expanded, the return value is @code{eq}
+to @var{form}.
+
+Repeating the example used for @code{macroexpand} above with
+@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does}
+expand the embedded calls to @code{inc}:
+
+@smallexample
+(macroexpand-all '(inc2 r s))
+     @result{} (progn (setq r (1+ r)) (setq s (1+ s)))
+@end smallexample
+
+@end defun
+
+@node Compiling Macros
+@section Macros and Byte Compilation
+@cindex byte-compiling macros
+
+  You might ask why we take the trouble to compute an expansion for a
+macro and then evaluate the expansion.  Why not have the macro body
+produce the desired results directly?  The reason has to do with
+compilation.
+
+  When a macro call appears in a Lisp program being compiled, the Lisp
+compiler calls the macro definition just as the interpreter would, and
+receives an expansion.  But instead of evaluating this expansion, it
+compiles the expansion as if it had appeared directly in the program.
+As a result, the compiled code produces the value and side effects
+intended for the macro, but executes at full compiled speed.  This would
+not work if the macro body computed the value and side effects
+itself---they would be computed at compile time, which is not useful.
+
+  In order for compilation of macro calls to work, the macros must
+already be defined in Lisp when the calls to them are compiled.  The
+compiler has a special feature to help you do this: if a file being
+compiled contains a @code{defmacro} form, the macro is defined
+temporarily for the rest of the compilation of that file.  To make this
+feature work, you must put the @code{defmacro} in the same file where it
+is used, and before its first use.
+
+  Byte-compiling a file executes any @code{require} calls at top-level
+in the file.  This is in case the file needs the required packages for
+proper compilation.  One way to ensure that necessary macro definitions
+are available during compilation is to require the files that define
+them (@pxref{Named Features}).  To avoid loading the macro definition files
+when someone @emph{runs} the compiled program, write
+@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
+During Compile}).
+
+@node Defining Macros
+@section Defining Macros
+
+  A Lisp macro is a list whose @sc{car} is @code{macro}.  Its @sc{cdr} should
+be a function; expansion of the macro works by applying the function
+(with @code{apply}) to the list of unevaluated argument-expressions
+from the macro call.
+
+  It is possible to use an anonymous Lisp macro just like an anonymous
+function, but this is never done, because it does not make sense to pass
+an anonymous macro to functionals such as @code{mapcar}.  In practice,
+all Lisp macros have names, and they are usually defined with the
+special form @code{defmacro}.
+
+@defspec defmacro name argument-list body-forms@dots{}
+@code{defmacro} defines the symbol @var{name} as a macro that looks
+like this:
+
+@example
+(macro lambda @var{argument-list} . @var{body-forms})
+@end example
+
+(Note that the @sc{cdr} of this list is a function---a lambda expression.)
+This macro object is stored in the function cell of @var{name}.  The
+value returned by evaluating the @code{defmacro} form is @var{name}, but
+usually we ignore this value.
+
+The shape and meaning of @var{argument-list} is the same as in a
+function, and the keywords @code{&rest} and @code{&optional} may be used
+(@pxref{Argument List}).  Macros may have a documentation string, but
+any @code{interactive} declaration is ignored since macros cannot be
+called interactively.
+@end defspec
+
+  The body of the macro definition can include a @code{declare} form,
+which can specify how @key{TAB} should indent macro calls, and how to
+step through them for Edebug.
+
+@defmac declare @var{specs}@dots{}
+@anchor{Definition of declare}
+A @code{declare} form is used in a macro definition to specify various
+additional information about it.  Two kinds of specification are
+currently supported:
+
+@table @code
+@item (debug @var{edebug-form-spec})
+Specify how to step through macro calls for Edebug.
+@xref{Instrumenting Macro Calls}.
+
+@item (indent @var{indent-spec})
+Specify how to indent calls to this macro.  @xref{Indenting Macros},
+for more details.
+@end table
+
+A @code{declare} form only has its special effect in the body of a
+@code{defmacro} form if it immediately follows the documentation
+string, if present, or the argument list otherwise.  (Strictly
+speaking, @emph{several} @code{declare} forms can follow the
+documentation string or argument list, but since a @code{declare} form
+can have several @var{specs}, they can always be combined into a
+single form.)  When used at other places in a @code{defmacro} form, or
+outside a @code{defmacro} form, @code{declare} just returns @code{nil}
+without evaluating any @var{specs}.
+@end defmac
+
+  No macro absolutely needs a @code{declare} form, because that form
+has no effect on how the macro expands, on what the macro means in the
+program.  It only affects secondary features: indentation and Edebug.
+
+@node Backquote
+@section Backquote
+@cindex backquote (list substitution)
+@cindex ` (list substitution)
+@findex `
+
+  Macros often need to construct large list structures from a mixture of
+constants and nonconstant parts.  To make this easier, use the @samp{`}
+syntax (usually called @dfn{backquote}).
+
+  Backquote allows you to quote a list, but selectively evaluate
+elements of that list.  In the simplest case, it is identical to the
+special form @code{quote} (@pxref{Quoting}).  For example, these
+two forms yield identical results:
+
+@example
+@group
+`(a list of (+ 2 3) elements)
+     @result{} (a list of (+ 2 3) elements)
+@end group
+@group
+'(a list of (+ 2 3) elements)
+     @result{} (a list of (+ 2 3) elements)
+@end group
+@end example
+
+@findex , @r{(with backquote)}
+The special marker @samp{,} inside of the argument to backquote
+indicates a value that isn't constant.  Backquote evaluates the
+argument of @samp{,} and puts the value in the list structure:
+
+@example
+@group
+(list 'a 'list 'of (+ 2 3) 'elements)
+     @result{} (a list of 5 elements)
+@end group
+@group
+`(a list of ,(+ 2 3) elements)
+     @result{} (a list of 5 elements)
+@end group
+@end example
+
+  Substitution with @samp{,} is allowed at deeper levels of the list
+structure also.  For example:
+
+@example
+@group
+(defmacro t-becomes-nil (variable)
+  `(if (eq ,variable t)
+       (setq ,variable nil)))
+@end group
+
+@group
+(t-becomes-nil foo)
+     @equiv{} (if (eq foo t) (setq foo nil))
+@end group
+@end example
+
+@findex ,@@ @r{(with backquote)}
+@cindex splicing (with backquote)
+  You can also @dfn{splice} an evaluated value into the resulting list,
+using the special marker @samp{,@@}.  The elements of the spliced list
+become elements at the same level as the other elements of the resulting
+list.  The equivalent code without using @samp{`} is often unreadable.
+Here are some examples:
+
+@example
+@group
+(setq some-list '(2 3))
+     @result{} (2 3)
+@end group
+@group
+(cons 1 (append some-list '(4) some-list))
+     @result{} (1 2 3 4 2 3)
+@end group
+@group
+`(1 ,@@some-list 4 ,@@some-list)
+     @result{} (1 2 3 4 2 3)
+@end group
+
+@group
+(setq list '(hack foo bar))
+     @result{} (hack foo bar)
+@end group
+@group
+(cons 'use
+  (cons 'the
+    (cons 'words (append (cdr list) '(as elements)))))
+     @result{} (use the words foo bar as elements)
+@end group
+@group
+`(use the words ,@@(cdr list) as elements)
+     @result{} (use the words foo bar as elements)
+@end group
+@end example
+
+In old Emacs versions, before version 19.29, @samp{`} used a different
+syntax which required an extra level of parentheses around the entire
+backquote construct.  Likewise, each @samp{,} or @samp{,@@} substitution
+required an extra level of parentheses surrounding both the @samp{,} or
+@samp{,@@} and the following expression.  The old syntax required
+whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the
+following expression.
+
+This syntax is still accepted, for compatibility with old Emacs
+versions, but support for it will soon disappear.
+
+@node Problems with Macros
+@section Common Problems Using Macros
+
+  The basic facts of macro expansion have counterintuitive consequences.
+This section describes some important consequences that can lead to
+trouble, and rules to follow to avoid trouble.
+
+@menu
+* Wrong Time::             Do the work in the expansion, not in the macro.
+* Argument Evaluation::    The expansion should evaluate each macro arg once.
+* Surprising Local Vars::  Local variable bindings in the expansion
+                              require special care.
+* Eval During Expansion::  Don't evaluate them; put them in the expansion.
+* Repeated Expansion::     Avoid depending on how many times expansion is done.
+@end menu
+
+@node Wrong Time
+@subsection Wrong Time
+
+  The most common problem in writing macros is doing some of the
+real work prematurely---while expanding the macro, rather than in the
+expansion itself.  For instance, one real package had this macro
+definition:
+
+@example
+(defmacro my-set-buffer-multibyte (arg)
+  (if (fboundp 'set-buffer-multibyte)
+      (set-buffer-multibyte arg)))
+@end example
+
+With this erroneous macro definition, the program worked fine when
+interpreted but failed when compiled.  This macro definition called
+@code{set-buffer-multibyte} during compilation, which was wrong, and
+then did nothing when the compiled package was run.  The definition
+that the programmer really wanted was this:
+
+@example
+(defmacro my-set-buffer-multibyte (arg)
+  (if (fboundp 'set-buffer-multibyte)
+      `(set-buffer-multibyte ,arg)))
+@end example
+
+@noindent
+This macro expands, if appropriate, into a call to
+@code{set-buffer-multibyte} that will be executed when the compiled
+program is actually run.
+
+@node Argument Evaluation
+@subsection Evaluating Macro Arguments Repeatedly
+
+  When defining a macro you must pay attention to the number of times
+the arguments will be evaluated when the expansion is executed.  The
+following macro (used to facilitate iteration) illustrates the problem.
+This macro allows us to write a simple ``for'' loop such as one might
+find in Pascal.
+
+@findex for
+@smallexample
+@group
+(defmacro for (var from init to final do &rest body)
+  "Execute a simple \"for\" loop.
+For example, (for i from 1 to 10 do (print i))."
+  (list 'let (list (list var init))
+        (cons 'while (cons (list '<= var final)
+                           (append body (list (list 'inc var)))))))
+@end group
+@result{} for
+
+@group
+(for i from 1 to 3 do
+   (setq square (* i i))
+   (princ (format "\n%d %d" i square)))
+@expansion{}
+@end group
+@group
+(let ((i 1))
+  (while (<= i 3)
+    (setq square (* i i))
+    (princ (format "\n%d %d" i square))
+    (inc i)))
+@end group
+@group
+
+     @print{}1       1
+     @print{}2       4
+     @print{}3       9
+@result{} nil
+@end group
+@end smallexample
+
+@noindent
+The arguments @code{from}, @code{to}, and @code{do} in this macro are
+``syntactic sugar''; they are entirely ignored.  The idea is that you
+will write noise words (such as @code{from}, @code{to}, and @code{do})
+in those positions in the macro call.
+
+Here's an equivalent definition simplified through use of backquote:
+
+@smallexample
+@group
+(defmacro for (var from init to final do &rest body)
+  "Execute a simple \"for\" loop.
+For example, (for i from 1 to 10 do (print i))."
+  `(let ((,var ,init))
+     (while (<= ,var ,final)
+       ,@@body
+       (inc ,var))))
+@end group
+@end smallexample
+
+Both forms of this definition (with backquote and without) suffer from
+the defect that @var{final} is evaluated on every iteration.  If
+@var{final} is a constant, this is not a problem.  If it is a more
+complex form, say @code{(long-complex-calculation x)}, this can slow
+down the execution significantly.  If @var{final} has side effects,
+executing it more than once is probably incorrect.
+
+@cindex macro argument evaluation
+A well-designed macro definition takes steps to avoid this problem by
+producing an expansion that evaluates the argument expressions exactly
+once unless repeated evaluation is part of the intended purpose of the
+macro.  Here is a correct expansion for the @code{for} macro:
+
+@smallexample
+@group
+(let ((i 1)
+      (max 3))
+  (while (<= i max)
+    (setq square (* i i))
+    (princ (format "%d      %d" i square))
+    (inc i)))
+@end group
+@end smallexample
+
+Here is a macro definition that creates this expansion:
+
+@smallexample
+@group
+(defmacro for (var from init to final do &rest body)
+  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+  `(let ((,var ,init)
+         (max ,final))
+     (while (<= ,var max)
+       ,@@body
+       (inc ,var))))
+@end group
+@end smallexample
+
+  Unfortunately, this fix introduces another problem,
+described in the following section.
+
+@node Surprising Local Vars
+@subsection Local Variables in Macro Expansions
+
+@ifnottex
+  In the previous section, the definition of @code{for} was fixed as
+follows to make the expansion evaluate the macro arguments the proper
+number of times:
+
+@smallexample
+@group
+(defmacro for (var from init to final do &rest body)
+  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+@end group
+@group
+  `(let ((,var ,init)
+         (max ,final))
+     (while (<= ,var max)
+       ,@@body
+       (inc ,var))))
+@end group
+@end smallexample
+@end ifnottex
+
+  The new definition of @code{for} has a new problem: it introduces a
+local variable named @code{max} which the user does not expect.  This
+causes trouble in examples such as the following:
+
+@smallexample
+@group
+(let ((max 0))
+  (for x from 0 to 10 do
+    (let ((this (frob x)))
+      (if (< max this)
+          (setq max this)))))
+@end group
+@end smallexample
+
+@noindent
+The references to @code{max} inside the body of the @code{for}, which
+are supposed to refer to the user's binding of @code{max}, really access
+the binding made by @code{for}.
+
+The way to correct this is to use an uninterned symbol instead of
+@code{max} (@pxref{Creating Symbols}).  The uninterned symbol can be
+bound and referred to just like any other symbol, but since it is
+created by @code{for}, we know that it cannot already appear in the
+user's program.  Since it is not interned, there is no way the user can
+put it into the program later.  It will never appear anywhere except
+where put by @code{for}.  Here is a definition of @code{for} that works
+this way:
+
+@smallexample
+@group
+(defmacro for (var from init to final do &rest body)
+  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+  (let ((tempvar (make-symbol "max")))
+    `(let ((,var ,init)
+           (,tempvar ,final))
+       (while (<= ,var ,tempvar)
+         ,@@body
+         (inc ,var)))))
+@end group
+@end smallexample
+
+@noindent
+This creates an uninterned symbol named @code{max} and puts it in the
+expansion instead of the usual interned symbol @code{max} that appears
+in expressions ordinarily.
+
+@node Eval During Expansion
+@subsection Evaluating Macro Arguments in Expansion
+
+  Another problem can happen if the macro definition itself
+evaluates any of the macro argument expressions, such as by calling
+@code{eval} (@pxref{Eval}).  If the argument is supposed to refer to the
+user's variables, you may have trouble if the user happens to use a
+variable with the same name as one of the macro arguments.  Inside the
+macro body, the macro argument binding is the most local binding of this
+variable, so any references inside the form being evaluated do refer to
+it.  Here is an example:
+
+@example
+@group
+(defmacro foo (a)
+  (list 'setq (eval a) t))
+     @result{} foo
+@end group
+@group
+(setq x 'b)
+(foo x) @expansion{} (setq b t)
+     @result{} t                  ; @r{and @code{b} has been set.}
+;; @r{but}
+(setq a 'c)
+(foo a) @expansion{} (setq a t)
+     @result{} t                  ; @r{but this set @code{a}, not @code{c}.}
+
+@end group
+@end example
+
+  It makes a difference whether the user's variable is named @code{a} or
+@code{x}, because @code{a} conflicts with the macro argument variable
+@code{a}.
+
+  Another problem with calling @code{eval} in a macro definition is that
+it probably won't do what you intend in a compiled program.  The
+byte-compiler runs macro definitions while compiling the program, when
+the program's own computations (which you might have wished to access
+with @code{eval}) don't occur and its local variable bindings don't
+exist.
+
+  To avoid these problems, @strong{don't evaluate an argument expression
+while computing the macro expansion}.  Instead, substitute the
+expression into the macro expansion, so that its value will be computed
+as part of executing the expansion.  This is how the other examples in
+this chapter work.
+
+@node Repeated Expansion
+@subsection How Many Times is the Macro Expanded?
+
+  Occasionally problems result from the fact that a macro call is
+expanded each time it is evaluated in an interpreted function, but is
+expanded only once (during compilation) for a compiled function.  If the
+macro definition has side effects, they will work differently depending
+on how many times the macro is expanded.
+
+  Therefore, you should avoid side effects in computation of the
+macro expansion, unless you really know what you are doing.
+
+  One special kind of side effect can't be avoided: constructing Lisp
+objects.  Almost all macro expansions include constructed lists; that is
+the whole point of most macros.  This is usually safe; there is just one
+case where you must be careful: when the object you construct is part of a
+quoted constant in the macro expansion.
+
+  If the macro is expanded just once, in compilation, then the object is
+constructed just once, during compilation.  But in interpreted
+execution, the macro is expanded each time the macro call runs, and this
+means a new object is constructed each time.
+
+  In most clean Lisp code, this difference won't matter.  It can matter
+only if you perform side-effects on the objects constructed by the macro
+definition.  Thus, to avoid trouble, @strong{avoid side effects on
+objects constructed by macro definitions}.  Here is an example of how
+such side effects can get you into trouble:
+
+@lisp
+@group
+(defmacro empty-object ()
+  (list 'quote (cons nil nil)))
+@end group
+
+@group
+(defun initialize (condition)
+  (let ((object (empty-object)))
+    (if condition
+        (setcar object condition))
+    object))
+@end group
+@end lisp
+
+@noindent
+If @code{initialize} is interpreted, a new list @code{(nil)} is
+constructed each time @code{initialize} is called.  Thus, no side effect
+survives between calls.  If @code{initialize} is compiled, then the
+macro @code{empty-object} is expanded during compilation, producing a
+single ``constant'' @code{(nil)} that is reused and altered each time
+@code{initialize} is called.
+
+One way to avoid pathological cases like this is to think of
+@code{empty-object} as a funny kind of constant, not as a memory
+allocation construct.  You wouldn't use @code{setcar} on a constant such
+as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)}
+either.
+
+@node Indenting Macros
+@section Indenting Macros
+
+  You can use the @code{declare} form in the macro definition to
+specify how to @key{TAB} should indent indent calls to the macro.  You
+write it like this:
+
+@example
+(declare (indent @var{indent-spec}))
+@end example
+
+@noindent
+Here are the possibilities for @var{indent-spec}:
+
+@table @asis
+@item @code{nil}
+This is the same as no property---use the standard indentation pattern.
+@item @code{defun}
+Handle this function like a @samp{def} construct: treat the second
+line as the start of a @dfn{body}.
+@item an integer, @var{number}
+The first @var{number} arguments of the function are
+@dfn{distinguished} arguments; the rest are considered the body
+of the expression.  A line in the expression is indented according to
+whether the first argument on it is distinguished or not.  If the
+argument is part of the body, the line is indented @code{lisp-body-indent}
+more columns than the open-parenthesis starting the containing
+expression.  If the argument is distinguished and is either the first
+or second argument, it is indented @emph{twice} that many extra columns.
+If the argument is distinguished and not the first or second argument,
+the line uses the standard pattern.
+@item a symbol, @var{symbol}
+@var{symbol} should be a function name; that function is called to
+calculate the indentation of a line within this expression.  The
+function receives two arguments:
+@table @asis
+@item @var{state}
+The value returned by @code{parse-partial-sexp} (a Lisp primitive for
+indentation and nesting computation) when it parses up to the
+beginning of this line.
+@item @var{pos}
+The position at which the line being indented begins.
+@end table
+@noindent
+It should return either a number, which is the number of columns of
+indentation for that line, or a list whose car is such a number.  The
+difference between returning a number and returning a list is that a
+number says that all following lines at the same nesting level should
+be indented just like this one; a list says that following lines might
+call for different indentations.  This makes a difference when the
+indentation is being computed by @kbd{C-M-q}; if the value is a
+number, @kbd{C-M-q} need not recalculate indentation for the following
+lines until the end of the list.
+@end table
+
+@ignore
+   arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b
+@end ignore
diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in
new file mode 100644
index 00000000000..7e35339d17f
--- /dev/null
+++ b/doc/lispref/makefile.w32-in
@@ -0,0 +1,123 @@
+# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual.
+
+# 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.
+
+# Standard configure variables.
+srcdir = .
+
+infodir = $(srcdir)/../info
+usermanualdir = $(srcdir)/../man
+
+# Redefine `TEX' if `tex' does not invoke plain TeX.  For example:
+# TEX=platex
+TEX=tex
+INSTALL_INFO = install-info
+MAKEINFO = makeinfo --force
+
+# The environment variable and its value to add $(srcdir) to the path
+# searched for TeX input files.
+texinputdir = $(srcdir)\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" /C
+
+# The name of the manual:
+VERSION=2.9
+manual = elisp-manual-21-$(VERSION)
+
+# List of all the texinfo files in the manual:
+
+srcs = \
+  $(srcdir)/abbrevs.texi \
+  $(srcdir)/advice.texi \
+  $(srcdir)/anti.texi \
+  $(srcdir)/back.texi \
+  $(srcdir)/backups.texi \
+  $(srcdir)/buffers.texi \
+  $(srcdir)/commands.texi \
+  $(srcdir)/compile.texi \
+  $(srcdir)/control.texi \
+  $(srcdir)/customize.texi \
+  $(srcdir)/debugging.texi \
+  $(srcdir)/display.texi \
+  $(srcdir)/edebug.texi \
+  $(srcdir)/elisp.texi \
+  $(srcdir)/errors.texi \
+  $(srcdir)/eval.texi \
+  $(srcdir)/files.texi \
+  $(srcdir)/frames.texi \
+  $(srcdir)/functions.texi \
+  $(srcdir)/hash.texi \
+  $(srcdir)/help.texi \
+  $(srcdir)/hooks.texi \
+  $(srcdir)/internals.texi \
+  $(srcdir)/intro.texi \
+  $(srcdir)/keymaps.texi \
+  $(srcdir)/lists.texi \
+  $(srcdir)/loading.texi \
+  $(srcdir)/locals.texi \
+  $(srcdir)/macros.texi \
+  $(srcdir)/maps.texi \
+  $(srcdir)/markers.texi \
+  $(srcdir)/minibuf.texi \
+  $(srcdir)/modes.texi \
+  $(srcdir)/nonascii.texi \
+  $(srcdir)/numbers.texi \
+  $(srcdir)/objects.texi \
+  $(srcdir)/os.texi \
+  $(srcdir)/positions.texi \
+  $(srcdir)/processes.texi \
+  $(srcdir)/searching.texi \
+  $(srcdir)/sequences.texi \
+  $(srcdir)/streams.texi \
+  $(srcdir)/strings.texi \
+  $(srcdir)/symbols.texi \
+  $(srcdir)/syntax.texi \
+  $(srcdir)/text.texi \
+  $(srcdir)/tips.texi \
+  $(srcdir)/variables.texi \
+  $(srcdir)/windows.texi \
+  $(srcdir)/index.texi \
+  $(srcdir)/gpl.texi \
+  $(srcdir)/doclicense.texi
+
+
+.PHONY: clean
+
+# The info file is named `elisp'.
+
+info: $(infodir)/elisp
+
+$(infodir)/dir:
+	$(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp
+
+$(infodir)/elisp: $(srcs)
+	$(MAKEINFO) -I. -I$(srcdir) -o $(infodir)/elisp $(srcdir)/elisp.texi
+
+elisp.dvi: $(srcs)
+	$(texinputdir) $(TEX) -I $(usermanualdir) $(srcdir)/elisp.texi
+
+clean:
+	- $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
+                 *.vr *.vrs *.pg *.pgs *.ky *.kys
+	- $(DEL) make.out core
+	- $(DEL) $(infodir)/elisp*
+
+distclean: clean
+
+maintainer-clean: distclean
+	- $(DEL) elisp elisp-? elisp-?? elisp.dvi elisp.oaux
diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi
new file mode 100644
index 00000000000..724091970c3
--- /dev/null
+++ b/doc/lispref/maps.texi
@@ -0,0 +1,230 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/maps
+@node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top
+@appendix Standard Keymaps
+@cindex standard keymaps
+
+The following symbols are used as the names for various keymaps.
+Some of these exist when Emacs is first started, others are
+loaded only when their respective mode is used.  This is not
+an exhaustive list.
+
+Several keymaps are used in the minibuffer.  @xref{Completion Commands}.
+
+Almost all of these maps are used as local maps.  Indeed, of the modes
+that presently exist, only Vip mode and Terminal mode ever change the
+global keymap.
+
+@table @code
+@item apropos-mode-map
+@vindex apropos-mode-map
+A sparse keymap for @code{apropos} buffers.
+
+@item Buffer-menu-mode-map
+@vindex Buffer-menu-mode-map
+A full keymap used by Buffer Menu mode.
+
+@item c-mode-map
+@vindex c-mode-map
+A sparse keymap used by C mode.
+
+@item command-history-map
+@vindex command-history-map
+A full keymap used by Command History mode.
+
+@item ctl-x-4-map
+A sparse keymap for subcommands of the prefix @kbd{C-x 4}.
+
+@item ctl-x-5-map
+A sparse keymap for subcommands of the prefix @kbd{C-x 5}.
+
+@item ctl-x-map
+A full keymap for @kbd{C-x} commands.
+
+@item custom-mode-map
+A full keymap for Custom mode.
+
+@item debugger-mode-map
+@vindex debugger-mode-map
+A full keymap used by Debugger mode.
+
+@item dired-mode-map
+@vindex dired-mode-map
+A full keymap for @code{dired-mode} buffers.
+
+@item edit-abbrevs-map
+@vindex edit-abbrevs-map
+A sparse keymap used in @code{edit-abbrevs}.
+
+@item edit-tab-stops-map
+@vindex edit-tab-stops-map
+A sparse keymap used in @code{edit-tab-stops}.
+
+@item electric-buffer-menu-mode-map
+@vindex electric-buffer-menu-mode-map
+A full keymap used by Electric Buffer Menu mode.
+
+@item electric-history-map
+@vindex electric-history-map
+A full keymap used by Electric Command History mode.
+
+@item emacs-lisp-mode-map
+@vindex emacs-lisp-mode-map
+A sparse keymap used by Emacs Lisp mode.
+
+@item esc-map
+A full keymap for @kbd{ESC} (or @kbd{Meta}) commands.
+
+@item facemenu-menu
+@vindex facemenu-menu
+The sparse keymap that displays the Text Properties menu.
+
+@item facemenu-background-menu
+@vindex facemenu-background-menu
+The sparse keymap that displays the Background Color submenu of the Text
+Properties menu.
+
+@item facemenu-face-menu
+@vindex facemenu-face-menu
+The sparse keymap that displays the Face submenu of the Text Properties menu.
+
+@item facemenu-foreground-menu
+@vindex facemenu-foreground-menu
+The sparse keymap that displays the Foreground Color submenu of the Text
+Properties menu.
+
+@item facemenu-indentation-menu
+@vindex facemenu-indentation-menu
+The sparse keymap that displays the Indentation submenu of the Text
+Properties menu.
+
+@item facemenu-justification-menu
+@vindex facemenu-justification-menu
+The sparse keymap that displays the Justification submenu of the Text
+Properties menu.
+
+@item facemenu-special-menu
+@vindex facemenu-special-menu
+The sparse keymap that displays the Special Props submenu of the Text
+Properties menu.
+
+@item function-key-map
+The keymap for translating keypad and function keys.@*
+If there are none, then it contains an empty sparse keymap.
+@xref{Translation Keymaps}.
+
+@item fundamental-mode-map
+@vindex fundamental-mode-map
+The sparse keymap for Fundamental mode.@*
+It is empty and should not be changed.
+
+@item global-map
+The full keymap containing default global key bindings.@*
+Modes should not modify the Global map.
+
+@item grep-mode-map
+@vindex grep-mode-map
+The keymap for @code{grep-mode} buffers.
+
+@item help-map
+The sparse keymap for the keys that follow the help character @kbd{C-h}.
+
+@item help-mode-map
+@vindex help-mode-map
+The sparse keymap for Help mode.
+
+@item Helper-help-map
+@vindex Helper-help-map
+A full keymap used by the help utility package.@*
+It has the same keymap in its value cell and in its function
+cell.
+
+@item Info-edit-map
+@vindex Info-edit-map
+A sparse keymap used by the @kbd{e} command of Info.
+
+@item Info-mode-map
+@vindex Info-mode-map
+A sparse keymap containing Info commands.
+
+@item isearch-mode-map
+@vindex isearch-mode-map
+A keymap that defines the characters you can type within incremental
+search.
+
+@item key-translation-map
+A keymap for translating keys.  This one overrides ordinary key
+bindings, unlike @code{function-key-map}.  @xref{Translation Keymaps}.
+
+@item kmacro-map
+@vindex kmacro-map
+A sparse keymap for keys that follows the @kbd{C-x C-k} prefix
+search.
+
+@item lisp-interaction-mode-map
+@vindex lisp-interaction-mode-map
+A sparse keymap used by Lisp Interaction mode.
+
+@item lisp-mode-map
+@vindex lisp-mode-map
+A sparse keymap used by Lisp mode.
+
+@item menu-bar-edit-menu
+@vindex menu-bar-edit-menu
+The keymap which displays the Edit menu in the menu bar.
+
+@item menu-bar-files-menu
+@vindex menu-bar-files-menu
+The keymap which displays the Files menu in the menu bar.
+
+@item menu-bar-help-menu
+@vindex menu-bar-help-menu
+The keymap which displays the Help menu in the menu bar.
+
+@item menu-bar-mule-menu
+@vindex menu-bar-mule-menu
+The keymap which displays the Mule menu in the menu bar.
+
+@item menu-bar-search-menu
+@vindex menu-bar-search-menu
+The keymap which displays the Search menu in the menu bar.
+
+@item menu-bar-tools-menu
+@vindex menu-bar-tools-menu
+The keymap which displays the Tools menu in the menu bar.
+
+@item mode-specific-map
+The keymap for characters following @kbd{C-c}.  Note, this is in the
+global map.  This map is not actually mode specific: its name was chosen
+to be informative for the user in @kbd{C-h b} (@code{display-bindings}),
+where it describes the main use of the @kbd{C-c} prefix key.
+
+@item occur-mode-map
+@vindex occur-mode-map
+A sparse keymap used by Occur mode.
+
+@item query-replace-map
+A sparse keymap used for responses in @code{query-replace} and related
+commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}.  The functions
+that use this map do not support prefix keys; they look up one event at a
+time.
+
+@item text-mode-map
+@vindex text-mode-map
+A sparse keymap used by Text mode.
+
+@item tool-bar-map
+The keymap defining the contents of the tool bar.
+
+@item view-mode-map
+@vindex view-mode-map
+A full keymap used by View mode.
+@end table
+
+@ignore
+   arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9
+@end ignore
diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
new file mode 100644
index 00000000000..519b8a1316a
--- /dev/null
+++ b/doc/lispref/markers.texi
@@ -0,0 +1,664 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/markers
+@node Markers, Text, Positions, Top
+@chapter Markers
+@cindex markers
+
+  A @dfn{marker} is a Lisp object used to specify a position in a buffer
+relative to the surrounding text.  A marker changes its offset from the
+beginning of the buffer automatically whenever text is inserted or
+deleted, so that it stays with the two characters on either side of it.
+
+@menu
+* Overview of Markers::      The components of a marker, and how it relocates.
+* Predicates on Markers::    Testing whether an object is a marker.
+* Creating Markers::         Making empty markers or markers at certain places.
+* Information from Markers:: Finding the marker's buffer or character position.
+* Marker Insertion Types::   Two ways a marker can relocate when you
+                               insert where it points.
+* Moving Markers::           Moving the marker to a new buffer or position.
+* The Mark::                 How "the mark" is implemented with a marker.
+* The Region::               How to access "the region".
+@end menu
+
+@node Overview of Markers
+@section Overview of Markers
+
+  A marker specifies a buffer and a position in that buffer.  The
+marker can be used to represent a position in the functions that
+require one, just as an integer could be used.  In that case, the
+marker's buffer is normally ignored.  Of course, a marker used in this
+way usually points to a position in the buffer that the function
+operates on, but that is entirely the programmer's responsibility.
+@xref{Positions}, for a complete description of positions.
+
+  A marker has three attributes: the marker position, the marker
+buffer, and the insertion type.  The marker position is an integer
+that is equivalent (at a given time) to the marker as a position in
+that buffer.  But the marker's position value can change often during
+the life of the marker.  Insertion and deletion of text in the buffer
+relocate the marker.  The idea is that a marker positioned between two
+characters remains between those two characters despite insertion and
+deletion elsewhere in the buffer.  Relocation changes the integer
+equivalent of the marker.
+
+@cindex marker relocation
+  Deleting text around a marker's position leaves the marker between the
+characters immediately before and after the deleted text.  Inserting
+text at the position of a marker normally leaves the marker either in
+front of or after the new text, depending on the marker's @dfn{insertion
+type} (@pxref{Marker Insertion Types})---unless the insertion is done
+with @code{insert-before-markers} (@pxref{Insertion}).
+
+@cindex marker garbage collection
+  Insertion and deletion in a buffer must check all the markers and
+relocate them if necessary.  This slows processing in a buffer with a
+large number of markers.  For this reason, it is a good idea to make a
+marker point nowhere if you are sure you don't need it any more.
+Unreferenced markers are garbage collected eventually, but until then
+will continue to use time if they do point somewhere.
+
+@cindex markers as numbers
+  Because it is common to perform arithmetic operations on a marker
+position, most of the arithmetic operations (including @code{+} and
+@code{-}) accept markers as arguments.  In such cases, the marker
+stands for its current position.
+
+Here are examples of creating markers, setting markers, and moving point
+to markers:
+
+@example
+@group
+;; @r{Make a new marker that initially does not point anywhere:}
+(setq m1 (make-marker))
+     @result{} #<marker in no buffer>
+@end group
+
+@group
+;; @r{Set @code{m1} to point between the 99th and 100th characters}
+;;   @r{in the current buffer:}
+(set-marker m1 100)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+
+@group
+;; @r{Now insert one character at the beginning of the buffer:}
+(goto-char (point-min))
+     @result{} 1
+(insert "Q")
+     @result{} nil
+@end group
+
+@group
+;; @r{@code{m1} is updated appropriately.}
+m1
+     @result{} #<marker at 101 in markers.texi>
+@end group
+
+@group
+;; @r{Two markers that point to the same position}
+;;   @r{are not @code{eq}, but they are @code{equal}.}
+(setq m2 (copy-marker m1))
+     @result{} #<marker at 101 in markers.texi>
+(eq m1 m2)
+     @result{} nil
+(equal m1 m2)
+     @result{} t
+@end group
+
+@group
+;; @r{When you are finished using a marker, make it point nowhere.}
+(set-marker m1 nil)
+     @result{} #<marker in no buffer>
+@end group
+@end example
+
+@node Predicates on Markers
+@section Predicates on Markers
+
+  You can test an object to see whether it is a marker, or whether it is
+either an integer or a marker.  The latter test is useful in connection
+with the arithmetic functions that work with both markers and integers.
+
+@defun markerp object
+This function returns @code{t} if @var{object} is a marker, @code{nil}
+otherwise.  Note that integers are not markers, even though many
+functions will accept either a marker or an integer.
+@end defun
+
+@defun integer-or-marker-p object
+This function returns @code{t} if @var{object} is an integer or a marker,
+@code{nil} otherwise.
+@end defun
+
+@defun number-or-marker-p object
+This function returns @code{t} if @var{object} is a number (either
+integer or floating point) or a marker, @code{nil} otherwise.
+@end defun
+
+@node Creating Markers
+@section Functions that Create Markers
+
+  When you create a new marker, you can make it point nowhere, or point
+to the present position of point, or to the beginning or end of the
+accessible portion of the buffer, or to the same place as another given
+marker.
+
+The next four functions all return markers with insertion type
+@code{nil}.  @xref{Marker Insertion Types}.
+
+@defun make-marker
+This function returns a newly created marker that does not point
+anywhere.
+
+@example
+@group
+(make-marker)
+     @result{} #<marker in no buffer>
+@end group
+@end example
+@end defun
+
+@defun point-marker
+This function returns a new marker that points to the present position
+of point in the current buffer.  @xref{Point}.  For an example, see
+@code{copy-marker}, below.
+@end defun
+
+@defun point-min-marker
+This function returns a new marker that points to the beginning of the
+accessible portion of the buffer.  This will be the beginning of the
+buffer unless narrowing is in effect.  @xref{Narrowing}.
+@end defun
+
+@defun point-max-marker
+This function returns a new marker that points to the end of the
+accessible portion of the buffer.  This will be the end of the buffer
+unless narrowing is in effect.  @xref{Narrowing}.
+
+Here are examples of this function and @code{point-min-marker}, shown in
+a buffer containing a version of the source file for the text of this
+chapter.
+
+@example
+@group
+(point-min-marker)
+     @result{} #<marker at 1 in markers.texi>
+(point-max-marker)
+     @result{} #<marker at 15573 in markers.texi>
+@end group
+
+@group
+(narrow-to-region 100 200)
+     @result{} nil
+@end group
+@group
+(point-min-marker)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@group
+(point-max-marker)
+     @result{} #<marker at 200 in markers.texi>
+@end group
+@end example
+@end defun
+
+@defun copy-marker marker-or-integer &optional insertion-type
+If passed a marker as its argument, @code{copy-marker} returns a
+new marker that points to the same place and the same buffer as does
+@var{marker-or-integer}.  If passed an integer as its argument,
+@code{copy-marker} returns a new marker that points to position
+@var{marker-or-integer} in the current buffer.
+
+The new marker's insertion type is specified by the argument
+@var{insertion-type}.  @xref{Marker Insertion Types}.
+
+If passed an integer argument less than 1, @code{copy-marker} returns a
+new marker that points to the beginning of the current buffer.  If
+passed an integer argument greater than the length of the buffer,
+@code{copy-marker} returns a new marker that points to the end of the
+buffer.
+
+@example
+@group
+(copy-marker 0)
+     @result{} #<marker at 1 in markers.texi>
+@end group
+
+@group
+(copy-marker 20000)
+     @result{} #<marker at 7572 in markers.texi>
+@end group
+@end example
+
+An error is signaled if @var{marker} is neither a marker nor an
+integer.
+@end defun
+
+  Two distinct markers are considered @code{equal} (even though not
+@code{eq}) to each other if they have the same position and buffer, or
+if they both point nowhere.
+
+@example
+@group
+(setq p (point-marker))
+     @result{} #<marker at 2139 in markers.texi>
+@end group
+
+@group
+(setq q (copy-marker p))
+     @result{} #<marker at 2139 in markers.texi>
+@end group
+
+@group
+(eq p q)
+     @result{} nil
+@end group
+
+@group
+(equal p q)
+     @result{} t
+@end group
+@end example
+
+@node Information from Markers
+@section Information from Markers
+
+  This section describes the functions for accessing the components of a
+marker object.
+
+@defun marker-position marker
+This function returns the position that @var{marker} points to, or
+@code{nil} if it points nowhere.
+@end defun
+
+@defun marker-buffer marker
+This function returns the buffer that @var{marker} points into, or
+@code{nil} if it points nowhere.
+
+@example
+@group
+(setq m (make-marker))
+     @result{} #<marker in no buffer>
+@end group
+@group
+(marker-position m)
+     @result{} nil
+@end group
+@group
+(marker-buffer m)
+     @result{} nil
+@end group
+
+@group
+(set-marker m 3770 (current-buffer))
+     @result{} #<marker at 3770 in markers.texi>
+@end group
+@group
+(marker-buffer m)
+     @result{} #<buffer markers.texi>
+@end group
+@group
+(marker-position m)
+     @result{} 3770
+@end group
+@end example
+@end defun
+
+@defun buffer-has-markers-at position
+This function returns @code{t} if one or more markers
+point at position @var{position} in the current buffer.
+@end defun
+
+@node Marker Insertion Types
+@section Marker Insertion Types
+
+@cindex insertion type of a marker
+  When you insert text directly at the place where a marker points,
+there are two possible ways to relocate that marker: it can point before
+the inserted text, or point after it.  You can specify which one a given
+marker should do by setting its @dfn{insertion type}.  Note that use of
+@code{insert-before-markers} ignores markers' insertion types, always
+relocating a marker to point after the inserted text.
+
+@defun set-marker-insertion-type marker type
+This function sets the insertion type of marker @var{marker} to
+@var{type}.  If @var{type} is @code{t}, @var{marker} will advance when
+text is inserted at its position.  If @var{type} is @code{nil},
+@var{marker} does not advance when text is inserted there.
+@end defun
+
+@defun marker-insertion-type marker
+This function reports the current insertion type of @var{marker}.
+@end defun
+
+Most functions that create markers, without an argument allowing to
+specify the insertion type, create them with insertion type
+@code{nil}.  Also, the mark has, by default, insertion type
+@code{nil}.
+
+@node Moving Markers
+@section Moving Marker Positions
+
+  This section describes how to change the position of an existing
+marker.  When you do this, be sure you know whether the marker is used
+outside of your program, and, if so, what effects will result from
+moving it---otherwise, confusing things may happen in other parts of
+Emacs.
+
+@defun set-marker marker position &optional buffer
+This function moves @var{marker} to @var{position}
+in @var{buffer}.  If @var{buffer} is not provided, it defaults to
+the current buffer.
+
+If @var{position} is less than 1, @code{set-marker} moves @var{marker}
+to the beginning of the buffer.  If @var{position} is greater than the
+size of the buffer, @code{set-marker} moves marker to the end of the
+buffer.  If @var{position} is @code{nil} or a marker that points
+nowhere, then @var{marker} is set to point nowhere.
+
+The value returned is @var{marker}.
+
+@example
+@group
+(setq m (point-marker))
+     @result{} #<marker at 4714 in markers.texi>
+@end group
+@group
+(set-marker m 55)
+     @result{} #<marker at 55 in markers.texi>
+@end group
+@group
+(setq b (get-buffer "foo"))
+     @result{} #<buffer foo>
+@end group
+@group
+(set-marker m 0 b)
+     @result{} #<marker at 1 in foo>
+@end group
+@end example
+@end defun
+
+@defun move-marker marker position &optional buffer
+This is another name for @code{set-marker}.
+@end defun
+
+@node The Mark
+@section The Mark
+@cindex mark, the
+@cindex mark ring
+
+  One special marker in each buffer is designated @dfn{the mark}.  It
+specifies a position to bound a range of text for commands such as
+@code{kill-region} and @code{indent-rigidly}.  Lisp programs should
+set the mark only to values that have a potential use to the user, and
+never for their own internal purposes.  For example, the
+@code{replace-regexp} command sets the mark to the value of point
+before doing any replacements, because this enables the user to move
+back there conveniently after the replace is finished.
+
+  Many commands are designed to operate on the text between point and
+the mark when called interactively.  If you are writing such a
+command, don't examine the mark directly; instead, use
+@code{interactive} with the @samp{r} specification.  This provides the
+values of point and the mark as arguments to the command in an
+interactive call, but permits other Lisp programs to specify arguments
+explicitly.  @xref{Interactive Codes}.
+
+  Each buffer has a marker which represents the value of the mark in
+that buffer, independent of any other buffer.  When a buffer is newly
+created, this marker exists but does not point anywhere.  That means
+the mark ``doesn't exist'' in that buffer as yet.
+
+  Once the mark ``exists'' in a buffer, it normally never ceases to
+exist.  However, it may become @dfn{inactive}, if Transient Mark mode is
+enabled.  The variable @code{mark-active}, which is always buffer-local
+in all buffers, indicates whether the mark is active: non-@code{nil}
+means yes.  A command can request deactivation of the mark upon return
+to the editor command loop by setting @code{deactivate-mark} to a
+non-@code{nil} value (but this causes deactivation only if Transient
+Mark mode is enabled).
+
+  The main motivation for using Transient Mark mode is that this mode
+also enables highlighting of the region when the mark is active.
+@xref{Display}.
+
+  In addition to the mark, each buffer has a @dfn{mark ring} which is a
+list of markers containing previous values of the mark.  When editing
+commands change the mark, they should normally save the old value of the
+mark on the mark ring.  The variable @code{mark-ring-max} specifies the
+maximum number of entries in the mark ring; once the list becomes this
+long, adding a new element deletes the last element.
+
+  There is also a separate global mark ring, but that is used only in a
+few particular user-level commands, and is not relevant to Lisp
+programming.  So we do not describe it here.
+
+@defun mark &optional force
+@cindex current buffer mark
+This function returns the current buffer's mark position as an integer,
+or @code{nil} if no mark has ever been set in this buffer.
+
+If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
+@code{nil}, @code{mark} signals an error if the mark is inactive.
+However, if @var{force} is non-@code{nil}, then @code{mark} disregards
+inactivity of the mark, and returns the mark position anyway (or
+@code{nil}).
+@end defun
+
+@defun mark-marker
+This function returns the marker that represents the current buffer's
+mark.  It is not a copy, it is the marker used internally.  Therefore,
+changing this marker's position will directly affect the buffer's
+mark.  Don't do that unless that is the effect you want.
+
+@example
+@group
+(setq m (mark-marker))
+     @result{} #<marker at 3420 in markers.texi>
+@end group
+@group
+(set-marker m 100)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@group
+(mark-marker)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@end example
+
+Like any marker, this marker can be set to point at any buffer you
+like.  If you make it point at any buffer other than the one of which
+it is the mark, it will yield perfectly consistent, but rather odd,
+results.  We recommend that you not do it!
+@end defun
+
+@ignore
+@deffn Command set-mark-command jump
+If @var{jump} is @code{nil}, this command sets the mark to the value
+of point and pushes the previous value of the mark on the mark ring.  The
+message @samp{Mark set} is also displayed in the echo area.
+
+If @var{jump} is not @code{nil}, this command sets point to the value
+of the mark, and sets the mark to the previous saved mark value, which
+is popped off the mark ring.
+
+This function is @emph{only} intended for interactive use.
+@end deffn
+@end ignore
+
+@defun set-mark position
+This function sets the mark to @var{position}, and activates the mark.
+The old value of the mark is @emph{not} pushed onto the mark ring.
+
+@strong{Please note:} Use this function only if you want the user to
+see that the mark has moved, and you want the previous mark position to
+be lost.  Normally, when a new mark is set, the old one should go on the
+@code{mark-ring}.  For this reason, most applications should use
+@code{push-mark} and @code{pop-mark}, not @code{set-mark}.
+
+Novice Emacs Lisp programmers often try to use the mark for the wrong
+purposes.  The mark saves a location for the user's convenience.  An
+editing command should not alter the mark unless altering the mark is
+part of the user-level functionality of the command.  (And, in that
+case, this effect should be documented.)  To remember a location for
+internal use in the Lisp program, store it in a Lisp variable.  For
+example:
+
+@example
+@group
+(let ((beg (point)))
+  (forward-line 1)
+  (delete-region beg (point))).
+@end group
+@end example
+@end defun
+
+@c for interactive use only
+@ignore
+@deffn Command exchange-point-and-mark
+This function exchanges the positions of point and the mark.
+It is intended for interactive use.
+@end deffn
+@end ignore
+
+@defun push-mark &optional position nomsg activate
+This function sets the current buffer's mark to @var{position}, and
+pushes a copy of the previous mark onto @code{mark-ring}.  If
+@var{position} is @code{nil}, then the value of point is used.
+@code{push-mark} returns @code{nil}.
+
+The function @code{push-mark} normally @emph{does not} activate the
+mark.  To do that, specify @code{t} for the argument @var{activate}.
+
+A @samp{Mark set} message is displayed unless @var{nomsg} is
+non-@code{nil}.
+@end defun
+
+@defun pop-mark
+This function pops off the top element of @code{mark-ring} and makes
+that mark become the buffer's actual mark.  This does not move point in
+the buffer, and it does nothing if @code{mark-ring} is empty.  It
+deactivates the mark.
+
+The return value is not meaningful.
+@end defun
+
+@defopt transient-mark-mode
+@c  @cindex Transient Mark mode  Redundant
+This variable if non-@code{nil} enables Transient Mark mode, in which
+every buffer-modifying primitive sets @code{deactivate-mark}.  The
+consequence of this is that commands that modify the buffer normally
+make the mark inactive.
+
+Lisp programs can set @code{transient-mark-mode} to @code{only} to
+enable Transient Mark mode for the following command only.  During
+that following command, the value of @code{transient-mark-mode} is
+@code{identity}.  If it is still @code{identity} at the end of the
+command, it changes to @code{nil}.
+@end defopt
+
+@defopt mark-even-if-inactive
+If this is non-@code{nil}, Lisp programs and the Emacs user can use the
+mark even when it is inactive.  This option affects the behavior of
+Transient Mark mode.  When the option is non-@code{nil}, deactivation of
+the mark turns off region highlighting, but commands that use the mark
+behave as if the mark were still active.
+@end defopt
+
+@defvar deactivate-mark
+If an editor command sets this variable non-@code{nil}, then the editor
+command loop deactivates the mark after the command returns (if
+Transient Mark mode is enabled).  All the primitives that change the
+buffer set @code{deactivate-mark}, to deactivate the mark when the
+command is finished.
+
+To write Lisp code that modifies the buffer without causing
+deactivation of the mark at the end of the command, bind
+@code{deactivate-mark} to @code{nil} around the code that does the
+modification.  For example:
+
+@example
+(let (deactivate-mark)
+  (insert " "))
+@end example
+@end defvar
+
+@defun deactivate-mark
+This function deactivates the mark, if Transient Mark mode is enabled.
+Otherwise it does nothing.
+@end defun
+
+@defvar mark-active
+The mark is active when this variable is non-@code{nil}.  This variable
+is always buffer-local in each buffer.
+@end defvar
+
+@defvar activate-mark-hook
+@defvarx deactivate-mark-hook
+These normal hooks are run, respectively, when the mark becomes active
+and when it becomes inactive.  The hook @code{activate-mark-hook} is
+also run at the end of a command if the mark is active and it is
+possible that the region may have changed.
+@end defvar
+
+@defvar mark-ring
+The value of this buffer-local variable is the list of saved former
+marks of the current buffer, most recent first.
+
+@example
+@group
+mark-ring
+@result{} (#<marker at 11050 in markers.texi>
+    #<marker at 10832 in markers.texi>
+    @dots{})
+@end group
+@end example
+@end defvar
+
+@defopt mark-ring-max
+The value of this variable is the maximum size of @code{mark-ring}.  If
+more marks than this are pushed onto the @code{mark-ring},
+@code{push-mark} discards an old mark when it adds a new one.
+@end defopt
+
+@node The Region
+@section The Region
+@cindex region (between point and mark)
+
+  The text between point and the mark is known as @dfn{the region}.
+Various functions operate on text delimited by point and the mark, but
+only those functions specifically related to the region itself are
+described here.
+
+The next two functions signal an error if the mark does not point
+anywhere.  If Transient Mark mode is enabled and
+@code{mark-even-if-inactive} is @code{nil}, they also signal an error
+if the mark is inactive.
+
+@defun region-beginning
+This function returns the position of the beginning of the region (as
+an integer).  This is the position of either point or the mark,
+whichever is smaller.
+@end defun
+
+@defun region-end
+This function returns the position of the end of the region (as an
+integer).  This is the position of either point or the mark, whichever is
+larger.
+@end defun
+
+  Few programs need to use the @code{region-beginning} and
+@code{region-end} functions.  A command designed to operate on a region
+should normally use @code{interactive} with the @samp{r} specification
+to find the beginning and end of the region.  This lets other Lisp
+programs specify the bounds explicitly as arguments.  (@xref{Interactive
+Codes}.)
+
+@ignore
+   arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
+@end ignore
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
new file mode 100644
index 00000000000..98901df87f8
--- /dev/null
+++ b/doc/lispref/minibuf.texi
@@ -0,0 +1,1964 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/minibuf
+@node Minibuffers, Command Loop, Read and Print, Top
+@chapter Minibuffers
+@cindex arguments, reading
+@cindex complex arguments
+@cindex minibuffer
+
+  A @dfn{minibuffer} is a special buffer that Emacs commands use to
+read arguments more complicated than the single numeric prefix
+argument.  These arguments include file names, buffer names, and
+command names (as in @kbd{M-x}).  The minibuffer is displayed on the
+bottom line of the frame, in the same place as the echo area
+(@pxref{The Echo Area}), but only while it is in use for reading an
+argument.
+
+@menu
+* Intro to Minibuffers::      Basic information about minibuffers.
+* Text from Minibuffer::      How to read a straight text string.
+* Object from Minibuffer::    How to read a Lisp object or expression.
+* Minibuffer History::	      Recording previous minibuffer inputs
+				so the user can reuse them.
+* Initial Input::             Specifying initial contents for the minibuffer.
+* Completion::                How to invoke and customize completion.
+* Yes-or-No Queries::         Asking a question with a simple answer.
+* Multiple Queries::	      Asking a series of similar questions.
+* Reading a Password::	      Reading a password from the terminal.
+* Minibuffer Commands::       Commands used as key bindings in minibuffers.
+* Minibuffer Contents::       How such commands access the minibuffer text.
+* Minibuffer Windows::        Operating on the special minibuffer windows.
+* Recursive Mini::            Whether recursive entry to minibuffer is allowed.
+* Minibuffer Misc::           Various customization hooks and variables.
+@end menu
+
+@node Intro to Minibuffers
+@section Introduction to Minibuffers
+
+  In most ways, a minibuffer is a normal Emacs buffer.  Most operations
+@emph{within} a buffer, such as editing commands, work normally in a
+minibuffer.  However, many operations for managing buffers do not apply
+to minibuffers.  The name of a minibuffer always has the form @w{@samp{
+*Minibuf-@var{number}*}}, and it cannot be changed.  Minibuffers are
+displayed only in special windows used only for minibuffers; these
+windows always appear at the bottom of a frame.  (Sometimes frames have
+no minibuffer window, and sometimes a special kind of frame contains
+nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
+
+  The text in the minibuffer always starts with the @dfn{prompt string},
+the text that was specified by the program that is using the minibuffer
+to tell the user what sort of input to type.  This text is marked
+read-only so you won't accidentally delete or change it.  It is also
+marked as a field (@pxref{Fields}), so that certain motion functions,
+including @code{beginning-of-line}, @code{forward-word},
+@code{forward-sentence}, and @code{forward-paragraph}, stop at the
+boundary between the prompt and the actual text.  (In older Emacs
+versions, the prompt was displayed using a special mechanism and was not
+part of the buffer contents.)
+
+  The minibuffer's window is normally a single line; it grows
+automatically if necessary if the contents require more space.  You can
+explicitly resize it temporarily with the window sizing commands; it
+reverts to its normal size when the minibuffer is exited.  You can
+resize it permanently by using the window sizing commands in the frame's
+other window, when the minibuffer is not active.  If the frame contains
+just a minibuffer, you can change the minibuffer's size by changing the
+frame's size.
+
+  Use of the minibuffer reads input events, and that alters the values
+of variables such as @code{this-command} and @code{last-command}
+(@pxref{Command Loop Info}).  Your program should bind them around the
+code that uses the minibuffer, if you do not want that to change them.
+
+  If a command uses a minibuffer while there is an active minibuffer,
+this is called a @dfn{recursive minibuffer}.  The first minibuffer is
+named @w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
+incrementing the number at the end of the name.  (The names begin with a
+space so that they won't show up in normal buffer lists.)  Of several
+recursive minibuffers, the innermost (or most recently entered) is the
+active minibuffer.  We usually call this ``the'' minibuffer.  You can
+permit or forbid recursive minibuffers by setting the variable
+@code{enable-recursive-minibuffers} or by putting properties of that
+name on command symbols (@pxref{Recursive Mini}).
+
+  Like other buffers, a minibuffer uses a local keymap
+(@pxref{Keymaps}) to specify special key bindings.  The function that
+invokes the minibuffer also sets up its local map according to the job
+to be done.  @xref{Text from Minibuffer}, for the non-completion
+minibuffer local maps.  @xref{Completion Commands}, for the minibuffer
+local maps for completion.
+
+  When Emacs is running in batch mode, any request to read from the
+minibuffer actually reads a line from the standard input descriptor that
+was supplied when Emacs was started.
+
+@node Text from Minibuffer
+@section Reading Text Strings with the Minibuffer
+
+  Most often, the minibuffer is used to read text as a string.  It can
+also be used to read a Lisp object in textual form.  The most basic
+primitive for minibuffer input is @code{read-from-minibuffer}; it can do
+either one.  There are also specialized commands for reading
+commands, variables, file names, etc. (@pxref{Completion}).
+
+  In most cases, you should not call minibuffer input functions in the
+middle of a Lisp function.  Instead, do all minibuffer input as part of
+reading the arguments for a command, in the @code{interactive}
+specification.  @xref{Defining Commands}.
+
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
+This function is the most general way to get input through the
+minibuffer.  By default, it accepts arbitrary text and returns it as a
+string; however, if @var{read} is non-@code{nil}, then it uses
+@code{read} to convert the text into a Lisp object (@pxref{Input
+Functions}).
+
+The first thing this function does is to activate a minibuffer and
+display it with @var{prompt-string} as the prompt.  This value must be a
+string.  Then the user can edit text in the minibuffer.
+
+When the user types a command to exit the minibuffer,
+@code{read-from-minibuffer} constructs the return value from the text in
+the minibuffer.  Normally it returns a string containing that text.
+However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
+reads the text and returns the resulting Lisp object, unevaluated.
+(@xref{Input Functions}, for information about reading.)
+
+The argument @var{default} specifies a default value to make available
+through the history commands.  It should be a string, or @code{nil}.
+If non-@code{nil}, the user can access it using
+@code{next-history-element}, usually bound in the minibuffer to
+@kbd{M-n}.  If @var{read} is non-@code{nil}, then @var{default} is
+also used as the input to @code{read}, if the user enters empty input.
+(If @var{read} is non-@code{nil} and @var{default} is @code{nil}, empty
+input results in an @code{end-of-file} error.)  However, in the usual
+case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
+ignores @var{default} when the user enters empty input and returns an
+empty string, @code{""}.  In this respect, it is different from all
+the other minibuffer input functions in this chapter.
+
+If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
+use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
+value of @code{minibuffer-local-map} is used as the keymap.  Specifying
+a keymap is the most important way to customize the minibuffer for
+various applications such as completion.
+
+The argument @var{hist} specifies which history list variable to use
+for saving the input and for history commands used in the minibuffer.
+It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.
+
+If the variable @code{minibuffer-allow-text-properties} is
+non-@code{nil}, then the string which is returned includes whatever text
+properties were present in the minibuffer.  Otherwise all the text
+properties are stripped when the value is returned.
+
+If the argument @var{inherit-input-method} is non-@code{nil}, then the
+minibuffer inherits the current input method (@pxref{Input Methods}) and
+the setting of @code{enable-multibyte-characters} (@pxref{Text
+Representations}) from whichever buffer was current before entering the
+minibuffer.
+
+Use of @var{initial-contents} is mostly deprecated; we recommend using
+a non-@code{nil} value only in conjunction with specifying a cons cell
+for @var{hist}.  @xref{Initial Input}.
+@end defun
+
+@defun read-string prompt &optional initial history default inherit-input-method
+This function reads a string from the minibuffer and returns it.  The
+arguments @var{prompt}, @var{initial}, @var{history} and
+@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
+The keymap used is @code{minibuffer-local-map}.
+
+The optional argument @var{default} is used as in
+@code{read-from-minibuffer}, except that, if non-@code{nil}, it also
+specifies a default value to return if the user enters null input.  As
+in @code{read-from-minibuffer} it should be a string, or @code{nil},
+which is equivalent to an empty string.
+
+This function is a simplified interface to the
+@code{read-from-minibuffer} function:
+
+@smallexample
+@group
+(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
+@equiv{}
+(let ((value
+       (read-from-minibuffer @var{prompt} @var{initial} nil nil
+                             @var{history} @var{default} @var{inherit})))
+  (if (and (equal value "") @var{default})
+      @var{default}
+    value))
+@end group
+@end smallexample
+@end defun
+
+@defvar minibuffer-allow-text-properties
+If this variable is @code{nil}, then @code{read-from-minibuffer} strips
+all text properties from the minibuffer input before returning it.
+This variable also affects @code{read-string}.  However,
+@code{read-no-blanks-input} (see below), as well as
+@code{read-minibuffer} and related functions (@pxref{Object from
+Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
+functions that do minibuffer input with completion, discard text
+properties unconditionally, regardless of the value of this variable.
+@end defvar
+
+@defvar minibuffer-local-map
+This
+@anchor{Definition of minibuffer-local-map}
+@c avoid page break at anchor; work around Texinfo deficiency
+is the default local keymap for reading from the minibuffer.  By
+default, it makes the following bindings:
+
+@table @asis
+@item @kbd{C-j}
+@code{exit-minibuffer}
+
+@item @key{RET}
+@code{exit-minibuffer}
+
+@item @kbd{C-g}
+@code{abort-recursive-edit}
+
+@item @kbd{M-n}
+@itemx @key{DOWN}
+@code{next-history-element}
+
+@item @kbd{M-p}
+@itemx @key{UP}
+@code{previous-history-element}
+
+@item @kbd{M-s}
+@code{next-matching-history-element}
+
+@item @kbd{M-r}
+@code{previous-matching-history-element}
+@end table
+@end defvar
+
+@c In version 18, initial is required
+@c Emacs 19 feature
+@defun read-no-blanks-input prompt &optional initial inherit-input-method
+This function reads a string from the minibuffer, but does not allow
+whitespace characters as part of the input: instead, those characters
+terminate the input.  The arguments @var{prompt}, @var{initial}, and
+@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
+
+This is a simplified interface to the @code{read-from-minibuffer}
+function, and passes the value of the @code{minibuffer-local-ns-map}
+keymap as the @var{keymap} argument for that function.  Since the keymap
+@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
+possible to put a space into the string, by quoting it.
+
+This function discards text properties, regardless of the value of
+@code{minibuffer-allow-text-properties}.
+
+@smallexample
+@group
+(read-no-blanks-input @var{prompt} @var{initial})
+@equiv{}
+(let (minibuffer-allow-text-properties)
+  (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
+@end group
+@end smallexample
+@end defun
+
+@defvar minibuffer-local-ns-map
+This built-in variable is the keymap used as the minibuffer local keymap
+in the function @code{read-no-blanks-input}.  By default, it makes the
+following bindings, in addition to those of @code{minibuffer-local-map}:
+
+@table @asis
+@item @key{SPC}
+@cindex @key{SPC} in minibuffer
+@code{exit-minibuffer}
+
+@item @key{TAB}
+@cindex @key{TAB} in minibuffer
+@code{exit-minibuffer}
+
+@item @kbd{?}
+@cindex @kbd{?} in minibuffer
+@code{self-insert-and-exit}
+@end table
+@end defvar
+
+@node Object from Minibuffer
+@section Reading Lisp Objects with the Minibuffer
+
+  This section describes functions for reading Lisp objects with the
+minibuffer.
+
+@defun read-minibuffer prompt &optional initial
+This function reads a Lisp object using the minibuffer, and returns it
+without evaluating it.  The arguments @var{prompt} and @var{initial} are
+used as in @code{read-from-minibuffer}.
+
+This is a simplified interface to the
+@code{read-from-minibuffer} function:
+
+@smallexample
+@group
+(read-minibuffer @var{prompt} @var{initial})
+@equiv{}
+(let (minibuffer-allow-text-properties)
+  (read-from-minibuffer @var{prompt} @var{initial} nil t))
+@end group
+@end smallexample
+
+Here is an example in which we supply the string @code{"(testing)"} as
+initial input:
+
+@smallexample
+@group
+(read-minibuffer
+ "Enter an expression: " (format "%s" '(testing)))
+
+;; @r{Here is how the minibuffer is displayed:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Enter an expression: (testing)@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+The user can type @key{RET} immediately to use the initial input as a
+default, or can edit the input.
+@end defun
+
+@defun eval-minibuffer prompt &optional initial
+This function reads a Lisp expression using the minibuffer, evaluates
+it, then returns the result.  The arguments @var{prompt} and
+@var{initial} are used as in @code{read-from-minibuffer}.
+
+This function simply evaluates the result of a call to
+@code{read-minibuffer}:
+
+@smallexample
+@group
+(eval-minibuffer @var{prompt} @var{initial})
+@equiv{}
+(eval (read-minibuffer @var{prompt} @var{initial}))
+@end group
+@end smallexample
+@end defun
+
+@defun edit-and-eval-command prompt form
+This function reads a Lisp expression in the minibuffer, and then
+evaluates it.  The difference between this command and
+@code{eval-minibuffer} is that here the initial @var{form} is not
+optional and it is treated as a Lisp object to be converted to printed
+representation rather than as a string of text.  It is printed with
+@code{prin1}, so if it is a string, double-quote characters (@samp{"})
+appear in the initial text.  @xref{Output Functions}.
+
+The first thing @code{edit-and-eval-command} does is to activate the
+minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
+representation of @var{form} in the minibuffer, and lets the user edit it.
+When the user exits the minibuffer, the edited text is read with
+@code{read} and then evaluated.  The resulting value becomes the value
+of @code{edit-and-eval-command}.
+
+In the following example, we offer the user an expression with initial
+text which is a valid form already:
+
+@smallexample
+@group
+(edit-and-eval-command "Please edit: " '(forward-word 1))
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following appears in the minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Please edit: (forward-word 1)@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+Typing @key{RET} right away would exit the minibuffer and evaluate the
+expression, thus moving point forward one word.
+@code{edit-and-eval-command} returns @code{nil} in this example.
+@end defun
+
+@node Minibuffer History
+@section Minibuffer History
+@cindex minibuffer history
+@cindex history list
+
+  A @dfn{minibuffer history list} records previous minibuffer inputs so
+the user can reuse them conveniently.  A history list is actually a
+symbol, not a list; it is a variable whose value is a list of strings
+(previous inputs), most recent first.
+
+  There are many separate history lists, used for different kinds of
+inputs.  It's the Lisp programmer's job to specify the right history
+list for each use of the minibuffer.
+
+  You specify the history list with the optional @var{hist} argument
+to either @code{read-from-minibuffer} or @code{completing-read}.  Here
+are the possible values for it:
+
+@table @asis
+@item @var{variable}
+Use @var{variable} (a symbol) as the history list.
+
+@item (@var{variable} . @var{startpos})
+Use @var{variable} (a symbol) as the history list, and assume that the
+initial history position is @var{startpos} (a nonnegative integer).
+
+Specifying 0 for @var{startpos} is equivalent to just specifying the
+symbol @var{variable}.  @code{previous-history-element} will display
+the most recent element of the history list in the minibuffer.  If you
+specify a positive @var{startpos}, the minibuffer history functions
+behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
+history element currently shown in the minibuffer.
+
+For consistency, you should also specify that element of the history
+as the initial minibuffer contents, using the @var{initial} argument
+to the minibuffer input function (@pxref{Initial Input}).
+@end table
+
+  If you don't specify @var{hist}, then the default history list
+@code{minibuffer-history} is used.  For other standard history lists,
+see below.  You can also create your own history list variable; just
+initialize it to @code{nil} before the first use.
+
+  Both @code{read-from-minibuffer} and @code{completing-read} add new
+elements to the history list automatically, and provide commands to
+allow the user to reuse items on the list.  The only thing your program
+needs to do to use a history list is to initialize it and to pass its
+name to the input functions when you wish.  But it is safe to modify the
+list by hand when the minibuffer input functions are not using it.
+
+  Emacs functions that add a new element to a history list can also
+delete old elements if the list gets too long.  The variable
+@code{history-length} specifies the maximum length for most history
+lists.  To specify a different maximum length for a particular history
+list, put the length in the @code{history-length} property of the
+history list symbol.  The variable @code{history-delete-duplicates}
+specifies whether to delete duplicates in history.
+
+@defun add-to-history history-var newelt &optional maxelt keep-all
+This function adds a new element @var{newelt}, if it isn't the empty
+string, to the history list stored in the variable @var{history-var},
+and returns the updated history list.  It limits the list length to
+the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
+(described below).  The possible values of @var{maxelt} have the same
+meaning as the values of @code{history-length}.
+
+Normally, @code{add-to-history} removes duplicate members from the
+history list if @code{history-delete-duplicates} is non-@code{nil}.
+However, if @var{keep-all} is non-@code{nil}, that says not to remove
+duplicates, and to add @var{newelt} to the list even if it is empty.
+@end defun
+
+@defvar history-add-new-input
+If the value of this variable is @code{nil}, standard functions that
+read from the minibuffer don't add new elements to the history list.
+This lets Lisp programs explicitly manage input history by using
+@code{add-to-history}.  By default, @code{history-add-new-input} is
+set to a non-@code{nil} value.
+@end defvar
+
+@defvar history-length
+The value of this variable specifies the maximum length for all
+history lists that don't specify their own maximum lengths.  If the
+value is @code{t}, that means there no maximum (don't delete old
+elements).  The value of @code{history-length} property of the history
+list variable's symbol, if set, overrides this variable for that
+particular history list.
+@end defvar
+
+@defvar history-delete-duplicates
+If the value of this variable is @code{t}, that means when adding a
+new history element, all previous identical elements are deleted.
+@end defvar
+
+  Here are some of the standard minibuffer history list variables:
+
+@defvar minibuffer-history
+The default history list for minibuffer history input.
+@end defvar
+
+@defvar query-replace-history
+A history list for arguments to @code{query-replace} (and similar
+arguments to other commands).
+@end defvar
+
+@defvar file-name-history
+A history list for file-name arguments.
+@end defvar
+
+@defvar buffer-name-history
+A history list for buffer-name arguments.
+@end defvar
+
+@defvar regexp-history
+A history list for regular expression arguments.
+@end defvar
+
+@defvar extended-command-history
+A history list for arguments that are names of extended commands.
+@end defvar
+
+@defvar shell-command-history
+A history list for arguments that are shell commands.
+@end defvar
+
+@defvar read-expression-history
+A history list for arguments that are Lisp expressions to evaluate.
+@end defvar
+
+@node Initial Input
+@section Initial Input
+
+Several of the functions for minibuffer input have an argument called
+@var{initial} or @var{initial-contents}.  This is a mostly-deprecated
+feature for specifying that the minibuffer should start out with
+certain text, instead of empty as usual.
+
+If @var{initial} is a string, the minibuffer starts out containing the
+text of the string, with point at the end, when the user starts to
+edit the text.  If the user simply types @key{RET} to exit the
+minibuffer, it will use the initial input string to determine the
+value to return.
+
+@strong{We discourage use of a non-@code{nil} value for
+@var{initial}}, because initial input is an intrusive interface.
+History lists and default values provide a much more convenient method
+to offer useful default inputs to the user.
+
+There is just one situation where you should specify a string for an
+@var{initial} argument.  This is when you specify a cons cell for the
+@var{hist} or @var{history} argument.  @xref{Minibuffer History}.
+
+@var{initial} can also be a cons cell of the form @code{(@var{string}
+. @var{position})}.  This means to insert @var{string} in the
+minibuffer but put point at @var{position} within the string's text.
+
+As a historical accident, @var{position} was implemented
+inconsistently in different functions.  In @code{completing-read},
+@var{position}'s value is interpreted as origin-zero; that is, a value
+of 0 means the beginning of the string, 1 means after the first
+character, etc.  In @code{read-minibuffer}, and the other
+non-completion minibuffer input functions that support this argument,
+1 means the beginning of the string 2 means after the first character,
+etc.
+
+Use of a cons cell as the value for @var{initial} arguments is
+deprecated in user code.
+
+@node Completion
+@section Completion
+@cindex completion
+
+  @dfn{Completion} is a feature that fills in the rest of a name
+starting from an abbreviation for it.  Completion works by comparing the
+user's input against a list of valid names and determining how much of
+the name is determined uniquely by what the user has typed.  For
+example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
+type the first few letters of the name of the buffer to which you wish
+to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
+extends the name as far as it can.
+
+  Standard Emacs commands offer completion for names of symbols, files,
+buffers, and processes; with the functions in this section, you can
+implement completion for other kinds of names.
+
+  The @code{try-completion} function is the basic primitive for
+completion: it returns the longest determined completion of a given
+initial string, with a given set of strings to match against.
+
+  The function @code{completing-read} provides a higher-level interface
+for completion.  A call to @code{completing-read} specifies how to
+determine the list of valid names.  The function then activates the
+minibuffer with a local keymap that binds a few keys to commands useful
+for completion.  Other functions provide convenient simple interfaces
+for reading certain kinds of names with completion.
+
+@menu
+* Basic Completion::       Low-level functions for completing strings.
+                             (These are too low level to use the minibuffer.)
+* Minibuffer Completion::  Invoking the minibuffer with completion.
+* Completion Commands::    Minibuffer commands that do completion.
+* High-Level Completion::  Convenient special cases of completion
+                             (reading buffer name, file name, etc.)
+* Reading File Names::     Using completion to read file names.
+* Programmed Completion::  Writing your own completion-function.
+@end menu
+
+@node Basic Completion
+@subsection Basic Completion Functions
+
+  The completion functions @code{try-completion},
+@code{all-completions} and @code{test-completion} have nothing in
+themselves to do with minibuffers.  We describe them in this chapter
+so as to keep them near the higher-level completion features that do
+use the minibuffer.
+
+  If you store a completion alist in a variable, you should mark the
+variable as ``risky'' with a non-@code{nil}
+@code{risky-local-variable} property.
+
+@defun try-completion string collection &optional predicate
+This function returns the longest common substring of all possible
+completions of @var{string} in @var{collection}.  The value of
+@var{collection} must be a list of strings or symbols, an alist, an
+obarray, a hash table, or a function that implements a virtual set of
+strings (see below).
+
+Completion compares @var{string} against each of the permissible
+completions specified by @var{collection}; if the beginning of the
+permissible completion equals @var{string}, it matches.  If no permissible
+completions match, @code{try-completion} returns @code{nil}.  If only
+one permissible completion matches, and the match is exact, then
+@code{try-completion} returns @code{t}.  Otherwise, the value is the
+longest initial sequence common to all the permissible completions that
+match.
+
+If @var{collection} is an alist (@pxref{Association Lists}), the
+permissible completions are the elements of the alist that are either
+strings, symbols, or conses whose @sc{car} is a string or symbol.
+Symbols are converted to strings using @code{symbol-name}.  Other
+elements of the alist are ignored. (Remember that in Emacs Lisp, the
+elements of alists do not @emph{have} to be conses.)  In particular, a
+list of strings or symbols is allowed, even though we usually do not
+think of such lists as alists.
+
+@cindex obarray in completion
+If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
+of all symbols in the obarray form the set of permissible completions.  The
+global variable @code{obarray} holds an obarray containing the names of
+all interned Lisp symbols.
+
+Note that the only valid way to make a new obarray is to create it
+empty and then add symbols to it one by one using @code{intern}.
+Also, you cannot intern a given symbol in more than one obarray.
+
+If @var{collection} is a hash table, then the keys that are strings
+are the possible completions.  Other keys are ignored.
+
+You can also use a symbol that is a function as @var{collection}.  Then
+the function is solely responsible for performing completion;
+@code{try-completion} returns whatever this function returns.  The
+function is called with three arguments: @var{string}, @var{predicate}
+and @code{nil}.  (The reason for the third argument is so that the same
+function can be used in @code{all-completions} and do the appropriate
+thing in either case.)  @xref{Programmed Completion}.
+
+If the argument @var{predicate} is non-@code{nil}, then it must be a
+function of one argument, unless @var{collection} is a hash table, in
+which case it should be a function of two arguments.  It is used to
+test each possible match, and the match is accepted only if
+@var{predicate} returns non-@code{nil}.  The argument given to
+@var{predicate} is either a string or a cons cell (the @sc{car} of
+which is a string) from the alist, or a symbol (@emph{not} a symbol
+name) from the obarray.  If @var{collection} is a hash table,
+@var{predicate} is called with two arguments, the string key and the
+associated value.
+
+In addition, to be acceptable, a completion must also match all the
+regular expressions in @code{completion-regexp-list}.  (Unless
+@var{collection} is a function, in which case that function has to
+handle @code{completion-regexp-list} itself.)
+
+In the first of the following examples, the string @samp{foo} is
+matched by three of the alist @sc{car}s.  All of the matches begin with
+the characters @samp{fooba}, so that is the result.  In the second
+example, there is only one possible match, and it is exact, so the value
+is @code{t}.
+
+@smallexample
+@group
+(try-completion
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
+     @result{} "fooba"
+@end group
+
+@group
+(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
+     @result{} t
+@end group
+@end smallexample
+
+In the following example, numerous symbols begin with the characters
+@samp{forw}, and all of them begin with the word @samp{forward}.  In
+most of the symbols, this is followed with a @samp{-}, but not in all,
+so no more than @samp{forward} can be completed.
+
+@smallexample
+@group
+(try-completion "forw" obarray)
+     @result{} "forward"
+@end group
+@end smallexample
+
+Finally, in the following example, only two of the three possible
+matches pass the predicate @code{test} (the string @samp{foobaz} is
+too short).  Both of those begin with the string @samp{foobar}.
+
+@smallexample
+@group
+(defun test (s)
+  (> (length (car s)) 6))
+     @result{} test
+@end group
+@group
+(try-completion
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ 'test)
+     @result{} "foobar"
+@end group
+@end smallexample
+@end defun
+
+@defun all-completions string collection &optional predicate nospace
+This function returns a list of all possible completions of
+@var{string}.  The arguments to this function (aside from
+@var{nospace}) are the same as those of @code{try-completion}.  Also,
+this function uses @code{completion-regexp-list} in the same way that
+@code{try-completion} does.  The optional argument @var{nospace} only
+matters if @var{string} is the empty string.  In that case, if
+@var{nospace} is non-@code{nil}, completions that start with a space
+are ignored.
+
+If @var{collection} is a function, it is called with three arguments:
+@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
+returns whatever the function returns.  @xref{Programmed Completion}.
+
+Here is an example, using the function @code{test} shown in the
+example for @code{try-completion}:
+
+@smallexample
+@group
+(defun test (s)
+  (> (length (car s)) 6))
+     @result{} test
+@end group
+
+@group
+(all-completions
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ 'test)
+     @result{} ("foobar1" "foobar2")
+@end group
+@end smallexample
+@end defun
+
+@defun test-completion string collection &optional predicate
+@anchor{Definition of test-completion}
+This function returns non-@code{nil} if @var{string} is a valid
+completion possibility specified by @var{collection} and
+@var{predicate}.  The arguments are the same as in
+@code{try-completion}.  For instance, if @var{collection} is a list of
+strings, this is true if @var{string} appears in the list and
+@var{predicate} is satisfied.
+
+This function uses @code{completion-regexp-list} in the same
+way that @code{try-completion} does.
+
+If @var{predicate} is non-@code{nil} and if @var{collection} contains
+several strings that are equal to each other, as determined by
+@code{compare-strings} according to @code{completion-ignore-case},
+then @var{predicate} should accept either all or none of them.
+Otherwise, the return value of @code{test-completion} is essentially
+unpredictable.
+
+If @var{collection} is a function, it is called with three arguments,
+the values @var{string}, @var{predicate} and @code{lambda}; whatever
+it returns, @code{test-completion} returns in turn.
+@end defun
+
+@defvar completion-ignore-case
+If the value of this variable is non-@code{nil}, Emacs does not
+consider case significant in completion.
+@end defvar
+
+@defvar completion-regexp-list
+This is a list of regular expressions.  The completion functions only
+consider a completion acceptable if it matches all regular expressions
+in this list, with @code{case-fold-search} (@pxref{Searching and Case})
+bound to the value of @code{completion-ignore-case}.
+@end defvar
+
+@defmac lazy-completion-table var fun
+This macro provides a way to initialize the variable @var{var} as a
+collection for completion in a lazy way, not computing its actual
+contents until they are first needed.  You use this macro to produce a
+value that you store in @var{var}.  The actual computation of the
+proper value is done the first time you do completion using @var{var}.
+It is done by calling @var{fun} with no arguments.  The
+value @var{fun} returns becomes the permanent value of @var{var}.
+
+Here is an example of use:
+
+@smallexample
+(defvar foo (lazy-completion-table foo make-my-alist))
+@end smallexample
+@end defmac
+
+@node Minibuffer Completion
+@subsection Completion and the Minibuffer
+@cindex minibuffer completion
+@cindex reading from minibuffer with completion
+
+  This section describes the basic interface for reading from the
+minibuffer with completion.
+
+@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
+This function reads a string in the minibuffer, assisting the user by
+providing completion.  It activates the minibuffer with prompt
+@var{prompt}, which must be a string.
+
+The actual completion is done by passing @var{collection} and
+@var{predicate} to the function @code{try-completion}.  This happens
+in certain commands bound in the local keymaps used for completion.
+Some of these commands also call @code{test-completion}.  Thus, if
+@var{predicate} is non-@code{nil}, it should be compatible with
+@var{collection} and @code{completion-ignore-case}.  @xref{Definition
+of test-completion}.
+
+If @var{require-match} is @code{nil}, the exit commands work regardless
+of the input in the minibuffer.  If @var{require-match} is @code{t}, the
+usual minibuffer exit commands won't exit unless the input completes to
+an element of @var{collection}.  If @var{require-match} is neither
+@code{nil} nor @code{t}, then the exit commands won't exit unless the
+input already in the buffer matches an element of @var{collection}.
+
+However, empty input is always permitted, regardless of the value of
+@var{require-match}; in that case, @code{completing-read} returns
+@var{default}, or @code{""}, if @var{default} is @code{nil}.  The
+value of @var{default} (if non-@code{nil}) is also available to the
+user through the history commands.
+
+The function @code{completing-read} uses
+@code{minibuffer-local-completion-map} as the keymap if
+@var{require-match} is @code{nil}, and uses
+@code{minibuffer-local-must-match-map} if @var{require-match} is
+non-@code{nil}.  @xref{Completion Commands}.
+
+The argument @var{hist} specifies which history list variable to use for
+saving the input and for minibuffer history commands.  It defaults to
+@code{minibuffer-history}.  @xref{Minibuffer History}.
+
+The argument @var{initial} is mostly deprecated; we recommend using a
+non-@code{nil} value only in conjunction with specifying a cons cell
+for @var{hist}.  @xref{Initial Input}.  For default input, use
+@var{default} instead.
+
+If the argument @var{inherit-input-method} is non-@code{nil}, then the
+minibuffer inherits the current input method (@pxref{Input
+Methods}) and the setting of @code{enable-multibyte-characters}
+(@pxref{Text Representations}) from whichever buffer was current before
+entering the minibuffer.
+
+If the built-in variable @code{completion-ignore-case} is
+non-@code{nil}, completion ignores case when comparing the input
+against the possible matches.  @xref{Basic Completion}.  In this mode
+of operation, @var{predicate} must also ignore case, or you will get
+surprising results.
+
+Here's an example of using @code{completing-read}:
+
+@smallexample
+@group
+(completing-read
+ "Complete a foo: "
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ nil t "fo")
+@end group
+
+@group
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following appears in the minibuffer:}
+
+---------- Buffer: Minibuffer ----------
+Complete a foo: fo@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
+@code{completing-read} returns @code{barfoo}.
+
+The @code{completing-read} function binds variables to pass
+information to the commands that actually do completion.
+They are described in the following section.
+@end defun
+
+@node Completion Commands
+@subsection Minibuffer Commands that Do Completion
+
+  This section describes the keymaps, commands and user options used
+in the minibuffer to do completion.  The description refers to the
+situation when Partial Completion mode is disabled (as it is by
+default).  When enabled, this minor mode uses its own alternatives to
+some of the commands described below.  @xref{Completion Options,,,
+emacs, The GNU Emacs Manual}, for a short description of Partial
+Completion mode.
+
+@defvar minibuffer-completion-table
+The value of this variable is the collection used for completion in
+the minibuffer.  This is the global variable that contains what
+@code{completing-read} passes to @code{try-completion}.  It is used by
+minibuffer completion commands such as @code{minibuffer-complete-word}.
+@end defvar
+
+@defvar minibuffer-completion-predicate
+This variable's value is the predicate that @code{completing-read}
+passes to @code{try-completion}.  The variable is also used by the other
+minibuffer completion functions.
+@end defvar
+
+@defvar minibuffer-completion-confirm
+When the value of this variable is non-@code{nil}, Emacs asks for
+confirmation of a completion before exiting the minibuffer.
+@code{completing-read} binds this variable, and the function
+@code{minibuffer-complete-and-exit} checks the value before exiting.
+@end defvar
+
+@deffn Command minibuffer-complete-word
+This function completes the minibuffer contents by at most a single
+word.  Even if the minibuffer contents have only one completion,
+@code{minibuffer-complete-word} does not add any characters beyond the
+first character that is not a word constituent.  @xref{Syntax Tables}.
+@end deffn
+
+@deffn Command minibuffer-complete
+This function completes the minibuffer contents as far as possible.
+@end deffn
+
+@deffn Command minibuffer-complete-and-exit
+This function completes the minibuffer contents, and exits if
+confirmation is not required, i.e., if
+@code{minibuffer-completion-confirm} is @code{nil}.  If confirmation
+@emph{is} required, it is given by repeating this command
+immediately---the command is programmed to work without confirmation
+when run twice in succession.
+@end deffn
+
+@deffn Command minibuffer-completion-help
+This function creates a list of the possible completions of the
+current minibuffer contents.  It works by calling @code{all-completions}
+using the value of the variable @code{minibuffer-completion-table} as
+the @var{collection} argument, and the value of
+@code{minibuffer-completion-predicate} as the @var{predicate} argument.
+The list of completions is displayed as text in a buffer named
+@samp{*Completions*}.
+@end deffn
+
+@defun display-completion-list completions &optional common-substring
+This function displays @var{completions} to the stream in
+@code{standard-output}, usually a buffer.  (@xref{Read and Print}, for more
+information about streams.)  The argument @var{completions} is normally
+a list of completions just returned by @code{all-completions}, but it
+does not have to be.  Each element may be a symbol or a string, either
+of which is simply printed.  It can also be a list of two strings,
+which is printed as if the strings were concatenated.  The first of
+the two strings is the actual completion, the second string serves as
+annotation.
+
+The argument @var{common-substring} is the prefix that is common to
+all the completions.  With normal Emacs completion, it is usually the
+same as the string that was completed.  @code{display-completion-list}
+uses this to highlight text in the completion list for better visual
+feedback.  This is not needed in the minibuffer; for minibuffer
+completion, you can pass @code{nil}.
+
+This function is called by @code{minibuffer-completion-help}.  The
+most common way to use it is together with
+@code{with-output-to-temp-buffer}, like this:
+
+@example
+(with-output-to-temp-buffer "*Completions*"
+  (display-completion-list
+    (all-completions (buffer-string) my-alist)
+    (buffer-string)))
+@end example
+@end defun
+
+@defopt completion-auto-help
+If this variable is non-@code{nil}, the completion commands
+automatically display a list of possible completions whenever nothing
+can be completed because the next character is not uniquely determined.
+@end defopt
+
+@defvar minibuffer-local-completion-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is not required.  By default, this
+keymap makes the following bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}
+(@pxref{Definition of minibuffer-local-map}).
+@end defvar
+
+@defvar minibuffer-local-must-match-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is required.  Therefore, no keys
+are bound to @code{exit-minibuffer}, the command that exits the
+minibuffer unconditionally.  By default, this keymap makes the following
+bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+
+@item @kbd{C-j}
+@code{minibuffer-complete-and-exit}
+
+@item @key{RET}
+@code{minibuffer-complete-and-exit}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}.
+@end defvar
+
+@defvar minibuffer-local-filename-completion-map
+This is like @code{minibuffer-local-completion-map}
+except that it does not bind @key{SPC}.  This keymap is used by the
+function @code{read-file-name}.
+@end defvar
+
+@defvar minibuffer-local-must-match-filename-map
+This is like @code{minibuffer-local-must-match-map}
+except that it does not bind @key{SPC}.  This keymap is used by the
+function @code{read-file-name}.
+@end defvar
+
+@node High-Level Completion
+@subsection High-Level Completion  Functions
+
+  This section describes the higher-level convenient functions for
+reading certain sorts of names with completion.
+
+  In most cases, you should not call these functions in the middle of a
+Lisp function.  When possible, do all minibuffer input as part of
+reading the arguments for a command, in the @code{interactive}
+specification.  @xref{Defining Commands}.
+
+@defun read-buffer prompt &optional default existing
+This function reads the name of a buffer and returns it as a string.
+The argument @var{default} is the default name to use, the value to
+return if the user exits with an empty minibuffer.  If non-@code{nil},
+it should be a string or a buffer.  It is mentioned in the prompt, but
+is not inserted in the minibuffer as initial input.
+
+The argument @var{prompt} should be a string ending with a colon and a
+space.  If @var{default} is non-@code{nil}, the function inserts it in
+@var{prompt} before the colon to follow the convention for reading from
+the minibuffer with a default value (@pxref{Programming Tips}).
+
+If @var{existing} is non-@code{nil}, then the name specified must be
+that of an existing buffer.  The usual commands to exit the minibuffer
+do not exit if the text is not valid, and @key{RET} does completion to
+attempt to find a valid name.  If @var{existing} is neither @code{nil}
+nor @code{t}, confirmation is required after completion.  (However,
+@var{default} is not checked for validity; it is returned, whatever it
+is, if the user exits with the minibuffer empty.)
+
+In the following example, the user enters @samp{minibuffer.t}, and
+then types @key{RET}.  The argument @var{existing} is @code{t}, and the
+only buffer name starting with the given input is
+@samp{minibuffer.texi}, so that name is the value.
+
+@example
+(read-buffer "Buffer name: " "foo" t)
+@group
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears,}
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Buffer name (default foo): @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+
+@group
+;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
+     @result{} "minibuffer.texi"
+@end group
+@end example
+@end defun
+
+@defvar read-buffer-function
+This variable specifies how to read buffer names.  For example, if you
+set this variable to @code{iswitchb-read-buffer}, all Emacs commands
+that call @code{read-buffer} to read a buffer name will actually use the
+@code{iswitchb} package to read it.
+@end defvar
+
+@defun read-command prompt &optional default
+This function reads the name of a command and returns it as a Lisp
+symbol.  The argument @var{prompt} is used as in
+@code{read-from-minibuffer}.  Recall that a command is anything for
+which @code{commandp} returns @code{t}, and a command name is a symbol
+for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
+
+The argument @var{default} specifies what to return if the user enters
+null input.  It can be a symbol or a string; if it is a string,
+@code{read-command} interns it before returning it.  If @var{default} is
+@code{nil}, that means no default has been specified; then if the user
+enters null input, the return value is @code{(intern "")}, that is, a
+symbol whose name is an empty string.
+
+@example
+(read-command "Command name? ")
+
+@group
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Command name?
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+If the user types @kbd{forward-c @key{RET}}, then this function returns
+@code{forward-char}.
+
+The @code{read-command} function is a simplified interface to
+@code{completing-read}.  It uses the variable @code{obarray} so as to
+complete in the set of extant Lisp symbols, and it uses the
+@code{commandp} predicate so as to accept only command names:
+
+@cindex @code{commandp} example
+@example
+@group
+(read-command @var{prompt})
+@equiv{}
+(intern (completing-read @var{prompt} obarray
+                         'commandp t nil))
+@end group
+@end example
+@end defun
+
+@defun read-variable prompt &optional default
+@anchor{Definition of read-variable}
+This function reads the name of a user variable and returns it as a
+symbol.
+
+The argument @var{default} specifies what to return if the user enters
+null input.  It can be a symbol or a string; if it is a string,
+@code{read-variable} interns it before returning it.  If @var{default}
+is @code{nil}, that means no default has been specified; then if the
+user enters null input, the return value is @code{(intern "")}.
+
+@example
+@group
+(read-variable "Variable name? ")
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears,}
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Variable name? @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
+returns @code{fill-prefix}.
+
+In general, @code{read-variable} is similar to @code{read-command},
+but uses the predicate @code{user-variable-p} instead of
+@code{commandp}:
+
+@cindex @code{user-variable-p} example
+@example
+@group
+(read-variable @var{prompt})
+@equiv{}
+(intern
+ (completing-read @var{prompt} obarray
+                  'user-variable-p t nil))
+@end group
+@end example
+@end defun
+
+  See also the functions @code{read-coding-system} and
+@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
+and @code{read-input-method-name}, in @ref{Input Methods}.
+
+@node Reading File Names
+@subsection Reading File Names
+@cindex read file names
+@cindex prompt for file name
+
+  Here is another high-level completion function, designed for reading a
+file name.  It provides special features including automatic insertion
+of the default directory.
+
+@defun read-file-name prompt &optional directory default existing initial predicate
+This function reads a file name in the minibuffer, prompting with
+@var{prompt} and providing completion.
+
+If @var{existing} is non-@code{nil}, then the user must specify the name
+of an existing file; @key{RET} performs completion to make the name
+valid if possible, and then refuses to exit if it is not valid.  If the
+value of @var{existing} is neither @code{nil} nor @code{t}, then
+@key{RET} also requires confirmation after completion.  If
+@var{existing} is @code{nil}, then the name of a nonexistent file is
+acceptable.
+
+@code{read-file-name} uses
+@code{minibuffer-local-filename-completion-map} as the keymap if
+@var{existing} is @code{nil}, and uses
+@code{minibuffer-local-must-match-filename-map} if @var{existing} is
+non-@code{nil}.  @xref{Completion Commands}.
+
+The argument @var{directory} specifies the directory to use for
+completion of relative file names.  It should be an absolute directory
+name.  If @code{insert-default-directory} is non-@code{nil},
+@var{directory} is also inserted in the minibuffer as initial input.
+It defaults to the current buffer's value of @code{default-directory}.
+
+@c Emacs 19 feature
+If you specify @var{initial}, that is an initial file name to insert
+in the buffer (after @var{directory}, if that is inserted).  In this
+case, point goes at the beginning of @var{initial}.  The default for
+@var{initial} is @code{nil}---don't insert any file name.  To see what
+@var{initial} does, try the command @kbd{C-x C-v}.  @strong{Please
+note:} we recommend using @var{default} rather than @var{initial} in
+most cases.
+
+If @var{default} is non-@code{nil}, then the function returns
+@var{default} if the user exits the minibuffer with the same non-empty
+contents that @code{read-file-name} inserted initially.  The initial
+minibuffer contents are always non-empty if
+@code{insert-default-directory} is non-@code{nil}, as it is by
+default.  @var{default} is not checked for validity, regardless of the
+value of @var{existing}.  However, if @var{existing} is
+non-@code{nil}, the initial minibuffer contents should be a valid file
+(or directory) name.  Otherwise @code{read-file-name} attempts
+completion if the user exits without any editing, and does not return
+@var{default}.  @var{default} is also available through the history
+commands.
+
+If @var{default} is @code{nil}, @code{read-file-name} tries to find a
+substitute default to use in its place, which it treats in exactly the
+same way as if it had been specified explicitly.  If @var{default} is
+@code{nil}, but @var{initial} is non-@code{nil}, then the default is
+the absolute file name obtained from @var{directory} and
+@var{initial}.  If both @var{default} and @var{initial} are @code{nil}
+and the buffer is visiting a file, @code{read-file-name} uses the
+absolute file name of that file as default.  If the buffer is not
+visiting a file, then there is no default.  In that case, if the user
+types @key{RET} without any editing, @code{read-file-name} simply
+returns the pre-inserted contents of the minibuffer.
+
+If the user types @key{RET} in an empty minibuffer, this function
+returns an empty string, regardless of the value of @var{existing}.
+This is, for instance, how the user can make the current buffer visit
+no file using @code{M-x set-visited-file-name}.
+
+If @var{predicate} is non-@code{nil}, it specifies a function of one
+argument that decides which file names are acceptable completion
+possibilities.  A file name is an acceptable value if @var{predicate}
+returns non-@code{nil} for it.
+
+@code{read-file-name} does not automatically expand file names.  You
+must call @code{expand-file-name} yourself if an absolute file name is
+required.
+
+Here is an example:
+
+@example
+@group
+(read-file-name "The file is ")
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following appears in the minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is /gp/gnu/elisp/@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+Typing @kbd{manual @key{TAB}} results in the following:
+
+@example
+@group
+---------- Buffer: Minibuffer ----------
+The file is /gp/gnu/elisp/manual.texi@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@c Wordy to avoid overfull hbox in smallbook mode.
+@noindent
+If the user types @key{RET}, @code{read-file-name} returns the file name
+as the string @code{"/gp/gnu/elisp/manual.texi"}.
+@end defun
+
+@defvar read-file-name-function
+If non-@code{nil}, this should be a function that accepts the same
+arguments as @code{read-file-name}.  When @code{read-file-name} is
+called, it calls this function with the supplied arguments instead of
+doing its usual work.
+@end defvar
+
+@defvar read-file-name-completion-ignore-case
+If this variable is non-@code{nil}, @code{read-file-name} ignores case
+when performing completion.
+@end defvar
+
+@defun read-directory-name prompt &optional directory default existing initial
+This function is like @code{read-file-name} but allows only directory
+names as completion possibilities.
+
+If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
+@code{read-directory-name} constructs a substitute default by
+combining @var{directory} (or the current buffer's default directory
+if @var{directory} is @code{nil}) and @var{initial}.  If both
+@var{default} and @var{initial} are @code{nil}, this function uses
+@var{directory} as substitute default, or the current buffer's default
+directory if @var{directory} is @code{nil}.
+@end defun
+
+@defopt insert-default-directory
+This variable is used by @code{read-file-name}, and thus, indirectly,
+by most commands reading file names.  (This includes all commands that
+use the code letters @samp{f} or @samp{F} in their interactive form.
+@xref{Interactive Codes,, Code Characters for interactive}.)  Its
+value controls whether @code{read-file-name} starts by placing the
+name of the default directory in the minibuffer, plus the initial file
+name if any.  If the value of this variable is @code{nil}, then
+@code{read-file-name} does not place any initial input in the
+minibuffer (unless you specify initial input with the @var{initial}
+argument).  In that case, the default directory is still used for
+completion of relative file names, but is not displayed.
+
+If this variable is @code{nil} and the initial minibuffer contents are
+empty, the user may have to explicitly fetch the next history element
+to access a default value.  If the variable is non-@code{nil}, the
+initial minibuffer contents are always non-empty and the user can
+always request a default value by immediately typing @key{RET} in an
+unedited minibuffer.  (See above.)
+
+For example:
+
+@example
+@group
+;; @r{Here the minibuffer starts out with the default directory.}
+(let ((insert-default-directory t))
+  (read-file-name "The file is "))
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is ~lewis/manual/@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+
+@group
+;; @r{Here the minibuffer is empty and only the prompt}
+;;   @r{appears on its line.}
+(let ((insert-default-directory nil))
+  (read-file-name "The file is "))
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+@end defopt
+
+@node Programmed Completion
+@subsection Programmed Completion
+@cindex programmed completion
+
+  Sometimes it is not possible to create an alist or an obarray
+containing all the intended possible completions.  In such a case, you
+can supply your own function to compute the completion of a given string.
+This is called @dfn{programmed completion}.
+
+  To use this feature, pass a symbol with a function definition as the
+@var{collection} argument to @code{completing-read}.  The function
+@code{completing-read} arranges to pass your completion function along
+to @code{try-completion} and @code{all-completions}, which will then let
+your function do all the work.
+
+  The completion function should accept three arguments:
+
+@itemize @bullet
+@item
+The string to be completed.
+
+@item
+The predicate function to filter possible matches, or @code{nil} if
+none.  Your function should call the predicate for each possible match,
+and ignore the possible match if the predicate returns @code{nil}.
+
+@item
+A flag specifying the type of operation.
+@end itemize
+
+  There are three flag values for three operations:
+
+@itemize @bullet
+@item
+@code{nil} specifies @code{try-completion}.  The completion function
+should return the completion of the specified string, or @code{t} if the
+string is a unique and exact match already, or @code{nil} if the string
+matches no possibility.
+
+If the string is an exact match for one possibility, but also matches
+other longer possibilities, the function should return the string, not
+@code{t}.
+
+@item
+@code{t} specifies @code{all-completions}.  The completion function
+should return a list of all possible completions of the specified
+string.
+
+@item
+@code{lambda} specifies @code{test-completion}.  The completion
+function should return @code{t} if the specified string is an exact
+match for some possibility; @code{nil} otherwise.
+@end itemize
+
+  It would be consistent and clean for completion functions to allow
+lambda expressions (lists that are functions) as well as function
+symbols as @var{collection}, but this is impossible.  Lists as
+completion tables already have other meanings, and it would be
+unreliable to treat one differently just because it is also a possible
+function.  So you must arrange for any function you wish to use for
+completion to be encapsulated in a symbol.
+
+  Emacs uses programmed completion when completing file names.
+@xref{File Name Completion}.
+
+@defmac dynamic-completion-table function
+This macro is a convenient way to write a function that can act as
+programmed completion function.  The argument @var{function} should be
+a function that takes one argument, a string, and returns an alist of
+possible completions of it.  You can think of
+@code{dynamic-completion-table} as a transducer between that interface
+and the interface for programmed completion functions.
+@end defmac
+
+@node Yes-or-No Queries
+@section Yes-or-No Queries
+@cindex asking the user questions
+@cindex querying the user
+@cindex yes-or-no questions
+
+  This section describes functions used to ask the user a yes-or-no
+question.  The function @code{y-or-n-p} can be answered with a single
+character; it is useful for questions where an inadvertent wrong answer
+will not have serious consequences.  @code{yes-or-no-p} is suitable for
+more momentous questions, since it requires three or four characters to
+answer.
+
+   If either of these functions is called in a command that was invoked
+using the mouse---more precisely, if @code{last-nonmenu-event}
+(@pxref{Command Loop Info}) is either @code{nil} or a list---then it
+uses a dialog box or pop-up menu to ask the question.  Otherwise, it
+uses keyboard input.  You can force use of the mouse or use of keyboard
+input by binding @code{last-nonmenu-event} to a suitable value around
+the call.
+
+  Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
+@code{y-or-n-p} does not; but it seems best to describe them together.
+
+@defun y-or-n-p prompt
+This function asks the user a question, expecting input in the echo
+area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
+user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
+and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit,'' like
+@kbd{C-g}, because the question might look like a minibuffer and for
+that reason the user might try to use @kbd{C-]} to get out.  The answer
+is a single character, with no @key{RET} needed to terminate it.  Upper
+and lower case are equivalent.
+
+``Asking the question'' means printing @var{prompt} in the echo area,
+followed by the string @w{@samp{(y or n) }}.  If the input is not one of
+the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
+@kbd{@key{DEL}}, or something that quits), the function responds
+@samp{Please answer y or n.}, and repeats the request.
+
+This function does not actually use the minibuffer, since it does not
+allow editing of the answer.  It actually uses the echo area (@pxref{The
+Echo Area}), which uses the same screen space as the minibuffer.  The
+cursor moves to the echo area while the question is being asked.
+
+The answers and their meanings, even @samp{y} and @samp{n}, are not
+hardwired.  The keymap @code{query-replace-map} specifies them.
+@xref{Search and Replace}.
+
+In the following example, the user first types @kbd{q}, which is
+invalid.  At the next prompt the user types @kbd{y}.
+
+@smallexample
+@group
+(y-or-n-p "Do you need a lift? ")
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears in the echo area:}
+@end group
+
+@group
+---------- Echo area ----------
+Do you need a lift? (y or n)
+---------- Echo area ----------
+@end group
+
+;; @r{If the user then types @kbd{q}, the following appears:}
+
+@group
+---------- Echo area ----------
+Please answer y or n.  Do you need a lift? (y or n)
+---------- Echo area ----------
+@end group
+
+;; @r{When the user types a valid answer,}
+;;   @r{it is displayed after the question:}
+
+@group
+---------- Echo area ----------
+Do you need a lift? (y or n) y
+---------- Echo area ----------
+@end group
+@end smallexample
+
+@noindent
+We show successive lines of echo area messages, but only one actually
+appears on the screen at a time.
+@end defun
+
+@defun y-or-n-p-with-timeout prompt seconds default-value
+Like @code{y-or-n-p}, except that if the user fails to answer within
+@var{seconds} seconds, this function stops waiting and returns
+@var{default-value}.  It works by setting up a timer; see @ref{Timers}.
+The argument @var{seconds} may be an integer or a floating point number.
+@end defun
+
+@defun yes-or-no-p prompt
+This function asks the user a question, expecting input in the
+minibuffer.  It returns @code{t} if the user enters @samp{yes},
+@code{nil} if the user types @samp{no}.  The user must type @key{RET} to
+finalize the response.  Upper and lower case are equivalent.
+
+@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
+followed by @w{@samp{(yes or no) }}.  The user must type one of the
+expected responses; otherwise, the function responds @samp{Please answer
+yes or no.}, waits about two seconds and repeats the request.
+
+@code{yes-or-no-p} requires more work from the user than
+@code{y-or-n-p} and is appropriate for more crucial decisions.
+
+Here is an example:
+
+@smallexample
+@group
+(yes-or-no-p "Do you really want to remove everything? ")
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears,}
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: minibuffer ----------
+Do you really want to remove everything? (yes or no)
+---------- Buffer: minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+If the user first types @kbd{y @key{RET}}, which is invalid because this
+function demands the entire word @samp{yes}, it responds by displaying
+these prompts, with a brief pause between them:
+
+@smallexample
+@group
+---------- Buffer: minibuffer ----------
+Please answer yes or no.
+Do you really want to remove everything? (yes or no)
+---------- Buffer: minibuffer ----------
+@end group
+@end smallexample
+@end defun
+
+@node Multiple Queries
+@section Asking Multiple Y-or-N Questions
+
+  When you have a series of similar questions to ask, such as ``Do you
+want to save this buffer'' for each buffer in turn, you should use
+@code{map-y-or-n-p} to ask the collection of questions, rather than
+asking each question individually.  This gives the user certain
+convenient facilities such as the ability to answer the whole series at
+once.
+
+@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
+This function asks the user a series of questions, reading a
+single-character answer in the echo area for each one.
+
+The value of @var{list} specifies the objects to ask questions about.
+It should be either a list of objects or a generator function.  If it is
+a function, it should expect no arguments, and should return either the
+next object to ask about, or @code{nil} meaning stop asking questions.
+
+The argument @var{prompter} specifies how to ask each question.  If
+@var{prompter} is a string, the question text is computed like this:
+
+@example
+(format @var{prompter} @var{object})
+@end example
+
+@noindent
+where @var{object} is the next object to ask about (as obtained from
+@var{list}).
+
+If not a string, @var{prompter} should be a function of one argument
+(the next object to ask about) and should return the question text.  If
+the value is a string, that is the question to ask the user.  The
+function can also return @code{t} meaning do act on this object (and
+don't ask the user), or @code{nil} meaning ignore this object (and don't
+ask the user).
+
+The argument @var{actor} says how to act on the answers that the user
+gives.  It should be a function of one argument, and it is called with
+each object that the user says yes for.  Its argument is always an
+object obtained from @var{list}.
+
+If the argument @var{help} is given, it should be a list of this form:
+
+@example
+(@var{singular} @var{plural} @var{action})
+@end example
+
+@noindent
+where @var{singular} is a string containing a singular noun that
+describes the objects conceptually being acted on, @var{plural} is the
+corresponding plural noun, and @var{action} is a transitive verb
+describing what @var{actor} does.
+
+If you don't specify @var{help}, the default is @code{("object"
+"objects" "act on")}.
+
+Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
+@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
+that object; @kbd{!} to act on all following objects; @key{ESC} or
+@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
+the current object and then exit; or @kbd{C-h} to get help.  These are
+the same answers that @code{query-replace} accepts.  The keymap
+@code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
+as well as for @code{query-replace}; see @ref{Search and Replace}.
+
+You can use @var{action-alist} to specify additional possible answers
+and what they mean.  It is an alist of elements of the form
+@code{(@var{char} @var{function} @var{help})}, each of which defines one
+additional answer.  In this element, @var{char} is a character (the
+answer); @var{function} is a function of one argument (an object from
+@var{list}); @var{help} is a string.
+
+When the user responds with @var{char}, @code{map-y-or-n-p} calls
+@var{function}.  If it returns non-@code{nil}, the object is considered
+``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
+@var{list}.  If it returns @code{nil}, the prompt is repeated for the
+same object.
+
+Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
+prompting.  But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
+does not do that.
+
+If @code{map-y-or-n-p} is called in a command that was invoked using the
+mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
+Loop Info}) is either @code{nil} or a list---then it uses a dialog box
+or pop-up menu to ask the question.  In this case, it does not use
+keyboard input or the echo area.  You can force use of the mouse or use
+of keyboard input by binding @code{last-nonmenu-event} to a suitable
+value around the call.
+
+The return value of @code{map-y-or-n-p} is the number of objects acted on.
+@end defun
+
+@node Reading a Password
+@section Reading a Password
+@cindex passwords, reading
+
+  To read a password to pass to another program, you can use the
+function @code{read-passwd}.
+
+@defun read-passwd prompt &optional confirm default
+This function reads a password, prompting with @var{prompt}.  It does
+not echo the password as the user types it; instead, it echoes @samp{.}
+for each character in the password.
+
+The optional argument @var{confirm}, if non-@code{nil}, says to read the
+password twice and insist it must be the same both times.  If it isn't
+the same, the user has to type it over and over until the last two
+times match.
+
+The optional argument @var{default} specifies the default password to
+return if the user enters empty input.  If @var{default} is @code{nil},
+then @code{read-passwd} returns the null string in that case.
+@end defun
+
+@node Minibuffer Commands
+@section Minibuffer Commands
+
+  This section describes some commands meant for use in the
+minibuffer.
+
+@deffn Command exit-minibuffer
+This command exits the active minibuffer.  It is normally bound to
+keys in minibuffer local keymaps.
+@end deffn
+
+@deffn Command self-insert-and-exit
+This command exits the active minibuffer after inserting the last
+character typed on the keyboard (found in @code{last-command-char};
+@pxref{Command Loop Info}).
+@end deffn
+
+@deffn Command previous-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th previous (older) history element.
+@end deffn
+
+@deffn Command next-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th more recent history element.
+@end deffn
+
+@deffn Command previous-matching-history-element pattern n
+This command replaces the minibuffer contents with the value of the
+@var{n}th previous (older) history element that matches @var{pattern} (a
+regular expression).
+@end deffn
+
+@deffn Command next-matching-history-element pattern n
+This command replaces the minibuffer contents with the value of the
+@var{n}th next (newer) history element that matches @var{pattern} (a
+regular expression).
+@end deffn
+
+@node Minibuffer Windows
+@section Minibuffer Windows
+@cindex minibuffer windows
+
+  These functions access and select minibuffer windows
+and test whether they are active.
+
+@defun active-minibuffer-window
+This function returns the currently active minibuffer window, or
+@code{nil} if none is currently active.
+@end defun
+
+@defun minibuffer-window &optional frame
+@anchor{Definition of minibuffer-window}
+This function returns the minibuffer window used for frame @var{frame}.
+If @var{frame} is @code{nil}, that stands for the current frame.  Note
+that the minibuffer window used by a frame need not be part of that
+frame---a frame that has no minibuffer of its own necessarily uses some
+other frame's minibuffer window.
+@end defun
+
+@defun set-minibuffer-window window
+This function specifies @var{window} as the minibuffer window to use.
+This affects where the minibuffer is displayed if you put text in it
+without invoking the usual minibuffer commands.  It has no effect on
+the usual minibuffer input functions because they all start by
+choosing the minibuffer window according to the current frame.
+@end defun
+
+@c Emacs 19 feature
+@defun window-minibuffer-p &optional window
+This function returns non-@code{nil} if @var{window} is a minibuffer
+window.
+@var{window} defaults to the selected window.
+@end defun
+
+It is not correct to determine whether a given window is a minibuffer by
+comparing it with the result of @code{(minibuffer-window)}, because
+there can be more than one minibuffer window if there is more than one
+frame.
+
+@defun minibuffer-window-active-p window
+This function returns non-@code{nil} if @var{window}, assumed to be
+a minibuffer window, is currently active.
+@end defun
+
+@node Minibuffer Contents
+@section Minibuffer Contents
+
+  These functions access the minibuffer prompt and contents.
+
+@defun minibuffer-prompt
+This function returns the prompt string of the currently active
+minibuffer.  If no minibuffer is active, it returns @code{nil}.
+@end defun
+
+@defun minibuffer-prompt-end
+This function returns the current
+position of the end of the minibuffer prompt, if a minibuffer is
+current.  Otherwise, it returns the minimum valid buffer position.
+@end defun
+
+@defun minibuffer-prompt-width
+This function returns the current display-width of the minibuffer
+prompt, if a minibuffer is current.  Otherwise, it returns zero.
+@end defun
+
+@defun minibuffer-contents
+This function returns the editable
+contents of the minibuffer (that is, everything except the prompt) as
+a string, if a minibuffer is current.  Otherwise, it returns the
+entire contents of the current buffer.
+@end defun
+
+@defun minibuffer-contents-no-properties
+This is like @code{minibuffer-contents}, except that it does not copy text
+properties, just the characters themselves.  @xref{Text Properties}.
+@end defun
+
+@defun minibuffer-completion-contents
+This is like @code{minibuffer-contents}, except that it returns only
+the contents before point.  That is the part that completion commands
+operate on.  @xref{Minibuffer Completion}.
+@end defun
+
+@defun delete-minibuffer-contents
+This function erases the editable contents of the minibuffer (that is,
+everything except the prompt), if a minibuffer is current.  Otherwise,
+it erases the entire current buffer.
+@end defun
+
+@node Recursive Mini
+@section Recursive Minibuffers
+@cindex recursive minibuffers
+
+  These functions and variables deal with recursive minibuffers
+(@pxref{Recursive Editing}):
+
+@defun minibuffer-depth
+This function returns the current depth of activations of the
+minibuffer, a nonnegative integer.  If no minibuffers are active, it
+returns zero.
+@end defun
+
+@defopt enable-recursive-minibuffers
+If this variable is non-@code{nil}, you can invoke commands (such as
+@code{find-file}) that use minibuffers even while the minibuffer window
+is active.  Such invocation produces a recursive editing level for a new
+minibuffer.  The outer-level minibuffer is invisible while you are
+editing the inner one.
+
+If this variable is @code{nil}, you cannot invoke minibuffer
+commands when the minibuffer window is active, not even if you switch to
+another window to do it.
+@end defopt
+
+@c Emacs 19 feature
+If a command name has a property @code{enable-recursive-minibuffers}
+that is non-@code{nil}, then the command can use the minibuffer to read
+arguments even if it is invoked from the minibuffer.  A command can
+also achieve this by binding @code{enable-recursive-minibuffers}
+to @code{t} in the interactive declaration (@pxref{Using Interactive}).
+The minibuffer command @code{next-matching-history-element} (normally
+@kbd{M-s} in the minibuffer) does the latter.
+
+@node Minibuffer Misc
+@section Minibuffer Miscellany
+
+@defun minibufferp &optional buffer-or-name
+This function returns non-@code{nil} if @var{buffer-or-name} is a
+minibuffer.  If @var{buffer-or-name} is omitted, it tests the current
+buffer.
+@end defun
+
+@defvar minibuffer-setup-hook
+This is a normal hook that is run whenever the minibuffer is entered.
+@xref{Hooks}.
+@end defvar
+
+@defvar minibuffer-exit-hook
+This is a normal hook that is run whenever the minibuffer is exited.
+@xref{Hooks}.
+@end defvar
+
+@defvar minibuffer-help-form
+@anchor{Definition of minibuffer-help-form}
+The current value of this variable is used to rebind @code{help-form}
+locally inside the minibuffer (@pxref{Help Functions}).
+@end defvar
+
+@defvar minibuffer-scroll-window
+@anchor{Definition of minibuffer-scroll-window}
+If the value of this variable is non-@code{nil}, it should be a window
+object.  When the function @code{scroll-other-window} is called in the
+minibuffer, it scrolls this window.
+@end defvar
+
+@defun minibuffer-selected-window
+This function returns the window which was selected when the
+minibuffer was entered.  If selected window is not a minibuffer
+window, it returns @code{nil}.
+@end defun
+
+@defopt max-mini-window-height
+This variable specifies the maximum height for resizing minibuffer
+windows.  If a float, it specifies a fraction of the height of the
+frame.  If an integer, it specifies a number of lines.
+@end defopt
+
+@defun minibuffer-message string
+This function displays @var{string} temporarily at the end of the
+minibuffer text, for two seconds, or until the next input event
+arrives, whichever comes first.
+@end defun
+
+@ignore
+   arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
+@end ignore
diff --git a/doc/lispref/mkinstalldirs b/doc/lispref/mkinstalldirs
new file mode 100755
index 00000000000..f945dbf2bce
--- /dev/null
+++ b/doc/lispref/mkinstalldirs
@@ -0,0 +1,38 @@
+#! /bin/sh
+# mkinstalldirs --- make directory hierarchy
+# Author: Noah Friedman <friedman@prep.ai.mit.edu>
+# Created: 1993-05-16
+# Public domain
+
+errstatus=0
+
+for file
+do
+   set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'`
+   shift
+
+   pathcomp=
+   for d
+   do
+     pathcomp="$pathcomp$d"
+     case "$pathcomp" in
+       -* ) pathcomp=./$pathcomp ;;
+     esac
+
+     if test ! -d "$pathcomp"; then
+        echo "mkdir $pathcomp" 1>&2
+
+        mkdir "$pathcomp" || lasterr=$?
+
+        if test ! -d "$pathcomp"; then
+  	  errstatus=$lasterr
+        fi
+     fi
+
+     pathcomp="$pathcomp/"
+   done
+done
+
+exit $errstatus
+
+# mkinstalldirs ends here
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
new file mode 100644
index 00000000000..3d60756a901
--- /dev/null
+++ b/doc/lispref/modes.texi
@@ -0,0 +1,3271 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/modes
+@node Modes, Documentation, Keymaps, Top
+@chapter Major and Minor Modes
+@cindex mode
+
+  A @dfn{mode} is a set of definitions that customize Emacs and can be
+turned on and off while you edit.  There are two varieties of modes:
+@dfn{major modes}, which are mutually exclusive and used for editing
+particular kinds of text, and @dfn{minor modes}, which provide features
+that users can enable individually.
+
+  This chapter describes how to write both major and minor modes, how to
+indicate them in the mode line, and how they run hooks supplied by the
+user.  For related topics such as keymaps and syntax tables, see
+@ref{Keymaps}, and @ref{Syntax Tables}.
+
+@menu
+* Hooks::              How to use hooks; how to write code that provides hooks.
+* Major Modes::        Defining major modes.
+* Minor Modes::        Defining minor modes.
+* Mode Line Format::   Customizing the text that appears in the mode line.
+* Imenu::              How a mode can provide a menu
+                         of definitions in the buffer.
+* Font Lock Mode::     How modes can highlight text according to syntax.
+* Desktop Save Mode::  How modes can have buffer state saved between
+                         Emacs sessions.
+@end menu
+
+@node Hooks
+@section Hooks
+@cindex hooks
+
+  A @dfn{hook} is a variable where you can store a function or functions
+to be called on a particular occasion by an existing program.  Emacs
+provides hooks for the sake of customization.  Most often, hooks are set
+up in the init file (@pxref{Init File}), but Lisp programs can set them also.
+@xref{Standard Hooks}, for a list of standard hook variables.
+
+@cindex normal hook
+  Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
+contain lists of functions to be called with no arguments.  By
+convention, whenever the hook name ends in @samp{-hook}, that tells
+you it is normal.  We try to make all hooks normal, as much as
+possible, so that you can use them in a uniform way.
+
+  Every major mode function is supposed to run a normal hook called
+the @dfn{mode hook} as the one of the last steps of initialization.
+This makes it easy for a user to customize the behavior of the mode,
+by overriding the buffer-local variable assignments already made by
+the mode.  Most minor mode functions also run a mode hook at the end.
+But hooks are used in other contexts too.  For example, the hook
+@code{suspend-hook} runs just before Emacs suspends itself
+(@pxref{Suspending Emacs}).
+
+  The recommended way to add a hook function to a normal hook is by
+calling @code{add-hook} (see below).  The hook functions may be any of
+the valid kinds of functions that @code{funcall} accepts (@pxref{What
+Is a Function}).  Most normal hook variables are initially void;
+@code{add-hook} knows how to deal with this.  You can add hooks either
+globally or buffer-locally with @code{add-hook}.
+
+@cindex abnormal hook
+  If the hook variable's name does not end with @samp{-hook}, that
+indicates it is probably an @dfn{abnormal hook}.  That means the hook
+functions are called with arguments, or their return values are used
+in some way.  The hook's documentation says how the functions are
+called.  You can use @code{add-hook} to add a function to an abnormal
+hook, but you must write the function to follow the hook's calling
+convention.
+
+  By convention, abnormal hook names end in @samp{-functions} or
+@samp{-hooks}.  If the variable's name ends in @samp{-function}, then
+its value is just a single function, not a list of functions.
+
+  Here's an example that uses a mode hook to turn on Auto Fill mode when
+in Lisp Interaction mode:
+
+@example
+(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+@end example
+
+  At the appropriate time, Emacs uses the @code{run-hooks} function to
+run particular hooks.
+
+@defun run-hooks &rest hookvars
+This function takes one or more normal hook variable names as
+arguments, and runs each hook in turn.  Each argument should be a
+symbol that is a normal hook variable.  These arguments are processed
+in the order specified.
+
+If a hook variable has a non-@code{nil} value, that value should be a
+list of functions.  @code{run-hooks} calls all the functions, one by
+one, with no arguments.
+
+The hook variable's value can also be a single function---either a
+lambda expression or a symbol with a function definition---which
+@code{run-hooks} calls.  But this usage is obsolete.
+@end defun
+
+@defun run-hook-with-args hook &rest args
+This function is the way to run an abnormal hook and always call all
+of the hook functions.  It calls each of the hook functions one by
+one, passing each of them the arguments @var{args}.
+@end defun
+
+@defun run-hook-with-args-until-failure hook &rest args
+This function is the way to run an abnormal hook until one of the hook
+functions fails.  It calls each of the hook functions, passing each of
+them the arguments @var{args}, until some hook function returns
+@code{nil}.  It then stops and returns @code{nil}.  If none of the
+hook functions return @code{nil}, it returns a non-@code{nil} value.
+@end defun
+
+@defun run-hook-with-args-until-success hook &rest args
+This function is the way to run an abnormal hook until a hook function
+succeeds.  It calls each of the hook functions, passing each of them
+the arguments @var{args}, until some hook function returns
+non-@code{nil}.  Then it stops, and returns whatever was returned by
+the last hook function that was called.  If all hook functions return
+@code{nil}, it returns @code{nil} as well.
+@end defun
+
+@defun add-hook hook function &optional append local
+This function is the handy way to add function @var{function} to hook
+variable @var{hook}.  You can use it for abnormal hooks as well as for
+normal hooks.  @var{function} can be any Lisp function that can accept
+the proper number of arguments for @var{hook}.  For example,
+
+@example
+(add-hook 'text-mode-hook 'my-text-hook-function)
+@end example
+
+@noindent
+adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
+
+If @var{function} is already present in @var{hook} (comparing using
+@code{equal}), then @code{add-hook} does not add it a second time.
+
+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: normally,
+@var{function} goes at the front of the hook list, so it will be
+executed first (barring another @code{add-hook} call).  If the optional
+argument @var{append} is non-@code{nil}, the new hook function goes at
+the end of the hook list and will be executed last.
+
+@code{add-hook} can handle the cases where @var{hook} is void or its
+value is a single function; it sets or changes the value to a list of
+functions.
+
+If @var{local} is non-@code{nil}, that says to add @var{function} to
+the buffer-local hook list instead of to the global hook list.  If
+needed, this makes the hook buffer-local and adds @code{t} to the
+buffer-local value.  The latter acts as a flag to run the hook
+functions in the default value as well as in the local value.
+@end defun
+
+@defun remove-hook hook function &optional local
+This function removes @var{function} from the hook variable
+@var{hook}.  It compares @var{function} with elements of @var{hook}
+using @code{equal}, so it works for both symbols and lambda
+expressions.
+
+If @var{local} is non-@code{nil}, that says to remove @var{function}
+from the buffer-local hook list instead of from the global hook list.
+@end defun
+
+@node Major Modes
+@section Major Modes
+@cindex major mode
+
+  Major modes specialize Emacs for editing particular kinds of text.
+Each buffer has only one major mode at a time.  For each major mode
+there is a function to switch to that mode in the current buffer; its
+name should end in @samp{-mode}.  These functions work by setting
+buffer-local variable bindings and other data associated with the
+buffer, such as a local keymap.  The effect lasts until you switch
+to another major mode in the same buffer.
+
+@menu
+* Major Mode Basics::
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* Auto Major Mode::         How Emacs chooses the major mode automatically.
+* Mode Help::               Finding out how to use a mode.
+* Derived Modes::           Defining a new major mode based on another major
+                              mode.
+* Generic Modes::           Defining a simple major mode that supports
+                              comment syntax and Font Lock mode.
+* Mode Hooks::              Hooks run at the end of major mode functions.
+* Example Major Modes::     Text mode and Lisp modes.
+@end menu
+
+@node Major Mode Basics
+@subsection Major Mode Basics
+@cindex Fundamental mode
+
+  The least specialized major mode is called @dfn{Fundamental mode}.
+This mode has no mode-specific definitions or variable settings, so each
+Emacs command behaves in its default manner, and each option is in its
+default state.  All other major modes redefine various keys and options.
+For example, Lisp Interaction mode provides special key bindings for
+@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
+(@code{lisp-indent-line}), and other keys.
+
+  When you need to write several editing commands to help you perform a
+specialized editing task, creating a new major mode is usually a good
+idea.  In practice, writing a major mode is easy (in contrast to
+writing a minor mode, which is often difficult).
+
+  If the new mode is similar to an old one, it is often unwise to
+modify the old one to serve two purposes, since it may become harder
+to use and maintain.  Instead, copy and rename an existing major mode
+definition and alter the copy---or use @code{define-derived-mode} to
+define a @dfn{derived mode} (@pxref{Derived Modes}).  For example,
+Rmail Edit mode is a major mode that is very similar to Text mode
+except that it provides two additional commands.  Its definition is
+distinct from that of Text mode, but uses that of Text mode.
+
+  Even if the new mode is not an obvious derivative of any other mode,
+it is convenient to use @code{define-derived-mode} with a @code{nil}
+parent argument, since it automatically enforces the most important
+coding conventions for you.
+
+  For a very simple programming language major mode that handles
+comments and fontification, you can use @code{define-generic-mode}.
+@xref{Generic Modes}.
+
+  Rmail Edit mode offers an example of changing the major mode
+temporarily for a buffer, so it can be edited in a different way (with
+ordinary Emacs commands rather than Rmail commands).  In such cases, the
+temporary major mode usually provides a command to switch back to the
+buffer's usual mode (Rmail mode, in this case).  You might be tempted to
+present the temporary redefinitions inside a recursive edit and restore
+the usual ones when the user exits; but this is a bad idea because it
+constrains the user's options when it is done in more than one buffer:
+recursive edits must be exited most-recently-entered first.  Using an
+alternative major mode avoids this limitation.  @xref{Recursive
+Editing}.
+
+  The standard GNU Emacs Lisp library directory tree contains the code
+for several major modes, in files such as @file{text-mode.el},
+@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
+@file{rmail.el}.  They are found in various subdirectories of the
+@file{lisp} directory.  You can study these libraries to see how modes
+are written.  Text mode is perhaps the simplest major mode aside from
+Fundamental mode.  Rmail mode is a complicated and specialized mode.
+
+@node Major Mode Conventions
+@subsection Major Mode Conventions
+@cindex major mode conventions
+@cindex conventions for writing major modes
+
+  The code for existing major modes follows various coding conventions,
+including conventions for local keymap and syntax table initialization,
+global names, and hooks.  Please follow these conventions when you
+define a new major mode.  (Fundamental mode is an exception to many
+of these conventions, because its definition is to present the global
+state of Emacs.)
+
+  This list of conventions is only partial, because each major mode
+should aim for consistency in general with other Emacs major modes.
+This makes Emacs as a whole more coherent.  It is impossible to list
+here all the possible points where this issue might come up; if the
+Emacs developers point out an area where your major mode deviates from
+the usual conventions, please make it compatible.
+
+@itemize @bullet
+@item
+Define a command whose name ends in @samp{-mode}, with no arguments,
+that switches to the new mode in the current buffer.  This command
+should set up the keymap, syntax table, and buffer-local variables in an
+existing buffer, without changing the buffer's contents.
+
+@item
+Write a documentation string for this command that describes the
+special commands available in this mode.  @kbd{C-h m}
+(@code{describe-mode}) in your mode will display this string.
+
+The documentation string may include the special documentation
+substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
+@samp{\<@var{keymap}>}, which enable the documentation to adapt
+automatically to the user's own key bindings.  @xref{Keys in
+Documentation}.
+
+@item
+The major mode command should start by calling
+@code{kill-all-local-variables}.  This runs the normal hook
+@code{change-major-mode-hook}, then gets rid of the buffer-local
+variables of the major mode previously in effect.  @xref{Creating
+Buffer-Local}.
+
+@item
+The major mode command should set the variable @code{major-mode} to the
+major mode command symbol.  This is how @code{describe-mode} discovers
+which documentation to print.
+
+@item
+The major mode command should set the variable @code{mode-name} to the
+``pretty'' name of the mode, as a string.  This string appears in the
+mode line.
+
+@item
+@cindex functions in modes
+Since all global names are in the same name space, all the global
+variables, constants, and functions that are part of the mode should
+have names that start with the major mode name (or with an abbreviation
+of it if the name is long).  @xref{Coding Conventions}.
+
+@item
+In a major mode for editing some kind of structured text, such as a
+programming language, indentation of text according to structure is
+probably useful.  So the mode should set @code{indent-line-function}
+to a suitable function, and probably customize other variables
+for indentation.
+
+@item
+@cindex keymaps in modes
+The major mode should usually have its own keymap, which is used as the
+local keymap in all buffers in that mode.  The major mode command should
+call @code{use-local-map} to install this local map.  @xref{Active
+Keymaps}, for more information.
+
+This keymap should be stored permanently in a global variable named
+@code{@var{modename}-mode-map}.  Normally the library that defines the
+mode sets this variable.
+
+@xref{Tips for Defining}, for advice about how to write the code to set
+up the mode's keymap variable.
+
+@item
+The key sequences bound in a major mode keymap should usually start with
+@kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
+@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}.  The other punctuation
+characters are reserved for minor modes, and ordinary letters are
+reserved for users.
+
+A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
+@kbd{M-s}.  The bindings for @kbd{M-n} and @kbd{M-p} should normally
+be some kind of ``moving forward and backward,'' but this does not
+necessarily mean cursor motion.
+
+It is legitimate for a major mode to rebind a standard key sequence if
+it provides a command that does ``the same job'' in a way better
+suited to the text this mode is used for.  For example, a major mode
+for editing a programming language might redefine @kbd{C-M-a} to
+``move to the beginning of a function'' in a way that works better for
+that language.
+
+It is also legitimate for a major mode to rebind a standard key
+sequence whose standard meaning is rarely useful in that mode.  For
+instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
+rarely of any use in the minibuffer.  Major modes such as Dired or
+Rmail that do not allow self-insertion of text can reasonably redefine
+letters and other printing characters as special commands.
+
+@item
+Major modes modes for editing text should not define @key{RET} to do
+anything other than insert a newline.  However, it is ok for
+specialized modes for text that users don't directly edit, such as
+Dired and Info modes, to redefine @key{RET} to do something entirely
+different.
+
+@item
+Major modes should not alter options that are primarily a matter of user
+preference, such as whether Auto-Fill mode is enabled.  Leave this to
+each user to decide.  However, a major mode should customize other
+variables so that Auto-Fill mode will work usefully @emph{if} the user
+decides to use it.
+
+@item
+@cindex syntax tables in modes
+The mode may have its own syntax table or may share one with other
+related modes.  If it has its own syntax table, it should store this in
+a variable named @code{@var{modename}-mode-syntax-table}.  @xref{Syntax
+Tables}.
+
+@item
+If the mode handles a language that has a syntax for comments, it should
+set the variables that define the comment syntax.  @xref{Options for
+Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
+
+@item
+@cindex abbrev tables in modes
+The mode may have its own abbrev table or may share one with other
+related modes.  If it has its own abbrev table, it should store this
+in a variable named @code{@var{modename}-mode-abbrev-table}.  If the
+major mode command defines any abbrevs itself, it should pass @code{t}
+for the @var{system-flag} argument to @code{define-abbrev}.
+@xref{Defining Abbrevs}.
+
+@item
+The mode should specify how to do highlighting for Font Lock mode, by
+setting up a buffer-local value for the variable
+@code{font-lock-defaults} (@pxref{Font Lock Mode}).
+
+@item
+The mode should specify how Imenu should find the definitions or
+sections of a buffer, by setting up a buffer-local value for the
+variable @code{imenu-generic-expression}, for the two variables
+@code{imenu-prev-index-position-function} and
+@code{imenu-extract-index-name-function}, or for the variable
+@code{imenu-create-index-function} (@pxref{Imenu}).
+
+@item
+The mode can specify a local value for
+@code{eldoc-documentation-function} to tell ElDoc mode how to handle
+this mode.
+
+@item
+Use @code{defvar} or @code{defcustom} to set mode-related variables, so
+that they are not reinitialized if they already have a value.  (Such
+reinitialization could discard customizations made by the user.)
+
+@item
+@cindex buffer-local variables in modes
+To make a buffer-local binding for an Emacs customization variable, use
+@code{make-local-variable} in the major mode command, not
+@code{make-variable-buffer-local}.  The latter function would make the
+variable local to every buffer in which it is subsequently set, which
+would affect buffers that do not use this mode.  It is undesirable for a
+mode to have such global effects.  @xref{Buffer-Local Variables}.
+
+With rare exceptions, the only reasonable way to use
+@code{make-variable-buffer-local} in a Lisp package is for a variable
+which is used only within that package.  Using it on a variable used by
+other packages would interfere with them.
+
+@item
+@cindex mode hook
+@cindex major mode hook
+Each major mode should have a normal @dfn{mode hook} named
+@code{@var{modename}-mode-hook}.  The very last thing the major mode command
+should do is to call @code{run-mode-hooks}.  This runs the mode hook,
+and then runs the normal hook @code{after-change-major-mode-hook}.
+@xref{Mode Hooks}.
+
+@item
+The major mode command may start by calling some other major mode
+command (called the @dfn{parent mode}) and then alter some of its
+settings.  A mode that does this is called a @dfn{derived mode}.  The
+recommended way to define one is to use @code{define-derived-mode},
+but this is not required.  Such a mode should call the parent mode
+command inside a @code{delay-mode-hooks} form.  (Using
+@code{define-derived-mode} does this automatically.)  @xref{Derived
+Modes}, and @ref{Mode Hooks}.
+
+@item
+If something special should be done if the user switches a buffer from
+this mode to any other major mode, this mode can set up a buffer-local
+value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
+
+@item
+If this mode is appropriate only for specially-prepared text, then the
+major mode command symbol should have a property named @code{mode-class}
+with value @code{special}, put on as follows:
+
+@kindex mode-class @r{(property)}
+@cindex @code{special}
+@example
+(put 'funny-mode 'mode-class 'special)
+@end example
+
+@noindent
+This tells Emacs that new buffers created while the current buffer is
+in Funny mode should not inherit Funny mode, in case
+@code{default-major-mode} is @code{nil}.  Modes such as Dired, Rmail,
+and Buffer List use this feature.
+
+@item
+If you want to make the new mode the default for files with certain
+recognizable names, add an element to @code{auto-mode-alist} to select
+the mode for those file names (@pxref{Auto Major Mode}).  If you
+define the mode command to autoload, you should add this element in
+the same file that calls @code{autoload}.  If you use an autoload
+cookie for the mode command, you can also use an autoload cookie for
+the form that adds the element (@pxref{autoload cookie}).  If you do
+not autoload the mode command, it is sufficient to add the element in
+the file that contains the mode definition.
+
+@item
+In the comments that document the file, you should provide a sample
+@code{autoload} form and an example of how to add to
+@code{auto-mode-alist}, that users can include in their init files
+(@pxref{Init File}).
+
+@item
+@cindex mode loading
+The top-level forms in the file defining the mode should be written so
+that they may be evaluated more than once without adverse consequences.
+Even if you never load the file more than once, someone else will.
+@end itemize
+
+@node Auto Major Mode
+@subsection How Emacs Chooses a Major Mode
+@cindex major mode, automatic selection
+
+  Based on information in the file name or in the file itself, Emacs
+automatically selects a major mode for the new buffer when a file is
+visited.  It also processes local variables specified in the file text.
+
+@deffn Command fundamental-mode
+  Fundamental mode is a major mode that is not specialized for anything
+in particular.  Other major modes are defined in effect by comparison
+with this one---their definitions say what to change, starting from
+Fundamental mode.  The @code{fundamental-mode} function does @emph{not}
+run any mode hooks; you're not supposed to customize it.  (If you want Emacs
+to behave differently in Fundamental mode, change the @emph{global}
+state of Emacs.)
+@end deffn
+
+@deffn Command normal-mode &optional find-file
+This function establishes the proper major mode and buffer-local variable
+bindings for the current buffer.  First it calls @code{set-auto-mode}
+(see below), then it runs @code{hack-local-variables} to parse, and
+bind or evaluate as appropriate, the file's local variables
+(@pxref{File Local Variables}).
+
+If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
+@code{normal-mode} assumes that the @code{find-file} function is calling
+it.  In this case, it may process local variables in the @samp{-*-}
+line or at the end of the file.  The variable
+@code{enable-local-variables} controls whether to do so.  @xref{File
+Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
+for the syntax of the local variables section of a file.
+
+If you run @code{normal-mode} interactively, the argument
+@var{find-file} is normally @code{nil}.  In this case,
+@code{normal-mode} unconditionally processes any file local variables.
+
+If @code{normal-mode} processes the local variables list and this list
+specifies a major mode, that mode overrides any mode chosen by
+@code{set-auto-mode}.  If neither @code{set-auto-mode} nor
+@code{hack-local-variables} specify a major mode, the buffer stays in
+the major mode determined by @code{default-major-mode} (see below).
+
+@cindex file mode specification error
+@code{normal-mode} uses @code{condition-case} around the call to the
+major mode function, so errors are caught and reported as a @samp{File
+mode specification error},  followed by the original error message.
+@end deffn
+
+@defun set-auto-mode &optional keep-mode-if-same
+@cindex visited file mode
+  This function selects the major mode that is appropriate for the
+current buffer.  It bases its decision (in order of precedence) on
+the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
+@code{interpreter-mode-alist}), on the text at the beginning of the
+buffer (using @code{magic-mode-alist}), and finally on the visited
+file name (using @code{auto-mode-alist}).  @xref{Choosing Modes, , How
+Major Modes are Chosen, emacs, The GNU Emacs Manual}.  However, this
+function does not look for the @samp{mode:} local variable near the
+end of a file; the @code{hack-local-variables} function does that.
+If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
+does not check the @w{@samp{-*-}} line for a mode tag either.
+
+If @var{keep-mode-if-same} is non-@code{nil}, this function does not
+call the mode command if the buffer is already in the proper major
+mode.  For instance, @code{set-visited-file-name} sets this to
+@code{t} to avoid killing buffer local variables that the user may
+have set.
+@end defun
+
+@defopt default-major-mode
+This variable holds the default major mode for new buffers.  The
+standard value is @code{fundamental-mode}.
+
+If the value of @code{default-major-mode} is @code{nil}, Emacs uses
+the (previously) current buffer's major mode as the default major mode
+of a new buffer.  However, if that major mode symbol has a @code{mode-class}
+property with value @code{special}, then it is not used for new buffers;
+Fundamental mode is used instead.  The modes that have this property are
+those such as Dired and Rmail that are useful only with text that has
+been specially prepared.
+@end defopt
+
+@defun set-buffer-major-mode buffer
+This function sets the major mode of @var{buffer} to the value of
+@code{default-major-mode}; if that variable is @code{nil}, it uses the
+current buffer's major mode (if that is suitable).  As an exception,
+if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
+@code{initial-major-mode}.
+
+The low-level primitives for creating buffers do not use this function,
+but medium-level commands such as @code{switch-to-buffer} and
+@code{find-file-noselect} use it whenever they create buffers.
+@end defun
+
+@defopt initial-major-mode
+@cindex @samp{*scratch*}
+The value of this variable determines the major mode of the initial
+@samp{*scratch*} buffer.  The value should be a symbol that is a major
+mode command.  The default value is @code{lisp-interaction-mode}.
+@end defopt
+
+@defvar interpreter-mode-alist
+This variable specifies major modes to use for scripts that specify a
+command interpreter in a @samp{#!} line.  Its value is an alist with
+elements of the form @code{(@var{interpreter} . @var{mode})}; for
+example, @code{("perl" . perl-mode)} is one element present by
+default.  The element says to use mode @var{mode} if the file
+specifies an interpreter which matches @var{interpreter}.
+@end defvar
+
+@defvar magic-mode-alist
+This variable's value is an alist with elements of the form
+@code{(@var{regexp} .  @var{function})}, where @var{regexp} is a
+regular expression and @var{function} is a function or @code{nil}.
+After visiting a file, @code{set-auto-mode} calls @var{function} if
+the text at the beginning of the buffer matches @var{regexp} and
+@var{function} is non-@code{nil}; if @var{function} is @code{nil},
+@code{auto-mode-alist} gets to decide the mode.
+@end defvar
+
+@defvar magic-fallback-mode-alist
+This works like @code{magic-mode-alist}, except that it is handled
+only if @code{auto-mode-alist} does not specify a mode for this file.
+@end defvar
+
+@defvar auto-mode-alist
+This variable contains an association list of file name patterns
+(regular expressions) and corresponding major mode commands.  Usually,
+the file name patterns test for suffixes, such as @samp{.el} and
+@samp{.c}, but this need not be the case.  An ordinary element of the
+alist looks like @code{(@var{regexp} .  @var{mode-function})}.
+
+For example,
+
+@smallexample
+@group
+(("\\`/tmp/fol/" . text-mode)
+ ("\\.texinfo\\'" . texinfo-mode)
+ ("\\.texi\\'" . texinfo-mode)
+@end group
+@group
+ ("\\.el\\'" . emacs-lisp-mode)
+ ("\\.c\\'" . c-mode)
+ ("\\.h\\'" . c-mode)
+ @dots{})
+@end group
+@end smallexample
+
+When you visit a file whose expanded file name (@pxref{File Name
+Expansion}), with version numbers and backup suffixes removed using
+@code{file-name-sans-versions} (@pxref{File Name Components}), matches
+a @var{regexp}, @code{set-auto-mode} calls the corresponding
+@var{mode-function}.  This feature enables Emacs to select the proper
+major mode for most files.
+
+If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
+@var{function} t)}, then after calling @var{function}, Emacs searches
+@code{auto-mode-alist} again for a match against the portion of the file
+name that did not match before.  This feature is useful for
+uncompression packages: an entry of the form @code{("\\.gz\\'"
+@var{function} t)} can uncompress the file and then put the uncompressed
+file in the proper mode according to the name sans @samp{.gz}.
+
+Here is an example of how to prepend several pattern pairs to
+@code{auto-mode-alist}.  (You might use this sort of expression in your
+init file.)
+
+@smallexample
+@group
+(setq auto-mode-alist
+  (append
+   ;; @r{File name (within directory) starts with a dot.}
+   '(("/\\.[^/]*\\'" . fundamental-mode)
+     ;; @r{File name has no dot.}
+     ("[^\\./]*\\'" . fundamental-mode)
+     ;; @r{File name ends in @samp{.C}.}
+     ("\\.C\\'" . c++-mode))
+   auto-mode-alist))
+@end group
+@end smallexample
+@end defvar
+
+@node Mode Help
+@subsection Getting Help about a Major Mode
+@cindex mode help
+@cindex help for major mode
+@cindex documentation for major mode
+
+  The @code{describe-mode} function is used to provide information
+about major modes.  It is normally called with @kbd{C-h m}.  The
+@code{describe-mode} function uses the value of @code{major-mode},
+which is why every major mode function needs to set the
+@code{major-mode} variable.
+
+@deffn Command describe-mode
+This function displays the documentation of the current major mode.
+
+The @code{describe-mode} function calls the @code{documentation}
+function using the value of @code{major-mode} as an argument.  Thus, it
+displays the documentation string of the major mode function.
+(@xref{Accessing Documentation}.)
+@end deffn
+
+@defvar major-mode
+This buffer-local variable holds the symbol for the current buffer's
+major mode.  This symbol should have a function definition that is the
+command to switch to that major mode.  The @code{describe-mode}
+function uses the documentation string of the function as the
+documentation of the major mode.
+@end defvar
+
+@node Derived Modes
+@subsection Defining Derived Modes
+@cindex derived mode
+
+  It's often useful to define a new major mode in terms of an existing
+one.  An easy way to do this is to use @code{define-derived-mode}.
+
+@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
+This construct defines @var{variant} as a major mode command, using
+@var{name} as the string form of the mode name.  @var{variant} and
+@var{parent} should be unquoted symbols.
+
+The new command @var{variant} is defined to call the function
+@var{parent}, then override certain aspects of that parent mode:
+
+@itemize @bullet
+@item
+The new mode has its own sparse keymap, named
+@code{@var{variant}-map}.  @code{define-derived-mode}
+makes the parent mode's keymap the parent of the new map, unless
+@code{@var{variant}-map} is already set and already has a parent.
+
+@item
+The new mode has its own syntax table, kept in the variable
+@code{@var{variant}-syntax-table}, unless you override this using the
+@code{:syntax-table} keyword (see below).  @code{define-derived-mode}
+makes the parent mode's syntax-table the parent of
+@code{@var{variant}-syntax-table}, unless the latter is already set
+and already has a parent different from the standard syntax table.
+
+@item
+The new mode has its own abbrev table, kept in the variable
+@code{@var{variant}-abbrev-table}, unless you override this using the
+@code{:abbrev-table} keyword (see below).
+
+@item
+The new mode has its own mode hook, @code{@var{variant}-hook}.  It
+runs this hook, after running the hooks of its ancestor modes, with
+@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
+@end itemize
+
+In addition, you can specify how to override other aspects of
+@var{parent} with @var{body}.  The command @var{variant}
+evaluates the forms in @var{body} after setting up all its usual
+overrides, just before running the mode hooks.
+
+You can also specify @code{nil} for @var{parent}.  This gives the new
+mode no parent.  Then @code{define-derived-mode} behaves as described
+above, but, of course, omits all actions connected with @var{parent}.
+
+The argument @var{docstring} specifies the documentation string for
+the new mode.  @code{define-derived-mode} adds some general
+information about the mode's hook, followed by the mode's keymap, at
+the end of this docstring.  If you omit @var{docstring},
+@code{define-derived-mode} generates a documentation string.
+
+The @var{keyword-args} are pairs of keywords and values.  The values
+are evaluated.  The following keywords are currently supported:
+
+@table @code
+@item :syntax-table
+You can use this to explicitly specify a syntax table for the new
+mode.  If you specify a @code{nil} value, the new mode uses the same
+syntax table as @var{parent}, or the standard syntax table if
+@var{parent} is @code{nil}.  (Note that this does @emph{not} follow
+the convention used for non-keyword arguments that a @code{nil} value
+is equivalent with not specifying the argument.)
+
+@item :abbrev-table
+You can use this to explicitly specify an abbrev table for the new
+mode.  If you specify a @code{nil} value, the new mode uses the same
+abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
+if @var{parent} is @code{nil}.  (Again, a @code{nil} value is
+@emph{not} equivalent to not specifying this keyword.)
+
+@item :group
+If this is specified, the value should be the customization group for
+this mode.  (Not all major modes have one.)  Only the (still
+experimental and unadvertised) command @code{customize-mode} currently
+uses this.  @code{define-derived-mode} does @emph{not} automatically
+define the specified customization group.
+@end table
+
+Here is a hypothetical example:
+
+@example
+(define-derived-mode hypertext-mode
+  text-mode "Hypertext"
+  "Major mode for hypertext.
+\\@{hypertext-mode-map@}"
+  (setq case-fold-search nil))
+
+(define-key hypertext-mode-map
+  [down-mouse-3] 'do-hyper-link)
+@end example
+
+Do not write an @code{interactive} spec in the definition;
+@code{define-derived-mode} does that automatically.
+@end defmac
+
+@node Generic Modes
+@subsection Generic Modes
+@cindex generic mode
+
+  @dfn{Generic modes} are simple major modes with basic support for
+comment syntax and Font Lock mode.  To define a generic mode, use the
+macro @code{define-generic-mode}.  See the file @file{generic-x.el}
+for some examples of the use of @code{define-generic-mode}.
+
+@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
+This macro defines a generic mode command named @var{mode} (a symbol,
+not quoted).  The optional argument @var{docstring} is the
+documentation for the mode command.  If you do not supply it,
+@code{define-generic-mode} generates one by default.
+
+The argument @var{comment-list} is a list in which each element is
+either a character, a string of one or two characters, or a cons cell.
+A character or a string is set up in the mode's syntax table as a
+``comment starter.''  If the entry is a cons cell, the @sc{car} is set
+up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
+(Use @code{nil} for the latter if you want comments to end at the end
+of the line.)  Note that the syntax table mechanism has limitations
+about what comment starters and enders are actually possible.
+@xref{Syntax Tables}.
+
+The argument @var{keyword-list} is a list of keywords to highlight
+with @code{font-lock-keyword-face}.  Each keyword should be a string.
+Meanwhile, @var{font-lock-list} is a list of additional expressions to
+highlight.  Each element of this list should have the same form as an
+element of @code{font-lock-keywords}.  @xref{Search-based
+Fontification}.
+
+The argument @var{auto-mode-list} is a list of regular expressions to
+add to the variable @code{auto-mode-alist}.  They are added by the execution
+of the @code{define-generic-mode} form, not by expanding the macro call.
+
+Finally, @var{function-list} is a list of functions for the mode
+command to call for additional setup.  It calls these functions just
+before it runs the mode hook variable @code{@var{mode}-hook}.
+@end defmac
+
+@node Mode Hooks
+@subsection Mode Hooks
+
+  Every major mode function should finish by running its mode hook and
+the mode-independent normal hook @code{after-change-major-mode-hook}.
+It does this by calling @code{run-mode-hooks}.  If the major mode is a
+derived mode, that is if it calls another major mode (the parent mode)
+in its body, it should do this inside @code{delay-mode-hooks} so that
+the parent won't run these hooks itself.  Instead, the derived mode's
+call to @code{run-mode-hooks} runs the parent's mode hook too.
+@xref{Major Mode Conventions}.
+
+  Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
+When user-implemented major modes have not been updated to use it,
+they won't entirely follow these conventions: they may run the
+parent's mode hook too early, or fail to run
+@code{after-change-major-mode-hook}.  If you encounter such a major
+mode, please correct it to follow these conventions.
+
+  When you defined a major mode using @code{define-derived-mode}, it
+automatically makes sure these conventions are followed.  If you
+define a major mode ``by hand,'' not using @code{define-derived-mode},
+use the following functions to handle these conventions automatically.
+
+@defun run-mode-hooks &rest hookvars
+Major modes should run their mode hook using this function.  It is
+similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
+@code{after-change-major-mode-hook}.
+
+When this function is called during the execution of a
+@code{delay-mode-hooks} form, it does not run the hooks immediately.
+Instead, it arranges for the next call to @code{run-mode-hooks} to run
+them.
+@end defun
+
+@defmac delay-mode-hooks body@dots{}
+When one major mode command calls another, it should do so inside of
+@code{delay-mode-hooks}.
+
+This macro executes @var{body}, but tells all @code{run-mode-hooks}
+calls during the execution of @var{body} to delay running their hooks.
+The hooks will actually run during the next call to
+@code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
+construct.
+@end defmac
+
+@defvar after-change-major-mode-hook
+This is a normal hook run by @code{run-mode-hooks}.  It is run at the
+very end of every properly-written major mode function.
+@end defvar
+
+@node Example Major Modes
+@subsection Major Mode Examples
+
+  Text mode is perhaps the simplest mode besides Fundamental mode.
+Here are excerpts from  @file{text-mode.el} that illustrate many of
+the conventions listed above:
+
+@smallexample
+@group
+;; @r{Create the syntax table for this mode.}
+(defvar text-mode-syntax-table
+  (let ((st (make-syntax-table)))
+    (modify-syntax-entry ?\" ".   " st)
+    (modify-syntax-entry ?\\ ".   " st)
+    ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
+    (modify-syntax-entry ?' "w p" st)
+    st)
+  "Syntax table used while in `text-mode'.")
+@end group
+
+;; @r{Create the keymap for this mode.}
+@group
+(defvar text-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map "\e\t" 'ispell-complete-word)
+    (define-key map "\es" 'center-line)
+    (define-key map "\eS" 'center-paragraph)
+    map)
+  "Keymap for `text-mode'.
+Many other modes, such as Mail mode, Outline mode
+and Indented Text mode, inherit all the commands
+defined in this map.")
+@end group
+@end smallexample
+
+  Here is how the actual mode command is defined now:
+
+@smallexample
+@group
+(define-derived-mode text-mode nil "Text"
+  "Major mode for editing text written for humans to read.
+In this mode, paragraphs are delimited only by blank or white lines.
+You can thus get the full benefit of adaptive filling
+ (see the variable `adaptive-fill-mode').
+\\@{text-mode-map@}
+Turning on Text mode runs the normal hook `text-mode-hook'."
+@end group
+@group
+  (make-local-variable 'text-mode-variant)
+  (setq text-mode-variant t)
+  ;; @r{These two lines are a feature added recently.}
+  (set (make-local-variable 'require-final-newline)
+       mode-require-final-newline)
+  (set (make-local-variable 'indent-line-function) 'indent-relative))
+@end group
+@end smallexample
+
+@noindent
+(The last line is redundant nowadays, since @code{indent-relative} is
+the default value, and we'll delete it in a future version.)
+
+  Here is how it was defined formerly, before
+@code{define-derived-mode} existed:
+
+@smallexample
+@group
+;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
+(defvar text-mode-abbrev-table nil
+  "Abbrev table used while in text mode.")
+(define-abbrev-table 'text-mode-abbrev-table ())
+@end group
+
+@group
+(defun text-mode ()
+  "Major mode for editing text intended for humans to read...
+ Special commands: \\@{text-mode-map@}
+@end group
+@group
+Turning on text-mode runs the hook `text-mode-hook'."
+  (interactive)
+  (kill-all-local-variables)
+  (use-local-map text-mode-map)
+@end group
+@group
+  (setq local-abbrev-table text-mode-abbrev-table)
+  (set-syntax-table text-mode-syntax-table)
+@end group
+@group
+  ;; @r{These four lines are absent from the current version}
+  ;; @r{not because this is done some other way, but rather}
+  ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
+  (make-local-variable 'paragraph-start)
+  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
+  (make-local-variable 'paragraph-separate)
+  (setq paragraph-separate paragraph-start)
+  (make-local-variable 'indent-line-function)
+  (setq indent-line-function 'indent-relative-maybe)
+@end group
+@group
+  (setq mode-name "Text")
+  (setq major-mode 'text-mode)
+  (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
+                                    ;   @r{customize the mode with a hook.}
+@end group
+@end smallexample
+
+@cindex @file{lisp-mode.el}
+  The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
+Interaction mode) have more features than Text mode and the code is
+correspondingly more complicated.  Here are excerpts from
+@file{lisp-mode.el} that illustrate how these modes are written.
+
+@cindex syntax table example
+@smallexample
+@group
+;; @r{Create mode-specific table variables.}
+(defvar lisp-mode-syntax-table nil "")
+(defvar lisp-mode-abbrev-table nil "")
+@end group
+
+@group
+(defvar emacs-lisp-mode-syntax-table
+  (let ((table (make-syntax-table)))
+    (let ((i 0))
+@end group
+
+@group
+      ;; @r{Set syntax of chars up to @samp{0} to say they are}
+      ;;   @r{part of symbol names but not words.}
+      ;;   @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
+      (while (< i ?0)
+	(modify-syntax-entry i "_   " table)
+	(setq i (1+ i)))
+      ;; @r{@dots{} similar code follows for other character ranges.}
+@end group
+@group
+      ;; @r{Then set the syntax codes for characters that are special in Lisp.}
+      (modify-syntax-entry ?  "    " table)
+      (modify-syntax-entry ?\t "    " table)
+      (modify-syntax-entry ?\f "    " table)
+      (modify-syntax-entry ?\n ">   " table)
+@end group
+@group
+      ;; @r{Give CR the same syntax as newline, for selective-display.}
+      (modify-syntax-entry ?\^m ">   " table)
+      (modify-syntax-entry ?\; "<   " table)
+      (modify-syntax-entry ?` "'   " table)
+      (modify-syntax-entry ?' "'   " table)
+      (modify-syntax-entry ?, "'   " table)
+@end group
+@group
+      ;; @r{@dots{}likewise for many other characters@dots{}}
+      (modify-syntax-entry ?\( "()  " table)
+      (modify-syntax-entry ?\) ")(  " table)
+      (modify-syntax-entry ?\[ "(]  " table)
+      (modify-syntax-entry ?\] ")[  " table))
+    table))
+@end group
+@group
+;; @r{Create an abbrev table for lisp-mode.}
+(define-abbrev-table 'lisp-mode-abbrev-table ())
+@end group
+@end smallexample
+
+  The three modes for Lisp share much of their code.  For instance,
+each calls the following function to set various variables:
+
+@smallexample
+@group
+(defun lisp-mode-variables (lisp-syntax)
+  (when lisp-syntax
+    (set-syntax-table lisp-mode-syntax-table))
+  (setq local-abbrev-table lisp-mode-abbrev-table)
+  @dots{}
+@end group
+@end smallexample
+
+  In Lisp and most programming languages, we want the paragraph
+commands to treat only blank lines as paragraph separators.  And the
+modes should understand the Lisp conventions for comments.  The rest of
+@code{lisp-mode-variables} sets this up:
+
+@smallexample
+@group
+  (make-local-variable 'paragraph-start)
+  (setq paragraph-start (concat page-delimiter "\\|$" ))
+  (make-local-variable 'paragraph-separate)
+  (setq paragraph-separate paragraph-start)
+  @dots{}
+@end group
+@group
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'lisp-comment-indent))
+  @dots{}
+@end group
+@end smallexample
+
+  Each of the different Lisp modes has a slightly different keymap.  For
+example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
+Lisp modes do not.  However, all Lisp modes have some commands in
+common.  The following code sets up the common commands:
+
+@smallexample
+@group
+(defvar shared-lisp-mode-map ()
+  "Keymap for commands shared by all sorts of Lisp modes.")
+
+;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
+(if shared-lisp-mode-map
+    ()
+   (setq shared-lisp-mode-map (make-sparse-keymap))
+   (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
+   (define-key shared-lisp-mode-map "\177"
+               'backward-delete-char-untabify))
+@end group
+@end smallexample
+
+@noindent
+And here is the code to set up the keymap for Lisp mode:
+
+@smallexample
+@group
+(defvar lisp-mode-map ()
+  "Keymap for ordinary Lisp mode...")
+
+(if lisp-mode-map
+    ()
+  (setq lisp-mode-map (make-sparse-keymap))
+  (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
+  (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
+  (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
+@end group
+@end smallexample
+
+  Finally, here is the complete major mode function definition for
+Lisp mode.
+
+@smallexample
+@group
+(defun lisp-mode ()
+  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
+Commands:
+Delete converts tabs to spaces as it moves back.
+Blank lines separate paragraphs.  Semicolons start comments.
+\\@{lisp-mode-map@}
+Note that `run-lisp' may be used either to start an inferior Lisp job
+or to switch back to an existing one.
+@end group
+
+@group
+Entry to this mode calls the value of `lisp-mode-hook'
+if that value is non-nil."
+  (interactive)
+  (kill-all-local-variables)
+@end group
+@group
+  (use-local-map lisp-mode-map)          ; @r{Select the mode's keymap.}
+  (setq major-mode 'lisp-mode)           ; @r{This is how @code{describe-mode}}
+                                         ;   @r{finds out what to describe.}
+  (setq mode-name "Lisp")                ; @r{This goes into the mode line.}
+  (lisp-mode-variables t)                ; @r{This defines various variables.}
+  (make-local-variable 'comment-start-skip)
+  (setq comment-start-skip
+        "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
+  (make-local-variable 'font-lock-keywords-case-fold-search)
+  (setq font-lock-keywords-case-fold-search t)
+@end group
+@group
+  (setq imenu-case-fold-search t)
+  (set-syntax-table lisp-mode-syntax-table)
+  (run-mode-hooks 'lisp-mode-hook))      ; @r{This permits the user to use a}
+                                         ;   @r{hook to customize the mode.}
+@end group
+@end smallexample
+
+@node Minor Modes
+@section Minor Modes
+@cindex minor mode
+
+  A @dfn{minor mode} provides features that users may enable or disable
+independently of the choice of major mode.  Minor modes can be enabled
+individually or in combination.  Minor modes would be better named
+``generally available, optional feature modes,'' except that such a name
+would be unwieldy.
+
+  A minor mode is not usually meant as a variation of a single major mode.
+Usually they are general and can apply to many major modes.  For
+example, Auto Fill mode works with any major mode that permits text
+insertion.  To be general, a minor mode must be effectively independent
+of the things major modes do.
+
+  A minor mode is often much more difficult to implement than a major
+mode.  One reason is that you should be able to activate and deactivate
+minor modes in any order.  A minor mode should be able to have its
+desired effect regardless of the major mode and regardless of the other
+minor modes in effect.
+
+  Often the biggest problem in implementing a minor mode is finding a
+way to insert the necessary hook into the rest of Emacs.  Minor mode
+keymaps make this easier than it used to be.
+
+@defvar minor-mode-list
+The value of this variable is a list of all minor mode commands.
+@end defvar
+
+@menu
+* Minor Mode Conventions::      Tips for writing a minor mode.
+* Keymaps and Minor Modes::     How a minor mode can have its own keymap.
+* Defining Minor Modes::        A convenient facility for defining minor modes.
+@end menu
+
+@node Minor Mode Conventions
+@subsection Conventions for Writing Minor Modes
+@cindex minor mode conventions
+@cindex conventions for writing minor modes
+
+  There are conventions for writing minor modes just as there are for
+major modes.  Several of the major mode conventions apply to minor
+modes as well: those regarding the name of the mode initialization
+function, the names of global symbols, the use of a hook at the end of
+the initialization function, and the use of keymaps and other tables.
+
+  In addition, there are several conventions that are specific to
+minor modes.  (The easiest way to follow all the conventions is to use
+the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
+
+@itemize @bullet
+@item
+@cindex mode variable
+Make a variable whose name ends in @samp{-mode} to control the minor
+mode.  We call this the @dfn{mode variable}.  The minor mode command
+should set this variable (@code{nil} to disable; anything else to
+enable).
+
+If possible, implement the mode so that setting the variable
+automatically enables or disables the mode.  Then the minor mode command
+does not need to do anything except set the variable.
+
+This variable is used in conjunction with the @code{minor-mode-alist} to
+display the minor mode name in the mode line.  It can also enable
+or disable a minor mode keymap.  Individual commands or hooks can also
+check the variable's value.
+
+If you want the minor mode to be enabled separately in each buffer,
+make the variable buffer-local.
+
+@item
+Define a command whose name is the same as the mode variable.
+Its job is to enable and disable the mode by setting the variable.
+
+The command should accept one optional argument.  If the argument is
+@code{nil}, it should toggle the mode (turn it on if it is off, and
+off if it is on).  It should turn the mode on if the argument is a
+positive integer, the symbol @code{t}, or a list whose @sc{car} is one
+of those.  It should turn the mode off if the argument is a negative
+integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
+negative integer or zero.  The meaning of other arguments is not
+specified.
+
+Here is an example taken from the definition of @code{transient-mark-mode}.
+It shows the use of @code{transient-mark-mode} as a variable that enables or
+disables the mode's behavior, and also shows the proper way to toggle,
+enable or disable the minor mode based on the raw prefix argument value.
+
+@smallexample
+@group
+(setq transient-mark-mode
+      (if (null arg) (not transient-mark-mode)
+        (> (prefix-numeric-value arg) 0)))
+@end group
+@end smallexample
+
+@item
+Add an element to @code{minor-mode-alist} for each minor mode
+(@pxref{Definition of minor-mode-alist}), if you want to indicate the
+minor mode in the mode line.  This element should be a list of the
+following form:
+
+@smallexample
+(@var{mode-variable} @var{string})
+@end smallexample
+
+Here @var{mode-variable} is the variable that controls enabling of the
+minor mode, and @var{string} is a short string, starting with a space,
+to represent the mode in the mode line.  These strings must be short so
+that there is room for several of them at once.
+
+When you add an element to @code{minor-mode-alist}, use @code{assq} to
+check for an existing element, to avoid duplication.  For example:
+
+@smallexample
+@group
+(unless (assq 'leif-mode minor-mode-alist)
+  (setq minor-mode-alist
+        (cons '(leif-mode " Leif") minor-mode-alist)))
+@end group
+@end smallexample
+
+@noindent
+or like this, using @code{add-to-list} (@pxref{List Variables}):
+
+@smallexample
+@group
+(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
+@end group
+@end smallexample
+@end itemize
+
+  Global minor modes distributed with Emacs should if possible support
+enabling and disabling via Custom (@pxref{Customization}).  To do this,
+the first step is to define the mode variable with @code{defcustom}, and
+specify @code{:type boolean}.
+
+  If just setting the variable is not sufficient to enable the mode, you
+should also specify a @code{:set} method which enables the mode by
+invoking the mode command.  Note in the variable's documentation string that
+setting the variable other than via Custom may not take effect.
+
+  Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
+and specify a @code{:require} so that customizing the variable will load
+the library that defines the mode.  This will copy suitable definitions
+into @file{loaddefs.el} so that users can use @code{customize-option} to
+enable the mode.  For example:
+
+@smallexample
+@group
+
+;;;###autoload
+(defcustom msb-mode nil
+  "Toggle msb-mode.
+Setting this variable directly does not take effect;
+use either \\[customize] or the function `msb-mode'."
+  :set 'custom-set-minor-mode
+  :initialize 'custom-initialize-default
+  :version "20.4"
+  :type    'boolean
+  :group   'msb
+  :require 'msb)
+@end group
+@end smallexample
+
+@node Keymaps and Minor Modes
+@subsection Keymaps and Minor Modes
+
+  Each minor mode can have its own keymap, which is active when the mode
+is enabled.  To set up a keymap for a minor mode, add an element to the
+alist @code{minor-mode-map-alist}.  @xref{Definition of minor-mode-map-alist}.
+
+@cindex @code{self-insert-command}, minor modes
+  One use of minor mode keymaps is to modify the behavior of certain
+self-inserting characters so that they do something else as well as
+self-insert.  In general, this is the only way to do that, since the
+facilities for customizing @code{self-insert-command} are limited to
+special cases (designed for abbrevs and Auto Fill mode).  (Do not try
+substituting your own definition of @code{self-insert-command} for the
+standard one.  The editor command loop handles this function specially.)
+
+The key sequences bound in a minor mode should consist of @kbd{C-c}
+followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}.  (The other
+punctuation characters are reserved for major modes.)
+
+@node Defining Minor Modes
+@subsection Defining Minor Modes
+
+  The macro @code{define-minor-mode} offers a convenient way of
+implementing a mode in one self-contained definition.
+
+@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
+This macro defines a new minor mode whose name is @var{mode} (a
+symbol).  It defines a command named @var{mode} to toggle the minor
+mode, with @var{doc} as its documentation string.  It also defines a
+variable named @var{mode}, which is set to @code{t} or @code{nil} by
+enabling or disabling the mode.  The variable is initialized to
+@var{init-value}.  Except in unusual circumstances (see below), this
+value must be @code{nil}.
+
+The string @var{lighter} says what to display in the mode line
+when the mode is enabled; if it is @code{nil}, the mode is not displayed
+in the mode line.
+
+The optional argument @var{keymap} specifies the keymap for the minor mode.
+It can be a variable name, whose value is the keymap, or it can be an alist
+specifying bindings in this form:
+
+@example
+(@var{key-sequence} . @var{definition})
+@end example
+
+The above three arguments @var{init-value}, @var{lighter}, and
+@var{keymap} can be (partially) omitted when @var{keyword-args} are
+used.  The @var{keyword-args} consist of keywords followed by
+corresponding values.  A few keywords have special meanings:
+
+@table @code
+@item :group @var{group}
+Custom group name to use in all generated @code{defcustom} forms.
+Defaults to @var{mode} without the possible trailing @samp{-mode}.
+@strong{Warning:} don't use this default group name unless you have
+written a @code{defgroup} to define that group properly.  @xref{Group
+Definitions}.
+
+@item :global @var{global}
+If non-@code{nil}, this specifies that the minor mode should be global
+rather than buffer-local.  It defaults to @code{nil}.
+
+One of the effects of making a minor mode global is that the
+@var{mode} variable becomes a customization variable.  Toggling it
+through the Custom interface turns the mode on and off, and its value
+can be saved for future Emacs sessions (@pxref{Saving
+Customizations,,, emacs, The GNU Emacs Manual}.  For the saved
+variable to work, you should ensure that the @code{define-minor-mode}
+form is evaluated each time Emacs starts; for packages that are not
+part of Emacs, the easiest way to do this is to specify a
+@code{:require} keyword.
+
+@item :init-value @var{init-value}
+This is equivalent to specifying @var{init-value} positionally.
+
+@item :lighter @var{lighter}
+This is equivalent to specifying @var{lighter} positionally.
+
+@item :keymap @var{keymap}
+This is equivalent to specifying @var{keymap} positionally.
+@end table
+
+Any other keyword arguments are passed directly to the
+@code{defcustom} generated for the variable @var{mode}.
+
+The command named @var{mode} first performs the standard actions such
+as setting the variable named @var{mode} and then executes the
+@var{body} forms, if any.  It finishes by running the mode hook
+variable @code{@var{mode}-hook}.
+@end defmac
+
+  The initial value must be @code{nil} except in cases where (1) the
+mode is preloaded in Emacs, or (2) it is painless for loading to
+enable the mode even though the user did not request it.  For
+instance, if the mode has no effect unless something else is enabled,
+and will always be loaded by that time, enabling it by default is
+harmless.  But these are unusual circumstances.  Normally, the
+initial value must be @code{nil}.
+
+@findex easy-mmode-define-minor-mode
+  The name @code{easy-mmode-define-minor-mode} is an alias
+for this macro.
+
+  Here is an example of using @code{define-minor-mode}:
+
+@smallexample
+(define-minor-mode hungry-mode
+  "Toggle Hungry mode.
+With no argument, this command toggles the mode.
+Non-null prefix argument turns on the mode.
+Null prefix argument turns off the mode.
+
+When Hungry mode is enabled, the control delete key
+gobbles all preceding whitespace except the last.
+See the command \\[hungry-electric-delete]."
+ ;; The initial value.
+ nil
+ ;; The indicator for the mode line.
+ " Hungry"
+ ;; The minor mode bindings.
+ '(("\C-\^?" . hungry-electric-delete))
+ :group 'hunger)
+@end smallexample
+
+@noindent
+This defines a minor mode named ``Hungry mode,'' a command named
+@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
+which indicates whether the mode is enabled, and a variable named
+@code{hungry-mode-map} which holds the keymap that is active when the
+mode is enabled.  It initializes the keymap with a key binding for
+@kbd{C-@key{DEL}}.  It puts the variable @code{hungry-mode} into
+custom group @code{hunger}.  There are no @var{body} forms---many
+minor modes don't need any.
+
+  Here's an equivalent way to write it:
+
+@smallexample
+(define-minor-mode hungry-mode
+  "Toggle Hungry mode.
+With no argument, this command toggles the mode.
+Non-null prefix argument turns on the mode.
+Null prefix argument turns off the mode.
+
+When Hungry mode is enabled, the control delete key
+gobbles all preceding whitespace except the last.
+See the command \\[hungry-electric-delete]."
+ ;; The initial value.
+ :init-value nil
+ ;; The indicator for the mode line.
+ :lighter " Hungry"
+ ;; The minor mode bindings.
+ :keymap
+ '(("\C-\^?" . hungry-electric-delete)
+   ("\C-\M-\^?"
+    . (lambda ()
+        (interactive)
+        (hungry-electric-delete t))))
+ :group 'hunger)
+@end smallexample
+
+@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{}
+This defines a global toggle named @var{global-mode} whose meaning is
+to enable or disable the buffer-local minor mode @var{mode} in all
+buffers.  To turn on the minor mode in a buffer, it uses the function
+@var{turn-on}; to turn off the minor mode, it calls @code{mode} with
+@minus{}1 as argument.
+
+Globally enabling the mode also affects buffers subsequently created
+by visiting files, and buffers that use a major mode other than
+Fundamental mode; but it does not detect the creation of a new buffer
+in Fundamental mode.
+
+This defines the customization option @var{global-mode} (@pxref{Customization}),
+which can be toggled in the Custom interface to turn the minor mode on
+and off.  As with @code{define-minor-mode}, you should ensure that the
+@code{define-globalized-minor-mode} form is evaluated each time Emacs
+starts, for example by providing a @code{:require} keyword.
+
+Use @code{:group @var{group}} in @var{keyword-args} to specify the
+custom group for the mode variable of the global minor mode.
+@end defmac
+
+@node Mode Line Format
+@section Mode-Line Format
+@cindex mode line
+
+  Each Emacs window (aside from minibuffer windows) typically has a mode
+line at the bottom, which displays status information about the buffer
+displayed in the window.  The mode line contains information about the
+buffer, such as its name, associated file, depth of recursive editing,
+and major and minor modes.  A window can also have a @dfn{header
+line}, which is much like the mode line but appears at the top of the
+window.
+
+  This section describes how to control the contents of the mode line
+and header line.  We include it in this chapter because much of the
+information displayed in the mode line relates to the enabled major and
+minor modes.
+
+@menu
+* Base: Mode Line Basics. Basic ideas of mode line control.
+* Data: Mode Line Data.   The data structure that controls the mode line.
+* Top: Mode Line Top.     The top level variable, mode-line-format.
+* Mode Line Variables::   Variables used in that data structure.
+* %-Constructs::          Putting information into a mode line.
+* Properties in Mode::    Using text properties in the mode line.
+* Header Lines::          Like a mode line, but at the top.
+* Emulating Mode Line::   Formatting text as the mode line would.
+@end menu
+
+@node Mode Line Basics
+@subsection Mode Line Basics
+
+  @code{mode-line-format} is a buffer-local variable that holds a
+@dfn{mode line construct}, a kind of template, which controls what is
+displayed on the mode line of the current buffer.  The value of
+@code{header-line-format} specifies the buffer's header line in the
+same way.  All windows for the same buffer use the same
+@code{mode-line-format} and @code{header-line-format}.
+
+  For efficiency, Emacs does not continuously recompute the mode
+line and header line of a window.  It does so when circumstances
+appear to call for it---for instance, if you change the window
+configuration, switch buffers, narrow or widen the buffer, scroll, or
+change the buffer's modification status.  If you modify any of the
+variables referenced by @code{mode-line-format} (@pxref{Mode Line
+Variables}), or any other variables and data structures that affect
+how text is displayed (@pxref{Display}), you may want to force an
+update of the mode line so as to display the new information or
+display it in the new way.
+
+@defun force-mode-line-update &optional all
+Force redisplay of the current buffer's mode line and header line.
+The next redisplay will update the mode line and header line based on
+the latest values of all relevant variables.  With optional
+non-@code{nil} @var{all}, force redisplay of all mode lines and header
+lines.
+
+This function also forces recomputation of the menu bar menus
+and the frame title.
+@end defun
+
+  The selected window's mode line is usually displayed in a different
+color using the face @code{mode-line}.  Other windows' mode lines
+appear in the face @code{mode-line-inactive} instead.  @xref{Faces}.
+
+@node Mode Line Data
+@subsection The Data Structure of the Mode Line
+@cindex mode-line construct
+
+  The mode-line contents are controlled by a data structure called a
+@dfn{mode-line construct}, made up of lists, strings, symbols, and
+numbers kept in buffer-local variables.  Each data type has a specific
+meaning for the mode-line appearance, as described below.  The same
+data structure is used for constructing frame titles (@pxref{Frame
+Titles}) and header lines (@pxref{Header Lines}).
+
+  A mode-line construct may be as simple as a fixed string of text,
+but it usually specifies how to combine fixed strings with variables'
+values to construct the text.  Many of these variables are themselves
+defined to have mode-line constructs as their values.
+
+  Here are the meanings of various data types as mode-line constructs:
+
+@table @code
+@cindex percent symbol in mode line
+@item @var{string}
+A string as a mode-line construct appears verbatim except for
+@dfn{@code{%}-constructs} in it.  These stand for substitution of
+other data; see @ref{%-Constructs}.
+
+If parts of the string have @code{face} properties, they control
+display of the text just as they would text in the buffer.  Any
+characters which have no @code{face} properties are displayed, by
+default, in the face @code{mode-line} or @code{mode-line-inactive}
+(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).  The
+@code{help-echo} and @code{local-map} properties in @var{string} have
+special meanings.  @xref{Properties in Mode}.
+
+@item @var{symbol}
+A symbol as a mode-line construct stands for its value.  The value of
+@var{symbol} is used as a mode-line construct, in place of @var{symbol}.
+However, the symbols @code{t} and @code{nil} are ignored, as is any
+symbol whose value is void.
+
+There is one exception: if the value of @var{symbol} is a string, it is
+displayed verbatim: the @code{%}-constructs are not recognized.
+
+Unless @var{symbol} is marked as ``risky'' (i.e., it has a
+non-@code{nil} @code{risky-local-variable} property), all text
+properties specified in @var{symbol}'s value are ignored.  This
+includes the text properties of strings in @var{symbol}'s value, as
+well as all @code{:eval} and @code{:propertize} forms in it.  (The
+reason for this is security: non-risky variables could be set
+automatically from file variables without prompting the user.)
+
+@item (@var{string} @var{rest}@dots{})
+@itemx (@var{list} @var{rest}@dots{})
+A list whose first element is a string or list means to process all the
+elements recursively and concatenate the results.  This is the most
+common form of mode-line construct.
+
+@item (:eval @var{form})
+A list whose first element is the symbol @code{:eval} says to evaluate
+@var{form}, and use the result as a string to display.  Make sure this
+evaluation cannot load any files, as doing so could cause infinite
+recursion.
+
+@item (:propertize @var{elt} @var{props}@dots{})
+A list whose first element is the symbol @code{:propertize} says to
+process the mode-line construct @var{elt} recursively, then add the text
+properties specified by @var{props} to the result.  The argument
+@var{props} should consist of zero or more pairs @var{text-property}
+@var{value}.  (This feature is new as of Emacs 22.1.)
+
+@item (@var{symbol} @var{then} @var{else})
+A list whose first element is a symbol that is not a keyword specifies
+a conditional.  Its meaning depends on the value of @var{symbol}.  If
+@var{symbol} has a non-@code{nil} value, the second element,
+@var{then}, is processed recursively as a mode-line element.
+Otherwise, the third element, @var{else}, is processed recursively.
+You may omit @var{else}; then the mode-line element displays nothing
+if the value of @var{symbol} is @code{nil} or void.
+
+@item (@var{width} @var{rest}@dots{})
+A list whose first element is an integer specifies truncation or
+padding of the results of @var{rest}.  The remaining elements
+@var{rest} are processed recursively as mode-line constructs and
+concatenated together.  When @var{width} is positive, the result is
+space filled on the right if its width is less than @var{width}.  When
+@var{width} is negative, the result is truncated on the right to
+@minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
+
+For example, the usual way to show what percentage of a buffer is above
+the top of the window is to use a list like this: @code{(-3 "%p")}.
+@end table
+
+@node Mode Line Top
+@subsection The Top Level of Mode Line Control
+
+  The variable in overall control of the mode line is
+@code{mode-line-format}.
+
+@defvar mode-line-format
+The value of this variable is a mode-line construct that controls the
+contents of the mode-line.  It is always buffer-local in all buffers.
+
+If you set this variable to @code{nil} in a buffer, that buffer does
+not have a mode line.  (A window that is just one line tall never
+displays a mode line.)
+@end defvar
+
+  The default value of @code{mode-line-format} is designed to use the
+values of other variables such as @code{mode-line-position} and
+@code{mode-line-modes} (which in turn incorporates the values of the
+variables @code{mode-name} and @code{minor-mode-alist}).  Very few
+modes need to alter @code{mode-line-format} itself.  For most
+purposes, it is sufficient to alter some of the variables that
+@code{mode-line-format} either directly or indirectly refers to.
+
+  If you do alter @code{mode-line-format} itself, the new value should
+use the same variables that appear in the default value (@pxref{Mode
+Line Variables}), rather than duplicating their contents or displaying
+the information in another fashion.  This way, customizations made by
+the user or by Lisp programs (such as @code{display-time} and major
+modes) via changes to those variables remain effective.
+
+  Here is an example of a @code{mode-line-format} that might be
+useful for @code{shell-mode}, since it contains the host name and default
+directory.
+
+@example
+@group
+(setq mode-line-format
+  (list "-"
+   'mode-line-mule-info
+   'mode-line-modified
+   'mode-line-frame-identification
+   "%b--"
+@end group
+@group
+   ;; @r{Note that this is evaluated while making the list.}
+   ;; @r{It makes a mode-line construct which is just a string.}
+   (getenv "HOST")
+@end group
+   ":"
+   'default-directory
+   "   "
+   'global-mode-string
+   "   %[("
+   '(:eval (mode-line-mode-name))
+   'mode-line-process
+   'minor-mode-alist
+   "%n"
+   ")%]--"
+@group
+   '(which-func-mode ("" which-func-format "--"))
+   '(line-number-mode "L%l--")
+   '(column-number-mode "C%c--")
+   '(-3 "%p")
+   "-%-"))
+@end group
+@end example
+
+@noindent
+(The variables @code{line-number-mode}, @code{column-number-mode}
+and @code{which-func-mode} enable particular minor modes; as usual,
+these variable names are also the minor mode command names.)
+
+@node Mode Line Variables
+@subsection Variables Used in the Mode Line
+
+  This section describes variables incorporated by the standard value
+of @code{mode-line-format} into the text of the mode line.  There is
+nothing inherently special about these variables; any other variables
+could have the same effects on the mode line if
+@code{mode-line-format}'s value were changed to use them.  However,
+various parts of Emacs set these variables on the understanding that
+they will control parts of the mode line; therefore, practically
+speaking, it is essential for the mode line to use them.
+
+@defvar mode-line-mule-info
+This variable holds the value of the mode-line construct that displays
+information about the language environment, buffer coding system, and
+current input method.  @xref{Non-ASCII Characters}.
+@end defvar
+
+@defvar mode-line-modified
+This variable holds the value of the mode-line construct that displays
+whether the current buffer is modified.
+
+The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
+This means that the mode line displays @samp{**} if the buffer is
+modified, @samp{--} if the buffer is not modified, @samp{%%} if the
+buffer is read only, and @samp{%*} if the buffer is read only and
+modified.
+
+Changing this variable does not force an update of the mode line.
+@end defvar
+
+@defvar mode-line-frame-identification
+This variable identifies the current frame.  The default value is
+@code{"  "} if you are using a window system which can show multiple
+frames, or @code{"-%F  "} on an ordinary terminal which shows only one
+frame at a time.
+@end defvar
+
+@defvar mode-line-buffer-identification
+This variable identifies the buffer being displayed in the window.  Its
+default value is @code{("%12b")}, which displays the buffer name, padded
+with spaces to at least 12 columns.
+@end defvar
+
+@defvar mode-line-position
+This variable indicates the position in the buffer.  Here is a
+simplified version of its default value.  The actual default value
+also specifies addition of the @code{help-echo} text property.
+
+@example
+@group
+((-3 "%p")
+ (size-indication-mode (8 " of %I"))
+@end group
+@group
+ (line-number-mode
+  ((column-number-mode
+    (10 " (%l,%c)")
+    (6 " L%l")))
+  ((column-number-mode
+    (5 " C%c")))))
+@end group
+@end example
+
+This means that @code{mode-line-position} displays at least the buffer
+percentage and possibly the buffer size, the line number and the column
+number.
+@end defvar
+
+@defvar vc-mode
+The variable @code{vc-mode}, buffer-local in each buffer, records
+whether the buffer's visited file is maintained with version control,
+and, if so, which kind.  Its value is a string that appears in the mode
+line, or @code{nil} for no version control.
+@end defvar
+
+@defvar mode-line-modes
+This variable displays the buffer's major and minor modes.  Here is a
+simplified version of its default value.  The real default value also
+specifies addition of text properties.
+
+@example
+@group
+("%[(" mode-name
+ mode-line-process minor-mode-alist
+ "%n" ")%]--")
+@end group
+@end example
+
+So @code{mode-line-modes} normally also displays the recursive editing
+level, information on the process status and whether narrowing is in
+effect.
+@end defvar
+
+  The following three variables are used in @code{mode-line-modes}:
+
+@defvar mode-name
+This buffer-local variable holds the ``pretty'' name of the current
+buffer's major mode.  Each major mode should set this variable so that the
+mode name will appear in the mode line.
+@end defvar
+
+@defvar mode-line-process
+This buffer-local variable contains the mode-line information on process
+status in modes used for communicating with subprocesses.  It is
+displayed immediately following the major mode name, with no intervening
+space.  For example, its value in the @samp{*shell*} buffer is
+@code{(":%s")}, which allows the shell to display its status along
+with the major mode as: @samp{(Shell:run)}.  Normally this variable
+is @code{nil}.
+@end defvar
+
+@defvar minor-mode-alist
+@anchor{Definition of minor-mode-alist}
+This variable holds an association list whose elements specify how the
+mode line should indicate that a minor mode is active.  Each element of
+the @code{minor-mode-alist} should be a two-element list:
+
+@example
+(@var{minor-mode-variable} @var{mode-line-string})
+@end example
+
+More generally, @var{mode-line-string} can be any mode-line spec.  It
+appears in the mode line when the value of @var{minor-mode-variable}
+is non-@code{nil}, and not otherwise.  These strings should begin with
+spaces so that they don't run together.  Conventionally, the
+@var{minor-mode-variable} for a specific mode is set to a
+non-@code{nil} value when that minor mode is activated.
+
+@code{minor-mode-alist} itself is not buffer-local.  Each variable
+mentioned in the alist should be buffer-local if its minor mode can be
+enabled separately in each buffer.
+@end defvar
+
+@defvar global-mode-string
+This variable holds a mode-line spec that, by default, appears in the
+mode line just after the @code{which-func-mode} minor mode if set,
+else after @code{mode-line-modes}.  The command @code{display-time}
+sets @code{global-mode-string} to refer to the variable
+@code{display-time-string}, which holds a string containing the time
+and load information.
+
+The @samp{%M} construct substitutes the value of
+@code{global-mode-string}, but that is obsolete, since the variable is
+included in the mode line from @code{mode-line-format}.
+@end defvar
+
+  The variable @code{default-mode-line-format} is where
+@code{mode-line-format} usually gets its value:
+
+@defvar default-mode-line-format
+This variable holds the default @code{mode-line-format} for buffers
+that do not override it.  This is the same as @code{(default-value
+'mode-line-format)}.
+
+Here is a simplified version of the default value of
+@code{default-mode-line-format}.  The real default value also
+specifies addition of text properties.
+
+@example
+@group
+("-"
+ mode-line-mule-info
+ mode-line-modified
+ mode-line-frame-identification
+ mode-line-buffer-identification
+@end group
+ "   "
+ mode-line-position
+ (vc-mode vc-mode)
+ "   "
+@group
+ mode-line-modes
+ (which-func-mode ("" which-func-format "--"))
+ (global-mode-string ("--" global-mode-string))
+ "-%-")
+@end group
+@end example
+@end defvar
+
+@node %-Constructs
+@subsection @code{%}-Constructs in the Mode Line
+
+  Strings used as mode-line constructs can use certain
+@code{%}-constructs to substitute various kinds of data.  Here is a
+list of the defined @code{%}-constructs, and what they mean.  In any
+construct except @samp{%%}, you can add a decimal integer after the
+@samp{%} to specify a minimum field width.  If the width is less, the
+field is padded with spaces to the right.
+
+@table @code
+@item %b
+The current buffer name, obtained with the @code{buffer-name} function.
+@xref{Buffer Names}.
+
+@item %c
+The current column number of point.
+
+@item %e
+When Emacs is nearly out of memory for Lisp objects, a brief message
+saying so.  Otherwise, this is empty.
+
+@item %f
+The visited file name, obtained with the @code{buffer-file-name}
+function.  @xref{Buffer File Name}.
+
+@item %F
+The title (only on a window system) or the name of the selected frame.
+@xref{Basic Parameters}.
+
+@item %i
+The size of the accessible part of the current buffer; basically
+@code{(- (point-max) (point-min))}.
+
+@item %I
+Like @samp{%i}, but the size is printed in a more readable way by using
+@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
+abbreviate.
+
+@item %l
+The current line number of point, counting within the accessible portion
+of the buffer.
+
+@item %n
+@samp{Narrow} when narrowing is in effect; nothing otherwise (see
+@code{narrow-to-region} in @ref{Narrowing}).
+
+@item %p
+The percentage of the buffer text above the @strong{top} of window, or
+@samp{Top}, @samp{Bottom} or @samp{All}.  Note that the default
+mode-line specification truncates this to three characters.
+
+@item %P
+The percentage of the buffer text that is above the @strong{bottom} of
+the window (which includes the text visible in the window, as well as
+the text above the top), plus @samp{Top} if the top of the buffer is
+visible on screen; or @samp{Bottom} or @samp{All}.
+
+@item %s
+The status of the subprocess belonging to the current buffer, obtained with
+@code{process-status}.  @xref{Process Information}.
+
+@item %t
+Whether the visited file is a text file or a binary file.  This is a
+meaningful distinction only on certain operating systems (@pxref{MS-DOS
+File Types}).
+
+@item %z
+The mnemonics of keyboard, terminal, and buffer coding systems.
+
+@item %Z
+Like @samp{%z}, but including the end-of-line format.
+
+@item %*
+@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+@samp{-} otherwise.  @xref{Buffer Modification}.
+
+@item %+
+@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+@samp{-} otherwise.  This differs from @samp{%*} only for a modified
+read-only buffer.  @xref{Buffer Modification}.
+
+@item %&
+@samp{*} if the buffer is modified, and @samp{-} otherwise.
+
+@item %[
+An indication of the depth of recursive editing levels (not counting
+minibuffer levels): one @samp{[} for each editing level.
+@xref{Recursive Editing}.
+
+@item %]
+One @samp{]} for each recursive editing level (not counting minibuffer
+levels).
+
+@item %-
+Dashes sufficient to fill the remainder of the mode line.
+
+@item %%
+The character @samp{%}---this is how to include a literal @samp{%} in a
+string in which @code{%}-constructs are allowed.
+@end table
+
+The following two @code{%}-constructs are still supported, but they are
+obsolete, since you can get the same results with the variables
+@code{mode-name} and @code{global-mode-string}.
+
+@table @code
+@item %m
+The value of @code{mode-name}.
+
+@item %M
+The value of @code{global-mode-string}.
+@end table
+
+@node Properties in Mode
+@subsection Properties in the Mode Line
+@cindex text properties in the mode line
+
+  Certain text properties are meaningful in the
+mode line.  The @code{face} property affects the appearance of text; the
+@code{help-echo} property associates help strings with the text, and
+@code{local-map} can make the text mouse-sensitive.
+
+  There are four ways to specify text properties for text in the mode
+line:
+
+@enumerate
+@item
+Put a string with a text property directly into the mode-line data
+structure.
+
+@item
+Put a text property on a mode-line %-construct such as @samp{%12b}; then
+the expansion of the %-construct will have that same text property.
+
+@item
+Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
+give @var{elt} a text property specified by @var{props}.
+
+@item
+Use a list containing @code{:eval @var{form}} in the mode-line data
+structure, and make @var{form} evaluate to a string that has a text
+property.
+@end enumerate
+
+  You can use the @code{local-map} property to specify a keymap.  This
+keymap only takes real effect for mouse clicks; binding character keys
+and function keys to it has no effect, since it is impossible to move
+point into the mode line.
+
+  When the mode line refers to a variable which does not have a
+non-@code{nil} @code{risky-local-variable} property, any text
+properties given or specified within that variable's values are
+ignored.  This is because such properties could otherwise specify
+functions to be called, and those functions could come from file
+local variables.
+
+@node Header Lines
+@subsection Window Header Lines
+@cindex header line (of a window)
+@cindex window header line
+
+  A window can have a @dfn{header line} at the
+top, just as it can have a mode line at the bottom.  The header line
+feature works just like the mode-line feature, except that it's
+controlled by different variables.
+
+@defvar header-line-format
+This variable, local in every buffer, specifies how to display the
+header line, for windows displaying the buffer.  The format of the value
+is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
+@end defvar
+
+@defvar default-header-line-format
+This variable holds the default @code{header-line-format} for buffers
+that do not override it.  This is the same as @code{(default-value
+'header-line-format)}.
+
+It is normally @code{nil}, so that ordinary buffers have no header line.
+@end defvar
+
+  A window that is just one line tall never displays a header line.  A
+window that is two lines tall cannot display both a mode line and a
+header line at once; if it has a mode line, then it does not display a
+header line.
+
+@node Emulating Mode Line
+@subsection Emulating Mode-Line Formatting
+
+  You can use the function @code{format-mode-line} to compute
+the text that would appear in a mode line or header line
+based on a certain mode-line specification.
+
+@defun format-mode-line format &optional face window buffer
+This function formats a line of text according to @var{format} as if
+it were generating the mode line for @var{window}, but instead of
+displaying the text in the mode line or the header line, it returns
+the text as a string.  The argument @var{window} defaults to the
+selected window.  If @var{buffer} is non-@code{nil}, all the
+information used is taken from @var{buffer}; by default, it comes from
+@var{window}'s buffer.
+
+The value string normally has text properties that correspond to the
+faces, keymaps, etc., that the mode line would have.  And any character
+for which no @code{face} property is specified gets a default
+value which is usually @var{face}.  (If @var{face} is @code{t},
+that stands for either @code{mode-line} if @var{window} is selected,
+otherwise @code{mode-line-inactive}.  If @var{face} is @code{nil} or
+omitted, that stands for no face property.)
+
+However, if @var{face} is an integer, the value has no text properties.
+
+For example, @code{(format-mode-line header-line-format)} returns the
+text that would appear in the selected window's header line (@code{""}
+if it has no header line).  @code{(format-mode-line header-line-format
+'header-line)} returns the same text, with each character
+carrying the face that it will have in the header line itself.
+@end defun
+
+@node Imenu
+@section Imenu
+
+@cindex Imenu
+  @dfn{Imenu} is a feature that lets users select a definition or
+section in the buffer, from a menu which lists all of them, to go
+directly to that location in the buffer.  Imenu works by constructing
+a buffer index which lists the names and buffer positions of the
+definitions, or other named portions of the buffer; then the user can
+choose one of them and move point to it.  Major modes can add a menu
+bar item to use Imenu using @code{imenu-add-to-menubar}.
+
+@defun imenu-add-to-menubar name
+This function defines a local menu bar item named @var{name}
+to run Imenu.
+@end defun
+
+  The user-level commands for using Imenu are described in the Emacs
+Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}).  This section
+explains how to customize Imenu's method of finding definitions or
+buffer portions for a particular major mode.
+
+  The usual and simplest way is to set the variable
+@code{imenu-generic-expression}:
+
+@defvar imenu-generic-expression
+This variable, if non-@code{nil}, is a list that specifies regular
+expressions for finding definitions for Imenu.  Simple elements of
+@code{imenu-generic-expression} look like this:
+
+@example
+(@var{menu-title} @var{regexp} @var{index})
+@end example
+
+Here, if @var{menu-title} is non-@code{nil}, it says that the matches
+for this element should go in a submenu of the buffer index;
+@var{menu-title} itself specifies the name for the submenu.  If
+@var{menu-title} is @code{nil}, the matches for this element go directly
+in the top level of the buffer index.
+
+The second item in the list, @var{regexp}, is a regular expression
+(@pxref{Regular Expressions}); anything in the buffer that it matches
+is considered a definition, something to mention in the buffer index.
+The third item, @var{index}, is a non-negative integer that indicates
+which subexpression in @var{regexp} matches the definition's name.
+
+An element can also look like this:
+
+@example
+(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
+@end example
+
+Each match for this element creates an index item, and when the index
+item is selected by the user, it calls @var{function} with arguments
+consisting of the item name, the buffer position, and @var{arguments}.
+
+For Emacs Lisp mode, @code{imenu-generic-expression} could look like
+this:
+
+@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
+@example
+@group
+((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
+\\s-+\\([-A-Za-z0-9+]+\\)" 2)
+@end group
+@group
+ ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
+\\s-+\\([-A-Za-z0-9+]+\\)" 2)
+@end group
+@group
+ ("*Types*"
+  "^\\s-*\
+(def\\(type\\|struct\\|class\\|ine-condition\\)\
+\\s-+\\([-A-Za-z0-9+]+\\)" 2))
+@end group
+@end example
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-case-fold-search
+This variable controls whether matching against the regular
+expressions in the value of @code{imenu-generic-expression} is
+case-sensitive: @code{t}, the default, means matching should ignore
+case.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-syntax-alist
+This variable is an alist of syntax table modifiers to use while
+processing @code{imenu-generic-expression}, to override the syntax table
+of the current buffer.  Each element should have this form:
+
+@example
+(@var{characters} . @var{syntax-description})
+@end example
+
+The @sc{car}, @var{characters}, can be either a character or a string.
+The element says to give that character or characters the syntax
+specified by @var{syntax-description}, which is passed to
+@code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
+
+This feature is typically used to give word syntax to characters which
+normally have symbol syntax, and thus to simplify
+@code{imenu-generic-expression} and speed up matching.
+For example, Fortran mode uses it this way:
+
+@example
+(setq imenu-syntax-alist '(("_$" . "w")))
+@end example
+
+The @code{imenu-generic-expression} regular expressions can then use
+@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this
+technique may be inconvenient when the mode needs to limit the initial
+character of a name to a smaller set of characters than are allowed in
+the rest of a name.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+  Another way to customize Imenu for a major mode is to set the
+variables @code{imenu-prev-index-position-function} and
+@code{imenu-extract-index-name-function}:
+
+@defvar imenu-prev-index-position-function
+If this variable is non-@code{nil}, its value should be a function that
+finds the next ``definition'' to put in the buffer index, scanning
+backward in the buffer from point.  It should return @code{nil} if it
+doesn't find another ``definition'' before point.  Otherwise it should
+leave point at the place it finds a ``definition'' and return any
+non-@code{nil} value.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-extract-index-name-function
+If this variable is non-@code{nil}, its value should be a function to
+return the name for a definition, assuming point is in that definition
+as the @code{imenu-prev-index-position-function} function would leave
+it.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+  The last way to customize Imenu for a major mode is to set the
+variable @code{imenu-create-index-function}:
+
+@defvar imenu-create-index-function
+This variable specifies the function to use for creating a buffer
+index.  The function should take no arguments, and return an index
+alist for the current buffer.  It is called within
+@code{save-excursion}, so where it leaves point makes no difference.
+
+The index alist can have three types of elements.  Simple elements
+look like this:
+
+@example
+(@var{index-name} . @var{index-position})
+@end example
+
+Selecting a simple element has the effect of moving to position
+@var{index-position} in the buffer.  Special elements look like this:
+
+@example
+(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
+@end example
+
+Selecting a special element performs:
+
+@example
+(funcall @var{function}
+         @var{index-name} @var{index-position} @var{arguments}@dots{})
+@end example
+
+A nested sub-alist element looks like this:
+
+@example
+(@var{menu-title} @var{sub-alist})
+@end example
+
+It creates the submenu @var{menu-title} specified by @var{sub-alist}.
+
+The default value of @code{imenu-create-index-function} is
+@code{imenu-default-create-index-function}.  This function calls the
+value of @code{imenu-prev-index-position-function} and the value of
+@code{imenu-extract-index-name-function} to produce the index alist.
+However, if either of these two variables is @code{nil}, the default
+function uses @code{imenu-generic-expression} instead.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@node Font Lock Mode
+@section Font Lock Mode
+@cindex Font Lock mode
+
+  @dfn{Font Lock mode} is a feature that automatically attaches
+@code{face} properties to certain parts of the buffer based on their
+syntactic role.  How it parses the buffer depends on the major mode;
+most major modes define syntactic criteria for which faces to use in
+which contexts.  This section explains how to customize Font Lock for a
+particular major mode.
+
+  Font Lock mode finds text to highlight in two ways: through
+syntactic parsing based on the syntax table, and through searching
+(usually for regular expressions).  Syntactic fontification happens
+first; it finds comments and string constants and highlights them.
+Search-based fontification happens second.
+
+@menu
+* Font Lock Basics::            Overview of customizing Font Lock.
+* Search-based Fontification::  Fontification based on regexps.
+* Customizing Keywords::        Customizing search-based fontification.
+* Other Font Lock Variables::   Additional customization facilities.
+* Levels of Font Lock::         Each mode can define alternative levels
+                                  so that the user can select more or less.
+* Precalculated Fontification:: How Lisp programs that produce the buffer
+                                  contents can also specify how to fontify it.
+* Faces for Font Lock::         Special faces specifically for Font Lock.
+* Syntactic Font Lock::         Fontification based on syntax tables.
+* Setting Syntax Properties::   Defining character syntax based on context
+                                  using the Font Lock mechanism.
+* Multiline Font Lock::         How to coerce Font Lock into properly
+                                  highlighting multiline constructs.
+@end menu
+
+@node Font Lock Basics
+@subsection Font Lock Basics
+
+  There are several variables that control how Font Lock mode highlights
+text.  But major modes should not set any of these variables directly.
+Instead, they should set @code{font-lock-defaults} as a buffer-local
+variable.  The value assigned to this variable is used, if and when Font
+Lock mode is enabled, to set all the other variables.
+
+@defvar font-lock-defaults
+This variable is set by major modes, as a buffer-local variable, to
+specify how to fontify text in that mode.  It automatically becomes
+buffer-local when you set it.  If its value is @code{nil}, Font-Lock
+mode does no highlighting, and you can use the @samp{Faces} menu
+(under @samp{Edit} and then @samp{Text Properties} in the menu bar) to
+assign faces explicitly to text in the buffer.
+
+If non-@code{nil}, the value should look like this:
+
+@example
+(@var{keywords} [@var{keywords-only} [@var{case-fold}
+ [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
+@end example
+
+The first element, @var{keywords}, indirectly specifies the value of
+@code{font-lock-keywords} which directs search-based fontification.
+It can be a symbol, a variable or a function whose value is the list
+to use for @code{font-lock-keywords}.  It can also be a list of
+several such symbols, one for each possible level of fontification.
+The first symbol specifies how to do level 1 fontification, the second
+symbol how to do level 2, and so on.  @xref{Levels of Font Lock}.
+
+The second element, @var{keywords-only}, specifies the value of the
+variable @code{font-lock-keywords-only}.  If this is omitted or
+@code{nil}, syntactic fontification (of strings and comments) is also
+performed.  If this is non-@code{nil}, such fontification is not
+performed.  @xref{Syntactic Font Lock}.
+
+The third element, @var{case-fold}, specifies the value of
+@code{font-lock-keywords-case-fold-search}.  If it is non-@code{nil},
+Font Lock mode ignores case when searching as directed by
+@code{font-lock-keywords}.
+
+If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
+should be a list of cons cells of the form @code{(@var{char-or-string}
+. @var{string})}.  These are used to set up a syntax table for
+syntactic fontification (@pxref{Syntax Table Functions}).  The
+resulting syntax table is stored in @code{font-lock-syntax-table}.
+
+The fifth element, @var{syntax-begin}, specifies the value of
+@code{font-lock-beginning-of-syntax-function}.  We recommend setting
+this variable to @code{nil} and using @code{syntax-begin-function}
+instead.
+
+All the remaining elements (if any) are collectively called
+@var{other-vars}.  Each of these elements should have the form
+@code{(@var{variable} . @var{value})}---which means, make
+@var{variable} buffer-local and then set it to @var{value}.  You can
+use these @var{other-vars} to set other variables that affect
+fontification, aside from those you can control with the first five
+elements.  @xref{Other Font Lock Variables}.
+@end defvar
+
+  If your mode fontifies text explicitly by adding
+@code{font-lock-face} properties, it can specify @code{(nil t)} for
+@code{font-lock-defaults} to turn off all automatic fontification.
+However, this is not required; it is possible to fontify some things
+using @code{font-lock-face} properties and set up automatic
+fontification for other parts of the text.
+
+@node Search-based Fontification
+@subsection Search-based Fontification
+
+  The most important variable for customizing Font Lock mode is
+@code{font-lock-keywords}.  It specifies the search criteria for
+search-based fontification.  You should specify the value of this
+variable with @var{keywords} in @code{font-lock-defaults}.
+
+@defvar font-lock-keywords
+This variable's value is a list of the keywords to highlight.  Be
+careful when composing regular expressions for this list; a poorly
+written pattern can dramatically slow things down!
+@end defvar
+
+  Each element of @code{font-lock-keywords} specifies how to find
+certain cases of text, and how to highlight those cases.  Font Lock mode
+processes the elements of @code{font-lock-keywords} one by one, and for
+each element, it finds and handles all matches.  Ordinarily, once
+part of the text has been fontified already, this cannot be overridden
+by a subsequent match in the same text; but you can specify different
+behavior using the @var{override} element of a @var{subexp-highlighter}.
+
+  Each element of @code{font-lock-keywords} should have one of these
+forms:
+
+@table @code
+@item @var{regexp}
+Highlight all matches for @var{regexp} using
+@code{font-lock-keyword-face}.  For example,
+
+@example
+;; @r{Highlight occurrences of the word @samp{foo}}
+;; @r{using @code{font-lock-keyword-face}.}
+"\\<foo\\>"
+@end example
+
+The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful
+for calculating optimal regular expressions to match a number of
+different keywords.
+
+@item @var{function}
+Find text by calling @var{function}, and highlight the matches
+it finds using @code{font-lock-keyword-face}.
+
+When @var{function} is called, it receives one argument, the limit of
+the search; it should begin searching at point, and not search beyond the
+limit.  It should return non-@code{nil} if it succeeds, and set the
+match data to describe the match that was found.  Returning @code{nil}
+indicates failure of the search.
+
+Fontification will call @var{function} repeatedly with the same limit,
+and with point where the previous invocation left it, until
+@var{function} fails.  On failure, @var{function} need not reset point
+in any particular way.
+
+@item (@var{matcher} . @var{subexp})
+In this kind of element, @var{matcher} is either a regular
+expression or a function, as described above.  The @sc{cdr},
+@var{subexp}, specifies which subexpression of @var{matcher} should be
+highlighted (instead of the entire text that @var{matcher} matched).
+
+@example
+;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
+;; @r{using @code{font-lock-keyword-face}.}
+("fu\\(bar\\)" . 1)
+@end example
+
+If you use @code{regexp-opt} to produce the regular expression
+@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
+Functions}) to calculate the value for @var{subexp}.
+
+@item (@var{matcher} . @var{facespec})
+In this kind of element, @var{facespec} is an expression whose value
+specifies the face to use for highlighting.  In the simplest case,
+@var{facespec} is a Lisp variable (a symbol) whose value is a face
+name.
+
+@example
+;; @r{Highlight occurrences of @samp{fubar},}
+;; @r{using the face which is the value of @code{fubar-face}.}
+("fubar" . fubar-face)
+@end example
+
+However, @var{facespec} can also evaluate to a list of this form:
+
+@example
+(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
+@end example
+
+@noindent
+to specify the face @var{face} and various additional text properties
+to put on the text that matches.  If you do this, be sure to add the
+other text property names that you set in this way to the value of
+@code{font-lock-extra-managed-props} so that the properties will also
+be cleared out when they are no longer appropriate.  Alternatively,
+you can set the variable @code{font-lock-unfontify-region-function} to
+a function that clears these properties.  @xref{Other Font Lock
+Variables}.
+
+@item (@var{matcher} . @var{subexp-highlighter})
+In this kind of element, @var{subexp-highlighter} is a list
+which specifies how to highlight matches found by @var{matcher}.
+It has the form:
+
+@example
+(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
+@end example
+
+The @sc{car}, @var{subexp}, is an integer specifying which subexpression
+of the match to fontify (0 means the entire matching text).  The second
+subelement, @var{facespec}, is an expression whose value specifies the
+face, as described above.
+
+The last two values in @var{subexp-highlighter}, @var{override} and
+@var{laxmatch}, are optional flags.  If @var{override} is @code{t},
+this element can override existing fontification made by previous
+elements of @code{font-lock-keywords}.  If it is @code{keep}, then
+each character is fontified if it has not been fontified already by
+some other element.  If it is @code{prepend}, the face specified by
+@var{facespec} is added to the beginning of the @code{font-lock-face}
+property.  If it is @code{append}, the face is added to the end of the
+@code{font-lock-face} property.
+
+If @var{laxmatch} is non-@code{nil}, it means there should be no error
+if there is no subexpression numbered @var{subexp} in @var{matcher}.
+Obviously, fontification of the subexpression numbered @var{subexp} will
+not occur.  However, fontification of other subexpressions (and other
+regexps) will continue.  If @var{laxmatch} is @code{nil}, and the
+specified subexpression is missing, then an error is signaled which
+terminates search-based fontification.
+
+Here are some examples of elements of this kind, and what they do:
+
+@smallexample
+;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
+;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
+;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
+("foo\\|bar" 0 foo-bar-face t)
+
+;; @r{Highlight the first subexpression within each occurrence}
+;; @r{that the function @code{fubar-match} finds,}
+;; @r{using the face which is the value of @code{fubar-face}.}
+(fubar-match 1 fubar-face)
+@end smallexample
+
+@item (@var{matcher} . @var{anchored-highlighter})
+In this kind of element, @var{anchored-highlighter} specifies how to
+highlight text that follows a match found by @var{matcher}.  So a
+match found by @var{matcher} acts as the anchor for further searches
+specified by @var{anchored-highlighter}.  @var{anchored-highlighter}
+is a list of the following form:
+
+@example
+(@var{anchored-matcher} @var{pre-form} @var{post-form}
+                        @var{subexp-highlighters}@dots{})
+@end example
+
+Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
+expression or a function.  After a match of @var{matcher} is found,
+point is at the end of the match.  Now, Font Lock evaluates the form
+@var{pre-form}.  Then it searches for matches of
+@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
+these.  A @var{subexp-highlighter} is as described above.  Finally,
+Font Lock evaluates @var{post-form}.
+
+The forms @var{pre-form} and @var{post-form} can be used to initialize
+before, and cleanup after, @var{anchored-matcher} is used.  Typically,
+@var{pre-form} is used to move point to some position relative to the
+match of @var{matcher}, before starting with @var{anchored-matcher}.
+@var{post-form} might be used to move back, before resuming with
+@var{matcher}.
+
+After Font Lock evaluates @var{pre-form}, it does not search for
+@var{anchored-matcher} beyond the end of the line.  However, if
+@var{pre-form} returns a buffer position that is greater than the
+position of point after @var{pre-form} is evaluated, then the position
+returned by @var{pre-form} is used as the limit of the search instead.
+It is generally a bad idea to return a position greater than the end
+of the line; in other words, the @var{anchored-matcher} search should
+not span lines.
+
+For example,
+
+@smallexample
+;; @r{Highlight occurrences of the word @samp{item} following}
+;; @r{an occurrence of the word @samp{anchor} (on the same line)}
+;; @r{in the value of @code{item-face}.}
+("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
+@end smallexample
+
+Here, @var{pre-form} and @var{post-form} are @code{nil}.  Therefore
+searching for @samp{item} starts at the end of the match of
+@samp{anchor}, and searching for subsequent instances of @samp{anchor}
+resumes from where searching for @samp{item} concluded.
+
+@item (@var{matcher} @var{highlighters}@dots{})
+This sort of element specifies several @var{highlighter} lists for a
+single @var{matcher}.  A @var{highlighter} list can be of the type
+@var{subexp-highlighter} or @var{anchored-highlighter} as described
+above.
+
+For example,
+
+@smallexample
+;; @r{Highlight occurrences of the word @samp{anchor} in the value}
+;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
+;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
+("\\<anchor\\>" (0 anchor-face)
+                ("\\<item\\>" nil nil (0 item-face)))
+@end smallexample
+
+@item (eval . @var{form})
+Here @var{form} is an expression to be evaluated the first time
+this value of @code{font-lock-keywords} is used in a buffer.
+Its value should have one of the forms described in this table.
+@end table
+
+@strong{Warning:} Do not design an element of @code{font-lock-keywords}
+to match text which spans lines; this does not work reliably.
+For details, see @xref{Multiline Font Lock}.
+
+You can use @var{case-fold} in @code{font-lock-defaults} to specify
+the value of @code{font-lock-keywords-case-fold-search} which says
+whether search-based fontification should be case-insensitive.
+
+@defvar font-lock-keywords-case-fold-search
+Non-@code{nil} means that regular expression matching for the sake of
+@code{font-lock-keywords} should be case-insensitive.
+@end defvar
+
+@node Customizing Keywords
+@subsection Customizing Search-Based Fontification
+
+  You can use @code{font-lock-add-keywords} to add additional
+search-based fontification rules to a major mode, and
+@code{font-lock-remove-keywords} to removes rules.
+
+@defun font-lock-add-keywords mode keywords &optional how
+This function adds highlighting @var{keywords}, for the current buffer
+or for major mode @var{mode}.  The argument @var{keywords} should be a
+list with the same format as the variable @code{font-lock-keywords}.
+
+If @var{mode} is a symbol which is a major mode command name, such as
+@code{c-mode}, the effect is that enabling Font Lock mode in
+@var{mode} will add @var{keywords} to @code{font-lock-keywords}.
+Calling with a non-@code{nil} value of @var{mode} is correct only in
+your @file{~/.emacs} file.
+
+If @var{mode} is @code{nil}, this function adds @var{keywords} to
+@code{font-lock-keywords} in the current buffer.  This way of calling
+@code{font-lock-add-keywords} is usually used in mode hook functions.
+
+By default, @var{keywords} are added at the beginning of
+@code{font-lock-keywords}.  If the optional argument @var{how} is
+@code{set}, they are used to replace the value of
+@code{font-lock-keywords}.  If @var{how} is any other non-@code{nil}
+value, they are added at the end of @code{font-lock-keywords}.
+
+Some modes provide specialized support you can use in additional
+highlighting patterns.  See the variables
+@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
+and @code{java-font-lock-extra-types}, for example.
+
+@strong{Warning:} major mode functions must not call
+@code{font-lock-add-keywords} under any circumstances, either directly
+or indirectly, except through their mode hooks.  (Doing so would lead
+to incorrect behavior for some minor modes.)  They should set up their
+rules for search-based fontification by setting
+@code{font-lock-keywords}.
+@end defun
+
+@defun font-lock-remove-keywords mode keywords
+This function removes @var{keywords} from @code{font-lock-keywords}
+for the current buffer or for major mode @var{mode}.  As in
+@code{font-lock-add-keywords}, @var{mode} should be a major mode
+command name or @code{nil}.  All the caveats and requirements for
+@code{font-lock-add-keywords} apply here too.
+@end defun
+
+  For example, this code
+
+@smallexample
+(font-lock-add-keywords 'c-mode
+ '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
+   ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
+@end smallexample
+
+@noindent
+adds two fontification patterns for C mode: one to fontify the word
+@samp{FIXME}, even in comments, and another to fontify the words
+@samp{and}, @samp{or} and @samp{not} as keywords.
+
+@noindent
+That example affects only C mode proper.  To add the same patterns to
+C mode @emph{and} all modes derived from it, do this instead:
+
+@smallexample
+(add-hook 'c-mode-hook
+ (lambda ()
+  (font-lock-add-keywords nil
+   '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
+     ("\\<\\(and\\|or\\|not\\)\\>" .
+      font-lock-keyword-face)))))
+@end smallexample
+
+@node Other Font Lock Variables
+@subsection Other Font Lock Variables
+
+  This section describes additional variables that a major mode can
+set by means of @var{other-vars} in @code{font-lock-defaults}
+(@pxref{Font Lock Basics}).
+
+@defvar font-lock-mark-block-function
+If this variable is non-@code{nil}, it should be a function that is
+called with no arguments, to choose an enclosing range of text for
+refontification for the command @kbd{M-o M-o}
+(@code{font-lock-fontify-block}).
+
+The function should report its choice by placing the region around it.
+A good choice is a range of text large enough to give proper results,
+but not too large so that refontification becomes slow.  Typical values
+are @code{mark-defun} for programming modes or @code{mark-paragraph} for
+textual modes.
+@end defvar
+
+@defvar font-lock-extra-managed-props
+This variable specifies additional properties (other than
+@code{font-lock-face}) that are being managed by Font Lock mode.  It
+is used by @code{font-lock-default-unfontify-region}, which normally
+only manages the @code{font-lock-face} property.  If you want Font
+Lock to manage other properties as well, you must specify them in a
+@var{facespec} in @code{font-lock-keywords} as well as add them to
+this list.  @xref{Search-based Fontification}.
+@end defvar
+
+@defvar font-lock-fontify-buffer-function
+Function to use for fontifying the buffer.  The default value is
+@code{font-lock-default-fontify-buffer}.
+@end defvar
+
+@defvar font-lock-unfontify-buffer-function
+Function to use for unfontifying the buffer.  This is used when
+turning off Font Lock mode.  The default value is
+@code{font-lock-default-unfontify-buffer}.
+@end defvar
+
+@defvar font-lock-fontify-region-function
+Function to use for fontifying a region.  It should take two
+arguments, the beginning and end of the region, and an optional third
+argument @var{verbose}.  If @var{verbose} is non-@code{nil}, the
+function should print status messages.  The default value is
+@code{font-lock-default-fontify-region}.
+@end defvar
+
+@defvar font-lock-unfontify-region-function
+Function to use for unfontifying a region.  It should take two
+arguments, the beginning and end of the region.  The default value is
+@code{font-lock-default-unfontify-region}.
+@end defvar
+
+@ignore
+@defvar font-lock-inhibit-thing-lock
+List of Font Lock mode related modes that should not be turned on.
+Currently, valid mode names are @code{fast-lock-mode},
+@code{jit-lock-mode} and @code{lazy-lock-mode}.
+@end defvar
+@end ignore
+
+@node Levels of Font Lock
+@subsection Levels of Font Lock
+
+  Many major modes offer three different levels of fontification.  You
+can define multiple levels by using a list of symbols for @var{keywords}
+in @code{font-lock-defaults}.  Each symbol specifies one level of
+fontification; it is up to the user to choose one of these levels.  The
+chosen level's symbol value is used to initialize
+@code{font-lock-keywords}.
+
+  Here are the conventions for how to define the levels of
+fontification:
+
+@itemize @bullet
+@item
+Level 1: highlight function declarations, file directives (such as include or
+import directives), strings and comments.  The idea is speed, so only
+the most important and top-level components are fontified.
+
+@item
+Level 2: in addition to level 1, highlight all language keywords,
+including type names that act like keywords, as well as named constant
+values.  The idea is that all keywords (either syntactic or semantic)
+should be fontified appropriately.
+
+@item
+Level 3: in addition to level 2, highlight the symbols being defined in
+function and variable declarations, and all builtin function names,
+wherever they appear.
+@end itemize
+
+@node Precalculated Fontification
+@subsection Precalculated Fontification
+
+  In addition to using @code{font-lock-defaults} for search-based
+fontification, you may use the special character property
+@code{font-lock-face} (@pxref{Special Properties}).  This property
+acts just like the explicit @code{face} property, but its activation
+is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
+@code{font-lock-face} is especially convenient for special modes
+which construct their text programmatically, such as
+@code{list-buffers} and @code{occur}.
+
+If your mode does not use any of the other machinery of Font Lock
+(i.e. it only uses the @code{font-lock-face} property), it should not
+set the variable @code{font-lock-defaults}.
+
+@node Faces for Font Lock
+@subsection Faces for Font Lock
+@cindex faces for font lock
+@cindex font lock faces
+
+  You can make Font Lock mode use any face, but several faces are
+defined specifically for Font Lock mode.  Each of these symbols is both
+a face name, and a variable whose default value is the symbol itself.
+Thus, the default value of @code{font-lock-comment-face} is
+@code{font-lock-comment-face}.  This means you can write
+@code{font-lock-comment-face} in a context such as
+@code{font-lock-keywords} where a face-name-valued expression is used.
+
+@table @code
+@item font-lock-comment-face
+@vindex font-lock-comment-face
+Used (typically) for comments.
+
+@item font-lock-comment-delimiter-face
+@vindex font-lock-comment-delimiter-face
+Used (typically) for comments delimiters.
+
+@item font-lock-doc-face
+@vindex font-lock-doc-face
+Used (typically) for documentation strings in the code.
+
+@item font-lock-string-face
+@vindex font-lock-string-face
+Used (typically) for string constants.
+
+@item font-lock-keyword-face
+@vindex font-lock-keyword-face
+Used (typically) for keywords---names that have special syntactic
+significance, like @code{for} and @code{if} in C.
+
+@item font-lock-builtin-face
+@vindex font-lock-builtin-face
+Used (typically) for built-in function names.
+
+@item font-lock-function-name-face
+@vindex font-lock-function-name-face
+Used (typically) for the name of a function being defined or declared,
+in a function definition or declaration.
+
+@item font-lock-variable-name-face
+@vindex font-lock-variable-name-face
+Used (typically) for the name of a variable being defined or declared,
+in a variable definition or declaration.
+
+@item font-lock-type-face
+@vindex font-lock-type-face
+Used (typically) for names of user-defined data types,
+where they are defined and where they are used.
+
+@item font-lock-constant-face
+@vindex font-lock-constant-face
+Used (typically) for constant names.
+
+@item font-lock-preprocessor-face
+@vindex font-lock-preprocessor-face
+Used (typically) for preprocessor commands.
+
+@item font-lock-negation-char-face
+@vindex font-lock-negation-char-face
+Used (typically) for easily-overlooked negation characters.
+
+@item font-lock-warning-face
+@vindex font-lock-warning-face
+Used (typically) for constructs that are peculiar, or that greatly
+change the meaning of other text.  For example, this is used for
+@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
+directives in C.
+@end table
+
+@node Syntactic Font Lock
+@subsection Syntactic Font Lock
+@cindex syntactic font lock
+
+Syntactic fontification uses the syntax table to find comments and
+string constants (@pxref{Syntax Tables}).  It highlights them using
+@code{font-lock-comment-face} and @code{font-lock-string-face}
+(@pxref{Faces for Font Lock}), or whatever
+@code{font-lock-syntactic-face-function} chooses.  There are several
+variables that affect syntactic fontification; you should set them by
+means of @code{font-lock-defaults} (@pxref{Font Lock Basics}).
+
+@defvar font-lock-keywords-only
+Non-@code{nil} means Font Lock should not do syntactic fontification;
+it should only fontify based on @code{font-lock-keywords}.  The normal
+way for a mode to set this variable to @code{t} is with
+@var{keywords-only} in @code{font-lock-defaults}.
+@end defvar
+
+@defvar font-lock-syntax-table
+This variable holds the syntax table to use for fontification of
+comments and strings.  Specify it using @var{syntax-alist} in
+@code{font-lock-defaults}.  If this is @code{nil}, fontification uses
+the buffer's syntax table.
+@end defvar
+
+@defvar font-lock-beginning-of-syntax-function
+If this variable is non-@code{nil}, it should be a function to move
+point back to a position that is syntactically at ``top level'' and
+outside of strings or comments.  Font Lock uses this when necessary
+to get the right results for syntactic fontification.
+
+This function is called with no arguments.  It should leave point at
+the beginning of any enclosing syntactic block.  Typical values are
+@code{beginning-of-line} (used when the start of the line is known to
+be outside a syntactic block), or @code{beginning-of-defun} for
+programming modes, or @code{backward-paragraph} for textual modes.
+
+If the value is @code{nil}, Font Lock uses
+@code{syntax-begin-function} to move back outside of any comment,
+string, or sexp.  This variable is semi-obsolete; we recommend setting
+@code{syntax-begin-function} instead.
+
+Specify this variable using @var{syntax-begin} in
+@code{font-lock-defaults}.
+@end defvar
+
+@defvar font-lock-syntactic-face-function
+A function to determine which face to use for a given syntactic
+element (a string or a comment).  The function is called with one
+argument, the parse state at point returned by
+@code{parse-partial-sexp}, and should return a face.  The default
+value returns @code{font-lock-comment-face} for comments and
+@code{font-lock-string-face} for strings.
+
+This can be used to highlighting different kinds of strings or
+comments differently.  It is also sometimes abused together with
+@code{font-lock-syntactic-keywords} to highlight constructs that span
+multiple lines, but this is too esoteric to document here.
+
+Specify this variable using @var{other-vars} in
+@code{font-lock-defaults}.
+@end defvar
+
+@node Setting Syntax Properties
+@subsection Setting Syntax Properties
+
+  Font Lock mode can be used to update @code{syntax-table} properties
+automatically (@pxref{Syntax Properties}).  This is useful in
+languages for which a single syntax table by itself is not sufficient.
+
+@defvar font-lock-syntactic-keywords
+This variable enables and controls updating @code{syntax-table}
+properties by Font Lock.  Its value should be a list of elements of
+this form:
+
+@example
+(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
+@end example
+
+The parts of this element have the same meanings as in the corresponding
+sort of element of @code{font-lock-keywords},
+
+@example
+(@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
+@end example
+
+However, instead of specifying the value @var{facespec} to use for the
+@code{face} property, it specifies the value @var{syntax} to use for
+the @code{syntax-table} property.  Here, @var{syntax} can be a string
+(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
+(as returned by @code{string-to-syntax}), or an expression whose value
+is one of those two types.  @var{override} cannot be @code{prepend} or
+@code{append}.
+
+For example, an element of the form:
+
+@example
+("\\$\\(#\\)" 1 ".")
+@end example
+
+highlights syntactically a hash character when following a dollar
+character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
+Assuming that the buffer syntax table specifies hash characters to
+have comment start syntax, the element will only highlight hash
+characters that do not follow dollar characters as comments
+syntactically.
+
+An element of the form:
+
+@example
+ ("\\('\\).\\('\\)"
+  (1 "\"")
+  (2 "\""))
+@end example
+
+highlights syntactically both single quotes which surround a single
+character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
+Assuming that the buffer syntax table does not specify single quotes
+to have quote syntax, the element will only highlight single quotes of
+the form @samp{'@var{c}'} as strings syntactically.  Other forms, such
+as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
+strings.
+
+Major modes normally set this variable with @var{other-vars} in
+@code{font-lock-defaults}.
+@end defvar
+
+@node Multiline Font Lock
+@subsection Multiline Font Lock Constructs
+@cindex multiline font lock
+
+  Normally, elements of @code{font-lock-keywords} should not match
+across multiple lines; that doesn't work reliably, because Font Lock
+usually scans just part of the buffer, and it can miss a multi-line
+construct that crosses the line boundary where the scan starts.  (The
+scan normally starts at the beginning of a line.)
+
+  Making elements that match multiline constructs work properly has
+two aspects: correct @emph{identification} and correct
+@emph{rehighlighting}.  The first means that Font Lock finds all
+multiline constructs.  The second means that Font Lock will correctly
+rehighlight all the relevant text when a multiline construct is
+changed---for example, if some of the text that was previously part of
+a multiline construct ceases to be part of it.  The two aspects are
+closely related, and often getting one of them to work will appear to
+make the other also work.  However, for reliable results you must
+attend explicitly to both aspects.
+
+  There are three ways to ensure correct identification of multiline
+constructs:
+
+@itemize
+@item
+Add a function to @code{font-lock-extend-region-functions} that does
+the @emph{identification} and extends the scan so that the scanned
+text never starts or ends in the middle of a multiline construct.
+@item
+Use the @code{font-lock-fontify-region-function} hook similarly to
+extend the scan so that the scanned text never starts or ends in the
+middle of a multiline construct.
+@item
+Somehow identify the multiline construct right when it gets inserted
+into the buffer (or at any point after that but before font-lock
+tries to highlight it), and mark it with a @code{font-lock-multiline}
+which will instruct font-lock not to start or end the scan in the
+middle of the construct.
+@end itemize
+
+  There are three ways to do rehighlighting of multiline constructs:
+
+@itemize
+@item
+Place a @code{font-lock-multiline} property on the construct.  This
+will rehighlight the whole construct if any part of it is changed.  In
+some cases you can do this automatically by setting the
+@code{font-lock-multiline} variable, which see.
+@item
+Make sure @code{jit-lock-contextually} is set and rely on it doing its
+job.  This will only rehighlight the part of the construct that
+follows the actual change, and will do it after a short delay.
+This only works if the highlighting of the various parts of your
+multiline construct never depends on text in subsequent lines.
+Since @code{jit-lock-contextually} is activated by default, this can
+be an attractive solution.
+@item
+Place a @code{jit-lock-defer-multiline} property on the construct.
+This works only if @code{jit-lock-contextually} is used, and with the
+same delay before rehighlighting, but like @code{font-lock-multiline},
+it also handles the case where highlighting depends on
+subsequent lines.
+@end itemize
+
+@menu
+* Font Lock Multiline::         Marking multiline chunks with a text property
+* Region to Fontify::           Controlling which region gets refontified
+                                  after a buffer change.
+@end menu
+
+@node Font Lock Multiline
+@subsubsection Font Lock Multiline
+
+  One way to ensure reliable rehighlighting of multiline Font Lock
+constructs is to put on them the text property @code{font-lock-multiline}.
+It should be present and non-@code{nil} for text that is part of a
+multiline construct.
+
+  When Font Lock is about to highlight a range of text, it first
+extends the boundaries of the range as necessary so that they do not
+fall within text marked with the @code{font-lock-multiline} property.
+Then it removes any @code{font-lock-multiline} properties from the
+range, and highlights it.  The highlighting specification (mostly
+@code{font-lock-keywords}) must reinstall this property each time,
+whenever it is appropriate.
+
+  @strong{Warning:} don't use the @code{font-lock-multiline} property
+on large ranges of text, because that will make rehighlighting slow.
+
+@defvar font-lock-multiline
+If the @code{font-lock-multiline} variable is set to @code{t}, Font
+Lock will try to add the @code{font-lock-multiline} property
+automatically on multiline constructs.  This is not a universal
+solution, however, since it slows down Font Lock somewhat.  It can
+miss some multiline constructs, or make the property larger or smaller
+than necessary.
+
+For elements whose @var{matcher} is a function, the function should
+ensure that submatch 0 covers the whole relevant multiline construct,
+even if only a small subpart will be highlighted.  It is often just as
+easy to add the @code{font-lock-multiline} property by hand.
+@end defvar
+
+  The @code{font-lock-multiline} property is meant to ensure proper
+refontification; it does not automatically identify new multiline
+constructs.  Identifying the requires that Font-Lock operate on large
+enough chunks at a time.  This will happen by accident on many cases,
+which may give the impression that multiline constructs magically work.
+If you set the @code{font-lock-multiline} variable non-@code{nil},
+this impression will be even stronger, since the highlighting of those
+constructs which are found will be properly updated from then on.
+But that does not work reliably.
+
+  To find multiline constructs reliably, you must either manually
+place the @code{font-lock-multiline} property on the text before
+Font-Lock looks at it, or use
+@code{font-lock-fontify-region-function}.
+
+@node Region to Fontify
+@subsubsection Region to Fontify after a Buffer Change
+
+  When a buffer is changed, the region that Font Lock refontifies is
+by default the smallest sequence of whole lines that spans the change.
+While this works well most of the time, sometimes it doesn't---for
+example, when a change alters the syntactic meaning of text on an
+earlier line.
+
+  You can enlarge (or even reduce) the region to fontify by setting
+one the following variables:
+
+@defvar font-lock-extend-after-change-region-function
+This buffer-local variable is either @code{nil} or a function for
+Font-Lock to call to determine the region to scan and fontify.
+
+The function is given three parameters, the standard @var{beg},
+@var{end}, and @var{old-len} from after-change-functions
+(@pxref{Change Hooks}).  It should return either a cons of the
+beginning and end buffer positions (in that order) of the region to
+fontify, or @code{nil} (which means choose the region in the standard
+way).  This function needs to preserve point, the match-data, and the
+current restriction.  The region it returns may start or end in the
+middle of a line.
+
+Since this function is called after every buffer change, it should be
+reasonably fast.
+@end defvar
+
+@node Desktop Save Mode
+@section Desktop Save Mode
+@cindex desktop save mode
+
+@dfn{Desktop Save Mode} is a feature to save the state of Emacs from
+one session to another.  The user-level commands for using Desktop
+Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
+Sessions,,, emacs, the GNU Emacs Manual}).  Modes whose buffers visit
+a file, don't have to do anything to use this feature.
+
+For buffers not visiting a file to have their state saved, the major
+mode must bind the buffer local variable @code{desktop-save-buffer} to
+a non-@code{nil} value.
+
+@defvar desktop-save-buffer
+If this buffer-local variable is non-@code{nil}, the buffer will have
+its state saved in the desktop file at desktop save.  If the value is
+a function, it is called at desktop save with argument
+@var{desktop-dirname}, and its value is saved in the desktop file along
+with the state of the buffer for which it was called.  When file names
+are returned as part of the auxiliary information, they should be
+formatted using the call
+
+@example
+(desktop-file-name @var{file-name} @var{desktop-dirname})
+@end example
+
+@end defvar
+
+For buffers not visiting a file to be restored, the major mode must
+define a function to do the job, and that function must be listed in
+the alist @code{desktop-buffer-mode-handlers}.
+
+@defvar desktop-buffer-mode-handlers
+Alist with elements
+
+@example
+(@var{major-mode} . @var{restore-buffer-function})
+@end example
+
+The function @var{restore-buffer-function} will be called with
+argument list
+
+@example
+(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
+@end example
+
+and it should return the restored buffer.
+Here @var{desktop-buffer-misc} is the value returned by the function
+optionally bound to @code{desktop-save-buffer}.
+@end defvar
+
+@ignore
+   arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e
+@end ignore
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
new file mode 100644
index 00000000000..a8f45e9dd20
--- /dev/null
+++ b/doc/lispref/nonascii.texi
@@ -0,0 +1,1504 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/characters
+@node Non-ASCII Characters, Searching and Matching, Text, Top
+@chapter Non-@acronym{ASCII} Characters
+@cindex multibyte characters
+@cindex characters, multi-byte
+@cindex non-@acronym{ASCII} characters
+
+  This chapter covers the special issues relating to non-@acronym{ASCII}
+characters and how they are stored in strings and buffers.
+
+@menu
+* Text Representations::    Unibyte and multibyte representations
+* Converting Representations::  Converting unibyte to multibyte and vice versa.
+* Selecting a Representation::  Treating a byte sequence as unibyte or multi.
+* Character Codes::         How unibyte and multibyte relate to
+                                codes of individual characters.
+* Character Sets::          The space of possible character codes
+                                is divided into various character sets.
+* Chars and Bytes::         More information about multibyte encodings.
+* Splitting Characters::    Converting a character to its byte sequence.
+* Scanning Charsets::       Which character sets are used in a buffer?
+* Translation of Characters::   Translation tables are used for conversion.
+* Coding Systems::          Coding systems are conversions for saving files.
+* Input Methods::           Input methods allow users to enter various
+                                non-ASCII characters without special keyboards.
+* Locales::                 Interacting with the POSIX locale.
+@end menu
+
+@node Text Representations
+@section Text Representations
+@cindex text representations
+
+  Emacs has two @dfn{text representations}---two ways to represent text
+in a string or buffer.  These are called @dfn{unibyte} and
+@dfn{multibyte}.  Each string, and each buffer, uses one of these two
+representations.  For most purposes, you can ignore the issue of
+representations, because Emacs converts text between them as
+appropriate.  Occasionally in Lisp programming you will need to pay
+attention to the difference.
+
+@cindex unibyte text
+  In unibyte representation, each character occupies one byte and
+therefore the possible character codes range from 0 to 255.  Codes 0
+through 127 are @acronym{ASCII} characters; the codes from 128 through 255
+are used for one non-@acronym{ASCII} character set (you can choose which
+character set by setting the variable @code{nonascii-insert-offset}).
+
+@cindex leading code
+@cindex multibyte text
+@cindex trailing codes
+  In multibyte representation, a character may occupy more than one
+byte, and as a result, the full range of Emacs character codes can be
+stored.  The first byte of a multibyte character is always in the range
+128 through 159 (octal 0200 through 0237).  These values are called
+@dfn{leading codes}.  The second and subsequent bytes of a multibyte
+character are always in the range 160 through 255 (octal 0240 through
+0377); these values are @dfn{trailing codes}.
+
+  Some sequences of bytes are not valid in multibyte text: for example,
+a single isolated byte in the range 128 through 159 is not allowed.  But
+character codes 128 through 159 can appear in multibyte text,
+represented as two-byte sequences.  All the character codes 128 through
+255 are possible (though slightly abnormal) in multibyte text; they
+appear in multibyte buffers and strings when you do explicit encoding
+and decoding (@pxref{Explicit Encoding}).
+
+  In a buffer, the buffer-local value of the variable
+@code{enable-multibyte-characters} specifies the representation used.
+The representation for a string is determined and recorded in the string
+when the string is constructed.
+
+@defvar enable-multibyte-characters
+This variable specifies the current buffer's text representation.
+If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
+it contains unibyte text.
+
+You cannot set this variable directly; instead, use the function
+@code{set-buffer-multibyte} to change a buffer's representation.
+@end defvar
+
+@defvar default-enable-multibyte-characters
+This variable's value is entirely equivalent to @code{(default-value
+'enable-multibyte-characters)}, and setting this variable changes that
+default value.  Setting the local binding of
+@code{enable-multibyte-characters} in a specific buffer is not allowed,
+but changing the default value is supported, and it is a reasonable
+thing to do, because it has no effect on existing buffers.
+
+The @samp{--unibyte} command line option does its job by setting the
+default value to @code{nil} early in startup.
+@end defvar
+
+@defun position-bytes position
+Return the byte-position corresponding to buffer position
+@var{position} in the current buffer.  This is 1 at the start of the
+buffer, and counts upward in bytes.  If @var{position} is out of
+range, the value is @code{nil}.
+@end defun
+
+@defun byte-to-position byte-position
+Return the buffer position corresponding to byte-position
+@var{byte-position} in the current buffer.  If @var{byte-position} is
+out of range, the value is @code{nil}.
+@end defun
+
+@defun multibyte-string-p string
+Return @code{t} if @var{string} is a multibyte string.
+@end defun
+
+@defun string-bytes string
+@cindex string, number of bytes
+This function returns the number of bytes in @var{string}.
+If @var{string} is a multibyte string, this can be greater than
+@code{(length @var{string})}.
+@end defun
+
+@node Converting Representations
+@section Converting Text Representations
+
+  Emacs can convert unibyte text to multibyte; it can also convert
+multibyte text to unibyte, though this conversion loses information.  In
+general these conversions happen when inserting text into a buffer, or
+when putting text from several strings together in one string.  You can
+also explicitly convert a string's contents to either representation.
+
+  Emacs chooses the representation for a string based on the text that
+it is constructed from.  The general rule is to convert unibyte text to
+multibyte text when combining it with other multibyte text, because the
+multibyte representation is more general and can hold whatever
+characters the unibyte text has.
+
+  When inserting text into a buffer, Emacs converts the text to the
+buffer's representation, as specified by
+@code{enable-multibyte-characters} in that buffer.  In particular, when
+you insert multibyte text into a unibyte buffer, Emacs converts the text
+to unibyte, even though this conversion cannot in general preserve all
+the characters that might be in the multibyte text.  The other natural
+alternative, to convert the buffer contents to multibyte, is not
+acceptable because the buffer's representation is a choice made by the
+user that cannot be overridden automatically.
+
+  Converting unibyte text to multibyte text leaves @acronym{ASCII} characters
+unchanged, and likewise character codes 128 through 159.  It converts
+the non-@acronym{ASCII} codes 160 through 255 by adding the value
+@code{nonascii-insert-offset} to each character code.  By setting this
+variable, you specify which character set the unibyte characters
+correspond to (@pxref{Character Sets}).  For example, if
+@code{nonascii-insert-offset} is 2048, which is @code{(- (make-char
+'latin-iso8859-1) 128)}, then the unibyte non-@acronym{ASCII} characters
+correspond to Latin 1.  If it is 2688, which is @code{(- (make-char
+'greek-iso8859-7) 128)}, then they correspond to Greek letters.
+
+  Converting multibyte text to unibyte is simpler: it discards all but
+the low 8 bits of each character code.  If @code{nonascii-insert-offset}
+has a reasonable value, corresponding to the beginning of some character
+set, this conversion is the inverse of the other: converting unibyte
+text to multibyte and back to unibyte reproduces the original unibyte
+text.
+
+@defvar nonascii-insert-offset
+This variable specifies the amount to add to a non-@acronym{ASCII} character
+when converting unibyte text to multibyte.  It also applies when
+@code{self-insert-command} inserts a character in the unibyte
+non-@acronym{ASCII} range, 128 through 255.  However, the functions
+@code{insert} and @code{insert-char} do not perform this conversion.
+
+The right value to use to select character set @var{cs} is @code{(-
+(make-char @var{cs}) 128)}.  If the value of
+@code{nonascii-insert-offset} is zero, then conversion actually uses the
+value for the Latin 1 character set, rather than zero.
+@end defvar
+
+@defvar nonascii-translation-table
+This variable provides a more general alternative to
+@code{nonascii-insert-offset}.  You can use it to specify independently
+how to translate each code in the range of 128 through 255 into a
+multibyte character.  The value should be a char-table, or @code{nil}.
+If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
+@end defvar
+
+The next three functions either return the argument @var{string}, or a
+newly created string with no text properties.
+
+@defun string-make-unibyte string
+This function converts the text of @var{string} to unibyte
+representation, if it isn't already, and returns the result.  If
+@var{string} is a unibyte string, it is returned unchanged.  Multibyte
+character codes are converted to unibyte according to
+@code{nonascii-translation-table} or, if that is @code{nil}, using
+@code{nonascii-insert-offset}.  If the lookup in the translation table
+fails, this function takes just the low 8 bits of each character.
+@end defun
+
+@defun string-make-multibyte string
+This function converts the text of @var{string} to multibyte
+representation, if it isn't already, and returns the result.  If
+@var{string} is a multibyte string or consists entirely of
+@acronym{ASCII} characters, it is returned unchanged.  In particular,
+if @var{string} is unibyte and entirely @acronym{ASCII}, the returned
+string is unibyte.  (When the characters are all @acronym{ASCII},
+Emacs primitives will treat the string the same way whether it is
+unibyte or multibyte.)  If @var{string} is unibyte and contains
+non-@acronym{ASCII} characters, the function
+@code{unibyte-char-to-multibyte} is used to convert each unibyte
+character to a multibyte character.
+@end defun
+
+@defun string-to-multibyte string
+This function returns a multibyte string containing the same sequence
+of character codes as @var{string}.  Unlike
+@code{string-make-multibyte}, this function unconditionally returns a
+multibyte string.  If @var{string} is a multibyte string, it is
+returned unchanged.
+@end defun
+
+@defun multibyte-char-to-unibyte char
+This convert the multibyte character @var{char} to a unibyte
+character, based on @code{nonascii-translation-table} and
+@code{nonascii-insert-offset}.
+@end defun
+
+@defun unibyte-char-to-multibyte char
+This convert the unibyte character @var{char} to a multibyte
+character, based on @code{nonascii-translation-table} and
+@code{nonascii-insert-offset}.
+@end defun
+
+@node Selecting a Representation
+@section Selecting a Representation
+
+  Sometimes it is useful to examine an existing buffer or string as
+multibyte when it was unibyte, or vice versa.
+
+@defun set-buffer-multibyte multibyte
+Set the representation type of the current buffer.  If @var{multibyte}
+is non-@code{nil}, the buffer becomes multibyte.  If @var{multibyte}
+is @code{nil}, the buffer becomes unibyte.
+
+This function leaves the buffer contents unchanged when viewed as a
+sequence of bytes.  As a consequence, it can change the contents viewed
+as characters; a sequence of two bytes which is treated as one character
+in multibyte representation will count as two characters in unibyte
+representation.  Character codes 128 through 159 are an exception.  They
+are represented by one byte in a unibyte buffer, but when the buffer is
+set to multibyte, they are converted to two-byte sequences, and vice
+versa.
+
+This function sets @code{enable-multibyte-characters} to record which
+representation is in use.  It also adjusts various data in the buffer
+(including overlays, text properties and markers) so that they cover the
+same text as they did before.
+
+You cannot use @code{set-buffer-multibyte} on an indirect buffer,
+because indirect buffers always inherit the representation of the
+base buffer.
+@end defun
+
+@defun string-as-unibyte string
+This function returns a string with the same bytes as @var{string} but
+treating each byte as a character.  This means that the value may have
+more characters than @var{string} has.
+
+If @var{string} is already a unibyte string, then the value is
+@var{string} itself.  Otherwise it is a newly created string, with no
+text properties.  If @var{string} is multibyte, any characters it
+contains of charset @code{eight-bit-control} or @code{eight-bit-graphic}
+are converted to the corresponding single byte.
+@end defun
+
+@defun string-as-multibyte string
+This function returns a string with the same bytes as @var{string} but
+treating each multibyte sequence as one character.  This means that the
+value may have fewer characters than @var{string} has.
+
+If @var{string} is already a multibyte string, then the value is
+@var{string} itself.  Otherwise it is a newly created string, with no
+text properties.  If @var{string} is unibyte and contains any individual
+8-bit bytes (i.e.@: not part of a multibyte form), they are converted to
+the corresponding multibyte character of charset @code{eight-bit-control}
+or @code{eight-bit-graphic}.
+@end defun
+
+@node Character Codes
+@section Character Codes
+@cindex character codes
+
+  The unibyte and multibyte text representations use different character
+codes.  The valid character codes for unibyte representation range from
+0 to 255---the values that can fit in one byte.  The valid character
+codes for multibyte representation range from 0 to 524287, but not all
+values in that range are valid.  The values 128 through 255 are not
+entirely proper in multibyte text, but they can occur if you do explicit
+encoding and decoding (@pxref{Explicit Encoding}).  Some other character
+codes cannot occur at all in multibyte text.  Only the @acronym{ASCII} codes
+0 through 127 are completely legitimate in both representations.
+
+@defun char-valid-p charcode &optional genericp
+This returns @code{t} if @var{charcode} is valid (either for unibyte
+text or for multibyte text).
+
+@example
+(char-valid-p 65)
+     @result{} t
+(char-valid-p 256)
+     @result{} nil
+(char-valid-p 2248)
+     @result{} t
+@end example
+
+If the optional argument @var{genericp} is non-@code{nil}, this
+function also returns @code{t} if @var{charcode} is a generic
+character (@pxref{Splitting Characters}).
+@end defun
+
+@node Character Sets
+@section Character Sets
+@cindex character sets
+
+  Emacs classifies characters into various @dfn{character sets}, each of
+which has a name which is a symbol.  Each character belongs to one and
+only one character set.
+
+  In general, there is one character set for each distinct script.  For
+example, @code{latin-iso8859-1} is one character set,
+@code{greek-iso8859-7} is another, and @code{ascii} is another.  An
+Emacs character set can hold at most 9025 characters; therefore, in some
+cases, characters that would logically be grouped together are split
+into several character sets.  For example, one set of Chinese
+characters, generally known as Big 5, is divided into two Emacs
+character sets, @code{chinese-big5-1} and @code{chinese-big5-2}.
+
+  @acronym{ASCII} characters are in character set @code{ascii}.  The
+non-@acronym{ASCII} characters 128 through 159 are in character set
+@code{eight-bit-control}, and codes 160 through 255 are in character set
+@code{eight-bit-graphic}.
+
+@defun charsetp object
+Returns @code{t} if @var{object} is a symbol that names a character set,
+@code{nil} otherwise.
+@end defun
+
+@defvar charset-list
+The value is a list of all defined character set names.
+@end defvar
+
+@defun charset-list
+This function returns the value of @code{charset-list}.  It is only
+provided for backward compatibility.
+@end defun
+
+@defun char-charset character
+This function returns the name of the character set that @var{character}
+belongs to, or the symbol @code{unknown} if @var{character} is not a
+valid character.
+@end defun
+
+@defun charset-plist charset
+This function returns the charset property list of the character set
+@var{charset}.  Although @var{charset} is a symbol, this is not the same
+as the property list of that symbol.  Charset properties are used for
+special purposes within Emacs.
+@end defun
+
+@deffn Command list-charset-chars charset
+This command displays a list of characters in the character set
+@var{charset}.
+@end deffn
+
+@node Chars and Bytes
+@section Characters and Bytes
+@cindex bytes and characters
+
+@cindex introduction sequence (of character)
+@cindex dimension (of character set)
+  In multibyte representation, each character occupies one or more
+bytes.  Each character set has an @dfn{introduction sequence}, which is
+normally one or two bytes long.  (Exception: the @code{ascii} character
+set and the @code{eight-bit-graphic} character set have a zero-length
+introduction sequence.)  The introduction sequence is the beginning of
+the byte sequence for any character in the character set.  The rest of
+the character's bytes distinguish it from the other characters in the
+same character set.  Depending on the character set, there are either
+one or two distinguishing bytes; the number of such bytes is called the
+@dfn{dimension} of the character set.
+
+@defun charset-dimension charset
+This function returns the dimension of @var{charset}; at present, the
+dimension is always 1 or 2.
+@end defun
+
+@defun charset-bytes charset
+This function returns the number of bytes used to represent a character
+in character set @var{charset}.
+@end defun
+
+  This is the simplest way to determine the byte length of a character
+set's introduction sequence:
+
+@example
+(- (charset-bytes @var{charset})
+   (charset-dimension @var{charset}))
+@end example
+
+@node Splitting Characters
+@section Splitting Characters
+@cindex character as bytes
+
+  The functions in this section convert between characters and the byte
+values used to represent them.  For most purposes, there is no need to
+be concerned with the sequence of bytes used to represent a character,
+because Emacs translates automatically when necessary.
+
+@defun split-char character
+Return a list containing the name of the character set of
+@var{character}, followed by one or two byte values (integers) which
+identify @var{character} within that character set.  The number of byte
+values is the character set's dimension.
+
+If @var{character} is invalid as a character code, @code{split-char}
+returns a list consisting of the symbol @code{unknown} and @var{character}.
+
+@example
+(split-char 2248)
+     @result{} (latin-iso8859-1 72)
+(split-char 65)
+     @result{} (ascii 65)
+(split-char 128)
+     @result{} (eight-bit-control 128)
+@end example
+@end defun
+
+@cindex generate characters in charsets
+@defun make-char charset &optional code1 code2
+This function returns the character in character set @var{charset} whose
+position codes are @var{code1} and @var{code2}.  This is roughly the
+inverse of @code{split-char}.  Normally, you should specify either one
+or both of @var{code1} and @var{code2} according to the dimension of
+@var{charset}.  For example,
+
+@example
+(make-char 'latin-iso8859-1 72)
+     @result{} 2248
+@end example
+
+Actually, the eighth bit of both @var{code1} and @var{code2} is zeroed
+before they are used to index @var{charset}.  Thus you may use, for
+instance, an ISO 8859 character code rather than subtracting 128, as
+is necessary to index the corresponding Emacs charset.
+@end defun
+
+@cindex generic characters
+  If you call @code{make-char} with no @var{byte-values}, the result is
+a @dfn{generic character} which stands for @var{charset}.  A generic
+character is an integer, but it is @emph{not} valid for insertion in the
+buffer as a character.  It can be used in @code{char-table-range} to
+refer to the whole character set (@pxref{Char-Tables}).
+@code{char-valid-p} returns @code{nil} for generic characters.
+For example:
+
+@example
+(make-char 'latin-iso8859-1)
+     @result{} 2176
+(char-valid-p 2176)
+     @result{} nil
+(char-valid-p 2176 t)
+     @result{} t
+(split-char 2176)
+     @result{} (latin-iso8859-1 0)
+@end example
+
+The character sets @code{ascii}, @code{eight-bit-control}, and
+@code{eight-bit-graphic} don't have corresponding generic characters.  If
+@var{charset} is one of them and you don't supply @var{code1},
+@code{make-char} returns the character code corresponding to the
+smallest code in @var{charset}.
+
+@node Scanning Charsets
+@section Scanning for Character Sets
+
+  Sometimes it is useful to find out which character sets appear in a
+part of a buffer or a string.  One use for this is in determining which
+coding systems (@pxref{Coding Systems}) are capable of representing all
+of the text in question.
+
+@defun charset-after &optional pos
+This function return the charset of a character in the current buffer
+at position @var{pos}.  If @var{pos} is omitted or @code{nil}, it
+defaults to the current value of point.  If @var{pos} is out of range,
+the value is @code{nil}.
+@end defun
+
+@defun find-charset-region beg end &optional translation
+This function returns a list of the character sets that appear in the
+current buffer between positions @var{beg} and @var{end}.
+
+The optional argument @var{translation} specifies a translation table to
+be used in scanning the text (@pxref{Translation of Characters}).  If it
+is non-@code{nil}, then each character in the region is translated
+through this table, and the value returned describes the translated
+characters instead of the characters actually in the buffer.
+@end defun
+
+@defun find-charset-string string &optional translation
+This function returns a list of the character sets that appear in the
+string @var{string}.  It is just like @code{find-charset-region}, except
+that it applies to the contents of @var{string} instead of part of the
+current buffer.
+@end defun
+
+@node Translation of Characters
+@section Translation of Characters
+@cindex character translation tables
+@cindex translation tables
+
+  A @dfn{translation table} is a char-table that specifies a mapping
+of characters into characters.  These tables are used in encoding and
+decoding, and for other purposes.  Some coding systems specify their
+own particular translation tables; there are also default translation
+tables which apply to all other coding systems.
+
+  For instance, the coding-system @code{utf-8} has a translation table
+that maps characters of various charsets (e.g.,
+@code{latin-iso8859-@var{x}}) into Unicode character sets.  This way,
+it can encode Latin-2 characters into UTF-8.  Meanwhile,
+@code{unify-8859-on-decoding-mode} operates by specifying
+@code{standard-translation-table-for-decode} to translate
+Latin-@var{x} characters into corresponding Unicode characters.
+
+@defun make-translation-table &rest translations
+This function returns a translation table based on the argument
+@var{translations}.  Each element of @var{translations} should be a
+list of elements of the form @code{(@var{from} . @var{to})}; this says
+to translate the character @var{from} into @var{to}.
+
+The arguments and the forms in each argument are processed in order,
+and if a previous form already translates @var{to} to some other
+character, say @var{to-alt}, @var{from} is also translated to
+@var{to-alt}.
+
+You can also map one whole character set into another character set with
+the same dimension.  To do this, you specify a generic character (which
+designates a character set) for @var{from} (@pxref{Splitting Characters}).
+In this case, if @var{to} is also a generic character, its character
+set should have the same dimension as @var{from}'s.  Then the
+translation table translates each character of @var{from}'s character
+set into the corresponding character of @var{to}'s character set.  If
+@var{from} is a generic character and @var{to} is an ordinary
+character, then the translation table translates every character of
+@var{from}'s character set into @var{to}.
+@end defun
+
+  In decoding, the translation table's translations are applied to the
+characters that result from ordinary decoding.  If a coding system has
+property @code{translation-table-for-decode}, that specifies the
+translation table to use.  (This is a property of the coding system,
+as returned by @code{coding-system-get}, not a property of the symbol
+that is the coding system's name. @xref{Coding System Basics,, Basic
+Concepts of Coding Systems}.)  Otherwise, if
+@code{standard-translation-table-for-decode} is non-@code{nil},
+decoding uses that table.
+
+  In encoding, the translation table's translations are applied to the
+characters in the buffer, and the result of translation is actually
+encoded.  If a coding system has property
+@code{translation-table-for-encode}, that specifies the translation
+table to use.  Otherwise the variable
+@code{standard-translation-table-for-encode} specifies the translation
+table.
+
+@defvar standard-translation-table-for-decode
+This is the default translation table for decoding, for
+coding systems that don't specify any other translation table.
+@end defvar
+
+@defvar standard-translation-table-for-encode
+This is the default translation table for encoding, for
+coding systems that don't specify any other translation table.
+@end defvar
+
+@defvar translation-table-for-input
+Self-inserting characters are translated through this translation
+table before they are inserted.  Search commands also translate their
+input through this table, so they can compare more reliably with
+what's in the buffer.
+
+@code{set-buffer-file-coding-system} sets this variable so that your
+keyboard input gets translated into the character sets that the buffer
+is likely to contain.  This variable automatically becomes
+buffer-local when set.
+@end defvar
+
+@node Coding Systems
+@section Coding Systems
+
+@cindex coding system
+  When Emacs reads or writes a file, and when Emacs sends text to a
+subprocess or receives text from a subprocess, it normally performs
+character code conversion and end-of-line conversion as specified
+by a particular @dfn{coding system}.
+
+  How to define a coding system is an arcane matter, and is not
+documented here.
+
+@menu
+* Coding System Basics::        Basic concepts.
+* Encoding and I/O::            How file I/O functions handle coding systems.
+* Lisp and Coding Systems::     Functions to operate on coding system names.
+* User-Chosen Coding Systems::  Asking the user to choose a coding system.
+* Default Coding Systems::      Controlling the default choices.
+* Specifying Coding Systems::   Requesting a particular coding system
+                                    for a single file operation.
+* Explicit Encoding::           Encoding or decoding text without doing I/O.
+* Terminal I/O Encoding::       Use of encoding for terminal I/O.
+* MS-DOS File Types::           How DOS "text" and "binary" files
+                                    relate to coding systems.
+@end menu
+
+@node Coding System Basics
+@subsection Basic Concepts of Coding Systems
+
+@cindex character code conversion
+  @dfn{Character code conversion} involves conversion between the encoding
+used inside Emacs and some other encoding.  Emacs supports many
+different encodings, in that it can convert to and from them.  For
+example, it can convert text to or from encodings such as Latin 1, Latin
+2, Latin 3, Latin 4, Latin 5, and several variants of ISO 2022.  In some
+cases, Emacs supports several alternative encodings for the same
+characters; for example, there are three coding systems for the Cyrillic
+(Russian) alphabet: ISO, Alternativnyj, and KOI8.
+
+  Most coding systems specify a particular character code for
+conversion, but some of them leave the choice unspecified---to be chosen
+heuristically for each file, based on the data.
+
+  In general, a coding system doesn't guarantee roundtrip identity:
+decoding a byte sequence using coding system, then encoding the
+resulting text in the same coding system, can produce a different byte
+sequence.  However, the following coding systems do guarantee that the
+byte sequence will be the same as what you originally decoded:
+
+@quotation
+chinese-big5 chinese-iso-8bit cyrillic-iso-8bit emacs-mule
+greek-iso-8bit hebrew-iso-8bit iso-latin-1 iso-latin-2 iso-latin-3
+iso-latin-4 iso-latin-5 iso-latin-8 iso-latin-9 iso-safe
+japanese-iso-8bit japanese-shift-jis korean-iso-8bit raw-text
+@end quotation
+
+  Encoding buffer text and then decoding the result can also fail to
+reproduce the original text.  For instance, if you encode Latin-2
+characters with @code{utf-8} and decode the result using the same
+coding system, you'll get Unicode characters (of charset
+@code{mule-unicode-0100-24ff}).  If you encode Unicode characters with
+@code{iso-latin-2} and decode the result with the same coding system,
+you'll get Latin-2 characters.
+
+@cindex EOL conversion
+@cindex end-of-line conversion
+@cindex line end conversion
+  @dfn{End of line conversion} handles three different conventions used
+on various systems for representing end of line in files.  The Unix
+convention is to use the linefeed character (also called newline).  The
+DOS convention is to use a carriage-return and a linefeed at the end of
+a line.  The Mac convention is to use just carriage-return.
+
+@cindex base coding system
+@cindex variant coding system
+  @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line
+conversion unspecified, to be chosen based on the data.  @dfn{Variant
+coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
+@code{latin-1-mac} specify the end-of-line conversion explicitly as
+well.  Most base coding systems have three corresponding variants whose
+names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
+
+  The coding system @code{raw-text} is special in that it prevents
+character code conversion, and causes the buffer visited with that
+coding system to be a unibyte buffer.  It does not specify the
+end-of-line conversion, allowing that to be determined as usual by the
+data, and has the usual three variants which specify the end-of-line
+conversion.  @code{no-conversion} is equivalent to @code{raw-text-unix}:
+it specifies no conversion of either character codes or end-of-line.
+
+  The coding system @code{emacs-mule} specifies that the data is
+represented in the internal Emacs encoding.  This is like
+@code{raw-text} in that no code conversion happens, but different in
+that the result is multibyte data.
+
+@defun coding-system-get coding-system property
+This function returns the specified property of the coding system
+@var{coding-system}.  Most coding system properties exist for internal
+purposes, but one that you might find useful is @code{mime-charset}.
+That property's value is the name used in MIME for the character coding
+which this coding system can read and write.  Examples:
+
+@example
+(coding-system-get 'iso-latin-1 'mime-charset)
+     @result{} iso-8859-1
+(coding-system-get 'iso-2022-cn 'mime-charset)
+     @result{} iso-2022-cn
+(coding-system-get 'cyrillic-koi8 'mime-charset)
+     @result{} koi8-r
+@end example
+
+The value of the @code{mime-charset} property is also defined
+as an alias for the coding system.
+@end defun
+
+@node Encoding and I/O
+@subsection Encoding and I/O
+
+  The principal purpose of coding systems is for use in reading and
+writing files.  The function @code{insert-file-contents} uses
+a coding system for decoding the file data, and @code{write-region}
+uses one to encode the buffer contents.
+
+  You can specify the coding system to use either explicitly
+(@pxref{Specifying Coding Systems}), or implicitly using a default
+mechanism (@pxref{Default Coding Systems}).  But these methods may not
+completely specify what to do.  For example, they may choose a coding
+system such as @code{undefined} which leaves the character code
+conversion to be determined from the data.  In these cases, the I/O
+operation finishes the job of choosing a coding system.  Very often
+you will want to find out afterwards which coding system was chosen.
+
+@defvar buffer-file-coding-system
+This buffer-local variable records the coding system that was used to visit
+the current buffer.  It is used for saving the buffer, and for writing part
+of the buffer with @code{write-region}.  If the text to be written
+cannot be safely encoded using the coding system specified by this
+variable, these operations select an alternative encoding by calling
+the function @code{select-safe-coding-system} (@pxref{User-Chosen
+Coding Systems}).  If selecting a different encoding requires to ask
+the user to specify a coding system, @code{buffer-file-coding-system}
+is updated to the newly selected coding system.
+
+@code{buffer-file-coding-system} does @emph{not} affect sending text
+to a subprocess.
+@end defvar
+
+@defvar save-buffer-coding-system
+This variable specifies the coding system for saving the buffer (by
+overriding @code{buffer-file-coding-system}).  Note that it is not used
+for @code{write-region}.
+
+When a command to save the buffer starts out to use
+@code{buffer-file-coding-system} (or @code{save-buffer-coding-system}),
+and that coding system cannot handle
+the actual text in the buffer, the command asks the user to choose
+another coding system (by calling @code{select-safe-coding-system}).
+After that happens, the command also updates
+@code{buffer-file-coding-system} to represent the coding system that
+the user specified.
+@end defvar
+
+@defvar last-coding-system-used
+I/O operations for files and subprocesses set this variable to the
+coding system name that was used.  The explicit encoding and decoding
+functions (@pxref{Explicit Encoding}) set it too.
+
+@strong{Warning:} Since receiving subprocess output sets this variable,
+it can change whenever Emacs waits; therefore, you should copy the
+value shortly after the function call that stores the value you are
+interested in.
+@end defvar
+
+  The variable @code{selection-coding-system} specifies how to encode
+selections for the window system.  @xref{Window System Selections}.
+
+@defvar file-name-coding-system
+The variable @code{file-name-coding-system} specifies the coding
+system to use for encoding file names.  Emacs encodes file names using
+that coding system for all file operations.  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.
+@end defvar
+
+  @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 are handled differently under the
+new coding system.  If you try to save one of these buffers under the
+visited file name, saving may use the wrong file name, or it may get
+an error.  If such a problem happens, use @kbd{C-x C-w} to specify a
+new file name for that buffer.
+
+@node Lisp and Coding Systems
+@subsection Coding Systems in Lisp
+
+  Here are the Lisp facilities for working with coding systems:
+
+@defun coding-system-list &optional base-only
+This function returns a list of all coding system names (symbols).  If
+@var{base-only} is non-@code{nil}, the value includes only the
+base coding systems.  Otherwise, it includes alias and variant coding
+systems as well.
+@end defun
+
+@defun coding-system-p object
+This function returns @code{t} if @var{object} is a coding system
+name or @code{nil}.
+@end defun
+
+@defun check-coding-system coding-system
+This function checks the validity of @var{coding-system}.
+If that is valid, it returns @var{coding-system}.
+Otherwise it signals an error with condition @code{coding-system-error}.
+@end defun
+
+@defun coding-system-eol-type coding-system
+This function returns the type of end-of-line (a.k.a.@: @dfn{eol})
+conversion used by @var{coding-system}.  If @var{coding-system}
+specifies a certain eol conversion, the return value is an integer 0,
+1, or 2, standing for @code{unix}, @code{dos}, and @code{mac},
+respectively.  If @var{coding-system} doesn't specify eol conversion
+explicitly, the return value is a vector of coding systems, each one
+with one of the possible eol conversion types, like this:
+
+@lisp
+(coding-system-eol-type 'latin-1)
+     @result{} [latin-1-unix latin-1-dos latin-1-mac]
+@end lisp
+
+@noindent
+If this function returns a vector, Emacs will decide, as part of the
+text encoding or decoding process, what eol conversion to use.  For
+decoding, the end-of-line format of the text is auto-detected, and the
+eol conversion is set to match it (e.g., DOS-style CRLF format will
+imply @code{dos} eol conversion).  For encoding, the eol conversion is
+taken from the appropriate default coding system (e.g.,
+@code{default-buffer-file-coding-system} for
+@code{buffer-file-coding-system}), or from the default eol conversion
+appropriate for the underlying platform.
+@end defun
+
+@defun coding-system-change-eol-conversion coding-system eol-type
+This function returns a coding system which is like @var{coding-system}
+except for its eol conversion, which is specified by @code{eol-type}.
+@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
+@code{nil}.  If it is @code{nil}, the returned coding system determines
+the end-of-line conversion from the data.
+
+@var{eol-type} may also be 0, 1 or 2, standing for @code{unix},
+@code{dos} and @code{mac}, respectively.
+@end defun
+
+@defun coding-system-change-text-conversion eol-coding text-coding
+This function returns a coding system which uses the end-of-line
+conversion of @var{eol-coding}, and the text conversion of
+@var{text-coding}.  If @var{text-coding} is @code{nil}, it returns
+@code{undecided}, or one of its variants according to @var{eol-coding}.
+@end defun
+
+@defun find-coding-systems-region from to
+This function returns a list of coding systems that could be used to
+encode a text between @var{from} and @var{to}.  All coding systems in
+the list can safely encode any multibyte characters in that portion of
+the text.
+
+If the text contains no multibyte characters, the function returns the
+list @code{(undecided)}.
+@end defun
+
+@defun find-coding-systems-string string
+This function returns a list of coding systems that could be used to
+encode the text of @var{string}.  All coding systems in the list can
+safely encode any multibyte characters in @var{string}.  If the text
+contains no multibyte characters, this returns the list
+@code{(undecided)}.
+@end defun
+
+@defun find-coding-systems-for-charsets charsets
+This function returns a list of coding systems that could be used to
+encode all the character sets in the list @var{charsets}.
+@end defun
+
+@defun detect-coding-region start end &optional highest
+This function chooses a plausible coding system for decoding the text
+from @var{start} to @var{end}.  This text should be a byte sequence
+(@pxref{Explicit Encoding}).
+
+Normally this function returns a list of coding systems that could
+handle decoding the text that was scanned.  They are listed in order of
+decreasing priority.  But if @var{highest} is non-@code{nil}, then the
+return value is just one coding system, the one that is highest in
+priority.
+
+If the region contains only @acronym{ASCII} characters except for such
+ISO-2022 control characters ISO-2022 as @code{ESC}, the value is
+@code{undecided} or @code{(undecided)}, or a variant specifying
+end-of-line conversion, if that can be deduced from the text.
+@end defun
+
+@defun detect-coding-string string &optional highest
+This function is like @code{detect-coding-region} except that it
+operates on the contents of @var{string} instead of bytes in the buffer.
+@end defun
+
+  @xref{Coding systems for a subprocess,, Process Information}, in
+particular the description of the functions
+@code{process-coding-system} and @code{set-process-coding-system}, for
+how to examine or set the coding systems used for I/O to a subprocess.
+
+@node User-Chosen Coding Systems
+@subsection User-Chosen Coding Systems
+
+@cindex select safe coding system
+@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file
+This function selects a coding system for encoding specified text,
+asking the user to choose if necessary.  Normally the specified text
+is the text in the current buffer between @var{from} and @var{to}.  If
+@var{from} is a string, the string specifies the text to encode, and
+@var{to} is ignored.
+
+If @var{default-coding-system} is non-@code{nil}, that is the first
+coding system to try; if that can handle the text,
+@code{select-safe-coding-system} returns that coding system.  It can
+also be a list of coding systems; then the function tries each of them
+one by one.  After trying all of them, it next tries the current
+buffer's value of @code{buffer-file-coding-system} (if it is not
+@code{undecided}), then the value of
+@code{default-buffer-file-coding-system} and finally the user's most
+preferred coding system, which the user can set using the command
+@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing
+Coding Systems, emacs, The GNU Emacs Manual}).
+
+If one of those coding systems can safely encode all the specified
+text, @code{select-safe-coding-system} chooses it and returns it.
+Otherwise, it asks the user to choose from a list of coding systems
+which can encode all the text, and returns the user's choice.
+
+@var{default-coding-system} can also be a list whose first element is
+t and whose other elements are coding systems.  Then, if no coding
+system in the list can handle the text, @code{select-safe-coding-system}
+queries the user immediately, without trying any of the three
+alternatives described above.
+
+The optional argument @var{accept-default-p}, if non-@code{nil},
+should be a function to determine whether a coding system selected
+without user interaction is acceptable. @code{select-safe-coding-system}
+calls this function with one argument, the base coding system of the
+selected coding system.  If @var{accept-default-p} returns @code{nil},
+@code{select-safe-coding-system} rejects the silently selected coding
+system, and asks the user to select a coding system from a list of
+possible candidates.
+
+@vindex select-safe-coding-system-accept-default-p
+If the variable @code{select-safe-coding-system-accept-default-p} is
+non-@code{nil}, its value overrides the value of
+@var{accept-default-p}.
+
+As a final step, before returning the chosen coding system,
+@code{select-safe-coding-system} checks whether that coding system is
+consistent with what would be selected if the contents of the region
+were read from a file.  (If not, this could lead to data corruption in
+a file subsequently re-visited and edited.)  Normally,
+@code{select-safe-coding-system} uses @code{buffer-file-name} as the
+file for this purpose, but if @var{file} is non-@code{nil}, it uses
+that file instead (this can be relevant for @code{write-region} and
+similar functions).  If it detects an apparent inconsistency,
+@code{select-safe-coding-system} queries the user before selecting the
+coding system.
+@end defun
+
+  Here are two functions you can use to let the user specify a coding
+system, with completion.  @xref{Completion}.
+
+@defun read-coding-system prompt &optional default
+This function reads a coding system using the minibuffer, prompting with
+string @var{prompt}, and returns the coding system name as a symbol.  If
+the user enters null input, @var{default} specifies which coding system
+to return.  It should be a symbol or a string.
+@end defun
+
+@defun read-non-nil-coding-system prompt
+This function reads a coding system using the minibuffer, prompting with
+string @var{prompt}, and returns the coding system name as a symbol.  If
+the user tries to enter null input, it asks the user to try again.
+@xref{Coding Systems}.
+@end defun
+
+@node Default Coding Systems
+@subsection Default Coding Systems
+
+  This section describes variables that specify the default coding
+system for certain files or when running certain subprograms, and the
+function that I/O operations use to access them.
+
+  The idea of these variables is that you set them once and for all to the
+defaults you want, and then do not change them again.  To specify a
+particular coding system for a particular operation in a Lisp program,
+don't change these variables; instead, override them using
+@code{coding-system-for-read} and @code{coding-system-for-write}
+(@pxref{Specifying Coding Systems}).
+
+@defvar auto-coding-regexp-alist
+This variable is an alist of text patterns and corresponding coding
+systems. Each element has the form @code{(@var{regexp}
+. @var{coding-system})}; a file whose first few kilobytes match
+@var{regexp} is decoded with @var{coding-system} when its contents are
+read into a buffer.  The settings in this alist take priority over
+@code{coding:} tags in the files and the contents of
+@code{file-coding-system-alist} (see below).  The default value is set
+so that Emacs automatically recognizes mail files in Babyl format and
+reads them with no code conversions.
+@end defvar
+
+@defvar file-coding-system-alist
+This variable is an alist that specifies the coding systems to use for
+reading and writing particular files.  Each element has the form
+@code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular
+expression that matches certain file names.  The element applies to file
+names that match @var{pattern}.
+
+The @sc{cdr} of the element, @var{coding}, should be either a coding
+system, a cons cell containing two coding systems, or a function name (a
+symbol with a function definition).  If @var{coding} is a coding system,
+that coding system is used for both reading the file and writing it.  If
+@var{coding} is a cons cell containing two coding systems, its @sc{car}
+specifies the coding system for decoding, and its @sc{cdr} specifies the
+coding system for encoding.
+
+If @var{coding} is a function name, the function should take one
+argument, a list of all arguments passed to
+@code{find-operation-coding-system}.  It must return a coding system
+or a cons cell containing two coding systems.  This value has the same
+meaning as described above.
+
+If @var{coding} (or what returned by the above function) is
+@code{undecided}, the normal code-detection is performed.
+@end defvar
+
+@defvar process-coding-system-alist
+This variable is an alist specifying which coding systems to use for a
+subprocess, depending on which program is running in the subprocess.  It
+works like @code{file-coding-system-alist}, except that @var{pattern} is
+matched against the program name used to start the subprocess.  The coding
+system or systems specified in this alist are used to initialize the
+coding systems used for I/O to the subprocess, but you can specify
+other coding systems later using @code{set-process-coding-system}.
+@end defvar
+
+  @strong{Warning:} Coding systems such as @code{undecided}, which
+determine the coding system from the data, do not work entirely reliably
+with asynchronous subprocess output.  This is because Emacs handles
+asynchronous subprocess output in batches, as it arrives.  If the coding
+system leaves the character code conversion unspecified, or leaves the
+end-of-line conversion unspecified, Emacs must try to detect the proper
+conversion from one batch at a time, and this does not always work.
+
+  Therefore, with an asynchronous subprocess, if at all possible, use a
+coding system which determines both the character code conversion and
+the end of line conversion---that is, one like @code{latin-1-unix},
+rather than @code{undecided} or @code{latin-1}.
+
+@defvar network-coding-system-alist
+This variable is an alist that specifies the coding system to use for
+network streams.  It works much like @code{file-coding-system-alist},
+with the difference that the @var{pattern} in an element may be either a
+port number or a regular expression.  If it is a regular expression, it
+is matched against the network service name used to open the network
+stream.
+@end defvar
+
+@defvar default-process-coding-system
+This variable specifies the coding systems to use for subprocess (and
+network stream) input and output, when nothing else specifies what to
+do.
+
+The value should be a cons cell of the form @code{(@var{input-coding}
+. @var{output-coding})}.  Here @var{input-coding} applies to input from
+the subprocess, and @var{output-coding} applies to output to it.
+@end defvar
+
+@defvar auto-coding-functions
+This variable holds a list of functions that try to determine a
+coding system for a file based on its undecoded contents.
+
+Each function in this list should be written to look at text in the
+current buffer, but should not modify it in any way.  The buffer will
+contain undecoded text of parts of the file.  Each function should
+take one argument, @var{size}, which tells it how many characters to
+look at, starting from point.  If the function succeeds in determining
+a coding system for the file, it should return that coding system.
+Otherwise, it should return @code{nil}.
+
+If a file has a @samp{coding:} tag, that takes precedence, so these
+functions won't be called.
+@end defvar
+
+@defun find-operation-coding-system operation &rest arguments
+This function returns the coding system to use (by default) for
+performing @var{operation} with @var{arguments}.  The value has this
+form:
+
+@example
+(@var{decoding-system} . @var{encoding-system})
+@end example
+
+The first element, @var{decoding-system}, is the coding system to use
+for decoding (in case @var{operation} does decoding), and
+@var{encoding-system} is the coding system for encoding (in case
+@var{operation} does encoding).
+
+The argument @var{operation} is a symbol, one of @code{write-region},
+@code{start-process}, @code{call-process}, @code{call-process-region},
+@code{insert-file-contents}, or @code{open-network-stream}.  These are
+the names of the Emacs I/O primitives that can do character code and
+eol conversion.
+
+The remaining arguments should be the same arguments that might be given
+to the corresponding I/O primitive.  Depending on the primitive, one
+of those arguments is selected as the @dfn{target}.  For example, if
+@var{operation} does file I/O, whichever argument specifies the file
+name is the target.  For subprocess primitives, the process name is the
+target.  For @code{open-network-stream}, the target is the service name
+or port number.
+
+Depending on @var{operation}, this function looks up the target in
+@code{file-coding-system-alist}, @code{process-coding-system-alist},
+or @code{network-coding-system-alist}.  If the target is found in the
+alist, @code{find-operation-coding-system} returns its association in
+the alist; otherwise it returns @code{nil}.
+
+If @var{operation} is @code{insert-file-contents}, the argument
+corresponding to the target may be a cons cell of the form
+@code{(@var{filename} . @var{buffer})}).  In that case, @var{filename}
+is a file name to look up in @code{file-coding-system-alist}, and
+@var{buffer} is a buffer that contains the file's contents (not yet
+decoded).  If @code{file-coding-system-alist} specifies a function to
+call for this file, and that function needs to examine the file's
+contents (as it usually does), it should examine the contents of
+@var{buffer} instead of reading the file.
+@end defun
+
+@node Specifying Coding Systems
+@subsection Specifying a Coding System for One Operation
+
+  You can specify the coding system for a specific operation by binding
+the variables @code{coding-system-for-read} and/or
+@code{coding-system-for-write}.
+
+@defvar coding-system-for-read
+If this variable is non-@code{nil}, it specifies the coding system to
+use for reading a file, or for input from a synchronous subprocess.
+
+It also applies to any asynchronous subprocess or network stream, but in
+a different way: the value of @code{coding-system-for-read} when you
+start the subprocess or open the network stream specifies the input
+decoding method for that subprocess or network stream.  It remains in
+use for that subprocess or network stream unless and until overridden.
+
+The right way to use this variable is to bind it with @code{let} for a
+specific I/O operation.  Its global value is normally @code{nil}, and
+you should not globally set it to any other value.  Here is an example
+of the right way to use the variable:
+
+@example
+;; @r{Read the file with no character code conversion.}
+;; @r{Assume @acronym{crlf} represents end-of-line.}
+(let ((coding-system-for-read 'emacs-mule-dos))
+  (insert-file-contents filename))
+@end example
+
+When its value is non-@code{nil}, this variable takes precedence over
+all other methods of specifying a coding system to use for input,
+including @code{file-coding-system-alist},
+@code{process-coding-system-alist} and
+@code{network-coding-system-alist}.
+@end defvar
+
+@defvar coding-system-for-write
+This works much like @code{coding-system-for-read}, except that it
+applies to output rather than input.  It affects writing to files,
+as well as sending output to subprocesses and net connections.
+
+When a single operation does both input and output, as do
+@code{call-process-region} and @code{start-process}, both
+@code{coding-system-for-read} and @code{coding-system-for-write}
+affect it.
+@end defvar
+
+@defvar inhibit-eol-conversion
+When this variable is non-@code{nil}, no end-of-line conversion is done,
+no matter which coding system is specified.  This applies to all the
+Emacs I/O and subprocess primitives, and to the explicit encoding and
+decoding functions (@pxref{Explicit Encoding}).
+@end defvar
+
+@node Explicit Encoding
+@subsection Explicit Encoding and Decoding
+@cindex encoding in coding systems
+@cindex decoding in coding systems
+
+  All the operations that transfer text in and out of Emacs have the
+ability to use a coding system to encode or decode the text.
+You can also explicitly encode and decode text using the functions
+in this section.
+
+  The result of encoding, and the input to decoding, are not ordinary
+text.  They logically consist of a series of byte values; that is, a
+series of characters whose codes are in the range 0 through 255.  In a
+multibyte buffer or string, character codes 128 through 159 are
+represented by multibyte sequences, but this is invisible to Lisp
+programs.
+
+  The usual way to read a file into a buffer as a sequence of bytes, so
+you can decode the contents explicitly, is with
+@code{insert-file-contents-literally} (@pxref{Reading from Files});
+alternatively, specify a non-@code{nil} @var{rawfile} argument when
+visiting a file with @code{find-file-noselect}.  These methods result in
+a unibyte buffer.
+
+  The usual way to use the byte sequence that results from explicitly
+encoding text is to copy it to a file or process---for example, to write
+it with @code{write-region} (@pxref{Writing to Files}), and suppress
+encoding by binding @code{coding-system-for-write} to
+@code{no-conversion}.
+
+  Here are the functions to perform explicit encoding or decoding.  The
+encoding functions produce sequences of bytes; the decoding functions
+are meant to operate on sequences of bytes.  All of these functions
+discard text properties.
+
+@deffn Command encode-coding-region start end coding-system
+This command encodes the text from @var{start} to @var{end} according
+to coding system @var{coding-system}.  The encoded text replaces the
+original text in the buffer.  The result of encoding is logically a
+sequence of bytes, but the buffer remains multibyte if it was multibyte
+before.
+
+This command returns the length of the encoded text.
+@end deffn
+
+@defun encode-coding-string string coding-system &optional nocopy
+This function encodes the text in @var{string} according to coding
+system @var{coding-system}.  It returns a new string containing the
+encoded text, except when @var{nocopy} is non-@code{nil}, in which
+case the function may return @var{string} itself if the encoding
+operation is trivial.  The result of encoding is a unibyte string.
+@end defun
+
+@deffn Command decode-coding-region start end coding-system
+This command decodes the text from @var{start} to @var{end} according
+to coding system @var{coding-system}.  The decoded text replaces the
+original text in the buffer.  To make explicit decoding useful, the text
+before decoding ought to be a sequence of byte values, but both
+multibyte and unibyte buffers are acceptable.
+
+This command returns the length of the decoded text.
+@end deffn
+
+@defun decode-coding-string string coding-system &optional nocopy
+This function decodes the text in @var{string} according to coding
+system @var{coding-system}.  It returns a new string containing the
+decoded text, except when @var{nocopy} is non-@code{nil}, in which
+case the function may return @var{string} itself if the decoding
+operation is trivial.  To make explicit decoding useful, the contents
+of @var{string} ought to be a sequence of byte values, but a multibyte
+string is acceptable.
+@end defun
+
+@defun decode-coding-inserted-region from to filename &optional visit beg end replace
+This function decodes the text from @var{from} to @var{to} as if
+it were being read from file @var{filename} using @code{insert-file-contents}
+using the rest of the arguments provided.
+
+The normal way to use this function is after reading text from a file
+without decoding, if you decide you would rather have decoded it.
+Instead of deleting the text and reading it again, this time with
+decoding, you can call this function.
+@end defun
+
+@node Terminal I/O Encoding
+@subsection Terminal I/O Encoding
+
+  Emacs can decode keyboard input using a coding system, and encode
+terminal output.  This is useful for terminals that transmit or display
+text using a particular encoding such as Latin-1.  Emacs does not set
+@code{last-coding-system-used} for encoding or decoding for the
+terminal.
+
+@defun keyboard-coding-system
+This function returns the coding system that is in use for decoding
+keyboard input---or @code{nil} if no coding system is to be used.
+@end defun
+
+@deffn Command set-keyboard-coding-system coding-system
+This command specifies @var{coding-system} as the coding system to
+use for decoding keyboard input.  If @var{coding-system} is @code{nil},
+that means do not decode keyboard input.
+@end deffn
+
+@defun terminal-coding-system
+This function returns the coding system that is in use for encoding
+terminal output---or @code{nil} for no encoding.
+@end defun
+
+@deffn Command set-terminal-coding-system coding-system
+This command specifies @var{coding-system} as the coding system to use
+for encoding terminal output.  If @var{coding-system} is @code{nil},
+that means do not encode terminal output.
+@end deffn
+
+@node MS-DOS File Types
+@subsection MS-DOS File Types
+@cindex DOS file types
+@cindex MS-DOS file types
+@cindex Windows file types
+@cindex file types on MS-DOS and Windows
+@cindex text files and binary files
+@cindex binary files and text files
+
+  On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
+end-of-line conversion for a file by looking at the file's name.  This
+feature classifies files as @dfn{text files} and @dfn{binary files}.  By
+``binary file'' we mean a file of literal byte values that are not
+necessarily meant to be characters; Emacs does no end-of-line conversion
+and no character code conversion for them.  On the other hand, the bytes
+in a text file are intended to represent characters; when you create a
+new file whose name implies that it is a text file, Emacs uses DOS
+end-of-line conversion.
+
+@defvar buffer-file-type
+This variable, automatically buffer-local in each buffer, records the
+file type of the buffer's visited file.  When a buffer does not specify
+a coding system with @code{buffer-file-coding-system}, this variable is
+used to determine which coding system to use when writing the contents
+of the buffer.  It should be @code{nil} for text, @code{t} for binary.
+If it is @code{t}, the coding system is @code{no-conversion}.
+Otherwise, @code{undecided-dos} is used.
+
+Normally this variable is set by visiting a file; it is set to
+@code{nil} if the file was visited without any actual conversion.
+@end defvar
+
+@defopt file-name-buffer-file-type-alist
+This variable holds an alist for recognizing text and binary files.
+Each element has the form (@var{regexp} . @var{type}), where
+@var{regexp} is matched against the file name, and @var{type} may be
+@code{nil} for text, @code{t} for binary, or a function to call to
+compute which.  If it is a function, then it is called with a single
+argument (the file name) and should return @code{t} or @code{nil}.
+
+When running on MS-DOS or MS-Windows, Emacs checks this alist to decide
+which coding system to use when reading a file.  For a text file,
+@code{undecided-dos} is used.  For a binary file, @code{no-conversion}
+is used.
+
+If no element in this alist matches a given file name, then
+@code{default-buffer-file-type} says how to treat the file.
+@end defopt
+
+@defopt default-buffer-file-type
+This variable says how to handle files for which
+@code{file-name-buffer-file-type-alist} says nothing about the type.
+
+If this variable is non-@code{nil}, then these files are treated as
+binary: the coding system @code{no-conversion} is used.  Otherwise,
+nothing special is done for them---the coding system is deduced solely
+from the file contents, in the usual Emacs fashion.
+@end defopt
+
+@node Input Methods
+@section Input Methods
+@cindex input methods
+
+  @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII}
+characters from the keyboard.  Unlike coding systems, which translate
+non-@acronym{ASCII} characters to and from encodings meant to be read by
+programs, input methods provide human-friendly commands.  (@xref{Input
+Methods,,, emacs, The GNU Emacs Manual}, for information on how users
+use input methods to enter text.)  How to define input methods is not
+yet documented in this manual, but here we describe how to use them.
+
+  Each input method has a name, which is currently a string;
+in the future, symbols may also be usable as input method names.
+
+@defvar current-input-method
+This variable holds the name of the input method now active in the
+current buffer.  (It automatically becomes local in each buffer when set
+in any fashion.)  It is @code{nil} if no input method is active in the
+buffer now.
+@end defvar
+
+@defopt default-input-method
+This variable holds the default input method for commands that choose an
+input method.  Unlike @code{current-input-method}, this variable is
+normally global.
+@end defopt
+
+@deffn Command set-input-method input-method
+This command activates input method @var{input-method} for the current
+buffer.  It also sets @code{default-input-method} to @var{input-method}.
+If @var{input-method} is @code{nil}, this command deactivates any input
+method for the current buffer.
+@end deffn
+
+@defun read-input-method-name prompt &optional default inhibit-null
+This function reads an input method name with the minibuffer, prompting
+with @var{prompt}.  If @var{default} is non-@code{nil}, that is returned
+by default, if the user enters empty input.  However, if
+@var{inhibit-null} is non-@code{nil}, empty input signals an error.
+
+The returned value is a string.
+@end defun
+
+@defvar input-method-alist
+This variable defines all the supported input methods.
+Each element defines one input method, and should have the form:
+
+@example
+(@var{input-method} @var{language-env} @var{activate-func}
+ @var{title} @var{description} @var{args}...)
+@end example
+
+Here @var{input-method} is the input method name, a string;
+@var{language-env} is another string, the name of the language
+environment this input method is recommended for.  (That serves only for
+documentation purposes.)
+
+@var{activate-func} is a function to call to activate this method.  The
+@var{args}, if any, are passed as arguments to @var{activate-func}.  All
+told, the arguments to @var{activate-func} are @var{input-method} and
+the @var{args}.
+
+@var{title} is a string to display in the mode line while this method is
+active.  @var{description} is a string describing this method and what
+it is good for.
+@end defvar
+
+  The fundamental interface to input methods is through the
+variable @code{input-method-function}.  @xref{Reading One Event},
+and @ref{Invoking the Input Method}.
+
+@node Locales
+@section Locales
+@cindex locale
+
+  POSIX defines a concept of ``locales'' which control which language
+to use in language-related features.  These Emacs variables control
+how Emacs interacts with these features.
+
+@defvar locale-coding-system
+@cindex keyboard input decoding on X
+This variable specifies the coding system to use for decoding system
+error messages and---on X Window system only---keyboard input, for
+encoding the format argument to @code{format-time-string}, and for
+decoding the return value of @code{format-time-string}.
+@end defvar
+
+@defvar system-messages-locale
+This variable specifies the locale to use for generating system error
+messages.  Changing the locale can cause messages to come out in a
+different language or in a different orthography.  If the variable is
+@code{nil}, the locale is specified by environment variables in the
+usual POSIX fashion.
+@end defvar
+
+@defvar system-time-locale
+This variable specifies the locale to use for formatting time values.
+Changing the locale can cause messages to appear according to the
+conventions of a different language.  If the variable is @code{nil}, the
+locale is specified by environment variables in the usual POSIX fashion.
+@end defvar
+
+@defun locale-info item
+This function returns locale data @var{item} for the current POSIX
+locale, if available.  @var{item} should be one of these symbols:
+
+@table @code
+@item codeset
+Return the character set as a string (locale item @code{CODESET}).
+
+@item days
+Return a 7-element vector of day names (locale items
+@code{DAY_1} through @code{DAY_7});
+
+@item months
+Return a 12-element vector of month names (locale items @code{MON_1}
+through @code{MON_12}).
+
+@item paper
+Return a list @code{(@var{width} @var{height})} for the default paper
+size measured in millimeters (locale items @code{PAPER_WIDTH} and
+@code{PAPER_HEIGHT}).
+@end table
+
+If the system can't provide the requested information, or if
+@var{item} is not one of those symbols, the value is @code{nil}.  All
+strings in the return value are decoded using
+@code{locale-coding-system}.  @xref{Locales,,, libc, The GNU Libc Manual},
+for more information about locales and locale items.
+@end defun
+
+@ignore
+   arch-tag: be705bf8-941b-4c35-84fc-ad7d20ddb7cb
+@end ignore
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
new file mode 100644
index 00000000000..4d7f3e7578a
--- /dev/null
+++ b/doc/lispref/numbers.texi
@@ -0,0 +1,1211 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/numbers
+@node Numbers, Strings and Characters, Lisp Data Types, Top
+@chapter Numbers
+@cindex integers
+@cindex numbers
+
+  GNU Emacs supports two numeric data types: @dfn{integers} and
+@dfn{floating point numbers}.  Integers are whole numbers such as
+@minus{}3, 0, 7, 13, and 511.  Their values are exact.  Floating point
+numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
+2.71828.  They can also be expressed in exponential notation: 1.5e2
+equals 150; in this example, @samp{e2} stands for ten to the second
+power, and that is multiplied by 1.5.  Floating point values are not
+exact; they have a fixed, limited amount of precision.
+
+@menu
+* Integer Basics::            Representation and range of integers.
+* Float Basics::	      Representation and range of floating point.
+* Predicates on Numbers::     Testing for numbers.
+* Comparison of Numbers::     Equality and inequality predicates.
+* Numeric Conversions::	      Converting float to integer and vice versa.
+* Arithmetic Operations::     How to add, subtract, multiply and divide.
+* Rounding Operations::       Explicitly rounding floating point numbers.
+* Bitwise Operations::        Logical and, or, not, shifting.
+* Math Functions::            Trig, exponential and logarithmic functions.
+* Random Numbers::            Obtaining random integers, predictable or not.
+@end menu
+
+@node Integer Basics
+@comment  node-name,  next,  previous,  up
+@section Integer Basics
+
+  The range of values for an integer depends on the machine.  The
+minimum range is @minus{}268435456 to 268435455 (29 bits; i.e.,
+@ifnottex
+-2**28
+@end ifnottex
+@tex
+@math{-2^{28}}
+@end tex
+to
+@ifnottex
+2**28 - 1),
+@end ifnottex
+@tex
+@math{2^{28}-1}),
+@end tex
+but some machines may provide a wider range.  Many examples in this
+chapter assume an integer has 29 bits.
+@cindex overflow
+
+  The Lisp reader reads an integer as a sequence of digits with optional
+initial sign and optional final period.
+
+@example
+ 1               ; @r{The integer 1.}
+ 1.              ; @r{The integer 1.}
++1               ; @r{Also the integer 1.}
+-1               ; @r{The integer @minus{}1.}
+ 536870913       ; @r{Also the integer 1, due to overflow.}
+ 0               ; @r{The integer 0.}
+-0               ; @r{The integer 0.}
+@end example
+
+@cindex integers in specific radix
+@cindex radix for reading an integer
+@cindex base for reading an integer
+@cindex hex numbers
+@cindex octal numbers
+@cindex reading numbers in hex, octal, and binary
+  The syntax for integers in bases other than 10 uses @samp{#}
+followed by a letter that specifies the radix: @samp{b} for binary,
+@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
+specify radix @var{radix}.  Case is not significant for the letter
+that specifies the radix.  Thus, @samp{#b@var{integer}} reads
+@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
+@var{integer} in radix @var{radix}.  Allowed values of @var{radix} run
+from 2 to 36.  For example:
+
+@example
+#b101100 @result{} 44
+#o54 @result{} 44
+#x2c @result{} 44
+#24r1k @result{} 44
+@end example
+
+  To understand how various functions work on integers, especially the
+bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
+view the numbers in their binary form.
+
+  In 29-bit binary, the decimal integer 5 looks like this:
+
+@example
+0 0000  0000 0000  0000 0000  0000 0101
+@end example
+
+@noindent
+(We have inserted spaces between groups of 4 bits, and two spaces
+between groups of 8 bits, to make the binary integer easier to read.)
+
+  The integer @minus{}1 looks like this:
+
+@example
+1 1111  1111 1111  1111 1111  1111 1111
+@end example
+
+@noindent
+@cindex two's complement
+@minus{}1 is represented as 29 ones.  (This is called @dfn{two's
+complement} notation.)
+
+  The negative integer, @minus{}5, is creating by subtracting 4 from
+@minus{}1.  In binary, the decimal integer 4 is 100.  Consequently,
+@minus{}5 looks like this:
+
+@example
+1 1111  1111 1111  1111 1111  1111 1011
+@end example
+
+  In this implementation, the largest 29-bit binary integer value is
+268,435,455 in decimal.  In binary, it looks like this:
+
+@example
+0 1111  1111 1111  1111 1111  1111 1111
+@end example
+
+  Since the arithmetic functions do not check whether integers go
+outside their range, when you add 1 to 268,435,455, the value is the
+negative integer @minus{}268,435,456:
+
+@example
+(+ 1 268435455)
+     @result{} -268435456
+     @result{} 1 0000  0000 0000  0000 0000  0000 0000
+@end example
+
+  Many of the functions described in this chapter accept markers for
+arguments in place of numbers.  (@xref{Markers}.)  Since the actual
+arguments to such functions may be either numbers or markers, we often
+give these arguments the name @var{number-or-marker}.  When the argument
+value is a marker, its position value is used and its buffer is ignored.
+
+@defvar most-positive-fixnum
+The value of this variable is the largest integer that Emacs Lisp
+can handle.
+@end defvar
+
+@defvar most-negative-fixnum
+The value of this variable is the smallest integer that Emacs Lisp can
+handle.  It is negative.
+@end defvar
+
+@node Float Basics
+@section Floating Point Basics
+
+  Floating point numbers are useful for representing numbers that are
+not integral.  The precise range of floating point numbers is
+machine-specific; it is the same as the range of the C data type
+@code{double} on the machine you are using.
+
+  The read-syntax for floating point numbers requires either a decimal
+point (with at least one digit following), an exponent, or both.  For
+example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
+@samp{.15e4} are five ways of writing a floating point number whose
+value is 1500.  They are all equivalent.  You can also use a minus sign
+to write negative floating point numbers, as in @samp{-1.0}.
+
+@cindex @acronym{IEEE} floating point
+@cindex positive infinity
+@cindex negative infinity
+@cindex infinity
+@cindex NaN
+  Most modern computers support the @acronym{IEEE} floating point standard,
+which provides for positive infinity and negative infinity as floating point
+values.  It also provides for a class of values called NaN or
+``not-a-number''; numerical functions return such values in cases where
+there is no correct answer.  For example, @code{(/ 0.0 0.0)} returns a
+NaN.  For practical purposes, there's no significant difference between
+different NaN values in Emacs Lisp, and there's no rule for precisely
+which NaN value should be used in a particular case, so Emacs Lisp
+doesn't try to distinguish them (but it does report the sign, if you
+print it).  Here are the read syntaxes for these special floating
+point values:
+
+@table @asis
+@item positive infinity
+@samp{1.0e+INF}
+@item negative infinity
+@samp{-1.0e+INF}
+@item Not-a-number 
+@samp{0.0e+NaN} or @samp{-0.0e+NaN}.
+@end table
+
+  To test whether a floating point value is a NaN, compare it with
+itself using @code{=}.  That returns @code{nil} for a NaN, and
+@code{t} for any other floating point value.
+
+  The value @code{-0.0} is distinguishable from ordinary zero in
+@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
+@code{=} consider them equal values.
+
+  You can use @code{logb} to extract the binary exponent of a floating
+point number (or estimate the logarithm of an integer):
+
+@defun logb number
+This function returns the binary exponent of @var{number}.  More
+precisely, the value is the logarithm of @var{number} base 2, rounded
+down to an integer.
+
+@example
+(logb 10)
+     @result{} 3
+(logb 10.0e20)
+     @result{} 69
+@end example
+@end defun
+
+@node Predicates on Numbers
+@section Type Predicates for Numbers
+@cindex predicates for numbers
+
+  The functions in this section test for numbers, or for a specific
+type of number.  The functions @code{integerp} and @code{floatp} can
+take any type of Lisp object as argument (they would not be of much
+use otherwise), but the @code{zerop} predicate requires a number as
+its argument.  See also @code{integer-or-marker-p} and
+@code{number-or-marker-p}, in @ref{Predicates on Markers}.
+
+@defun floatp object
+This predicate tests whether its argument is a floating point
+number and returns @code{t} if so, @code{nil} otherwise.
+
+@code{floatp} does not exist in Emacs versions 18 and earlier.
+@end defun
+
+@defun integerp object
+This predicate tests whether its argument is an integer, and returns
+@code{t} if so, @code{nil} otherwise.
+@end defun
+
+@defun numberp object
+This predicate tests whether its argument is a number (either integer or
+floating point), and returns @code{t} if so, @code{nil} otherwise.
+@end defun
+
+@defun wholenump object
+@cindex natural numbers
+The @code{wholenump} predicate (whose name comes from the phrase
+``whole-number-p'') tests to see whether its argument is a nonnegative
+integer, and returns @code{t} if so, @code{nil} otherwise.  0 is
+considered non-negative.
+
+@findex natnump
+@code{natnump} is an obsolete synonym for @code{wholenump}.
+@end defun
+
+@defun zerop number
+This predicate tests whether its argument is zero, and returns @code{t}
+if so, @code{nil} otherwise.  The argument must be a number.
+
+@code{(zerop x)} is equivalent to @code{(= x 0)}.
+@end defun
+
+@node Comparison of Numbers
+@section Comparison of Numbers
+@cindex number comparison
+@cindex comparing numbers
+
+  To test numbers for numerical equality, you should normally use
+@code{=}, not @code{eq}.  There can be many distinct floating point
+number objects with the same numeric value.  If you use @code{eq} to
+compare them, then you test whether two values are the same
+@emph{object}.  By contrast, @code{=} compares only the numeric values
+of the objects.
+
+  At present, each integer value has a unique Lisp object in Emacs Lisp.
+Therefore, @code{eq} is equivalent to @code{=} where integers are
+concerned.  It is sometimes convenient to use @code{eq} for comparing an
+unknown value with an integer, because @code{eq} does not report an
+error if the unknown value is not a number---it accepts arguments of any
+type.  By contrast, @code{=} signals an error if the arguments are not
+numbers or markers.  However, it is a good idea to use @code{=} if you
+can, even for comparing integers, just in case we change the
+representation of integers in a future Emacs version.
+
+  Sometimes it is useful to compare numbers with @code{equal}; it
+treats two numbers as equal if they have the same data type (both
+integers, or both floating point) and the same value.  By contrast,
+@code{=} can treat an integer and a floating point number as equal.
+@xref{Equality Predicates}.
+
+  There is another wrinkle: because floating point arithmetic is not
+exact, it is often a bad idea to check for equality of two floating
+point values.  Usually it is better to test for approximate equality.
+Here's a function to do this:
+
+@example
+(defvar fuzz-factor 1.0e-6)
+(defun approx-equal (x y)
+  (or (and (= x 0) (= y 0))
+      (< (/ (abs (- x y))
+            (max (abs x) (abs y)))
+         fuzz-factor)))
+@end example
+
+@cindex CL note---integers vrs @code{eq}
+@quotation
+@b{Common Lisp note:} Comparing numbers in Common Lisp always requires
+@code{=} because Common Lisp implements multi-word integers, and two
+distinct integer objects can have the same numeric value.  Emacs Lisp
+can have just one integer object for any given value because it has a
+limited range of integer values.
+@end quotation
+
+@defun = number-or-marker1 number-or-marker2
+This function tests whether its arguments are numerically equal, and
+returns @code{t} if so, @code{nil} otherwise.
+@end defun
+
+@defun eql value1 value2
+This function acts like @code{eq} except when both arguments are
+numbers.  It compares numbers by type and numeric value, so that
+@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
+@code{(eql 1 1)} both return @code{t}.
+@end defun
+
+@defun /= number-or-marker1 number-or-marker2
+This function tests whether its arguments are numerically equal, and
+returns @code{t} if they are not, and @code{nil} if they are.
+@end defun
+
+@defun <  number-or-marker1 number-or-marker2
+This function tests whether its first argument is strictly less than
+its second argument.  It returns @code{t} if so, @code{nil} otherwise.
+@end defun
+
+@defun <=  number-or-marker1 number-or-marker2
+This function tests whether its first argument is less than or equal
+to its second argument.  It returns @code{t} if so, @code{nil}
+otherwise.
+@end defun
+
+@defun >  number-or-marker1 number-or-marker2
+This function tests whether its first argument is strictly greater
+than its second argument.  It returns @code{t} if so, @code{nil}
+otherwise.
+@end defun
+
+@defun >=  number-or-marker1 number-or-marker2
+This function tests whether its first argument is greater than or
+equal to its second argument.  It returns @code{t} if so, @code{nil}
+otherwise.
+@end defun
+
+@defun max number-or-marker &rest numbers-or-markers
+This function returns the largest of its arguments.
+If any of the arguments is floating-point, the value is returned
+as floating point, even if it was given as an integer.
+
+@example
+(max 20)
+     @result{} 20
+(max 1 2.5)
+     @result{} 2.5
+(max 1 3 2.5)
+     @result{} 3.0
+@end example
+@end defun
+
+@defun min number-or-marker &rest numbers-or-markers
+This function returns the smallest of its arguments.
+If any of the arguments is floating-point, the value is returned
+as floating point, even if it was given as an integer.
+
+@example
+(min -4 1)
+     @result{} -4
+@end example
+@end defun
+
+@defun abs number
+This function returns the absolute value of @var{number}.
+@end defun
+
+@node Numeric Conversions
+@section Numeric Conversions
+@cindex rounding in conversions
+@cindex number conversions
+@cindex converting numbers
+
+To convert an integer to floating point, use the function @code{float}.
+
+@defun float number
+This returns @var{number} converted to floating point.
+If @var{number} is already a floating point number, @code{float} returns
+it unchanged.
+@end defun
+
+There are four functions to convert floating point numbers to integers;
+they differ in how they round.  All accept an argument @var{number}
+and an optional argument @var{divisor}.  Both arguments may be
+integers or floating point numbers.  @var{divisor} may also be
+@code{nil}.  If @var{divisor} is @code{nil} or omitted, these
+functions convert @var{number} to an integer, or return it unchanged
+if it already is an integer.  If @var{divisor} is non-@code{nil}, they
+divide @var{number} by @var{divisor} and convert the result to an
+integer.  An @code{arith-error} results if @var{divisor} is 0.
+
+@defun truncate number &optional divisor
+This returns @var{number}, converted to an integer by rounding towards
+zero.
+
+@example
+(truncate 1.2)
+     @result{} 1
+(truncate 1.7)
+     @result{} 1
+(truncate -1.2)
+     @result{} -1
+(truncate -1.7)
+     @result{} -1
+@end example
+@end defun
+
+@defun floor number &optional divisor
+This returns @var{number}, converted to an integer by rounding downward
+(towards negative infinity).
+
+If @var{divisor} is specified, this uses the kind of division
+operation that corresponds to @code{mod}, rounding downward.
+
+@example
+(floor 1.2)
+     @result{} 1
+(floor 1.7)
+     @result{} 1
+(floor -1.2)
+     @result{} -2
+(floor -1.7)
+     @result{} -2
+(floor 5.99 3)
+     @result{} 1
+@end example
+@end defun
+
+@defun ceiling number &optional divisor
+This returns @var{number}, converted to an integer by rounding upward
+(towards positive infinity).
+
+@example
+(ceiling 1.2)
+     @result{} 2
+(ceiling 1.7)
+     @result{} 2
+(ceiling -1.2)
+     @result{} -1
+(ceiling -1.7)
+     @result{} -1
+@end example
+@end defun
+
+@defun round number &optional divisor
+This returns @var{number}, converted to an integer by rounding towards the
+nearest integer.  Rounding a value equidistant between two integers
+may choose the integer closer to zero, or it may prefer an even integer,
+depending on your machine.
+
+@example
+(round 1.2)
+     @result{} 1
+(round 1.7)
+     @result{} 2
+(round -1.2)
+     @result{} -1
+(round -1.7)
+     @result{} -2
+@end example
+@end defun
+
+@node Arithmetic Operations
+@section Arithmetic Operations
+@cindex arithmetic operations
+
+  Emacs Lisp provides the traditional four arithmetic operations:
+addition, subtraction, multiplication, and division.  Remainder and modulus
+functions supplement the division functions.  The functions to
+add or subtract 1 are provided because they are traditional in Lisp and
+commonly used.
+
+  All of these functions except @code{%} return a floating point value
+if any argument is floating.
+
+  It is important to note that in Emacs Lisp, arithmetic functions
+do not check for overflow.  Thus @code{(1+ 268435455)} may evaluate to
+@minus{}268435456, depending on your hardware.
+
+@defun 1+ number-or-marker
+This function returns @var{number-or-marker} plus 1.
+For example,
+
+@example
+(setq foo 4)
+     @result{} 4
+(1+ foo)
+     @result{} 5
+@end example
+
+This function is not analogous to the C operator @code{++}---it does not
+increment a variable.  It just computes a sum.  Thus, if we continue,
+
+@example
+foo
+     @result{} 4
+@end example
+
+If you want to increment the variable, you must use @code{setq},
+like this:
+
+@example
+(setq foo (1+ foo))
+     @result{} 5
+@end example
+@end defun
+
+@defun 1- number-or-marker
+This function returns @var{number-or-marker} minus 1.
+@end defun
+
+@defun + &rest numbers-or-markers
+This function adds its arguments together.  When given no arguments,
+@code{+} returns 0.
+
+@example
+(+)
+     @result{} 0
+(+ 1)
+     @result{} 1
+(+ 1 2 3 4)
+     @result{} 10
+@end example
+@end defun
+
+@defun - &optional number-or-marker &rest more-numbers-or-markers
+The @code{-} function serves two purposes: negation and subtraction.
+When @code{-} has a single argument, the value is the negative of the
+argument.  When there are multiple arguments, @code{-} subtracts each of
+the @var{more-numbers-or-markers} from @var{number-or-marker},
+cumulatively.  If there are no arguments, the result is 0.
+
+@example
+(- 10 1 2 3 4)
+     @result{} 0
+(- 10)
+     @result{} -10
+(-)
+     @result{} 0
+@end example
+@end defun
+
+@defun * &rest numbers-or-markers
+This function multiplies its arguments together, and returns the
+product.  When given no arguments, @code{*} returns 1.
+
+@example
+(*)
+     @result{} 1
+(* 1)
+     @result{} 1
+(* 1 2 3 4)
+     @result{} 24
+@end example
+@end defun
+
+@defun / dividend divisor &rest divisors
+This function divides @var{dividend} by @var{divisor} and returns the
+quotient.  If there are additional arguments @var{divisors}, then it
+divides @var{dividend} by each divisor in turn.  Each argument may be a
+number or a marker.
+
+If all the arguments are integers, then the result is an integer too.
+This means the result has to be rounded.  On most machines, the result
+is rounded towards zero after each division, but some machines may round
+differently with negative arguments.  This is because the Lisp function
+@code{/} is implemented using the C division operator, which also
+permits machine-dependent rounding.  As a practical matter, all known
+machines round in the standard fashion.
+
+@cindex @code{arith-error} in division
+If you divide an integer by 0, an @code{arith-error} error is signaled.
+(@xref{Errors}.)  Floating point division by zero returns either
+infinity or a NaN if your machine supports @acronym{IEEE} floating point;
+otherwise, it signals an @code{arith-error} error.
+
+@example
+@group
+(/ 6 2)
+     @result{} 3
+@end group
+(/ 5 2)
+     @result{} 2
+(/ 5.0 2)
+     @result{} 2.5
+(/ 5 2.0)
+     @result{} 2.5
+(/ 5.0 2.0)
+     @result{} 2.5
+(/ 25 3 2)
+     @result{} 4
+@group
+(/ -17 6)
+     @result{} -2   @r{(could in theory be @minus{}3 on some machines)}
+@end group
+@end example
+@end defun
+
+@defun % dividend divisor
+@cindex remainder
+This function returns the integer remainder after division of @var{dividend}
+by @var{divisor}.  The arguments must be integers or markers.
+
+For negative arguments, the remainder is in principle machine-dependent
+since the quotient is; but in practice, all known machines behave alike.
+
+An @code{arith-error} results if @var{divisor} is 0.
+
+@example
+(% 9 4)
+     @result{} 1
+(% -9 4)
+     @result{} -1
+(% 9 -4)
+     @result{} 1
+(% -9 -4)
+     @result{} -1
+@end example
+
+For any two integers @var{dividend} and @var{divisor},
+
+@example
+@group
+(+ (% @var{dividend} @var{divisor})
+   (* (/ @var{dividend} @var{divisor}) @var{divisor}))
+@end group
+@end example
+
+@noindent
+always equals @var{dividend}.
+@end defun
+
+@defun mod dividend divisor
+@cindex modulus
+This function returns the value of @var{dividend} modulo @var{divisor};
+in other words, the remainder after division of @var{dividend}
+by @var{divisor}, but with the same sign as @var{divisor}.
+The arguments must be numbers or markers.
+
+Unlike @code{%}, @code{mod} returns a well-defined result for negative
+arguments.  It also permits floating point arguments; it rounds the
+quotient downward (towards minus infinity) to an integer, and uses that
+quotient to compute the remainder.
+
+An @code{arith-error} results if @var{divisor} is 0.
+
+@example
+@group
+(mod 9 4)
+     @result{} 1
+@end group
+@group
+(mod -9 4)
+     @result{} 3
+@end group
+@group
+(mod 9 -4)
+     @result{} -3
+@end group
+@group
+(mod -9 -4)
+     @result{} -1
+@end group
+@group
+(mod 5.5 2.5)
+     @result{} .5
+@end group
+@end example
+
+For any two numbers @var{dividend} and @var{divisor},
+
+@example
+@group
+(+ (mod @var{dividend} @var{divisor})
+   (* (floor @var{dividend} @var{divisor}) @var{divisor}))
+@end group
+@end example
+
+@noindent
+always equals @var{dividend}, subject to rounding error if either
+argument is floating point.  For @code{floor}, see @ref{Numeric
+Conversions}.
+@end defun
+
+@node Rounding Operations
+@section Rounding Operations
+@cindex rounding without conversion
+
+The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
+@code{ftruncate} take a floating point argument and return a floating
+point result whose value is a nearby integer.  @code{ffloor} returns the
+nearest integer below; @code{fceiling}, the nearest integer above;
+@code{ftruncate}, the nearest integer in the direction towards zero;
+@code{fround}, the nearest integer.
+
+@defun ffloor float
+This function rounds @var{float} to the next lower integral value, and
+returns that value as a floating point number.
+@end defun
+
+@defun fceiling float
+This function rounds @var{float} to the next higher integral value, and
+returns that value as a floating point number.
+@end defun
+
+@defun ftruncate float
+This function rounds @var{float} towards zero to an integral value, and
+returns that value as a floating point number.
+@end defun
+
+@defun fround float
+This function rounds @var{float} to the nearest integral value,
+and returns that value as a floating point number.
+@end defun
+
+@node Bitwise Operations
+@section Bitwise Operations on Integers
+@cindex bitwise arithmetic
+@cindex logical arithmetic
+
+  In a computer, an integer is represented as a binary number, a
+sequence of @dfn{bits} (digits which are either zero or one).  A bitwise
+operation acts on the individual bits of such a sequence.  For example,
+@dfn{shifting} moves the whole sequence left or right one or more places,
+reproducing the same pattern ``moved over.''
+
+  The bitwise operations in Emacs Lisp apply only to integers.
+
+@defun lsh integer1 count
+@cindex logical shift
+@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
+bits in @var{integer1} to the left @var{count} places, or to the right
+if @var{count} is negative, bringing zeros into the vacated bits.  If
+@var{count} is negative, @code{lsh} shifts zeros into the leftmost
+(most-significant) bit, producing a positive result even if
+@var{integer1} is negative.  Contrast this with @code{ash}, below.
+
+Here are two examples of @code{lsh}, shifting a pattern of bits one
+place to the left.  We show only the low-order eight bits of the binary
+pattern; the rest are all zero.
+
+@example
+@group
+(lsh 5 1)
+     @result{} 10
+;; @r{Decimal 5 becomes decimal 10.}
+00000101 @result{} 00001010
+
+(lsh 7 1)
+     @result{} 14
+;; @r{Decimal 7 becomes decimal 14.}
+00000111 @result{} 00001110
+@end group
+@end example
+
+@noindent
+As the examples illustrate, shifting the pattern of bits one place to
+the left produces a number that is twice the value of the previous
+number.
+
+Shifting a pattern of bits two places to the left produces results
+like this (with 8-bit binary numbers):
+
+@example
+@group
+(lsh 3 2)
+     @result{} 12
+;; @r{Decimal 3 becomes decimal 12.}
+00000011 @result{} 00001100
+@end group
+@end example
+
+On the other hand, shifting one place to the right looks like this:
+
+@example
+@group
+(lsh 6 -1)
+     @result{} 3
+;; @r{Decimal 6 becomes decimal 3.}
+00000110 @result{} 00000011
+@end group
+
+@group
+(lsh 5 -1)
+     @result{} 2
+;; @r{Decimal 5 becomes decimal 2.}
+00000101 @result{} 00000010
+@end group
+@end example
+
+@noindent
+As the example illustrates, shifting one place to the right divides the
+value of a positive integer by two, rounding downward.
+
+The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
+not check for overflow, so shifting left can discard significant bits
+and change the sign of the number.  For example, left shifting
+268,435,455 produces @minus{}2 on a 29-bit machine:
+
+@example
+(lsh 268435455 1)          ; @r{left shift}
+     @result{} -2
+@end example
+
+In binary, in the 29-bit implementation, the argument looks like this:
+
+@example
+@group
+;; @r{Decimal 268,435,455}
+0 1111  1111 1111  1111 1111  1111 1111
+@end group
+@end example
+
+@noindent
+which becomes the following when left shifted:
+
+@example
+@group
+;; @r{Decimal @minus{}2}
+1 1111  1111 1111  1111 1111  1111 1110
+@end group
+@end example
+@end defun
+
+@defun ash integer1 count
+@cindex arithmetic shift
+@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
+to the left @var{count} places, or to the right if @var{count}
+is negative.
+
+@code{ash} gives the same results as @code{lsh} except when
+@var{integer1} and @var{count} are both negative.  In that case,
+@code{ash} puts ones in the empty bit positions on the left, while
+@code{lsh} puts zeros in those bit positions.
+
+Thus, with @code{ash}, shifting the pattern of bits one place to the right
+looks like this:
+
+@example
+@group
+(ash -6 -1) @result{} -3
+;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
+1 1111  1111 1111  1111 1111  1111 1010
+     @result{}
+1 1111  1111 1111  1111 1111  1111 1101
+@end group
+@end example
+
+In contrast, shifting the pattern of bits one place to the right with
+@code{lsh} looks like this:
+
+@example
+@group
+(lsh -6 -1) @result{} 268435453
+;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
+1 1111  1111 1111  1111 1111  1111 1010
+     @result{}
+0 1111  1111 1111  1111 1111  1111 1101
+@end group
+@end example
+
+Here are other examples:
+
+@c !!! Check if lined up in smallbook format!  XDVI shows problem
+@c     with smallbook but not with regular book! --rjc 16mar92
+@smallexample
+@group
+                   ;  @r{             29-bit binary values}
+
+(lsh 5 2)          ;   5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 20         ;      =  @r{0 0000  0000 0000  0000 0000  0001 0100}
+@end group
+@group
+(ash 5 2)
+     @result{} 20
+(lsh -5 2)         ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} -20        ;      =  @r{1 1111  1111 1111  1111 1111  1110 1100}
+(ash -5 2)
+     @result{} -20
+@end group
+@group
+(lsh 5 -2)         ;   5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 1          ;      =  @r{0 0000  0000 0000  0000 0000  0000 0001}
+@end group
+@group
+(ash 5 -2)
+     @result{} 1
+@end group
+@group
+(lsh -5 -2)        ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} 134217726  ;      =  @r{0 0111  1111 1111  1111 1111  1111 1110}
+@end group
+@group
+(ash -5 -2)        ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} -2         ;      =  @r{1 1111  1111 1111  1111 1111  1111 1110}
+@end group
+@end smallexample
+@end defun
+
+@defun logand &rest ints-or-markers
+This function returns the ``logical and'' of the arguments: the
+@var{n}th bit is set in the result if, and only if, the @var{n}th bit is
+set in all the arguments.  (``Set'' means that the value of the bit is 1
+rather than 0.)
+
+For example, using 4-bit binary numbers, the ``logical and'' of 13 and
+12 is 12: 1101 combined with 1100 produces 1100.
+In both the binary numbers, the leftmost two bits are set (i.e., they
+are 1's), so the leftmost two bits of the returned value are set.
+However, for the rightmost two bits, each is zero in at least one of
+the arguments, so the rightmost two bits of the returned value are 0's.
+
+@noindent
+Therefore,
+
+@example
+@group
+(logand 13 12)
+     @result{} 12
+@end group
+@end example
+
+If @code{logand} is not passed any argument, it returns a value of
+@minus{}1.  This number is an identity element for @code{logand}
+because its binary representation consists entirely of ones.  If
+@code{logand} is passed just one argument, it returns that argument.
+
+@smallexample
+@group
+                   ; @r{               29-bit binary values}
+
+(logand 14 13)     ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
+                   ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
+     @result{} 12         ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+@end group
+
+@group
+(logand 14 13 4)   ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
+                   ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
+                   ;  4  =  @r{0 0000  0000 0000  0000 0000  0000 0100}
+     @result{} 4          ;  4  =  @r{0 0000  0000 0000  0000 0000  0000 0100}
+@end group
+
+@group
+(logand)
+     @result{} -1         ; -1  =  @r{1 1111  1111 1111  1111 1111  1111 1111}
+@end group
+@end smallexample
+@end defun
+
+@defun logior &rest ints-or-markers
+This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
+is set in the result if, and only if, the @var{n}th bit is set in at least
+one of the arguments.  If there are no arguments, the result is zero,
+which is an identity element for this operation.  If @code{logior} is
+passed just one argument, it returns that argument.
+
+@smallexample
+@group
+                   ; @r{              29-bit binary values}
+
+(logior 12 5)      ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 13         ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
+@end group
+
+@group
+(logior 12 5 7)    ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+                   ;  7  =  @r{0 0000  0000 0000  0000 0000  0000 0111}
+     @result{} 15         ; 15  =  @r{0 0000  0000 0000  0000 0000  0000 1111}
+@end group
+@end smallexample
+@end defun
+
+@defun logxor &rest ints-or-markers
+This function returns the ``exclusive or'' of its arguments: the
+@var{n}th bit is set in the result if, and only if, the @var{n}th bit is
+set in an odd number of the arguments.  If there are no arguments, the
+result is 0, which is an identity element for this operation.  If
+@code{logxor} is passed just one argument, it returns that argument.
+
+@smallexample
+@group
+                   ; @r{              29-bit binary values}
+
+(logxor 12 5)      ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 9          ;  9  =  @r{0 0000  0000 0000  0000 0000  0000 1001}
+@end group
+
+@group
+(logxor 12 5 7)    ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+                   ;  7  =  @r{0 0000  0000 0000  0000 0000  0000 0111}
+     @result{} 14         ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
+@end group
+@end smallexample
+@end defun
+
+@defun lognot integer
+This function returns the logical complement of its argument: the @var{n}th
+bit is one in the result if, and only if, the @var{n}th bit is zero in
+@var{integer}, and vice-versa.
+
+@example
+(lognot 5)
+     @result{} -6
+;;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+;; @r{becomes}
+;; -6  =  @r{1 1111  1111 1111  1111 1111  1111 1010}
+@end example
+@end defun
+
+@node Math Functions
+@section Standard Mathematical Functions
+@cindex transcendental functions
+@cindex mathematical functions
+@cindex floating-point functions
+
+  These mathematical functions allow integers as well as floating point
+numbers as arguments.
+
+@defun sin arg
+@defunx cos arg
+@defunx tan arg
+These are the ordinary trigonometric functions, with argument measured
+in radians.
+@end defun
+
+@defun asin arg
+The value of @code{(asin @var{arg})} is a number between
+@ifnottex
+@minus{}pi/2
+@end ifnottex
+@tex
+@math{-\pi/2}
+@end tex
+and
+@ifnottex
+pi/2
+@end ifnottex
+@tex
+@math{\pi/2}
+@end tex
+(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
+range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
+@end defun
+
+@defun acos arg
+The value of @code{(acos @var{arg})} is a number between 0 and
+@ifnottex
+pi
+@end ifnottex
+@tex
+@math{\pi}
+@end tex
+(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
+of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
+@end defun
+
+@defun atan y &optional x
+The value of @code{(atan @var{y})} is a number between
+@ifnottex
+@minus{}pi/2
+@end ifnottex
+@tex
+@math{-\pi/2}
+@end tex
+and
+@ifnottex
+pi/2
+@end ifnottex
+@tex
+@math{\pi/2}
+@end tex
+(exclusive) whose tangent is @var{y}.  If the optional second
+argument @var{x} is given, the value of @code{(atan y x)} is the
+angle in radians between the vector @code{[@var{x}, @var{y}]} and the
+@code{X} axis.
+@end defun
+
+@defun exp arg
+This is the exponential function; it returns
+@tex
+@math{e}
+@end tex
+@ifnottex
+@i{e}
+@end ifnottex
+to the power @var{arg}.
+@tex
+@math{e}
+@end tex
+@ifnottex
+@i{e}
+@end ifnottex
+is a fundamental mathematical constant also called the base of natural
+logarithms.
+@end defun
+
+@defun log arg &optional base
+This function returns the logarithm of @var{arg}, with base @var{base}.
+If you don't specify @var{base}, the base
+@tex
+@math{e}
+@end tex
+@ifnottex
+@i{e}
+@end ifnottex
+is used.  If @var{arg} is negative, it signals a @code{domain-error}
+error.
+@end defun
+
+@ignore
+@defun expm1 arg
+This function returns @code{(1- (exp @var{arg}))}, but it is more
+accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
+is close to 1.
+@end defun
+
+@defun log1p arg
+This function returns @code{(log (1+ @var{arg}))}, but it is more
+accurate than that when @var{arg} is so small that adding 1 to it would
+lose accuracy.
+@end defun
+@end ignore
+
+@defun log10 arg
+This function returns the logarithm of @var{arg}, with base 10.  If
+@var{arg} is negative, it signals a @code{domain-error} error.
+@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
+approximately.
+@end defun
+
+@defun expt x y
+This function returns @var{x} raised to power @var{y}.  If both
+arguments are integers and @var{y} is positive, the result is an
+integer; in this case, overflow causes truncation, so watch out.
+@end defun
+
+@defun sqrt arg
+This returns the square root of @var{arg}.  If @var{arg} is negative,
+it signals a @code{domain-error} error.
+@end defun
+
+@node Random Numbers
+@section Random Numbers
+@cindex random numbers
+
+A deterministic computer program cannot generate true random numbers.
+For most purposes, @dfn{pseudo-random numbers} suffice.  A series of
+pseudo-random numbers is generated in a deterministic fashion.  The
+numbers are not truly random, but they have certain properties that
+mimic a random series.  For example, all possible values occur equally
+often in a pseudo-random series.
+
+In Emacs, pseudo-random numbers are generated from a ``seed'' number.
+Starting from any given seed, the @code{random} function always
+generates the same sequence of numbers.  Emacs always starts with the
+same seed value, so the sequence of values of @code{random} is actually
+the same in each Emacs run!  For example, in one operating system, the
+first call to @code{(random)} after you start Emacs always returns
+@minus{}1457731, and the second one always returns @minus{}7692030.  This
+repeatability is helpful for debugging.
+
+If you want random numbers that don't always come out the same, execute
+@code{(random t)}.  This chooses a new seed based on the current time of
+day and on Emacs's process @acronym{ID} number.
+
+@defun random &optional limit
+This function returns a pseudo-random integer.  Repeated calls return a
+series of pseudo-random integers.
+
+If @var{limit} is a positive integer, the value is chosen to be
+nonnegative and less than @var{limit}.
+
+If @var{limit} is @code{t}, it means to choose a new seed based on the
+current time of day and on Emacs's process @acronym{ID} number.
+@c "Emacs'" is incorrect usage!
+
+On some machines, any integer representable in Lisp may be the result
+of @code{random}.  On other machines, the result can never be larger
+than a certain maximum or less than a certain (negative) minimum.
+@end defun
+
+@ignore
+   arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e
+@end ignore
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
new file mode 100644
index 00000000000..e75cde70202
--- /dev/null
+++ b/doc/lispref/objects.texi
@@ -0,0 +1,2036 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/objects
+@node Lisp Data Types, Numbers, Introduction, Top
+@chapter Lisp Data Types
+@cindex object
+@cindex Lisp object
+@cindex type
+@cindex data type
+
+  A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
+programs.  For our purposes, a @dfn{type} or @dfn{data type} is a set of
+possible objects.
+
+  Every object belongs to at least one type.  Objects of the same type
+have similar structures and may usually be used in the same contexts.
+Types can overlap, and objects can belong to two or more types.
+Consequently, we can ask whether an object belongs to a particular type,
+but not for ``the'' type of an object.
+
+@cindex primitive type
+  A few fundamental object types are built into Emacs.  These, from
+which all other types are constructed, are called @dfn{primitive types}.
+Each object belongs to one and only one primitive type.  These types
+include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
+@dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and
+@dfn{byte-code function}, plus several special types, such as
+@dfn{buffer}, that are related to editing.  (@xref{Editing Types}.)
+
+  Each primitive type has a corresponding Lisp function that checks
+whether an object is a member of that type.
+
+  Note that Lisp is unlike many other languages in that Lisp objects are
+@dfn{self-typing}: the primitive type of the object is implicit in the
+object itself.  For example, if an object is a vector, nothing can treat
+it as a number; Lisp knows it is a vector, not a number.
+
+  In most languages, the programmer must declare the data type of each
+variable, and the type is known by the compiler but not represented in
+the data.  Such type declarations do not exist in Emacs Lisp.  A Lisp
+variable can have any type of value, and it remembers whatever value
+you store in it, type and all.  (Actually, a small number of Emacs
+Lisp variables can only take on values of a certain type.
+@xref{Variables with Restricted Values}.)
+
+  This chapter describes the purpose, printed representation, and read
+syntax of each of the standard types in GNU Emacs Lisp.  Details on how
+to use these types can be found in later chapters.
+
+@menu
+* Printed Representation::      How Lisp objects are represented as text.
+* Comments::                    Comments and their formatting conventions.
+* Programming Types::           Types found in all Lisp systems.
+* Editing Types::               Types specific to Emacs.
+* Circular Objects::            Read syntax for circular structure.
+* Type Predicates::             Tests related to types.
+* Equality Predicates::         Tests of equality between any two objects.
+@end menu
+
+@node Printed Representation
+@comment  node-name,  next,  previous,  up
+@section Printed Representation and Read Syntax
+@cindex printed representation
+@cindex read syntax
+
+  The @dfn{printed representation} of an object is the format of the
+output generated by the Lisp printer (the function @code{prin1}) for
+that object.  Every data type has a unique printed representation.
+The @dfn{read syntax} of an object is the format of the input accepted
+by the Lisp reader (the function @code{read}) for that object.  This
+is not necessarily unique; many kinds of object have more than one
+syntax.  @xref{Read and Print}.
+
+@cindex hash notation
+  In most cases, an object's printed representation is also a read
+syntax for the object.  However, some types have no read syntax, since
+it does not make sense to enter objects of these types as constants in
+a Lisp program.  These objects are printed in @dfn{hash notation},
+which consists of the characters @samp{#<}, a descriptive string
+(typically the type name followed by the name of the object), and a
+closing @samp{>}.  For example:
+
+@example
+(current-buffer)
+     @result{} #<buffer objects.texi>
+@end example
+
+@noindent
+Hash notation cannot be read at all, so the Lisp reader signals the
+error @code{invalid-read-syntax} whenever it encounters @samp{#<}.
+@kindex invalid-read-syntax
+
+  In other languages, an expression is text; it has no other form.  In
+Lisp, an expression is primarily a Lisp object and only secondarily the
+text that is the object's read syntax.  Often there is no need to
+emphasize this distinction, but you must keep it in the back of your
+mind, or you will occasionally be very confused.
+
+  When you evaluate an expression interactively, the Lisp interpreter
+first reads the textual representation of it, producing a Lisp object,
+and then evaluates that object (@pxref{Evaluation}).  However,
+evaluation and reading are separate activities.  Reading returns the
+Lisp object represented by the text that is read; the object may or may
+not be evaluated later.  @xref{Input Functions}, for a description of
+@code{read}, the basic function for reading objects.
+
+@node Comments
+@comment  node-name,  next,  previous,  up
+@section Comments
+@cindex comments
+@cindex @samp{;} in comment
+
+  A @dfn{comment} is text that is written in a program only for the sake
+of humans that read the program, and that has no effect on the meaning
+of the program.  In Lisp, a semicolon (@samp{;}) starts a comment if it
+is not within a string or character constant.  The comment continues to
+the end of line.  The Lisp reader discards comments; they do not become
+part of the Lisp objects which represent the program within the Lisp
+system.
+
+  The @samp{#@@@var{count}} construct, which skips the next @var{count}
+characters, is useful for program-generated comments containing binary
+data.  The Emacs Lisp byte compiler uses this in its output files
+(@pxref{Byte Compilation}).  It isn't meant for source files, however.
+
+  @xref{Comment Tips}, for conventions for formatting comments.
+
+@node Programming Types
+@section Programming Types
+@cindex programming types
+
+  There are two general categories of types in Emacs Lisp: those having
+to do with Lisp programming, and those having to do with editing.  The
+former exist in many Lisp implementations, in one form or another.  The
+latter are unique to Emacs Lisp.
+
+@menu
+* Integer Type::        Numbers without fractional parts.
+* Floating Point Type:: Numbers with fractional parts and with a large range.
+* Character Type::      The representation of letters, numbers and
+                        control characters.
+* Symbol Type::         A multi-use object that refers to a function,
+                        variable, or property list, and has a unique identity.
+* Sequence Type::       Both lists and arrays are classified as sequences.
+* Cons Cell Type::      Cons cells, and lists (which are made from cons cells).
+* Array Type::          Arrays include strings and vectors.
+* String Type::         An (efficient) array of characters.
+* Vector Type::         One-dimensional arrays.
+* Char-Table Type::     One-dimensional sparse arrays indexed by characters.
+* Bool-Vector Type::    One-dimensional arrays of @code{t} or @code{nil}.
+* Hash Table Type::     Super-fast lookup tables.
+* Function Type::       A piece of executable code you can call from elsewhere.
+* Macro Type::          A method of expanding an expression into another
+                          expression, more fundamental but less pretty.
+* Primitive Function Type::     A function written in C, callable from Lisp.
+* Byte-Code Type::      A function written in Lisp, then compiled.
+* Autoload Type::       A type used for automatically loading seldom-used
+                        functions.
+@end menu
+
+@node Integer Type
+@subsection Integer Type
+
+  The range of values for integers in Emacs Lisp is @minus{}268435456 to
+268435455 (29 bits; i.e.,
+@ifnottex
+-2**28
+@end ifnottex
+@tex
+@math{-2^{28}}
+@end tex
+to
+@ifnottex
+2**28 - 1)
+@end ifnottex
+@tex
+@math{2^{28}-1})
+@end tex
+on most machines.  (Some machines may provide a wider range.)  It is
+important to note that the Emacs Lisp arithmetic functions do not check
+for overflow.  Thus @code{(1+ 268435455)} is @minus{}268435456 on most
+machines.
+
+  The read syntax for integers is a sequence of (base ten) digits with an
+optional sign at the beginning and an optional period at the end.  The
+printed representation produced by the Lisp interpreter never has a
+leading @samp{+} or a final @samp{.}.
+
+@example
+@group
+-1               ; @r{The integer -1.}
+1                ; @r{The integer 1.}
+1.               ; @r{Also the integer 1.}
++1               ; @r{Also the integer 1.}
+536870913        ; @r{Also the integer 1 on a 29-bit implementation.}
+@end group
+@end example
+
+  @xref{Numbers}, for more information.
+
+@node Floating Point Type
+@subsection Floating Point Type
+
+  Floating point numbers are the computer equivalent of scientific
+notation; you can think of a floating point number as a fraction
+together with a power of ten.  The precise number of significant
+figures and the range of possible exponents is machine-specific; Emacs
+uses the C data type @code{double} to store the value, and internally
+this records a power of 2 rather than a power of 10.
+
+  The printed representation for floating point numbers requires either
+a decimal point (with at least one digit following), an exponent, or
+both.  For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
+@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
+number whose value is 1500.  They are all equivalent.
+
+  @xref{Numbers}, for more information.
+
+@node Character Type
+@subsection Character Type
+@cindex @acronym{ASCII} character codes
+
+  A @dfn{character} in Emacs Lisp is nothing more than an integer.  In
+other words, characters are represented by their character codes.  For
+example, the character @kbd{A} is represented as the @w{integer 65}.
+
+  Individual characters are used occasionally in programs, but it is
+more common to work with @emph{strings}, which are sequences composed
+of characters.  @xref{String Type}.
+
+  Characters in strings, buffers, and files are currently limited to
+the range of 0 to 524287---nineteen bits.  But not all values in that
+range are valid character codes.  Codes 0 through 127 are
+@acronym{ASCII} codes; the rest are non-@acronym{ASCII}
+(@pxref{Non-ASCII Characters}).  Characters that represent keyboard
+input have a much wider range, to encode modifier keys such as
+Control, Meta and Shift.
+
+  There are special functions for producing a human-readable textual
+description of a character for the sake of messages.  @xref{Describing
+Characters}.
+
+@menu
+* Basic Char Syntax::
+* General Escape Syntax::
+* Ctl-Char Syntax::
+* Meta-Char Syntax::
+* Other Char Bits::
+@end menu
+
+@node Basic Char Syntax
+@subsubsection Basic Char Syntax
+@cindex read syntax for characters
+@cindex printed representation for characters
+@cindex syntax for characters
+@cindex @samp{?} in character constant
+@cindex question mark in character constant
+
+  Since characters are really integers, the printed representation of
+a character is a decimal number.  This is also a possible read syntax
+for a character, but writing characters that way in Lisp programs is
+not clear programming.  You should @emph{always} use the special read
+syntax formats that Emacs Lisp provides for characters.  These syntax
+formats start with a question mark.
+
+  The usual read syntax for alphanumeric characters is a question mark
+followed by the character; thus, @samp{?A} for the character
+@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
+character @kbd{a}.
+
+  For example:
+
+@example
+?Q @result{} 81     ?q @result{} 113
+@end example
+
+  You can use the same syntax for punctuation characters, but it is
+often a good idea to add a @samp{\} so that the Emacs commands for
+editing Lisp code don't get confused.  For example, @samp{?\(} is the
+way to write the open-paren character.  If the character is @samp{\},
+you @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
+
+@cindex whitespace
+@cindex bell character
+@cindex @samp{\a}
+@cindex backspace
+@cindex @samp{\b}
+@cindex tab (ASCII character)
+@cindex @samp{\t}
+@cindex vertical tab
+@cindex @samp{\v}
+@cindex formfeed
+@cindex @samp{\f}
+@cindex newline
+@cindex @samp{\n}
+@cindex return (ASCII character)
+@cindex @samp{\r}
+@cindex escape (ASCII character)
+@cindex @samp{\e}
+@cindex space (ASCII character)
+@cindex @samp{\s}
+  You can express the characters control-g, backspace, tab, newline,
+vertical tab, formfeed, space, return, del, and escape as @samp{?\a},
+@samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f},
+@samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively.
+(@samp{?\s} followed by a dash has a different meaning---it applies
+the ``super'' modifier to the following character.)  Thus,
+
+@example
+?\a @result{} 7                 ; @r{control-g, @kbd{C-g}}
+?\b @result{} 8                 ; @r{backspace, @key{BS}, @kbd{C-h}}
+?\t @result{} 9                 ; @r{tab, @key{TAB}, @kbd{C-i}}
+?\n @result{} 10                ; @r{newline, @kbd{C-j}}
+?\v @result{} 11                ; @r{vertical tab, @kbd{C-k}}
+?\f @result{} 12                ; @r{formfeed character, @kbd{C-l}}
+?\r @result{} 13                ; @r{carriage return, @key{RET}, @kbd{C-m}}
+?\e @result{} 27                ; @r{escape character, @key{ESC}, @kbd{C-[}}
+?\s @result{} 32                ; @r{space character, @key{SPC}}
+?\\ @result{} 92                ; @r{backslash character, @kbd{\}}
+?\d @result{} 127               ; @r{delete character, @key{DEL}}
+@end example
+
+@cindex escape sequence
+  These sequences which start with backslash are also known as
+@dfn{escape sequences}, because backslash plays the role of an
+``escape character''; this terminology has nothing to do with the
+character @key{ESC}.  @samp{\s} is meant for use in character
+constants; in string constants, just write the space.
+
+  A backslash is allowed, and harmless, preceding any character without
+a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
+There is no reason to add a backslash before most characters.  However,
+you should add a backslash before any of the characters
+@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
+Lisp code.  You can also add a backslash before whitespace characters such as
+space, tab, newline and formfeed.  However, it is cleaner to use one of
+the easily readable escape sequences, such as @samp{\t} or @samp{\s},
+instead of an actual whitespace character such as a tab or a space.
+(If you do write backslash followed by a space, you should write
+an extra space after the character constant to separate it from the
+following text.)
+
+@node General Escape Syntax
+@subsubsection General Escape Syntax
+
+  In addition to the specific excape sequences for special important
+control characters, Emacs provides general categories of escape syntax
+that you can use to specify non-ASCII text characters.
+
+@cindex unicode character escape
+  For instance, you can specify characters by their Unicode values.
+@code{?\u@var{nnnn}} represents a character that maps to the Unicode
+code point @samp{U+@var{nnnn}}.  There is a slightly different syntax
+for specifying characters with code points above @code{#xFFFF};
+@code{\U00@var{nnnnnn}} represents the character whose Unicode code
+point is @samp{U+@var{nnnnnn}}, if such a character is supported by
+Emacs.  If the corresponding character is not supported, Emacs signals
+an error.
+
+  This peculiar and inconvenient syntax was adopted for compatibility
+with other programming languages.  Unlike some other languages, Emacs
+Lisp supports this syntax in only character literals and strings.
+
+@cindex @samp{\} in character constant
+@cindex backslash in character constant
+@cindex octal character code
+  The most general read syntax for a character represents the
+character code in either octal or hex.  To use octal, write a question
+mark followed by a backslash and the octal character code (up to three
+octal digits); thus, @samp{?\101} for the character @kbd{A},
+@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
+character @kbd{C-b}.  Although this syntax can represent any
+@acronym{ASCII} character, it is preferred only when the precise octal
+value is more important than the @acronym{ASCII} representation.
+
+@example
+@group
+?\012 @result{} 10         ?\n @result{} 10         ?\C-j @result{} 10
+?\101 @result{} 65         ?A @result{} 65
+@end group
+@end example
+
+  To use hex, write a question mark followed by a backslash, @samp{x},
+and the hexadecimal character code.  You can use any number of hex
+digits, so you can represent any character code in this way.
+Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
+character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character
+@iftex
+@samp{@`a}.
+@end iftex
+@ifnottex
+@samp{a} with grave accent.
+@end ifnottex
+
+@node Ctl-Char Syntax
+@subsubsection Control-Character Syntax
+
+@cindex control characters
+  Control characters can be represented using yet another read syntax.
+This consists of a question mark followed by a backslash, caret, and the
+corresponding non-control character, in either upper or lower case.  For
+example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
+character @kbd{C-i}, the character whose value is 9.
+
+  Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
+equivalent to @samp{?\^I} and to @samp{?\^i}:
+
+@example
+?\^I @result{} 9     ?\C-I @result{} 9
+@end example
+
+  In strings and buffers, the only control characters allowed are those
+that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
+any character into a control character with @samp{C-}.  The character
+codes for these non-@acronym{ASCII} control characters include the
+@tex
+@math{2^{26}}
+@end tex
+@ifnottex
+2**26
+@end ifnottex
+bit as well as the code for the corresponding non-control
+character.  Ordinary terminals have no way of generating non-@acronym{ASCII}
+control characters, but you can generate them straightforwardly using X
+and other window systems.
+
+  For historical reasons, Emacs treats the @key{DEL} character as
+the control equivalent of @kbd{?}:
+
+@example
+?\^? @result{} 127     ?\C-? @result{} 127
+@end example
+
+@noindent
+As a result, it is currently not possible to represent the character
+@kbd{Control-?}, which is a meaningful input character under X, using
+@samp{\C-}.  It is not easy to change this, as various Lisp files refer
+to @key{DEL} in this way.
+
+  For representing control characters to be found in files or strings,
+we recommend the @samp{^} syntax; for control characters in keyboard
+input, we prefer the @samp{C-} syntax.  Which one you use does not
+affect the meaning of the program, but may guide the understanding of
+people who read it.
+
+@node Meta-Char Syntax
+@subsubsection Meta-Character Syntax
+
+@cindex meta characters
+  A @dfn{meta character} is a character typed with the @key{META}
+modifier key.  The integer that represents such a character has the
+@tex
+@math{2^{27}}
+@end tex
+@ifnottex
+2**27
+@end ifnottex
+bit set.  We use high bits for this and other modifiers to make
+possible a wide range of basic character codes.
+
+  In a string, the
+@tex
+@math{2^{7}}
+@end tex
+@ifnottex
+2**7
+@end ifnottex
+bit attached to an @acronym{ASCII} character indicates a meta
+character; thus, the meta characters that can fit in a string have
+codes in the range from 128 to 255, and are the meta versions of the
+ordinary @acronym{ASCII} characters.  (In Emacs versions 18 and older,
+this convention was used for characters outside of strings as well.)
+
+  The read syntax for meta characters uses @samp{\M-}.  For example,
+@samp{?\M-A} stands for @kbd{M-A}.  You can use @samp{\M-} together with
+octal character codes (see below), with @samp{\C-}, or with any other
+syntax for a character.  Thus, you can write @kbd{M-A} as @samp{?\M-A},
+or as @samp{?\M-\101}.  Likewise, you can write @kbd{C-M-b} as
+@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
+
+@node Other Char Bits
+@subsubsection Other Character Modifier Bits
+
+  The case of a graphic character is indicated by its character code;
+for example, @acronym{ASCII} distinguishes between the characters @samp{a}
+and @samp{A}.  But @acronym{ASCII} has no way to represent whether a control
+character is upper case or lower case.  Emacs uses the
+@tex
+@math{2^{25}}
+@end tex
+@ifnottex
+2**25
+@end ifnottex
+bit to indicate that the shift key was used in typing a control
+character.  This distinction is possible only when you use X terminals
+or other special terminals; ordinary terminals do not report the
+distinction to the computer in any way.  The Lisp syntax for
+the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
+represents the shifted-control-o character.
+
+@cindex hyper characters
+@cindex super characters
+@cindex alt characters
+  The X Window System defines three other
+@anchor{modifier bits}modifier bits that can be set
+in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}.  The syntaxes
+for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}.  (Case is
+significant in these prefixes.)  Thus, @samp{?\H-\M-\A-x} represents
+@kbd{Alt-Hyper-Meta-x}.  (Note that @samp{\s} with no following @samp{-}
+represents the space character.)
+@tex
+Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}}
+for super and @math{2^{24}} for hyper.
+@end tex
+@ifnottex
+Numerically, the
+bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
+@end ifnottex
+
+@node Symbol Type
+@subsection Symbol Type
+
+  A @dfn{symbol} in GNU Emacs Lisp is an object with a name.  The
+symbol name serves as the printed representation of the symbol.  In
+ordinary Lisp use, with one single obarray (@pxref{Creating Symbols},
+a symbol's name is unique---no two symbols have the same name.
+
+  A symbol can serve as a variable, as a function name, or to hold a
+property list.  Or it may serve only to be distinct from all other Lisp
+objects, so that its presence in a data structure may be recognized
+reliably.  In a given context, usually only one of these uses is
+intended.  But you can use one symbol in all of these ways,
+independently.
+
+  A symbol whose name starts with a colon (@samp{:}) is called a
+@dfn{keyword symbol}.  These symbols automatically act as constants, and
+are normally used only by comparing an unknown symbol with a few
+specific alternatives.
+
+@cindex @samp{\} in symbols
+@cindex backslash in symbols
+  A symbol name can contain any characters whatever.  Most symbol names
+are written with letters, digits, and the punctuation characters
+@samp{-+=*/}.  Such names require no special punctuation; the characters
+of the name suffice as long as the name does not look like a number.
+(If it does, write a @samp{\} at the beginning of the name to force
+interpretation as a symbol.)  The characters @samp{_~!@@$%^&:<>@{@}?} are
+less often used but also require no special punctuation.  Any other
+characters may be included in a symbol's name by escaping them with a
+backslash.  In contrast to its use in strings, however, a backslash in
+the name of a symbol simply quotes the single character that follows the
+backslash.  For example, in a string, @samp{\t} represents a tab
+character; in the name of a symbol, however, @samp{\t} merely quotes the
+letter @samp{t}.  To have a symbol with a tab character in its name, you
+must actually use a tab (preceded with a backslash).  But it's rare to
+do such a thing.
+
+@cindex CL note---case of letters
+@quotation
+@b{Common Lisp note:} In Common Lisp, lower case letters are always
+``folded'' to upper case, unless they are explicitly escaped.  In Emacs
+Lisp, upper case and lower case letters are distinct.
+@end quotation
+
+  Here are several examples of symbol names.  Note that the @samp{+} in
+the fifth example is escaped to prevent it from being read as a number.
+This is not necessary in the fourth example because the rest of the name
+makes it invalid as a number.
+
+@example
+@group
+foo                 ; @r{A symbol named @samp{foo}.}
+FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
+char-to-string      ; @r{A symbol named @samp{char-to-string}.}
+@end group
+@group
+1+                  ; @r{A symbol named @samp{1+}}
+                    ;   @r{(not @samp{+1}, which is an integer).}
+@end group
+@group
+\+1                 ; @r{A symbol named @samp{+1}}
+                    ;   @r{(not a very readable name).}
+@end group
+@group
+\(*\ 1\ 2\)         ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
+@c the @'s in this next line use up three characters, hence the
+@c apparent misalignment of the comment.
++-*/_~!@@$%^&=:<>@{@}  ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
+                    ;   @r{These characters need not be escaped.}
+@end group
+@end example
+
+@ifinfo
+@c This uses ``colon'' instead of a literal `:' because Info cannot
+@c cope with a `:' in a menu
+@cindex @samp{#@var{colon}} read syntax
+@end ifinfo
+@ifnotinfo
+@cindex @samp{#:} read syntax
+@end ifnotinfo
+  Normally the Lisp reader interns all symbols (@pxref{Creating
+Symbols}).  To prevent interning, you can write @samp{#:} before the
+name of the symbol.
+
+@node Sequence Type
+@subsection Sequence Types
+
+  A @dfn{sequence} is a Lisp object that represents an ordered set of
+elements.  There are two kinds of sequence in Emacs Lisp, lists and
+arrays.  Thus, an object of type list or of type array is also
+considered a sequence.
+
+  Arrays are further subdivided into strings, vectors, char-tables and
+bool-vectors.  Vectors can hold elements of any type, but string
+elements must be characters, and bool-vector elements must be @code{t}
+or @code{nil}.  Char-tables are like vectors except that they are
+indexed by any valid character code.  The characters in a string can
+have text properties like characters in a buffer (@pxref{Text
+Properties}), but vectors do not support text properties, even when
+their elements happen to be characters.
+
+  Lists, strings and the other array types are different, but they have
+important similarities.  For example, all have a length @var{l}, and all
+have elements which can be indexed from zero to @var{l} minus one.
+Several functions, called sequence functions, accept any kind of
+sequence.  For example, the function @code{elt} can be used to extract
+an element of a sequence, given its index.  @xref{Sequences Arrays
+Vectors}.
+
+  It is generally impossible to read the same sequence twice, since
+sequences are always created anew upon reading.  If you read the read
+syntax for a sequence twice, you get two sequences with equal contents.
+There is one exception: the empty list @code{()} always stands for the
+same object, @code{nil}.
+
+@node Cons Cell Type
+@subsection Cons Cell and List Types
+@cindex address field of register
+@cindex decrement field of register
+@cindex pointers
+
+  A @dfn{cons cell} is an object that consists of two slots, called the
+@sc{car} slot and the @sc{cdr} slot.  Each slot can @dfn{hold} or
+@dfn{refer to} any Lisp object.  We also say that ``the @sc{car} of
+this cons cell is'' whatever object its @sc{car} slot currently holds,
+and likewise for the @sc{cdr}.
+
+@quotation
+A note to C programmers: in Lisp, we do not distinguish between
+``holding'' a value and ``pointing to'' the value, because pointers in
+Lisp are implicit.
+@end quotation
+
+  A @dfn{list} is a series of cons cells, linked together so that the
+@sc{cdr} slot of each cons cell holds either the next cons cell or the
+empty list.  The empty list is actually the symbol @code{nil}.
+@xref{Lists}, for functions that work on lists.  Because most cons
+cells are used as part of lists, the phrase @dfn{list structure} has
+come to refer to any structure made out of cons cells.
+
+@cindex atoms
+  Because cons cells are so central to Lisp, we also have a word for
+``an object which is not a cons cell.''  These objects are called
+@dfn{atoms}.
+
+@cindex parenthesis
+@cindex @samp{(@dots{})} in lists
+  The read syntax and printed representation for lists are identical, and
+consist of a left parenthesis, an arbitrary number of elements, and a
+right parenthesis.  Here are examples of lists:
+
+@example
+(A 2 "A")            ; @r{A list of three elements.}
+()                   ; @r{A list of no elements (the empty list).}
+nil                  ; @r{A list of no elements (the empty list).}
+("A ()")             ; @r{A list of one element: the string @code{"A ()"}.}
+(A ())               ; @r{A list of two elements: @code{A} and the empty list.}
+(A nil)              ; @r{Equivalent to the previous.}
+((A B C))            ; @r{A list of one element}
+                     ;   @r{(which is a list of three elements).}
+@end example
+
+   Upon reading, each object inside the parentheses becomes an element
+of the list.  That is, a cons cell is made for each element.  The
+@sc{car} slot of the cons cell holds the element, and its @sc{cdr}
+slot refers to the next cons cell of the list, which holds the next
+element in the list.  The @sc{cdr} slot of the last cons cell is set to
+hold @code{nil}.
+
+  The names @sc{car} and @sc{cdr} derive from the history of Lisp.  The
+original Lisp implementation ran on an @w{IBM 704} computer which
+divided words into two parts, called the ``address'' part and the
+``decrement''; @sc{car} was an instruction to extract the contents of
+the address part of a register, and @sc{cdr} an instruction to extract
+the contents of the decrement.  By contrast, ``cons cells'' are named
+for the function @code{cons} that creates them, which in turn was named
+for its purpose, the construction of cells.
+
+@menu
+* Box Diagrams::                Drawing pictures of lists.
+* Dotted Pair Notation::        A general syntax for cons cells.
+* Association List Type::       A specially constructed list.
+@end menu
+
+@node Box Diagrams
+@subsubsection Drawing Lists as Box Diagrams
+@cindex box diagrams, for lists
+@cindex diagrams, boxed, for lists
+
+  A list can be illustrated by a diagram in which the cons cells are
+shown as pairs of boxes, like dominoes.  (The Lisp reader cannot read
+such an illustration; unlike the textual notation, which can be
+understood by both humans and computers, the box illustrations can be
+understood only by humans.)  This picture represents the three-element
+list @code{(rose violet buttercup)}:
+
+@example
+@group
+    --- ---      --- ---      --- ---
+   |   |   |--> |   |   |--> |   |   |--> nil
+    --- ---      --- ---      --- ---
+     |            |            |
+     |            |            |
+      --> rose     --> violet   --> buttercup
+@end group
+@end example
+
+  In this diagram, each box represents a slot that can hold or refer to
+any Lisp object.  Each pair of boxes represents a cons cell.  Each arrow
+represents a reference to a Lisp object, either an atom or another cons
+cell.
+
+  In this example, the first box, which holds the @sc{car} of the first
+cons cell, refers to or ``holds'' @code{rose} (a symbol).  The second
+box, holding the @sc{cdr} of the first cons cell, refers to the next
+pair of boxes, the second cons cell.  The @sc{car} of the second cons
+cell is @code{violet}, and its @sc{cdr} is the third cons cell.  The
+@sc{cdr} of the third (and last) cons cell is @code{nil}.
+
+  Here is another diagram of the same list, @code{(rose violet
+buttercup)}, sketched in a different manner:
+
+@smallexample
+@group
+ ---------------       ----------------       -------------------
+| car   | cdr   |     | car    | cdr   |     | car       | cdr   |
+| rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
+|       |       |     |        |       |     |           |       |
+ ---------------       ----------------       -------------------
+@end group
+@end smallexample
+
+@cindex @code{nil} as a list
+@cindex empty list
+  A list with no elements in it is the @dfn{empty list}; it is identical
+to the symbol @code{nil}.  In other words, @code{nil} is both a symbol
+and a list.
+
+  Here is the list @code{(A ())}, or equivalently @code{(A nil)},
+depicted with boxes and arrows:
+
+@example
+@group
+    --- ---      --- ---
+   |   |   |--> |   |   |--> nil
+    --- ---      --- ---
+     |            |
+     |            |
+      --> A        --> nil
+@end group
+@end example
+
+  Here is a more complex illustration, showing the three-element list,
+@code{((pine needles) oak maple)}, the first element of which is a
+two-element list:
+
+@example
+@group
+    --- ---      --- ---      --- ---
+   |   |   |--> |   |   |--> |   |   |--> nil
+    --- ---      --- ---      --- ---
+     |            |            |
+     |            |            |
+     |             --> oak      --> maple
+     |
+     |     --- ---      --- ---
+      --> |   |   |--> |   |   |--> nil
+           --- ---      --- ---
+            |            |
+            |            |
+             --> pine     --> needles
+@end group
+@end example
+
+  The same list represented in the second box notation looks like this:
+
+@example
+@group
+ --------------       --------------       --------------
+| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
+|   o   |   o------->| oak   |   o------->| maple |  nil |
+|   |   |      |     |       |      |     |       |      |
+ -- | ---------       --------------       --------------
+    |
+    |
+    |        --------------       ----------------
+    |       | car   | cdr  |     | car     | cdr  |
+     ------>| pine  |   o------->| needles |  nil |
+            |       |      |     |         |      |
+             --------------       ----------------
+@end group
+@end example
+
+@node Dotted Pair Notation
+@subsubsection Dotted Pair Notation
+@cindex dotted pair notation
+@cindex @samp{.} in lists
+
+  @dfn{Dotted pair notation} is a general syntax for cons cells that
+represents the @sc{car} and @sc{cdr} explicitly.  In this syntax,
+@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
+the object @var{a} and whose @sc{cdr} is the object @var{b}.  Dotted
+pair notation is more general than list syntax because the @sc{cdr}
+does not have to be a list.  However, it is more cumbersome in cases
+where list syntax would work.  In dotted pair notation, the list
+@samp{(1 2 3)} is written as @samp{(1 .  (2 . (3 . nil)))}.  For
+@code{nil}-terminated lists, you can use either notation, but list
+notation is usually clearer and more convenient.  When printing a
+list, the dotted pair notation is only used if the @sc{cdr} of a cons
+cell is not a list.
+
+  Here's an example using boxes to illustrate dotted pair notation.
+This example shows the pair @code{(rose . violet)}:
+
+@example
+@group
+    --- ---
+   |   |   |--> violet
+    --- ---
+     |
+     |
+      --> rose
+@end group
+@end example
+
+  You can combine dotted pair notation with list notation to represent
+conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
+You write a dot after the last element of the list, followed by the
+@sc{cdr} of the final cons cell.  For example, @code{(rose violet
+. buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
+The object looks like this:
+
+@example
+@group
+    --- ---      --- ---
+   |   |   |--> |   |   |--> buttercup
+    --- ---      --- ---
+     |            |
+     |            |
+      --> rose     --> violet
+@end group
+@end example
+
+  The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
+there is nothing that it could mean.  If anything, it would say to put
+@code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
+used for @code{violet}.
+
+  The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
+and looks like this:
+
+@example
+@group
+    --- ---      --- ---
+   |   |   |--> |   |   |--> nil
+    --- ---      --- ---
+     |            |
+     |            |
+      --> rose     --> violet
+@end group
+@end example
+
+  Similarly, the three-element list @code{(rose violet buttercup)}
+is equivalent to @code{(rose . (violet . (buttercup)))}.
+@ifnottex
+It looks like this:
+
+@example
+@group
+    --- ---      --- ---      --- ---
+   |   |   |--> |   |   |--> |   |   |--> nil
+    --- ---      --- ---      --- ---
+     |            |            |
+     |            |            |
+      --> rose     --> violet   --> buttercup
+@end group
+@end example
+@end ifnottex
+
+@node Association List Type
+@comment  node-name,  next,  previous,  up
+@subsubsection Association List Type
+
+  An @dfn{association list} or @dfn{alist} is a specially-constructed
+list whose elements are cons cells.  In each element, the @sc{car} is
+considered a @dfn{key}, and the @sc{cdr} is considered an
+@dfn{associated value}.  (In some cases, the associated value is stored
+in the @sc{car} of the @sc{cdr}.)  Association lists are often used as
+stacks, since it is easy to add or remove associations at the front of
+the list.
+
+  For example,
+
+@example
+(setq alist-of-colors
+      '((rose . red) (lily . white) (buttercup . yellow)))
+@end example
+
+@noindent
+sets the variable @code{alist-of-colors} to an alist of three elements.  In the
+first element, @code{rose} is the key and @code{red} is the value.
+
+  @xref{Association Lists}, for a further explanation of alists and for
+functions that work on alists.  @xref{Hash Tables}, for another kind of
+lookup table, which is much faster for handling a large number of keys.
+
+@node Array Type
+@subsection Array Type
+
+  An @dfn{array} is composed of an arbitrary number of slots for
+holding or referring to other Lisp objects, arranged in a contiguous block of
+memory.  Accessing any element of an array takes approximately the same
+amount of time.  In contrast, accessing an element of a list requires
+time proportional to the position of the element in the list.  (Elements
+at the end of a list take longer to access than elements at the
+beginning of a list.)
+
+  Emacs defines four types of array: strings, vectors, bool-vectors, and
+char-tables.
+
+  A string is an array of characters and a vector is an array of
+arbitrary objects.  A bool-vector can hold only @code{t} or @code{nil}.
+These kinds of array may have any length up to the largest integer.
+Char-tables are sparse arrays indexed by any valid character code; they
+can hold arbitrary objects.
+
+  The first element of an array has index zero, the second element has
+index 1, and so on.  This is called @dfn{zero-origin} indexing.  For
+example, an array of four elements has indices 0, 1, 2, @w{and 3}.  The
+largest possible index value is one less than the length of the array.
+Once an array is created, its length is fixed.
+
+  All Emacs Lisp arrays are one-dimensional.  (Most other programming
+languages support multidimensional arrays, but they are not essential;
+you can get the same effect with nested one-dimensional arrays.)  Each
+type of array has its own read syntax; see the following sections for
+details.
+
+  The array type is a subset of the sequence type, and contains the
+string type, the vector type, the bool-vector type, and the char-table
+type.
+
+@node String Type
+@subsection String Type
+
+  A @dfn{string} is an array of characters.  Strings are used for many
+purposes in Emacs, as can be expected in a text editor; for example, as
+the names of Lisp symbols, as messages for the user, and to represent
+text extracted from buffers.  Strings in Lisp are constants: evaluation
+of a string returns the same string.
+
+  @xref{Strings and Characters}, for functions that operate on strings.
+
+@menu
+* Syntax for Strings::
+* Non-ASCII in Strings::
+* Nonprinting Characters::
+* Text Props and Strings::
+@end menu
+
+@node Syntax for Strings
+@subsubsection Syntax for Strings
+
+@cindex @samp{"} in strings
+@cindex double-quote in strings
+@cindex @samp{\} in strings
+@cindex backslash in strings
+  The read syntax for strings is a double-quote, an arbitrary number of
+characters, and another double-quote, @code{"like this"}.  To include a
+double-quote in a string, precede it with a backslash; thus, @code{"\""}
+is a string containing just a single double-quote character.  Likewise,
+you can include a backslash by preceding it with another backslash, like
+this: @code{"this \\ is a single embedded backslash"}.
+
+@cindex newline in strings
+  The newline character is not special in the read syntax for strings;
+if you write a new line between the double-quotes, it becomes a
+character in the string.  But an escaped newline---one that is preceded
+by @samp{\}---does not become part of the string; i.e., the Lisp reader
+ignores an escaped newline while reading a string.  An escaped space
+@w{@samp{\ }} is likewise ignored.
+
+@example
+"It is useful to include newlines
+in documentation strings,
+but the newline is \
+ignored if escaped."
+     @result{} "It is useful to include newlines
+in documentation strings,
+but the newline is ignored if escaped."
+@end example
+
+@node Non-ASCII in Strings
+@subsubsection Non-@acronym{ASCII} Characters in Strings
+
+  You can include a non-@acronym{ASCII} international character in a string
+constant by writing it literally.  There are two text representations
+for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
+and multibyte.  If the string constant is read from a multibyte source,
+such as a multibyte buffer or string, or a file that would be visited as
+multibyte, then the character is read as a multibyte character, and that
+makes the string multibyte.  If the string constant is read from a
+unibyte source, then the character is read as unibyte and that makes the
+string unibyte.
+
+  You can also represent a multibyte non-@acronym{ASCII} character with its
+character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
+digits as necessary.  (Multibyte non-@acronym{ASCII} character codes are all
+greater than 256.)  Any character which is not a valid hex digit
+terminates this construct.  If the next character in the string could be
+interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
+terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
+one character, @samp{a} with grave accent.  @w{@samp{\ }} in a string
+constant is just like backslash-newline; it does not contribute any
+character to the string, but it does terminate the preceding hex escape.
+
+  You can represent a unibyte non-@acronym{ASCII} character with its
+character code, which must be in the range from 128 (0200 octal) to
+255 (0377 octal).  If you write all such character codes in octal and
+the string contains no other characters forcing it to be multibyte,
+this produces a unibyte string.  However, using any hex escape in a
+string (even for an @acronym{ASCII} character) forces the string to be
+multibyte.
+
+  You can also specify characters in a string by their numeric values
+in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}).
+
+  @xref{Text Representations}, for more information about the two
+text representations.
+
+@node Nonprinting Characters
+@subsubsection Nonprinting Characters in Strings
+
+  You can use the same backslash escape-sequences in a string constant
+as in character literals (but do not use the question mark that begins a
+character constant).  For example, you can write a string containing the
+nonprinting characters tab and @kbd{C-a}, with commas and spaces between
+them, like this: @code{"\t, \C-a"}.  @xref{Character Type}, for a
+description of the read syntax for characters.
+
+  However, not all of the characters you can write with backslash
+escape-sequences are valid in strings.  The only control characters that
+a string can hold are the @acronym{ASCII} control characters.  Strings do not
+distinguish case in @acronym{ASCII} control characters.
+
+  Properly speaking, strings cannot hold meta characters; but when a
+string is to be used as a key sequence, there is a special convention
+that provides a way to represent meta versions of @acronym{ASCII}
+characters in a string.  If you use the @samp{\M-} syntax to indicate
+a meta character in a string constant, this sets the
+@tex
+@math{2^{7}}
+@end tex
+@ifnottex
+2**7
+@end ifnottex
+bit of the character in the string.  If the string is used in
+@code{define-key} or @code{lookup-key}, this numeric code is translated
+into the equivalent meta character.  @xref{Character Type}.
+
+  Strings cannot hold characters that have the hyper, super, or alt
+modifiers.
+
+@node Text Props and Strings
+@subsubsection Text Properties in Strings
+
+  A string can hold properties for the characters it contains, in
+addition to the characters themselves.  This enables programs that copy
+text between strings and buffers to copy the text's properties with no
+special effort.  @xref{Text Properties}, for an explanation of what text
+properties mean.  Strings with text properties use a special read and
+print syntax:
+
+@example
+#("@var{characters}" @var{property-data}...)
+@end example
+
+@noindent
+where @var{property-data} consists of zero or more elements, in groups
+of three as follows:
+
+@example
+@var{beg} @var{end} @var{plist}
+@end example
+
+@noindent
+The elements @var{beg} and @var{end} are integers, and together specify
+a range of indices in the string; @var{plist} is the property list for
+that range.  For example,
+
+@example
+#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
+@end example
+
+@noindent
+represents a string whose textual contents are @samp{foo bar}, in which
+the first three characters have a @code{face} property with value
+@code{bold}, and the last three have a @code{face} property with value
+@code{italic}.  (The fourth character has no text properties, so its
+property list is @code{nil}.  It is not actually necessary to mention
+ranges with @code{nil} as the property list, since any characters not
+mentioned in any range will default to having no properties.)
+
+@node Vector Type
+@subsection Vector Type
+
+  A @dfn{vector} is a one-dimensional array of elements of any type.  It
+takes a constant amount of time to access any element of a vector.  (In
+a list, the access time of an element is proportional to the distance of
+the element from the beginning of the list.)
+
+  The printed representation of a vector consists of a left square
+bracket, the elements, and a right square bracket.  This is also the
+read syntax.  Like numbers and strings, vectors are considered constants
+for evaluation.
+
+@example
+[1 "two" (three)]      ; @r{A vector of three elements.}
+     @result{} [1 "two" (three)]
+@end example
+
+  @xref{Vectors}, for functions that work with vectors.
+
+@node Char-Table Type
+@subsection Char-Table Type
+
+  A @dfn{char-table} is a one-dimensional array of elements of any type,
+indexed by character codes.  Char-tables have certain extra features to
+make them more useful for many jobs that involve assigning information
+to character codes---for example, a char-table can have a parent to
+inherit from, a default value, and a small number of extra slots to use for
+special purposes.  A char-table can also specify a single value for
+a whole character set.
+
+  The printed representation of a char-table is like a vector
+except that there is an extra @samp{#^} at the beginning.
+
+  @xref{Char-Tables}, for special functions to operate on char-tables.
+Uses of char-tables include:
+
+@itemize @bullet
+@item
+Case tables (@pxref{Case Tables}).
+
+@item
+Character category tables (@pxref{Categories}).
+
+@item
+Display tables (@pxref{Display Tables}).
+
+@item
+Syntax tables (@pxref{Syntax Tables}).
+@end itemize
+
+@node Bool-Vector Type
+@subsection Bool-Vector Type
+
+  A @dfn{bool-vector} is a one-dimensional array of elements that
+must be @code{t} or @code{nil}.
+
+  The printed representation of a bool-vector is like a string, except
+that it begins with @samp{#&} followed by the length.  The string
+constant that follows actually specifies the contents of the bool-vector
+as a bitmap---each ``character'' in the string contains 8 bits, which
+specify the next 8 elements of the bool-vector (1 stands for @code{t},
+and 0 for @code{nil}).  The least significant bits of the character
+correspond to the lowest indices in the bool-vector.
+
+@example
+(make-bool-vector 3 t)
+     @result{} #&3"^G"
+(make-bool-vector 3 nil)
+     @result{} #&3"^@@"
+@end example
+
+@noindent
+These results make sense, because the binary code for @samp{C-g} is
+111 and @samp{C-@@} is the character with code 0.
+
+  If the length is not a multiple of 8, the printed representation
+shows extra elements, but these extras really make no difference.  For
+instance, in the next example, the two bool-vectors are equal, because
+only the first 3 bits are used:
+
+@example
+(equal #&3"\377" #&3"\007")
+     @result{} t
+@end example
+
+@node Hash Table Type
+@subsection Hash Table Type
+
+    A hash table is a very fast kind of lookup table, somewhat like an
+alist in that it maps keys to corresponding values, but much faster.
+Hash tables have no read syntax, and print using hash notation.
+@xref{Hash Tables}, for functions that operate on hash tables.
+
+@example
+(make-hash-table)
+     @result{} #<hash-table 'eql nil 0/65 0x83af980>
+@end example
+
+@node Function Type
+@subsection Function Type
+
+  Lisp functions are executable code, just like functions in other
+programming languages.  In Lisp, unlike most languages, functions are
+also Lisp objects.  A non-compiled function in Lisp is a lambda
+expression: that is, a list whose first element is the symbol
+@code{lambda} (@pxref{Lambda Expressions}).
+
+  In most programming languages, it is impossible to have a function
+without a name.  In Lisp, a function has no intrinsic name.  A lambda
+expression can be called as a function even though it has no name; to
+emphasize this, we also call it an @dfn{anonymous function}
+(@pxref{Anonymous Functions}).  A named function in Lisp is just a
+symbol with a valid function in its function cell (@pxref{Defining
+Functions}).
+
+  Most of the time, functions are called when their names are written in
+Lisp expressions in Lisp programs.  However, you can construct or obtain
+a function object at run time and then call it with the primitive
+functions @code{funcall} and @code{apply}.  @xref{Calling Functions}.
+
+@node Macro Type
+@subsection Macro Type
+
+  A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
+language.  It is represented as an object much like a function, but with
+different argument-passing semantics.  A Lisp macro has the form of a
+list whose first element is the symbol @code{macro} and whose @sc{cdr}
+is a Lisp function object, including the @code{lambda} symbol.
+
+  Lisp macro objects are usually defined with the built-in
+@code{defmacro} function, but any list that begins with @code{macro} is
+a macro as far as Emacs is concerned.  @xref{Macros}, for an explanation
+of how to write a macro.
+
+  @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
+Macros}) are entirely different things.  When we use the word ``macro''
+without qualification, we mean a Lisp macro, not a keyboard macro.
+
+@node Primitive Function Type
+@subsection Primitive Function Type
+@cindex special forms
+
+  A @dfn{primitive function} is a function callable from Lisp but
+written in the C programming language.  Primitive functions are also
+called @dfn{subrs} or @dfn{built-in functions}.  (The word ``subr'' is
+derived from ``subroutine.'')  Most primitive functions evaluate all
+their arguments when they are called.  A primitive function that does
+not evaluate all its arguments is called a @dfn{special form}
+(@pxref{Special Forms}).@refill
+
+  It does not matter to the caller of a function whether the function is
+primitive.  However, this does matter if you try to redefine a primitive
+with a function written in Lisp.  The reason is that the primitive
+function may be called directly from C code.  Calls to the redefined
+function from Lisp will use the new definition, but calls from C code
+may still use the built-in definition.  Therefore, @strong{we discourage
+redefinition of primitive functions}.
+
+  The term @dfn{function} refers to all Emacs functions, whether written
+in Lisp or C.  @xref{Function Type}, for information about the
+functions written in Lisp.
+
+  Primitive functions have no read syntax and print in hash notation
+with the name of the subroutine.
+
+@example
+@group
+(symbol-function 'car)          ; @r{Access the function cell}
+                                ;   @r{of the symbol.}
+     @result{} #<subr car>
+(subrp (symbol-function 'car))  ; @r{Is this a primitive function?}
+     @result{} t                       ; @r{Yes.}
+@end group
+@end example
+
+@node Byte-Code Type
+@subsection Byte-Code Function Type
+
+The byte compiler produces @dfn{byte-code function objects}.
+Internally, a byte-code function object is much like a vector; however,
+the evaluator handles this data type specially when it appears as a
+function to be called.  @xref{Byte Compilation}, for information about
+the byte compiler.
+
+The printed representation and read syntax for a byte-code function
+object is like that for a vector, with an additional @samp{#} before the
+opening @samp{[}.
+
+@node Autoload Type
+@subsection Autoload Type
+
+  An @dfn{autoload object} is a list whose first element is the symbol
+@code{autoload}.  It is stored as the function definition of a symbol,
+where it serves as a placeholder for the real definition.  The autoload
+object says that the real definition is found in a file of Lisp code
+that should be loaded when necessary.  It contains the name of the file,
+plus some other information about the real definition.
+
+  After the file has been loaded, the symbol should have a new function
+definition that is not an autoload object.  The new definition is then
+called as if it had been there to begin with.  From the user's point of
+view, the function call works as expected, using the function definition
+in the loaded file.
+
+  An autoload object is usually created with the function
+@code{autoload}, which stores the object in the function cell of a
+symbol.  @xref{Autoload}, for more details.
+
+@node Editing Types
+@section Editing Types
+@cindex editing types
+
+  The types in the previous section are used for general programming
+purposes, and most of them are common to most Lisp dialects.  Emacs Lisp
+provides several additional data types for purposes connected with
+editing.
+
+@menu
+* Buffer Type::         The basic object of editing.
+* Marker Type::         A position in a buffer.
+* Window Type::         Buffers are displayed in windows.
+* Frame Type::		Windows subdivide frames.
+* Window Configuration Type::   Recording the way a frame is subdivided.
+* Frame Configuration Type::    Recording the status of all frames.
+* Process Type::        A process running on the underlying OS.
+* Stream Type::         Receive or send characters.
+* Keymap Type::         What function a keystroke invokes.
+* Overlay Type::        How an overlay is represented.
+@end menu
+
+@node Buffer Type
+@subsection Buffer Type
+
+  A @dfn{buffer} is an object that holds text that can be edited
+(@pxref{Buffers}).  Most buffers hold the contents of a disk file
+(@pxref{Files}) so they can be edited, but some are used for other
+purposes.  Most buffers are also meant to be seen by the user, and
+therefore displayed, at some time, in a window (@pxref{Windows}).  But a
+buffer need not be displayed in any window.
+
+  The contents of a buffer are much like a string, but buffers are not
+used like strings in Emacs Lisp, and the available operations are
+different.  For example, you can insert text efficiently into an
+existing buffer, altering the buffer's contents, whereas ``inserting''
+text into a string requires concatenating substrings, and the result is
+an entirely new string object.
+
+  Each buffer has a designated position called @dfn{point}
+(@pxref{Positions}).  At any time, one buffer is the @dfn{current
+buffer}.  Most editing commands act on the contents of the current
+buffer in the neighborhood of point.  Many of the standard Emacs
+functions manipulate or test the characters in the current buffer; a
+whole chapter in this manual is devoted to describing these functions
+(@pxref{Text}).
+
+  Several other data structures are associated with each buffer:
+
+@itemize @bullet
+@item
+a local syntax table (@pxref{Syntax Tables});
+
+@item
+a local keymap (@pxref{Keymaps}); and,
+
+@item
+a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
+
+@item
+overlays (@pxref{Overlays}).
+
+@item
+text properties for the text in the buffer (@pxref{Text Properties}).
+@end itemize
+
+@noindent
+The local keymap and variable list contain entries that individually
+override global bindings or values.  These are used to customize the
+behavior of programs in different buffers, without actually changing the
+programs.
+
+  A buffer may be @dfn{indirect}, which means it shares the text
+of another buffer, but presents it differently.  @xref{Indirect Buffers}.
+
+  Buffers have no read syntax.  They print in hash notation, showing the
+buffer name.
+
+@example
+@group
+(current-buffer)
+     @result{} #<buffer objects.texi>
+@end group
+@end example
+
+@node Marker Type
+@subsection Marker Type
+
+  A @dfn{marker} denotes a position in a specific buffer.  Markers
+therefore have two components: one for the buffer, and one for the
+position.  Changes in the buffer's text automatically relocate the
+position value as necessary to ensure that the marker always points
+between the same two characters in the buffer.
+
+  Markers have no read syntax.  They print in hash notation, giving the
+current character position and the name of the buffer.
+
+@example
+@group
+(point-marker)
+     @result{} #<marker at 10779 in objects.texi>
+@end group
+@end example
+
+@xref{Markers}, for information on how to test, create, copy, and move
+markers.
+
+@node Window Type
+@subsection Window Type
+
+  A @dfn{window} describes the portion of the terminal screen that Emacs
+uses to display a buffer.  Every window has one associated buffer, whose
+contents appear in the window.  By contrast, a given buffer may appear
+in one window, no window, or several windows.
+
+  Though many windows may exist simultaneously, at any time one window
+is designated the @dfn{selected window}.  This is the window where the
+cursor is (usually) displayed when Emacs is ready for a command.  The
+selected window usually displays the current buffer, but this is not
+necessarily the case.
+
+  Windows are grouped on the screen into frames; each window belongs to
+one and only one frame.  @xref{Frame Type}.
+
+  Windows have no read syntax.  They print in hash notation, giving the
+window number and the name of the buffer being displayed.  The window
+numbers exist to identify windows uniquely, since the buffer displayed
+in any given window can change frequently.
+
+@example
+@group
+(selected-window)
+     @result{} #<window 1 on objects.texi>
+@end group
+@end example
+
+  @xref{Windows}, for a description of the functions that work on windows.
+
+@node Frame Type
+@subsection Frame Type
+
+  A @dfn{frame} is a screen area that contains one or more Emacs
+windows; we also use the term ``frame'' to refer to the Lisp object
+that Emacs uses to refer to the screen area.
+
+  Frames have no read syntax.  They print in hash notation, giving the
+frame's title, plus its address in core (useful to identify the frame
+uniquely).
+
+@example
+@group
+(selected-frame)
+     @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
+@end group
+@end example
+
+  @xref{Frames}, for a description of the functions that work on frames.
+
+@node Window Configuration Type
+@subsection Window Configuration Type
+@cindex window layout in a frame
+
+  A @dfn{window configuration} stores information about the positions,
+sizes, and contents of the windows in a frame, so you can recreate the
+same arrangement of windows later.
+
+  Window configurations do not have a read syntax; their print syntax
+looks like @samp{#<window-configuration>}.  @xref{Window
+Configurations}, for a description of several functions related to
+window configurations.
+
+@node Frame Configuration Type
+@subsection Frame Configuration Type
+@cindex screen layout
+@cindex window layout, all frames
+
+  A @dfn{frame configuration} stores information about the positions,
+sizes, and contents of the windows in all frames.  It is actually
+a list whose @sc{car} is @code{frame-configuration} and whose
+@sc{cdr} is an alist.  Each alist element describes one frame,
+which appears as the @sc{car} of that element.
+
+  @xref{Frame Configurations}, for a description of several functions
+related to frame configurations.
+
+@node Process Type
+@subsection Process Type
+
+  The word @dfn{process} usually means a running program.  Emacs itself
+runs in a process of this sort.  However, in Emacs Lisp, a process is a
+Lisp object that designates a subprocess created by the Emacs process.
+Programs such as shells, GDB, ftp, and compilers, running in
+subprocesses of Emacs, extend the capabilities of Emacs.
+
+  An Emacs subprocess takes textual input from Emacs and returns textual
+output to Emacs for further manipulation.  Emacs can also send signals
+to the subprocess.
+
+  Process objects have no read syntax.  They print in hash notation,
+giving the name of the process:
+
+@example
+@group
+(process-list)
+     @result{} (#<process shell>)
+@end group
+@end example
+
+@xref{Processes}, for information about functions that create, delete,
+return information about, send input or signals to, and receive output
+from processes.
+
+@node Stream Type
+@subsection Stream Type
+
+  A @dfn{stream} is an object that can be used as a source or sink for
+characters---either to supply characters for input or to accept them as
+output.  Many different types can be used this way: markers, buffers,
+strings, and functions.  Most often, input streams (character sources)
+obtain characters from the keyboard, a buffer, or a file, and output
+streams (character sinks) send characters to a buffer, such as a
+@file{*Help*} buffer, or to the echo area.
+
+  The object @code{nil}, in addition to its other meanings, may be used
+as a stream.  It stands for the value of the variable
+@code{standard-input} or @code{standard-output}.  Also, the object
+@code{t} as a stream specifies input using the minibuffer
+(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
+Area}).
+
+  Streams have no special printed representation or read syntax, and
+print as whatever primitive type they are.
+
+  @xref{Read and Print}, for a description of functions
+related to streams, including parsing and printing functions.
+
+@node Keymap Type
+@subsection Keymap Type
+
+  A @dfn{keymap} maps keys typed by the user to commands.  This mapping
+controls how the user's command input is executed.  A keymap is actually
+a list whose @sc{car} is the symbol @code{keymap}.
+
+  @xref{Keymaps}, for information about creating keymaps, handling prefix
+keys, local as well as global keymaps, and changing key bindings.
+
+@node Overlay Type
+@subsection Overlay Type
+
+  An @dfn{overlay} specifies properties that apply to a part of a
+buffer.  Each overlay applies to a specified range of the buffer, and
+contains a property list (a list whose elements are alternating property
+names and values).  Overlay properties are used to present parts of the
+buffer temporarily in a different display style.  Overlays have no read
+syntax, and print in hash notation, giving the buffer name and range of
+positions.
+
+  @xref{Overlays}, for how to create and use overlays.
+
+@node Circular Objects
+@section Read Syntax for Circular Objects
+@cindex circular structure, read syntax
+@cindex shared structure, read syntax
+@cindex @samp{#@var{n}=} read syntax
+@cindex @samp{#@var{n}#} read syntax
+
+  To represent shared or circular structures within a complex of Lisp
+objects, you can use the reader constructs @samp{#@var{n}=} and
+@samp{#@var{n}#}.
+
+  Use @code{#@var{n}=} before an object to label it for later reference;
+subsequently, you can use @code{#@var{n}#} to refer the same object in
+another place.  Here, @var{n} is some integer.  For example, here is how
+to make a list in which the first element recurs as the third element:
+
+@example
+(#1=(a) b #1#)
+@end example
+
+@noindent
+This differs from ordinary syntax such as this
+
+@example
+((a) b (a))
+@end example
+
+@noindent
+which would result in a list whose first and third elements
+look alike but are not the same Lisp object.  This shows the difference:
+
+@example
+(prog1 nil
+  (setq x '(#1=(a) b #1#)))
+(eq (nth 0 x) (nth 2 x))
+     @result{} t
+(setq x '((a) b (a)))
+(eq (nth 0 x) (nth 2 x))
+     @result{} nil
+@end example
+
+  You can also use the same syntax to make a circular structure, which
+appears as an ``element'' within itself.  Here is an example:
+
+@example
+#1=(a #1#)
+@end example
+
+@noindent
+This makes a list whose second element is the list itself.
+Here's how you can see that it really works:
+
+@example
+(prog1 nil
+  (setq x '#1=(a #1#)))
+(eq x (cadr x))
+     @result{} t
+@end example
+
+  The Lisp printer can produce this syntax to record circular and shared
+structure in a Lisp object, if you bind the variable @code{print-circle}
+to a non-@code{nil} value.  @xref{Output Variables}.
+
+@node Type Predicates
+@section Type Predicates
+@cindex type checking
+@kindex wrong-type-argument
+
+  The Emacs Lisp interpreter itself does not perform type checking on
+the actual arguments passed to functions when they are called.  It could
+not do so, since function arguments in Lisp do not have declared data
+types, as they do in other programming languages.  It is therefore up to
+the individual function to test whether each actual argument belongs to
+a type that the function can use.
+
+  All built-in functions do check the types of their actual arguments
+when appropriate, and signal a @code{wrong-type-argument} error if an
+argument is of the wrong type.  For example, here is what happens if you
+pass an argument to @code{+} that it cannot handle:
+
+@example
+@group
+(+ 2 'a)
+     @error{} Wrong type argument: number-or-marker-p, a
+@end group
+@end example
+
+@cindex type predicates
+@cindex testing types
+  If you want your program to handle different types differently, you
+must do explicit type checking.  The most common way to check the type
+of an object is to call a @dfn{type predicate} function.  Emacs has a
+type predicate for each type, as well as some predicates for
+combinations of types.
+
+  A type predicate function takes one argument; it returns @code{t} if
+the argument belongs to the appropriate type, and @code{nil} otherwise.
+Following a general Lisp convention for predicate functions, most type
+predicates' names end with @samp{p}.
+
+  Here is an example which uses the predicates @code{listp} to check for
+a list and @code{symbolp} to check for a symbol.
+
+@example
+(defun add-on (x)
+  (cond ((symbolp x)
+         ;; If X is a symbol, put it on LIST.
+         (setq list (cons x list)))
+        ((listp x)
+         ;; If X is a list, add its elements to LIST.
+         (setq list (append x list)))
+        (t
+         ;; We handle only symbols and lists.
+         (error "Invalid argument %s in add-on" x))))
+@end example
+
+  Here is a table of predefined type predicates, in alphabetical order,
+with references to further information.
+
+@table @code
+@item atom
+@xref{List-related Predicates, atom}.
+
+@item arrayp
+@xref{Array Functions, arrayp}.
+
+@item bool-vector-p
+@xref{Bool-Vectors, bool-vector-p}.
+
+@item bufferp
+@xref{Buffer Basics, bufferp}.
+
+@item byte-code-function-p
+@xref{Byte-Code Type, byte-code-function-p}.
+
+@item case-table-p
+@xref{Case Tables, case-table-p}.
+
+@item char-or-string-p
+@xref{Predicates for Strings, char-or-string-p}.
+
+@item char-table-p
+@xref{Char-Tables, char-table-p}.
+
+@item commandp
+@xref{Interactive Call, commandp}.
+
+@item consp
+@xref{List-related Predicates, consp}.
+
+@item display-table-p
+@xref{Display Tables, display-table-p}.
+
+@item floatp
+@xref{Predicates on Numbers, floatp}.
+
+@item frame-configuration-p
+@xref{Frame Configurations, frame-configuration-p}.
+
+@item frame-live-p
+@xref{Deleting Frames, frame-live-p}.
+
+@item framep
+@xref{Frames, framep}.
+
+@item functionp
+@xref{Functions, functionp}.
+
+@item hash-table-p
+@xref{Other Hash, hash-table-p}.
+
+@item integer-or-marker-p
+@xref{Predicates on Markers, integer-or-marker-p}.
+
+@item integerp
+@xref{Predicates on Numbers, integerp}.
+
+@item keymapp
+@xref{Creating Keymaps, keymapp}.
+
+@item keywordp
+@xref{Constant Variables}.
+
+@item listp
+@xref{List-related Predicates, listp}.
+
+@item markerp
+@xref{Predicates on Markers, markerp}.
+
+@item wholenump
+@xref{Predicates on Numbers, wholenump}.
+
+@item nlistp
+@xref{List-related Predicates, nlistp}.
+
+@item numberp
+@xref{Predicates on Numbers, numberp}.
+
+@item number-or-marker-p
+@xref{Predicates on Markers, number-or-marker-p}.
+
+@item overlayp
+@xref{Overlays, overlayp}.
+
+@item processp
+@xref{Processes, processp}.
+
+@item sequencep
+@xref{Sequence Functions, sequencep}.
+
+@item stringp
+@xref{Predicates for Strings, stringp}.
+
+@item subrp
+@xref{Function Cells, subrp}.
+
+@item symbolp
+@xref{Symbols, symbolp}.
+
+@item syntax-table-p
+@xref{Syntax Tables, syntax-table-p}.
+
+@item user-variable-p
+@xref{Defining Variables, user-variable-p}.
+
+@item vectorp
+@xref{Vectors, vectorp}.
+
+@item window-configuration-p
+@xref{Window Configurations, window-configuration-p}.
+
+@item window-live-p
+@xref{Deleting Windows, window-live-p}.
+
+@item windowp
+@xref{Basic Windows, windowp}.
+
+@item booleanp
+@xref{nil and t, booleanp}.
+
+@item string-or-null-p
+@xref{Predicates for Strings, string-or-null-p}.
+@end table
+
+  The most general way to check the type of an object is to call the
+function @code{type-of}.  Recall that each object belongs to one and
+only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
+Data Types}).  But @code{type-of} knows nothing about non-primitive
+types.  In most cases, it is more convenient to use type predicates than
+@code{type-of}.
+
+@defun type-of object
+This function returns a symbol naming the primitive type of
+@var{object}.  The value is one of the symbols @code{symbol},
+@code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
+@code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr},
+@code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
+@code{buffer}, @code{frame}, @code{process}, or
+@code{window-configuration}.
+
+@example
+(type-of 1)
+     @result{} integer
+@group
+(type-of 'nil)
+     @result{} symbol
+(type-of '())    ; @r{@code{()} is @code{nil}.}
+     @result{} symbol
+(type-of '(x))
+     @result{} cons
+@end group
+@end example
+@end defun
+
+@node Equality Predicates
+@section Equality Predicates
+@cindex equality
+
+  Here we describe two functions that test for equality between any two
+objects.  Other functions test equality between objects of specific
+types, e.g., strings.  For these predicates, see the appropriate chapter
+describing the data type.
+
+@defun eq object1 object2
+This function returns @code{t} if @var{object1} and @var{object2} are
+the same object, @code{nil} otherwise.
+
+@code{eq} returns @code{t} if @var{object1} and @var{object2} are
+integers with the same value.  Also, since symbol names are normally
+unique, if the arguments are symbols with the same name, they are
+@code{eq}.  For other types (e.g., lists, vectors, strings), two
+arguments with the same contents or elements are not necessarily
+@code{eq} to each other: they are @code{eq} only if they are the same
+object, meaning that a change in the contents of one will be reflected
+by the same change in the contents of the other.
+
+@example
+@group
+(eq 'foo 'foo)
+     @result{} t
+@end group
+
+@group
+(eq 456 456)
+     @result{} t
+@end group
+
+@group
+(eq "asdf" "asdf")
+     @result{} nil
+@end group
+
+@group
+(eq '(1 (2 (3))) '(1 (2 (3))))
+     @result{} nil
+@end group
+
+@group
+(setq foo '(1 (2 (3))))
+     @result{} (1 (2 (3)))
+(eq foo foo)
+     @result{} t
+(eq foo '(1 (2 (3))))
+     @result{} nil
+@end group
+
+@group
+(eq [(1 2) 3] [(1 2) 3])
+     @result{} nil
+@end group
+
+@group
+(eq (point-marker) (point-marker))
+     @result{} nil
+@end group
+@end example
+
+The @code{make-symbol} function returns an uninterned symbol, distinct
+from the symbol that is used if you write the name in a Lisp expression.
+Distinct symbols with the same name are not @code{eq}.  @xref{Creating
+Symbols}.
+
+@example
+@group
+(eq (make-symbol "foo") 'foo)
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun equal object1 object2
+This function returns @code{t} if @var{object1} and @var{object2} have
+equal components, @code{nil} otherwise.  Whereas @code{eq} tests if its
+arguments are the same object, @code{equal} looks inside nonidentical
+arguments to see if their elements or contents are the same.  So, if two
+objects are @code{eq}, they are @code{equal}, but the converse is not
+always true.
+
+@example
+@group
+(equal 'foo 'foo)
+     @result{} t
+@end group
+
+@group
+(equal 456 456)
+     @result{} t
+@end group
+
+@group
+(equal "asdf" "asdf")
+     @result{} t
+@end group
+@group
+(eq "asdf" "asdf")
+     @result{} nil
+@end group
+
+@group
+(equal '(1 (2 (3))) '(1 (2 (3))))
+     @result{} t
+@end group
+@group
+(eq '(1 (2 (3))) '(1 (2 (3))))
+     @result{} nil
+@end group
+
+@group
+(equal [(1 2) 3] [(1 2) 3])
+     @result{} t
+@end group
+@group
+(eq [(1 2) 3] [(1 2) 3])
+     @result{} nil
+@end group
+
+@group
+(equal (point-marker) (point-marker))
+     @result{} t
+@end group
+
+@group
+(eq (point-marker) (point-marker))
+     @result{} nil
+@end group
+@end example
+
+Comparison of strings is case-sensitive, but does not take account of
+text properties---it compares only the characters in the strings.  For
+technical reasons, a unibyte string and a multibyte string are
+@code{equal} if and only if they contain the same sequence of
+character codes and all these codes are either in the range 0 through
+127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
+(@pxref{Text Representations}).
+
+@example
+@group
+(equal "asdf" "ASDF")
+     @result{} nil
+@end group
+@end example
+
+However, two distinct buffers are never considered @code{equal}, even if
+their textual contents are the same.
+@end defun
+
+  The test for equality is implemented recursively; for example, given
+two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
+returns @code{t} if and only if both the expressions below return
+@code{t}:
+
+@example
+(equal (car @var{x}) (car @var{y}))
+(equal (cdr @var{x}) (cdr @var{y}))
+@end example
+
+Because of this recursive method, circular lists may therefore cause
+infinite recursion (leading to an error).
+
+@ignore
+   arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096
+@end ignore
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
new file mode 100644
index 00000000000..08f94b427eb
--- /dev/null
+++ b/doc/lispref/os.texi
@@ -0,0 +1,2004 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/os
+@node System Interface, Antinews, Display, Top
+@chapter Operating System Interface
+
+  This chapter is about starting and getting out of Emacs, access to
+values in the operating system environment, and terminal input, output,
+and flow control.
+
+  @xref{Building Emacs}, for related information.  See also
+@ref{Display}, for additional operating system status information
+pertaining to the terminal and the screen.
+
+@menu
+* Starting Up::         Customizing Emacs startup processing.
+* Getting Out::         How exiting works (permanent or temporary).
+* System Environment::  Distinguish the name and kind of system.
+* User Identification:: Finding the name and user id of the user.
+* Time of Day::		Getting the current time.
+* Time Conversion::     Converting a time from numeric form
+                          to calendrical data, and vice versa).
+* Time Parsing::        Converting a time from numeric form to text
+                          and vice versa.
+* Processor Run Time::  Getting the run time used by Emacs.
+* Time Calculations::   Adding, subtracting, comparing times, etc.
+* Timers::		Setting a timer to call a function at a certain time.
+* Idle Timers::         Setting a timer to call a function when Emacs has
+                          been idle for a certain length of time.
+* Terminal Input::      Accessing and recording terminal input.
+* Terminal Output::     Controlling and recording terminal output.
+* Sound Output::        Playing sounds on the computer's speaker.
+* X11 Keysyms::         Operating on key symbols for X Windows
+* Batch Mode::          Running Emacs without terminal interaction.
+* Session Management::  Saving and restoring state with X Session Management.
+@end menu
+
+@node Starting Up
+@section Starting Up Emacs
+
+  This section describes what Emacs does when it is started, and how you
+can customize these actions.
+
+@menu
+* Startup Summary::         Sequence of actions Emacs performs at startup.
+* Init File::               Details on reading the init file (@file{.emacs}).
+* Terminal-Specific::       How the terminal-specific Lisp file is read.
+* Command-Line Arguments::  How command-line arguments are processed,
+                              and how you can customize them.
+@end menu
+
+@node Startup Summary
+@subsection Summary: Sequence of Actions at Startup
+@cindex initialization of Emacs
+@cindex startup of Emacs
+@cindex @file{startup.el}
+
+   The order of operations performed (in @file{startup.el}) by Emacs when
+it is started up is as follows:
+
+@enumerate
+@item
+It adds subdirectories to @code{load-path}, by running the file named
+@file{subdirs.el} in each directory in the list.  Normally this file
+adds the directory's subdirectories to the list, and these will be
+scanned in their turn.  The files @file{subdirs.el} are normally
+generated automatically by Emacs installation.
+
+@item
+It sets the language environment and the terminal coding system,
+if requested by environment variables such as @code{LANG}.
+
+@item
+It loads the initialization library for the window system, if you are
+using a window system.  This library's name is
+@file{term/@var{windowsystem}-win.el}.
+
+@item
+It processes the initial options.  (Some of them are handled
+even earlier than this.)
+
+@item
+It initializes the window frame and faces, if appropriate.
+
+@item
+It runs the normal hook @code{before-init-hook}.
+
+@item
+It loads the library @file{site-start} (if any), unless the option
+@samp{-Q} (or @samp{--no-site-file}) was specified.  The library's file
+name is usually @file{site-start.el}.
+@cindex @file{site-start.el}
+
+@item
+It loads your init file (usually @file{~/.emacs}), unless the option
+@samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
+specified on the command line.  The @samp{-u} option can specify
+another user whose home directory should be used instead of @file{~}.
+
+@item
+It loads the library @file{default} (if any), unless
+@code{inhibit-default-init} is non-@code{nil}.  (This is not done in
+@samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the
+command line.)  The library's file name is usually @file{default.el}.
+@cindex @file{default.el}
+
+@item
+It runs the normal hook @code{after-init-hook}.
+
+@item
+It sets the major mode according to @code{initial-major-mode}, provided
+the buffer @samp{*scratch*} is still current and still in Fundamental
+mode.
+
+@item
+It loads the terminal-specific Lisp file, if any, except when in batch
+mode or using a window system.
+
+@item
+It displays the initial echo area message, unless you have suppressed
+that with @code{inhibit-startup-echo-area-message}.
+
+@item
+It processes the action arguments from the command line.
+
+@item
+It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
+
+@item
+It calls @code{frame-notice-user-settings}, which modifies the
+parameters of the selected frame according to whatever the init files
+specify.
+
+@item
+It runs @code{window-setup-hook}.  @xref{Window Systems}.
+
+@item
+It displays copyleft, nonwarranty, and basic use information, provided
+the value of @code{inhibit-startup-message} is @code{nil}, you didn't
+specify @samp{--no-splash} or @samp{-Q}.
+@end enumerate
+
+@defopt inhibit-startup-message
+This variable inhibits the initial startup messages (the nonwarranty,
+etc.).  If it is non-@code{nil}, then the messages are not printed.
+
+This variable exists so you can set it in your personal init file, once
+you are familiar with the contents of the startup message.  Do not set
+this variable in the init file of a new user, or in a way that affects
+more than one user, because that would prevent new users from receiving
+the information they are supposed to see.
+@end defopt
+
+@defopt inhibit-startup-echo-area-message
+This variable controls the display of the startup echo area message.
+You can suppress the startup echo area message by adding text with this
+form to your init file:
+
+@example
+(setq inhibit-startup-echo-area-message
+      "@var{your-login-name}")
+@end example
+
+Emacs explicitly checks for an expression as shown above in your init
+file; your login name must appear in the expression as a Lisp string
+constant.  Other methods of setting
+@code{inhibit-startup-echo-area-message} to the same value do not
+inhibit the startup message.
+
+This way, you can easily inhibit the message for yourself if you wish,
+but thoughtless copying of your init file will not inhibit the message
+for someone else.
+@end defopt
+
+@node Init File
+@subsection The Init File, @file{.emacs}
+@cindex init file
+@cindex @file{.emacs}
+
+  When you start Emacs, it normally attempts to load your @dfn{init
+file}, a file in your home directory.  Its normal name is
+@file{.emacs}, but you can also call it @file{.emacs.el}.
+Alternatively, you can use a file named @file{init.el} in a
+subdirectory @file{.emacs.d}.  Whichever place you use, you can also
+compile the file (@pxref{Byte Compilation}); then the actual file
+loaded will be @file{.emacs.elc} or @file{init.elc}.
+
+  The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
+control whether and where to find the init file; @samp{-q} (and the
+stronger @samp{-Q}) says not to load an init file, while @samp{-u
+@var{user}} says to load @var{user}'s init file instead of yours.
+@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}.  If neither
+option is specified, Emacs uses the @code{LOGNAME} environment
+variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
+systems) variable, to find your home directory and thus your init
+file; this way, even if you have su'd, Emacs still loads your own init
+file.  If those environment variables are absent, though, Emacs uses
+your user-id to find your home directory.
+
+@cindex default init file
+  A site may have a @dfn{default init file}, which is the library
+named @file{default.el}.  Emacs finds the @file{default.el} file
+through the standard search path for libraries (@pxref{How Programs Do
+Loading}).  The Emacs distribution does not come with this file; sites
+may provide one for local customizations.  If the default init file
+exists, it is loaded whenever you start Emacs, except in batch mode or
+if @samp{-q} (or @samp{-Q}) is specified.  But your own personal init
+file, if any, is loaded first; if it sets @code{inhibit-default-init}
+to a non-@code{nil} value, then Emacs does not subsequently load the
+@file{default.el} file.
+
+  Another file for site-customization is @file{site-start.el}.  Emacs
+loads this @emph{before} the user's init file.  You can inhibit the
+loading of this file with the option @samp{--no-site-file}.
+
+@defvar site-run-file
+This variable specifies the site-customization file to load before the
+user's init file.  Its normal value is @code{"site-start"}.  The only
+way you can change it with real effect is to do so before dumping
+Emacs.
+@end defvar
+
+  @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
+examples of how to make various commonly desired customizations in your
+@file{.emacs} file.
+
+@defopt inhibit-default-init
+This variable prevents Emacs from loading the default initialization
+library file for your session of Emacs.  If its value is non-@code{nil},
+then the default library is not loaded.  The default value is
+@code{nil}.
+@end defopt
+
+@defvar before-init-hook
+This normal hook is run, once, just before loading all the init files
+(the user's init file, @file{default.el}, and/or @file{site-start.el}).
+(The only way to change it with real effect is before dumping Emacs.)
+@end defvar
+
+@defvar after-init-hook
+This normal hook is run, once, just after loading all the init files
+(the user's init file, @file{default.el}, and/or @file{site-start.el}),
+before loading the terminal-specific library and processing the
+command-line action arguments.
+@end defvar
+
+@defvar emacs-startup-hook
+This normal hook is run, once, just after handling the command line
+arguments, just before @code{term-setup-hook}.
+@end defvar
+
+@defvar user-init-file
+This variable holds the absolute file name of the user's init file.  If the
+actual init file loaded is a compiled file, such as @file{.emacs.elc},
+the value refers to the corresponding source file.
+@end defvar
+
+@defvar user-emacs-directory
+This variable holds the name of the @file{.emacs.d} directory.  It is
+ordinarily @file{~/.emacs.d}, but differs on some platforms.
+@end defvar
+
+@node Terminal-Specific
+@subsection Terminal-Specific Initialization
+@cindex terminal-specific initialization
+
+  Each terminal type can have its own Lisp library that Emacs loads when
+run on that type of terminal.  The library's name is constructed by
+concatenating the value of the variable @code{term-file-prefix} and the
+terminal type (specified by the environment variable @code{TERM}).
+Normally, @code{term-file-prefix} has the value
+@code{"term/"}; changing this is not recommended.  Emacs finds the file
+in the normal manner, by searching the @code{load-path} directories, and
+trying the @samp{.elc} and @samp{.el} suffixes.
+
+@cindex Termcap
+  The usual function of a terminal-specific library is to enable
+special keys to send sequences that Emacs can recognize.  It may also
+need to set or add to @code{function-key-map} if the Termcap or
+Terminfo entry does not specify all the terminal's function keys.
+@xref{Terminal Input}.
+
+  When the name of the terminal type contains a hyphen, and no library
+is found whose name is identical to the terminal's name, Emacs strips
+from the terminal's name the last hyphen and everything that follows
+it, and tries again.  This process is repeated until Emacs finds a
+matching library or until there are no more hyphens in the name (the
+latter means the terminal doesn't have any library specific to it).
+Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
+libraries, Emacs will try the same library @file{term/aaa.el} for
+terminal types @samp{aaa-48} and @samp{aaa-30-rv}.  If necessary, the
+library can evaluate @code{(getenv "TERM")} to find the full name of
+the terminal type.@refill
+
+  Your init file can prevent the loading of the
+terminal-specific library by setting the variable
+@code{term-file-prefix} to @code{nil}.  This feature is useful when
+experimenting with your own peculiar customizations.
+
+  You can also arrange to override some of the actions of the
+terminal-specific library by setting the variable
+@code{term-setup-hook}.  This is a normal hook which Emacs runs using
+@code{run-hooks} at the end of Emacs initialization, after loading both
+your init file and any terminal-specific libraries.  You can
+use this variable to define initializations for terminals that do not
+have their own libraries.  @xref{Hooks}.
+
+@defvar term-file-prefix
+@cindex @code{TERM} environment variable
+If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
+a terminal-specific initialization file as follows:
+
+@example
+(load (concat term-file-prefix (getenv "TERM")))
+@end example
+
+@noindent
+You may set the @code{term-file-prefix} variable to @code{nil} in your
+init file if you do not wish to load the
+terminal-initialization file.  To do this, put the following in
+your init file: @code{(setq term-file-prefix nil)}.
+
+On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
+uses @samp{internal} as the terminal type.
+@end defvar
+
+@defvar term-setup-hook
+This variable is a normal hook that Emacs runs after loading your
+init file, the default initialization file (if any) and the
+terminal-specific Lisp file.
+
+You can use @code{term-setup-hook} to override the definitions made by a
+terminal-specific file.
+@end defvar
+
+  See @code{window-setup-hook} in @ref{Window Systems}, for a related
+feature.
+
+@node Command-Line Arguments
+@subsection Command-Line Arguments
+@cindex command-line arguments
+
+  You can use command-line arguments to request various actions when you
+start Emacs.  Since you do not need to start Emacs more than once per
+day, and will often leave your Emacs session running longer than that,
+command-line arguments are hardly ever used.  As a practical matter, it
+is best to avoid making the habit of using them, since this habit would
+encourage you to kill and restart Emacs unnecessarily often.  These
+options exist for two reasons: to be compatible with other editors (for
+invocation by other programs) and to enable shell scripts to run
+specific Lisp programs.
+
+  This section describes how Emacs processes command-line arguments,
+and how you can customize them.
+
+@ignore
+  (Note that some other editors require you to start afresh each time
+you want to edit a file.  With this kind of editor, you will probably
+specify the file as a command-line argument.  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 process.  Each time you want to edit
+a different file, you visit it with the existing Emacs, which eventually
+comes to have many files in it ready for editing.  Usually you do not
+kill the Emacs until you are about to log out.)
+@end ignore
+
+@defun command-line
+This function parses the command line that Emacs was called with,
+processes it, loads the user's init file and displays the
+startup messages.
+@end defun
+
+@defvar command-line-processed
+The value of this variable is @code{t} once the command line has been
+processed.
+
+If you redump Emacs by calling @code{dump-emacs}, you may wish to set
+this variable to @code{nil} first in order to cause the new dumped Emacs
+to process its new command-line arguments.
+@end defvar
+
+@defvar command-switch-alist
+@cindex switches on command line
+@cindex options on command line
+@cindex command-line options
+The value of this variable is an alist of user-defined command-line
+options and associated handler functions.  This variable exists so you
+can add elements to it.
+
+A @dfn{command-line option} is an argument on the command line, which
+has the form:
+
+@example
+-@var{option}
+@end example
+
+The elements of the @code{command-switch-alist} look like this:
+
+@example
+(@var{option} . @var{handler-function})
+@end example
+
+The @sc{car}, @var{option}, is a string, the name of a command-line
+option (not including the initial hyphen).  The @var{handler-function}
+is called to handle @var{option}, and receives the option name as its
+sole argument.
+
+In some cases, the option is followed in the command line by an
+argument.  In these cases, the @var{handler-function} can find all the
+remaining command-line arguments in the variable
+@code{command-line-args-left}.  (The entire list of command-line
+arguments is in @code{command-line-args}.)
+
+The command-line arguments are parsed by the @code{command-line-1}
+function in the @file{startup.el} file.  See also @ref{Emacs
+Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
+GNU Emacs Manual}.
+@end defvar
+
+@defvar command-line-args
+The value of this variable is the list of command-line arguments passed
+to Emacs.
+@end defvar
+
+@defvar command-line-functions
+This variable's value is a list of functions for handling an
+unrecognized command-line argument.  Each time the next argument to be
+processed has no special meaning, the functions in this list are called,
+in order of appearance, until one of them returns a non-@code{nil}
+value.
+
+These functions are called with no arguments.  They can access the
+command-line argument under consideration through the variable
+@code{argi}, which is bound temporarily at this point.  The remaining
+arguments (not including the current one) are in the variable
+@code{command-line-args-left}.
+
+When a function recognizes and processes the argument in @code{argi}, it
+should return a non-@code{nil} value to say it has dealt with that
+argument.  If it has also dealt with some of the following arguments, it
+can indicate that by deleting them from @code{command-line-args-left}.
+
+If all of these functions return @code{nil}, then the argument is used
+as a file name to visit.
+@end defvar
+
+@node Getting Out
+@section Getting Out of Emacs
+@cindex exiting Emacs
+
+  There are two ways to get out of Emacs: you can kill the Emacs job,
+which exits permanently, or you can suspend it, which permits you to
+reenter the Emacs process later.  As a practical matter, you seldom kill
+Emacs---only when you are about to log out.  Suspending is much more
+common.
+
+@menu
+* Killing Emacs::        Exiting Emacs irreversibly.
+* Suspending Emacs::     Exiting Emacs reversibly.
+@end menu
+
+@node Killing Emacs
+@comment  node-name,  next,  previous,  up
+@subsection Killing Emacs
+@cindex killing Emacs
+
+  Killing Emacs means ending the execution of the Emacs process.  The
+parent process normally resumes control.  The low-level primitive for
+killing Emacs is @code{kill-emacs}.
+
+@defun kill-emacs &optional exit-data
+This function exits the Emacs process and kills it.
+
+If @var{exit-data} is an integer, then it is used as the exit status
+of the Emacs process.  (This is useful primarily in batch operation; see
+@ref{Batch Mode}.)
+
+If @var{exit-data} is a string, its contents are stuffed into the
+terminal input buffer so that the shell (or whatever program next reads
+input) can read them.
+@end defun
+
+  All the information in the Emacs process, aside from files that have
+been saved, is lost when the Emacs process is killed.  Because killing
+Emacs inadvertently can lose a lot of work, Emacs queries for
+confirmation before actually terminating if you have buffers that need
+saving or subprocesses that are running.  This is done in the function
+@code{save-buffers-kill-emacs}, the higher level function from which
+@code{kill-emacs} is usually called.
+
+@defvar kill-emacs-query-functions
+After asking the standard questions, @code{save-buffers-kill-emacs}
+calls the functions in the list @code{kill-emacs-query-functions}, in
+order of appearance, with no arguments.  These functions can ask for
+additional confirmation from the user.  If any of them returns
+@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
+does not run the remaining functions in this hook.  Calling
+@code{kill-emacs} directly does not run this hook.
+@end defvar
+
+@defvar kill-emacs-hook
+This variable is a normal hook; once @code{save-buffers-kill-emacs} is
+finished with all file saving and confirmation, it calls
+@code{kill-emacs} which runs the functions in this hook.
+@code{kill-emacs} does not run this hook in batch mode.
+
+@code{kill-emacs} may be invoked directly (that is not via
+@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
+similar situations where interaction with the user is not possible.
+Thus, if your hook needs to interact with the user, put it on
+@code{kill-emacs-query-functions}; if it needs to run regardless of
+how Emacs is killed, put it on @code{kill-emacs-hook}.
+@end defvar
+
+@node Suspending Emacs
+@subsection Suspending Emacs
+@cindex suspending Emacs
+
+  @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
+control to its superior process, which is usually the shell.  This
+allows you to resume editing later in the same Emacs process, with the
+same buffers, the same kill ring, the same undo history, and so on.  To
+resume Emacs, use the appropriate command in the parent shell---most
+likely @code{fg}.
+
+  Some operating systems do not support suspension of jobs; on these
+systems, ``suspension'' actually creates a new shell temporarily as a
+subprocess of Emacs.  Then you would exit the shell to return to Emacs.
+
+  Suspension is not useful with window systems, because the Emacs job
+may not have a parent that can resume it again, and in any case you can
+give input to some other job such as a shell merely by moving to a
+different window.  Therefore, suspending is not allowed when Emacs is using
+a window system (X, MS Windows, or Mac).
+
+@defun suspend-emacs &optional string
+This function stops Emacs and returns control to the superior process.
+If and when the superior process resumes Emacs, @code{suspend-emacs}
+returns @code{nil} to its caller in Lisp.
+
+If @var{string} is non-@code{nil}, its characters are sent to be read
+as terminal input by Emacs's superior shell.  The characters in
+@var{string} are not echoed by the superior shell; only the results
+appear.
+
+Before suspending, @code{suspend-emacs} runs the normal hook
+@code{suspend-hook}.
+
+After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
+@code{suspend-resume-hook}.  @xref{Hooks}.
+
+The next redisplay after resumption will redraw the entire screen,
+unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
+(@pxref{Refresh Screen}).
+
+In the following example, note that @samp{pwd} is not echoed after
+Emacs is suspended.  But it is read and executed by the shell.
+
+@smallexample
+@group
+(suspend-emacs)
+     @result{} nil
+@end group
+
+@group
+(add-hook 'suspend-hook
+          (function (lambda ()
+                      (or (y-or-n-p
+                            "Really suspend? ")
+                          (error "Suspend canceled")))))
+     @result{} (lambda nil
+          (or (y-or-n-p "Really suspend? ")
+              (error "Suspend canceled")))
+@end group
+@group
+(add-hook 'suspend-resume-hook
+          (function (lambda () (message "Resumed!"))))
+     @result{} (lambda nil (message "Resumed!"))
+@end group
+@group
+(suspend-emacs "pwd")
+     @result{} nil
+@end group
+@group
+---------- Buffer: Minibuffer ----------
+Really suspend? @kbd{y}
+---------- Buffer: Minibuffer ----------
+@end group
+
+@group
+---------- Parent Shell ----------
+lewis@@slug[23] % /user/lewis/manual
+lewis@@slug[24] % fg
+@end group
+
+@group
+---------- Echo Area ----------
+Resumed!
+@end group
+@end smallexample
+@end defun
+
+@defvar suspend-hook
+This variable is a normal hook that Emacs runs before suspending.
+@end defvar
+
+@defvar suspend-resume-hook
+This variable is a normal hook that Emacs runs on resuming
+after a suspension.
+@end defvar
+
+@node System Environment
+@section Operating System Environment
+@cindex operating system environment
+
+  Emacs provides access to variables in the operating system environment
+through various functions.  These variables include the name of the
+system, the user's @acronym{UID}, and so on.
+
+@defvar system-configuration
+This variable holds the standard GNU configuration name for the
+hardware/software configuration of your system, as a string.  The
+convenient way to test parts of this string is with
+@code{string-match}.
+@end defvar
+
+@cindex system type and name
+@defvar system-type
+The value of this variable is a symbol indicating the type of operating
+system Emacs is operating on.  Here is a table of the possible values:
+
+@table @code
+@item alpha-vms
+VMS on the Alpha.
+
+@item aix-v3
+AIX.
+
+@item berkeley-unix
+Berkeley BSD.
+
+@item cygwin
+Cygwin.
+
+@item dgux
+Data General DGUX operating system.
+
+@item gnu
+the GNU system (using the GNU kernel, which consists of the HURD and Mach).
+
+@item gnu/linux
+A GNU/Linux system---that is, a variant GNU system, using the Linux
+kernel.  (These systems are the ones people often call ``Linux,'' but
+actually Linux is just the kernel, not the whole system.)
+
+@item hpux
+Hewlett-Packard HPUX operating system.
+
+@item irix
+Silicon Graphics Irix system.
+
+@item ms-dos
+Microsoft MS-DOS ``operating system.''  Emacs compiled with DJGPP for
+MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
+MS-Windows.
+
+@item next-mach
+NeXT Mach-based system.
+
+@item rtu
+Masscomp RTU, UCB universe.
+
+@item unisoft-unix
+UniSoft UniPlus.
+
+@item usg-unix-v
+AT&T System V.
+
+@item vax-vms
+VAX VMS.
+
+@item windows-nt
+Microsoft windows NT.  The same executable supports Windows 9X, but the
+value of @code{system-type} is @code{windows-nt} in either case.
+
+@item xenix
+SCO Xenix 386.
+@end table
+
+We do not wish to add new symbols to make finer distinctions unless it
+is absolutely necessary!  In fact, we hope to eliminate some of these
+alternatives in the future.  We recommend using
+@code{system-configuration} to distinguish between different operating
+systems.
+@end defvar
+
+@defun system-name
+This function returns the name of the machine you are running on.
+@example
+(system-name)
+     @result{} "www.gnu.org"
+@end example
+@end defun
+
+  The symbol @code{system-name} is a variable as well as a function.  In
+fact, the function returns whatever value the variable
+@code{system-name} currently holds.  Thus, you can set the variable
+@code{system-name} in case Emacs is confused about the name of your
+system.  The variable is also useful for constructing frame titles
+(@pxref{Frame Titles}).
+
+@defvar mail-host-address
+If this variable is non-@code{nil}, it is used instead of
+@code{system-name} for purposes of generating email addresses.  For
+example, it is used when constructing the default value of
+@code{user-mail-address}.  @xref{User Identification}.  (Since this is
+done when Emacs starts up, the value actually used is the one saved when
+Emacs was dumped.  @xref{Building Emacs}.)
+@end defvar
+
+@deffn Command getenv var
+@cindex environment variable access
+This function returns the value of the environment variable @var{var},
+as a string.  @var{var} should be a string.  If @var{var} is undefined
+in the environment, @code{getenv} returns @code{nil}.  If returns
+@samp{""} if @var{var} is set but null.  Within Emacs, the environment
+variable values are kept in the Lisp variable @code{process-environment}.
+
+@example
+@group
+(getenv "USER")
+     @result{} "lewis"
+@end group
+
+@group
+lewis@@slug[10] % printenv
+PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
+USER=lewis
+@end group
+@group
+TERM=ibmapa16
+SHELL=/bin/csh
+HOME=/user/lewis
+@end group
+@end example
+@end deffn
+
+@c Emacs 19 feature
+@deffn Command setenv variable &optional value
+This command sets the value of the environment variable named
+@var{variable} to @var{value}.  @var{variable} should be a string.
+Internally, Emacs Lisp can handle any string.  However, normally
+@var{variable} should be a valid shell identifier, that is, a sequence
+of letters, digits and underscores, starting with a letter or
+underscore.  Otherwise, errors may occur if subprocesses of Emacs try
+to access the value of @var{variable}.  If @var{value} is omitted or
+@code{nil}, @code{setenv} removes @var{variable} from the environment.
+Otherwise, @var{value} should be a string.
+
+@code{setenv} works by modifying @code{process-environment}; binding
+that variable with @code{let} is also reasonable practice.
+
+@code{setenv} returns the new value of @var{variable}, or @code{nil}
+if it removed @var{variable} from the environment.
+@end deffn
+
+@defvar process-environment
+This variable is a list of strings, each describing one environment
+variable.  The functions @code{getenv} and @code{setenv} work by means
+of this variable.
+
+@smallexample
+@group
+process-environment
+@result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
+    "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
+    "USER=lewis"
+@end group
+@group
+    "TERM=ibmapa16"
+    "SHELL=/bin/csh"
+    "HOME=/user/lewis")
+@end group
+@end smallexample
+
+If @code{process-environment} contains ``duplicate'' elements that
+specify the same environment variable, the first of these elements
+specifies the variable, and the other ``duplicates'' are ignored.
+@end defvar
+
+@defvar path-separator
+This variable holds a string which says which character separates
+directories in a search path (as found in an environment variable).  Its
+value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
+and MS-Windows.
+@end defvar
+
+@defun parse-colon-path path
+This function takes a search path string such as would be the value of
+the @code{PATH} environment variable, and splits it at the separators,
+returning a list of directory names.  @code{nil} in this list stands for
+``use the current directory.''  Although the function's name says
+``colon,'' it actually uses the value of @code{path-separator}.
+
+@example
+(parse-colon-path ":/foo:/bar")
+     @result{} (nil "/foo/" "/bar/")
+@end example
+@end defun
+
+@defvar invocation-name
+This variable holds the program name under which Emacs was invoked.  The
+value is a string, and does not include a directory name.
+@end defvar
+
+@defvar invocation-directory
+This variable holds the directory from which the Emacs executable was
+invoked, or perhaps @code{nil} if that directory cannot be determined.
+@end defvar
+
+@defvar installation-directory
+If non-@code{nil}, this is a directory within which to look for the
+@file{lib-src} and @file{etc} subdirectories.  This is non-@code{nil}
+when Emacs can't find those directories in their standard installed
+locations, but can find them in a directory related somehow to the one
+containing the Emacs executable.
+@end defvar
+
+@defun load-average &optional use-float
+This function returns the current 1-minute, 5-minute, and 15-minute load
+averages, in a list.
+
+By default, the values are integers that are 100 times the system load
+averages, which indicate the average number of processes trying to run.
+If @var{use-float} is non-@code{nil}, then they are returned
+as floating point numbers and without multiplying by 100.
+
+If it is impossible to obtain the load average, this function signals
+an error.  On some platforms, access to load averages requires
+installing Emacs as setuid or setgid so that it can read kernel
+information, and that usually isn't advisable.
+
+If the 1-minute load average is available, but the 5- or 15-minute
+averages are not, this function returns a shortened list containing
+the available averages.
+
+@example
+@group
+(load-average)
+     @result{} (169 48 36)
+@end group
+@group
+(load-average t)
+     @result{} (1.69 0.48 0.36)
+@end group
+
+@group
+lewis@@rocky[5] % uptime
+ 11:55am  up 1 day, 19:37,  3 users,
+ load average: 1.69, 0.48, 0.36
+@end group
+@end example
+@end defun
+
+@defun emacs-pid
+This function returns the process @acronym{ID} of the Emacs process,
+as an integer.
+@end defun
+
+@defvar tty-erase-char
+This variable holds the erase character that was selected
+in the system's terminal driver, before Emacs was started.
+The value is @code{nil} if Emacs is running under a window system.
+@end defvar
+
+@defun setprv privilege-name &optional setp getprv
+This function sets or resets a VMS privilege.  (It does not exist on
+other systems.)  The first argument is the privilege name, as a string.
+The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
+whether the privilege is to be turned on or off.  Its default is
+@code{nil}.  The function returns @code{t} if successful, @code{nil}
+otherwise.
+
+If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
+does not change the privilege, but returns @code{t} or @code{nil}
+indicating whether the privilege is currently enabled.
+@end defun
+
+@node User Identification
+@section User Identification
+@cindex user identification
+
+@defvar init-file-user
+This variable says which user's init files should be used by
+Emacs---or @code{nil} if none.  @code{""} stands for the user who
+originally logged in.  The value reflects command-line options such as
+@samp{-q} or @samp{-u @var{user}}.
+
+Lisp packages that load files of customizations, or any other sort of
+user profile, should obey this variable in deciding where to find it.
+They should load the profile of the user name found in this variable.
+If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
+option was used, then Lisp packages should not load any customization
+files or user profile.
+@end defvar
+
+@defvar user-mail-address
+This holds the nominal email address of the user who is using Emacs.
+Emacs normally sets this variable to a default value after reading your
+init files, but not if you have already set it.  So you can set the
+variable to some other value in your init file if you do not
+want to use the default value.
+@end defvar
+
+@defun user-login-name &optional uid
+If you don't specify @var{uid}, this function returns the name under
+which the user is logged in.  If the environment variable @code{LOGNAME}
+is set, that value is used.  Otherwise, if the environment variable
+@code{USER} is set, that value is used.  Otherwise, the value is based
+on the effective @acronym{UID}, not the real @acronym{UID}.
+
+If you specify @var{uid}, the value is the user name that corresponds
+to @var{uid} (which should be an integer), or @code{nil} if there is
+no such user.
+
+@example
+@group
+(user-login-name)
+     @result{} "lewis"
+@end group
+@end example
+@end defun
+
+@defun user-real-login-name
+This function returns the user name corresponding to Emacs's real
+@acronym{UID}.  This ignores the effective @acronym{UID} and ignores the
+environment variables @code{LOGNAME} and @code{USER}.
+@end defun
+
+@defun user-full-name &optional uid
+This function returns the full name of the logged-in user---or the value
+of the environment variable @code{NAME}, if that is set.
+
+@c "Bil" is the correct spelling.
+@example
+@group
+(user-full-name)
+     @result{} "Bil Lewis"
+@end group
+@end example
+
+If the Emacs job's user-id does not correspond to any known user (and
+provided @code{NAME} is not set), the value is @code{"unknown"}.
+
+If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
+or a string (a login name).  Then @code{user-full-name} returns the full
+name corresponding to that user-id or login name.  If you specify a
+user-id or login name that isn't defined, it returns @code{nil}.
+@end defun
+
+@vindex user-full-name
+@vindex user-real-login-name
+@vindex user-login-name
+  The symbols @code{user-login-name}, @code{user-real-login-name} and
+@code{user-full-name} are variables as well as functions.  The functions
+return the same values that the variables hold.  These variables allow
+you to ``fake out'' Emacs by telling the functions what to return.  The
+variables are also useful for constructing frame titles (@pxref{Frame
+Titles}).
+
+@defun user-real-uid
+This function returns the real @acronym{UID} of the user.
+The value may be a floating point number.
+
+@example
+@group
+(user-real-uid)
+     @result{} 19
+@end group
+@end example
+@end defun
+
+@defun user-uid
+This function returns the effective @acronym{UID} of the user.
+The value may be a floating point number.
+@end defun
+
+@node Time of Day
+@section Time of Day
+
+  This section explains how to determine the current time and the time
+zone.
+
+@defun current-time-string &optional time-value
+This function returns the current time and date as a human-readable
+string.  The format of the string is unvarying; the number of characters
+used for each part is always the same, so you can reliably use
+@code{substring} to extract pieces of it.  It is wise to count the
+characters from the beginning of the string rather than from the end, as
+additional information may some day be added at the end.
+
+@c Emacs 19 feature
+The argument @var{time-value}, if given, specifies a time to format
+instead of the current time.  The argument should be a list whose first
+two elements are integers.  Thus, you can use times obtained from
+@code{current-time} (see below) and from @code{file-attributes}
+(@pxref{Definition of file-attributes}).  @var{time-value} can also be
+a cons of two integers, but this is considered obsolete.
+
+@example
+@group
+(current-time-string)
+     @result{} "Wed Oct 14 22:21:05 1987"
+@end group
+@end example
+@end defun
+
+@c Emacs 19 feature
+@defun current-time
+This function returns the system's time value as a list of three
+integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
+@var{high} and @var{low} combine to give the number of seconds since
+0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
+@ifnottex
+@var{high} * 2**16 + @var{low}.
+@end ifnottex
+@tex
+$high*2^{16}+low$.
+@end tex
+
+The third element, @var{microsec}, gives the microseconds since the
+start of the current second (or 0 for systems that return time with
+the resolution of only one second).
+
+The first two elements can be compared with file time values such as you
+get with the function @code{file-attributes}.
+@xref{Definition of file-attributes}.
+@end defun
+
+@c Emacs 19 feature
+@defun current-time-zone &optional time-value
+This function returns a list describing the time zone that the user is
+in.
+
+The value has the form @code{(@var{offset} @var{name})}.  Here
+@var{offset} is an integer giving the number of seconds ahead of UTC
+(east of Greenwich).  A negative value means west of Greenwich.  The
+second element, @var{name}, is a string giving the name of the time
+zone.  Both elements change when daylight saving time begins or ends;
+if the user has specified a time zone that does not use a seasonal time
+adjustment, then the value is constant through time.
+
+If the operating system doesn't supply all the information necessary to
+compute the value, the unknown elements of the list are @code{nil}.
+
+The argument @var{time-value}, if given, specifies a time to analyze
+instead of the current time.  The argument should have the same form
+as for @code{current-time-string} (see above).  Thus, you can use
+times obtained from @code{current-time} (see above) and from
+@code{file-attributes}.  @xref{Definition of file-attributes}.
+@end defun
+
+@defun set-time-zone-rule tz
+This function specifies the local time zone according to @var{tz}.  If
+@var{tz} is @code{nil}, that means to use an implementation-defined
+default time zone.  If @var{tz} is @code{t}, that means to use
+Universal Time.  Otherwise, @var{tz} should be a string specifying a
+time zone rule.
+@end defun
+
+@defun float-time &optional time-value
+This function returns the current time as a floating-point number of
+seconds since the epoch.  The argument @var{time-value}, if given,
+specifies a time to convert instead of the current time.  The argument
+should have the same form as for @code{current-time-string} (see
+above).  Thus, it accepts the output of @code{current-time} and
+@code{file-attributes}.
+
+@emph{Warning}: Since the result is floating point, it may not be
+exact.  Do not use this function if precise time stamps are required.
+@end defun
+
+@node Time Conversion
+@section Time Conversion
+
+  These functions convert time values (lists of two or three integers)
+to calendrical information and vice versa.  You can get time values
+from the functions @code{current-time} (@pxref{Time of Day}) and
+@code{file-attributes} (@pxref{Definition of file-attributes}).
+
+  Many operating systems are limited to time values that contain 32 bits
+of information; these systems typically handle only the times from
+1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.  However, some
+operating systems have larger time values, and can represent times far
+in the past or future.
+
+  Time conversion functions always use the Gregorian calendar, even
+for dates before the Gregorian calendar was introduced.  Year numbers
+count the number of years since the year 1 B.C., and do not skip zero
+as traditional Gregorian years do; for example, the year number
+@minus{}37 represents the Gregorian year 38 B.C@.
+
+@defun decode-time &optional time
+This function converts a time value into calendrical information.  If
+you don't specify @var{time}, it decodes the current time.  The return
+value is a list of nine elements, as follows:
+
+@example
+(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
+@end example
+
+Here is what the elements mean:
+
+@table @var
+@item seconds
+The number of seconds past the minute, as an integer between 0 and 59.
+On some operating systems, this is 60 for leap seconds.
+@item minutes
+The number of minutes past the hour, as an integer between 0 and 59.
+@item hour
+The hour of the day, as an integer between 0 and 23.
+@item day
+The day of the month, as an integer between 1 and 31.
+@item month
+The month of the year, as an integer between 1 and 12.
+@item year
+The year, an integer typically greater than 1900.
+@item dow
+The day of week, as an integer between 0 and 6, where 0 stands for
+Sunday.
+@item dst
+@code{t} if daylight saving time is effect, otherwise @code{nil}.
+@item zone
+An integer indicating the time zone, as the number of seconds east of
+Greenwich.
+@end table
+
+@strong{Common Lisp Note:} Common Lisp has different meanings for
+@var{dow} and @var{zone}.
+@end defun
+
+@defun encode-time seconds minutes hour day month year &optional zone
+This function is the inverse of @code{decode-time}.  It converts seven
+items of calendrical data into a time value.  For the meanings of the
+arguments, see the table above under @code{decode-time}.
+
+Year numbers less than 100 are not treated specially.  If you want them
+to stand for years above 1900, or years above 2000, you must alter them
+yourself before you call @code{encode-time}.
+
+The optional argument @var{zone} defaults to the current time zone and
+its daylight saving time rules.  If specified, it can be either a list
+(as you would get from @code{current-time-zone}), a string as in the
+@code{TZ} environment variable, @code{t} for Universal Time, or an
+integer (as you would get from @code{decode-time}).  The specified
+zone is used without any further alteration for daylight saving time.
+
+If you pass more than seven arguments to @code{encode-time}, the first
+six are used as @var{seconds} through @var{year}, the last argument is
+used as @var{zone}, and the arguments in between are ignored.  This
+feature makes it possible to use the elements of a list returned by
+@code{decode-time} as the arguments to @code{encode-time}, like this:
+
+@example
+(apply 'encode-time (decode-time @dots{}))
+@end example
+
+You can perform simple date arithmetic by using out-of-range values for
+the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
+arguments; for example, day 0 means the day preceding the given month.
+
+The operating system puts limits on the range of possible time values;
+if you try to encode a time that is out of range, an error results.
+For instance, years before 1970 do not work on some systems;
+on others, years as early as 1901 do work.
+@end defun
+
+@node Time Parsing
+@section Parsing and Formatting Times
+
+  These functions convert time values (lists of two or three integers)
+to text in a string, and vice versa.
+
+@defun date-to-time string
+This function parses the time-string @var{string} and returns the
+corresponding time value.
+@end defun
+
+@defun format-time-string format-string &optional time universal
+This function converts @var{time} (or the current time, if @var{time} is
+omitted) to a string according to @var{format-string}.  The argument
+@var{format-string} may contain @samp{%}-sequences which say to
+substitute parts of the time.  Here is a table of what the
+@samp{%}-sequences mean:
+
+@table @samp
+@item %a
+This stands for the abbreviated name of the day of week.
+@item %A
+This stands for the full name of the day of week.
+@item %b
+This stands for the abbreviated name of the month.
+@item %B
+This stands for the full name of the month.
+@item %c
+This is a synonym for @samp{%x %X}.
+@item %C
+This has a locale-specific meaning.  In the default locale (named C), it
+is equivalent to @samp{%A, %B %e, %Y}.
+@item %d
+This stands for the day of month, zero-padded.
+@item %D
+This is a synonym for @samp{%m/%d/%y}.
+@item %e
+This stands for the day of month, blank-padded.
+@item %h
+This is a synonym for @samp{%b}.
+@item %H
+This stands for the hour (00-23).
+@item %I
+This stands for the hour (01-12).
+@item %j
+This stands for the day of the year (001-366).
+@item %k
+This stands for the hour (0-23), blank padded.
+@item %l
+This stands for the hour (1-12), blank padded.
+@item %m
+This stands for the month (01-12).
+@item %M
+This stands for the minute (00-59).
+@item %n
+This stands for a newline.
+@item %p
+This stands for @samp{AM} or @samp{PM}, as appropriate.
+@item %r
+This is a synonym for @samp{%I:%M:%S %p}.
+@item %R
+This is a synonym for @samp{%H:%M}.
+@item %S
+This stands for the seconds (00-59).
+@item %t
+This stands for a tab character.
+@item %T
+This is a synonym for @samp{%H:%M:%S}.
+@item %U
+This stands for the week of the year (01-52), assuming that weeks
+start on Sunday.
+@item %w
+This stands for the numeric day of week (0-6).  Sunday is day 0.
+@item %W
+This stands for the week of the year (01-52), assuming that weeks
+start on Monday.
+@item %x
+This has a locale-specific meaning.  In the default locale (named
+@samp{C}), it is equivalent to @samp{%D}.
+@item %X
+This has a locale-specific meaning.  In the default locale (named
+@samp{C}), it is equivalent to @samp{%T}.
+@item %y
+This stands for the year without century (00-99).
+@item %Y
+This stands for the year with century.
+@item %Z
+This stands for the time zone abbreviation (e.g., @samp{EST}).
+@item %z
+This stands for the time zone numerical offset (e.g., @samp{-0500}).
+@end table
+
+You can also specify the field width and type of padding for any of
+these @samp{%}-sequences.  This works as in @code{printf}: you write
+the field width as digits in the middle of a @samp{%}-sequences.  If you
+start the field width with @samp{0}, it means to pad with zeros.  If you
+start the field width with @samp{_}, it means to pad with spaces.
+
+For example, @samp{%S} specifies the number of seconds since the minute;
+@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
+pad with spaces to 3 positions.  Plain @samp{%3S} pads with zeros,
+because that is how @samp{%S} normally pads to two positions.
+
+The characters @samp{E} and @samp{O} act as modifiers when used between
+@samp{%} and one of the letters in the table above.  @samp{E} specifies
+using the current locale's ``alternative'' version of the date and time.
+In a Japanese locale, for example, @code{%Ex} might yield a date format
+based on the Japanese Emperors' reigns.  @samp{E} is allowed in
+@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
+@samp{%EY}.
+
+@samp{O} means to use the current locale's ``alternative''
+representation of numbers, instead of the ordinary decimal digits.  This
+is allowed with most letters, all the ones that output numbers.
+
+If @var{universal} is non-@code{nil}, that means to describe the time as
+Universal Time; @code{nil} means describe it using what Emacs believes
+is the local time zone (see @code{current-time-zone}).
+
+This function uses the C library function @code{strftime}
+(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
+Manual}) to do most of the work.  In order to communicate with that
+function, it first encodes its argument using the coding system
+specified by @code{locale-coding-system} (@pxref{Locales}); after
+@code{strftime} returns the resulting string,
+@code{format-time-string} decodes the string using that same coding
+system.
+@end defun
+
+@defun seconds-to-time seconds
+This function converts @var{seconds}, a floating point number of
+seconds since the epoch, to a time value and returns that.  To perform
+the inverse conversion, use @code{float-time}.
+@end defun
+
+@node Processor Run Time
+@section Processor Run time
+@cindex processor run time
+
+@defun get-internal-run-time
+This function returns the processor run time used by Emacs as a list
+of three integers: @code{(@var{high} @var{low} @var{microsec})}.  The
+integers @var{high} and @var{low} combine to give the number of
+seconds, which is
+@ifnottex
+@var{high} * 2**16 + @var{low}.
+@end ifnottex
+@tex
+$high*2^{16}+low$.
+@end tex
+
+The third element, @var{microsec}, gives the microseconds (or 0 for
+systems that return time with the resolution of only one second).
+
+If the system doesn't provide a way to determine the processor run
+time, get-internal-run-time returns the same time as current-time.
+@end defun
+
+@node Time Calculations
+@section Time Calculations
+
+  These functions perform calendrical computations using time values
+(the kind of list that @code{current-time} returns).
+
+@defun time-less-p t1 t2
+This returns @code{t} if time value @var{t1} is less than time value
+@var{t2}.
+@end defun
+
+@defun time-subtract t1 t2
+This returns the time difference @var{t1} @minus{} @var{t2} between
+two time values, in the same format as a time value.
+@end defun
+
+@defun time-add t1 t2
+This returns the sum of two time values, one of which ought to
+represent a time difference rather than a point in time.
+Here is how to add a number of seconds to a time value:
+
+@example
+(time-add @var{time} (seconds-to-time @var{seconds}))
+@end example
+@end defun
+
+@defun time-to-days time
+This function returns the number of days between the beginning of year
+1 and @var{time}.
+@end defun
+
+@defun time-to-day-in-year time
+This returns the day number within the year corresponding to @var{time}.
+@end defun
+
+@defun date-leap-year-p year
+This function returns @code{t} if @var{year} is a leap year.
+@end defun
+
+@node Timers
+@section Timers for Delayed Execution
+@cindex timer
+
+  You can set up a @dfn{timer} to call a function at a specified
+future time or after a certain length of idleness.
+
+  Emacs cannot run timers at any arbitrary point in a Lisp program; it
+can run them only when Emacs could accept output from a subprocess:
+namely, while waiting or inside certain primitive functions such as
+@code{sit-for} or @code{read-event} which @emph{can} wait.  Therefore, a
+timer's execution may be delayed if Emacs is busy.  However, the time of
+execution is very precise if Emacs is idle.
+
+  Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
+function, because quitting out of many timer functions can leave
+things in an inconsistent state.  This is normally unproblematical
+because most timer functions don't do a lot of work.  Indeed, for a
+timer to call a function that takes substantial time to run is likely
+to be annoying.  If a timer function needs to allow quitting, it
+should use @code{with-local-quit} (@pxref{Quitting}).  For example, if
+a timer function calls @code{accept-process-output} to receive output
+from an external process, that call should be wrapped inside
+@code{with-local-quit}, to ensure that @kbd{C-g} works if the external
+process hangs.
+
+  It is usually a bad idea for timer functions to alter buffer
+contents.  When they do, they usually should call @code{undo-boundary}
+both before and after changing the buffer, to separate the timer's
+changes from user commands' changes and prevent a single undo entry
+from growing to be quite large.
+
+  Timer functions should also avoid calling functions that cause Emacs
+to wait, such as @code{sit-for} (@pxref{Waiting}).  This can lead to
+unpredictable effects, since other timers (or even the same timer) can
+run while waiting.  If a timer function needs to perform an action
+after a certain time has elapsed, it can do this by scheduling a new
+timer.
+
+  If a timer function calls functions that can change the match data,
+it should save and restore the match data.  @xref{Saving Match Data}.
+
+@deffn Command run-at-time time repeat function &rest args
+This sets up a timer that calls the function @var{function} with
+arguments @var{args} at time @var{time}.  If @var{repeat} is a number
+(integer or floating point), the timer is scheduled to run again every
+@var{repeat} seconds after @var{time}.  If @var{repeat} is @code{nil},
+the timer runs only once.
+
+@var{time} may specify an absolute or a relative time.
+
+Absolute times may be specified using a string with a limited variety
+of formats, and are taken to be times @emph{today}, even if already in
+the past.  The recognized forms are @samp{@var{xxxx}},
+@samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
+and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
+@samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
+@samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
+@samp{@var{xx}:@var{xx}PM}.  A period can be used instead of a colon
+to separate the hour and minute parts.
+
+To specify a relative time as a string, use numbers followed by units.
+For example:
+
+@table @samp
+@item 1 min
+denotes 1 minute from now.
+@item 1 min 5 sec
+denotes 65 seconds from now.
+@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
+denotes exactly 103 months, 123 days, and 10862 seconds from now.
+@end table
+
+For relative time values, Emacs considers a month to be exactly thirty
+days, and a year to be exactly 365.25 days.
+
+Not all convenient formats are strings.  If @var{time} is a number
+(integer or floating point), that specifies a relative time measured in
+seconds.  The result of @code{encode-time} can also be used to specify
+an absolute value for @var{time}.
+
+In most cases, @var{repeat} has no effect on when @emph{first} call
+takes place---@var{time} alone specifies that.  There is one exception:
+if @var{time} is @code{t}, then the timer runs whenever the time is a
+multiple of @var{repeat} seconds after the epoch.  This is useful for
+functions like @code{display-time}.
+
+The function @code{run-at-time} returns a timer value that identifies
+the particular scheduled future action.  You can use this value to call
+@code{cancel-timer} (see below).
+@end deffn
+
+  A repeating timer nominally ought to run every @var{repeat} seconds,
+but remember that any invocation of a timer can be late.  Lateness of
+one repetition has no effect on the scheduled time of the next
+repetition.  For instance, if Emacs is busy computing for long enough
+to cover three scheduled repetitions of the timer, and then starts to
+wait, it will immediately call the timer function three times in
+immediate succession (presuming no other timers trigger before or
+between them).  If you want a timer to run again no less than @var{n}
+seconds after the last invocation, don't use the @var{repeat} argument.
+Instead, the timer function should explicitly reschedule the timer.
+
+@defvar timer-max-repeats
+This variable's value specifies the maximum number of times to repeat
+calling a timer function in a row, when many previously scheduled
+calls were unavoidably delayed.
+@end defvar
+
+@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
+Execute @var{body}, but give up after @var{seconds} seconds.  If
+@var{body} finishes before the time is up, @code{with-timeout} returns
+the value of the last form in @var{body}.  If, however, the execution of
+@var{body} is cut short by the timeout, then @code{with-timeout}
+executes all the @var{timeout-forms} and returns the value of the last
+of them.
+
+This macro works by setting a timer to run after @var{seconds} seconds.  If
+@var{body} finishes before that time, it cancels the timer.  If the
+timer actually runs, it terminates execution of @var{body}, then
+executes @var{timeout-forms}.
+
+Since timers can run within a Lisp program only when the program calls a
+primitive that can wait, @code{with-timeout} cannot stop executing
+@var{body} while it is in the midst of a computation---only when it
+calls one of those primitives.  So use @code{with-timeout} only with a
+@var{body} that waits for input, not one that does a long computation.
+@end defmac
+
+  The function @code{y-or-n-p-with-timeout} provides a simple way to use
+a timer to avoid waiting too long for an answer.  @xref{Yes-or-No
+Queries}.
+
+@defun cancel-timer timer
+This cancels the requested action for @var{timer}, which should be a
+timer---usually, one previously returned by @code{run-at-time} or
+@code{run-with-idle-timer}.  This cancels the effect of that call to
+one of these functions; the arrival of the specified time will not
+cause anything special to happen.
+@end defun
+
+@node Idle Timers
+@section Idle Timers
+
+  Here is how to set up a timer that runs when Emacs is idle for a
+certain length of time.  Aside from how to set them up, idle timers
+work just like ordinary timers.
+
+@deffn Command run-with-idle-timer secs repeat function &rest args
+Set up a timer which runs when Emacs has been idle for @var{secs}
+seconds.  The value of @var{secs} may be an integer or a floating point
+number; a value of the type returned by @code{current-idle-time}
+is also allowed.
+
+If @var{repeat} is @code{nil}, the timer runs just once, the first time
+Emacs remains idle for a long enough time.  More often @var{repeat} is
+non-@code{nil}, which means to run the timer @emph{each time} Emacs
+remains idle for @var{secs} seconds.
+
+The function @code{run-with-idle-timer} returns a timer value which you
+can use in calling @code{cancel-timer} (@pxref{Timers}).
+@end deffn
+
+@cindex idleness
+  Emacs becomes ``idle'' when it starts waiting for user input, and it
+remains idle until the user provides some input.  If a timer is set for
+five seconds of idleness, it runs approximately five seconds after Emacs
+first becomes idle.  Even if @var{repeat} is non-@code{nil}, this timer
+will not run again as long as Emacs remains idle, because the duration
+of idleness will continue to increase and will not go down to five
+seconds again.
+
+  Emacs can do various things while idle: garbage collect, autosave or
+handle data from a subprocess.  But these interludes during idleness do
+not interfere with idle timers, because they do not reset the clock of
+idleness to zero.  An idle timer set for 600 seconds will run when ten
+minutes have elapsed since the last user command was finished, even if
+subprocess output has been accepted thousands of times within those ten
+minutes, and even if there have been garbage collections and autosaves.
+
+  When the user supplies input, Emacs becomes non-idle while executing the
+input.  Then it becomes idle again, and all the idle timers that are
+set up to repeat will subsequently run another time, one by one.
+
+@c Emacs 19 feature
+@defun current-idle-time
+This function returns the length of time Emacs has been idle, as a
+list of three integers: @code{(@var{high} @var{low} @var{microsec})}.
+The integers @var{high} and @var{low} combine to give the number of
+seconds of idleness, which is
+@ifnottex
+@var{high} * 2**16 + @var{low}.
+@end ifnottex
+@tex
+$high*2^{16}+low$.
+@end tex
+
+The third element, @var{microsec}, gives the microseconds since the
+start of the current second (or 0 for systems that return time with
+the resolution of only one second).
+
+The main use of this function is when an idle timer function wants to
+``take a break'' for a while.  It can set up another idle timer to
+call the same function again, after a few seconds more idleness.
+Here's an example:
+
+@smallexample
+(defvar resume-timer nil
+  "Timer that `timer-function' used to reschedule itself, or nil.")
+
+(defun timer-function ()
+  ;; @r{If the user types a command while @code{resume-timer}}
+  ;; @r{is active, the next time this function is called from}
+  ;; @r{its main idle timer, deactivate @code{resume-timer}.}
+  (when resume-timer
+    (cancel-timer resume-timer))
+  ...@var{do the work for a while}...
+  (when @var{taking-a-break}
+    (setq resume-timer
+          (run-with-idle-timer
+            ;; Compute an idle time @var{break-length}
+            ;; more than the current value.
+            (time-add (current-idle-time)
+                      (seconds-to-time @var{break-length}))
+            nil
+            'timer-function))))
+@end smallexample
+@end defun
+
+  Some idle timer functions in user Lisp packages have a loop that
+does a certain amount of processing each time around, and exits when
+@code{(input-pending-p)} is non-@code{nil}.  That approach seems very
+natural but has two problems:
+
+@itemize
+@item
+It blocks out all process output (since Emacs accepts process output
+only while waiting).
+
+@item
+It blocks out any idle timers that ought to run during that time.
+@end itemize
+
+@noindent
+To avoid these problems, don't use that technique.  Instead, write
+such idle timers to reschedule themselves after a brief pause, using
+the method in the @code{timer-function} example above.
+
+@node Terminal Input
+@section Terminal Input
+@cindex terminal input
+
+  This section describes functions and variables for recording or
+manipulating terminal input.  See @ref{Display}, for related
+functions.
+
+@menu
+* Input Modes::		Options for how input is processed.
+* Recording Input::	Saving histories of recent or all input events.
+@end menu
+
+@node Input Modes
+@subsection Input Modes
+@cindex input modes
+@cindex terminal input modes
+
+@defun set-input-mode interrupt flow meta &optional quit-char
+This function sets the mode for reading keyboard input.  If
+@var{interrupt} is non-null, then Emacs uses input interrupts.  If it is
+@code{nil}, then it uses @sc{cbreak} mode.  The default setting is
+system-dependent.  Some systems always use @sc{cbreak} mode regardless
+of what is specified.
+
+When Emacs communicates directly with X, it ignores this argument and
+uses interrupts if that is the way it knows how to communicate.
+
+If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
+(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal.  This
+has no effect except in @sc{cbreak} mode.
+
+@c Emacs 19 feature
+The argument @var{meta} controls support for input character codes
+above 127.  If @var{meta} is @code{t}, Emacs converts characters with
+the 8th bit set into Meta characters.  If @var{meta} is @code{nil},
+Emacs disregards the 8th bit; this is necessary when the terminal uses
+it as a parity bit.  If @var{meta} is neither @code{t} nor @code{nil},
+Emacs uses all 8 bits of input unchanged.  This is good for terminals
+that use 8-bit character sets.
+
+@c Emacs 19 feature
+If @var{quit-char} is non-@code{nil}, it specifies the character to
+use for quitting.  Normally this character is @kbd{C-g}.
+@xref{Quitting}.
+@end defun
+
+The @code{current-input-mode} function returns the input mode settings
+Emacs is currently using.
+
+@c Emacs 19 feature
+@defun current-input-mode
+This function returns the current mode for reading keyboard input.  It
+returns a list, corresponding to the arguments of @code{set-input-mode},
+of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
+which:
+@table @var
+@item interrupt
+is non-@code{nil} when Emacs is using interrupt-driven input.  If
+@code{nil}, Emacs is using @sc{cbreak} mode.
+@item flow
+is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
+flow control for output to the terminal.  This value is meaningful only
+when @var{interrupt} is @code{nil}.
+@item meta
+is @code{t} if Emacs treats the eighth bit of input characters as
+the meta bit; @code{nil} means Emacs clears the eighth bit of every
+input character; any other value means Emacs uses all eight bits as the
+basic character code.
+@item quit
+is the character Emacs currently uses for quitting, usually @kbd{C-g}.
+@end table
+@end defun
+
+@node Recording Input
+@subsection Recording Input
+@cindex recording input
+
+@defun recent-keys
+This function returns a vector containing the last 300 input events from
+the keyboard or mouse.  All input events are included, whether or not
+they were used as parts of key sequences.  Thus, you always get the last
+100 input events, not counting events generated by keyboard macros.
+(These are excluded because they are less interesting for debugging; it
+should be enough to see the events that invoked the macros.)
+
+A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
+causes this function to return an empty vector immediately afterward.
+@end defun
+
+@deffn Command open-dribble-file filename
+@cindex dribble file
+This function opens a @dfn{dribble file} named @var{filename}.  When a
+dribble file is open, each input event from the keyboard or mouse (but
+not those from keyboard macros) is written in that file.  A
+non-character event is expressed using its printed representation
+surrounded by @samp{<@dots{}>}.
+
+You close the dribble file by calling this function with an argument
+of @code{nil}.
+
+This function is normally used to record the input necessary to
+trigger an Emacs bug, for the sake of a bug report.
+
+@example
+@group
+(open-dribble-file "~/dribble")
+     @result{} nil
+@end group
+@end example
+@end deffn
+
+  See also the @code{open-termscript} function (@pxref{Terminal Output}).
+
+@node Terminal Output
+@section Terminal Output
+@cindex terminal output
+
+  The terminal output functions send output to a text terminal, or keep
+track of output sent to the terminal.  The variable @code{baud-rate}
+tells you what Emacs thinks is the output speed of the terminal.
+
+@defvar baud-rate
+This variable's value is the output speed of the terminal, as far as
+Emacs knows.  Setting this variable does not change the speed of actual
+data transmission, but the value is used for calculations such as
+padding.
+
+  It also affects decisions about whether to scroll part of the
+screen or repaint on text terminals.  @xref{Forcing Redisplay},
+for the corresponding functionality on graphical terminals.
+
+The value is measured in baud.
+@end defvar
+
+  If you are running across a network, and different parts of the
+network work at different baud rates, the value returned by Emacs may be
+different from the value used by your local terminal.  Some network
+protocols communicate the local terminal speed to the remote machine, so
+that Emacs and other programs can get the proper value, but others do
+not.  If Emacs has the wrong value, it makes decisions that are less
+than optimal.  To fix the problem, set @code{baud-rate}.
+
+@defun baud-rate
+This obsolete function returns the value of the variable
+@code{baud-rate}.
+@end defun
+
+@defun send-string-to-terminal string
+This function sends @var{string} to the terminal without alteration.
+Control characters in @var{string} have terminal-dependent effects.
+This function operates only on text terminals.
+
+One use of this function is to define function keys on terminals that
+have downloadable function key definitions.  For example, this is how (on
+certain terminals) to define function key 4 to move forward four
+characters (by transmitting the characters @kbd{C-u C-f} to the
+computer):
+
+@example
+@group
+(send-string-to-terminal "\eF4\^U\^F")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@deffn Command open-termscript filename
+@cindex termscript file
+This function is used to open a @dfn{termscript file} that will record
+all the characters sent by Emacs to the terminal.  It returns
+@code{nil}.  Termscript files are useful for investigating problems
+where Emacs garbles the screen, problems that are due to incorrect
+Termcap entries or to undesirable settings of terminal options more
+often than to actual Emacs bugs.  Once you are certain which characters
+were actually output, you can determine reliably whether they correspond
+to the Termcap specifications in use.
+
+You close the termscript file by calling this function with an
+argument of @code{nil}.
+
+See also @code{open-dribble-file} in @ref{Recording Input}.
+
+@example
+@group
+(open-termscript "../junk/termscript")
+     @result{} nil
+@end group
+@end example
+@end deffn
+
+@node Sound Output
+@section Sound Output
+@cindex sound
+
+  To play sound using Emacs, use the function @code{play-sound}.  Only
+certain systems are supported; if you call @code{play-sound} on a system
+which cannot really do the job, it gives an error.  Emacs version 20 and
+earlier did not support sound at all.
+
+  The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
+or Sun Audio format (@samp{.au}).
+
+@defun play-sound sound
+This function plays a specified sound.  The argument, @var{sound}, has
+the form @code{(sound @var{properties}...)}, where the @var{properties}
+consist of alternating keywords (particular symbols recognized
+specially) and values corresponding to them.
+
+Here is a table of the keywords that are currently meaningful in
+@var{sound}, and their meanings:
+
+@table @code
+@item :file @var{file}
+This specifies the file containing the sound to play.
+If the file name is not absolute, it is expanded against
+the directory @code{data-directory}.
+
+@item :data @var{data}
+This specifies the sound to play without need to refer to a file.  The
+value, @var{data}, should be a string containing the same bytes as a
+sound file.  We recommend using a unibyte string.
+
+@item :volume @var{volume}
+This specifies how loud to play the sound.  It should be a number in the
+range of 0 to 1.  The default is to use whatever volume has been
+specified before.
+
+@item :device @var{device}
+This specifies the system device on which to play the sound, as a
+string.  The default device is system-dependent.
+@end table
+
+Before actually playing the sound, @code{play-sound}
+calls the functions in the list @code{play-sound-functions}.
+Each function is called with one argument, @var{sound}.
+@end defun
+
+@defun play-sound-file file &optional volume device
+This function is an alternative interface to playing a sound @var{file}
+specifying an optional @var{volume} and @var{device}.
+@end defun
+
+@defvar play-sound-functions
+A list of functions to be called before playing a sound.  Each function
+is called with one argument, a property list that describes the sound.
+@end defvar
+
+@node X11 Keysyms
+@section Operating on X11 Keysyms
+@cindex X11 keysyms
+
+To define system-specific X11 keysyms, set the variable
+@code{system-key-alist}.
+
+@defvar system-key-alist
+This variable's value should be an alist with one element for each
+system-specific keysym.  Each element has the form @code{(@var{code}
+. @var{symbol})}, where @var{code} is the numeric keysym code (not
+including the ``vendor specific'' bit,
+@ifnottex
+-2**28),
+@end ifnottex
+@tex
+$-2^{28}$),
+@end tex
+and @var{symbol} is the name for the function key.
+
+For example @code{(168 . mute-acute)} defines a system-specific key (used
+by HP X servers) whose numeric code is
+@ifnottex
+-2**28
+@end ifnottex
+@tex
+$-2^{28}$
+@end tex
++ 168.
+
+It is not crucial to exclude from the alist the keysyms of other X
+servers; those do no harm, as long as they don't conflict with the ones
+used by the X server actually in use.
+
+The variable is always local to the current terminal, and cannot be
+buffer-local.  @xref{Multiple Displays}.
+@end defvar
+
+You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
+
+@defvar x-alt-keysym
+@defvarx x-meta-keysym
+@defvarx x-hyper-keysym
+@defvarx x-super-keysym
+The name of the keysym that should stand for the Alt modifier
+(respectively, for Meta, Hyper, and Super).  For example, here is
+how to swap the Meta and Alt modifiers within Emacs:
+@lisp
+(setq x-alt-keysym 'meta)
+(setq x-meta-keysym 'alt)
+@end lisp
+@end defvar
+
+@node Batch Mode
+@section Batch Mode
+@cindex batch mode
+
+  The command-line option @samp{-batch} causes Emacs to run
+noninteractively.  In this mode, Emacs does not read commands from the
+terminal, it does not alter the terminal modes, and it does not expect
+to be outputting to an erasable screen.  The idea is that you specify
+Lisp programs to run; when they are finished, Emacs should exit.  The
+way to specify the programs to run is with @samp{-l @var{file}}, which
+loads the library named @var{file}, or @samp{-f @var{function}}, which
+calls @var{function} with no arguments, or @samp{--eval @var{form}}.
+
+  Any Lisp program output that would normally go to the echo area,
+either using @code{message}, or using @code{prin1}, etc., with @code{t}
+as the stream, goes instead to Emacs's standard error descriptor when
+in batch mode.  Similarly, input that would normally come from the
+minibuffer is read from the standard input descriptor.
+Thus, Emacs behaves much like a noninteractive
+application program.  (The echo area output that Emacs itself normally
+generates, such as command echoing, is suppressed entirely.)
+
+@defvar noninteractive
+This variable is non-@code{nil} when Emacs is running in batch mode.
+@end defvar
+
+@node Session Management
+@section Session Management
+@cindex session manager
+
+Emacs supports the X Session Management Protocol for suspension and
+restart of applications.  In the X Window System, a program called the
+@dfn{session manager} has the responsibility to keep track of the
+applications that are running.  During shutdown, the session manager
+asks applications to save their state, and delays the actual shutdown
+until they respond.  An application can also cancel the shutdown.
+
+When the session manager restarts a suspended session, it directs
+these applications to individually reload their saved state.  It does
+this by specifying a special command-line argument that says what
+saved session to restore.  For Emacs, this argument is @samp{--smid
+@var{session}}.
+
+@defvar emacs-save-session-functions
+Emacs supports saving state by using a hook called
+@code{emacs-save-session-functions}.  Each function in this hook is
+called when the session manager tells Emacs that the window system is
+shutting down.  The functions are called with no arguments and with the
+current buffer set to a temporary buffer.  Each function can use
+@code{insert} to add Lisp code to this buffer.  At the end, Emacs
+saves the buffer in a file that a subsequent Emacs invocation will
+load in order to restart the saved session.
+
+If a function in @code{emacs-save-session-functions} returns
+non-@code{nil}, Emacs tells the session manager to cancel the
+shutdown.
+@end defvar
+
+Here is an example that just inserts some text into @samp{*scratch*} when
+Emacs is restarted by the session manager.
+
+@example
+@group
+(add-hook 'emacs-save-session-functions 'save-yourself-test)
+@end group
+
+@group
+(defun save-yourself-test ()
+  (insert "(save-excursion
+  (switch-to-buffer \"*scratch*\")
+  (insert \"I am restored\"))")
+  nil)
+@end group
+@end example
+
+@ignore
+   arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7
+@end ignore
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
new file mode 100644
index 00000000000..939b3f75fc1
--- /dev/null
+++ b/doc/lispref/positions.texi
@@ -0,0 +1,1004 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/positions
+@node Positions, Markers, Frames, Top
+@chapter Positions
+@cindex position (in buffer)
+
+  A @dfn{position} is the index of a character in the text of a buffer.
+More precisely, a position identifies the place between two characters
+(or before the first character, or after the last character), so we can
+speak of the character before or after a given position.  However, we
+often speak of the character ``at'' a position, meaning the character
+after that position.
+
+  Positions are usually represented as integers starting from 1, but
+can also be represented as @dfn{markers}---special objects that
+relocate automatically when text is inserted or deleted so they stay
+with the surrounding characters.  Functions that expect an argument to
+be a position (an integer), but accept a marker as a substitute,
+normally ignore which buffer the marker points into; they convert the
+marker to an integer, and use that integer, exactly as if you had
+passed the integer as the argument, even if the marker points to the
+``wrong'' buffer.  A marker that points nowhere cannot convert to an
+integer; using it instead of an integer causes an error.
+@xref{Markers}.
+
+  See also the ``field'' feature (@pxref{Fields}), which provides
+functions that are used by many cursor-motion commands.
+
+@menu
+* Point::         The special position where editing takes place.
+* Motion::        Changing point.
+* Excursions::    Temporary motion and buffer changes.
+* Narrowing::     Restricting editing to a portion of the buffer.
+@end menu
+
+@node Point
+@section Point
+@cindex point
+
+  @dfn{Point} is a special buffer position used by many editing
+commands, including the self-inserting typed characters and text
+insertion functions.  Other commands move point through the text
+to allow editing and insertion at different places.
+
+  Like other positions, point designates a place between two characters
+(or before the first character, or after the last character), rather
+than a particular character.  Usually terminals display the cursor over
+the character that immediately follows point; point is actually before
+the character on which the cursor sits.
+
+@cindex point with narrowing
+  The value of point is a number no less than 1, and no greater than the
+buffer size plus 1.  If narrowing is in effect (@pxref{Narrowing}), then
+point is constrained to fall within the accessible portion of the buffer
+(possibly at one end of it).
+
+  Each buffer has its own value of point, which is independent of the
+value of point in other buffers.  Each window also has a value of point,
+which is independent of the value of point in other windows on the same
+buffer.  This is why point can have different values in various windows
+that display the same buffer.  When a buffer appears in only one window,
+the buffer's point and the window's point normally have the same value,
+so the distinction is rarely important.  @xref{Window Point}, for more
+details.
+
+@defun point
+@cindex current buffer position
+This function returns the value of point in the current buffer,
+as an integer.
+
+@need 700
+@example
+@group
+(point)
+     @result{} 175
+@end group
+@end example
+@end defun
+
+@defun point-min
+This function returns the minimum accessible value of point in the
+current buffer.  This is normally 1, but if narrowing is in effect, it
+is the position of the start of the region that you narrowed to.
+(@xref{Narrowing}.)
+@end defun
+
+@defun point-max
+This function returns the maximum accessible value of point in the
+current buffer.  This is @code{(1+ (buffer-size))}, unless narrowing is
+in effect, in which case it is the position of the end of the region
+that you narrowed to.  (@xref{Narrowing}.)
+@end defun
+
+@defun buffer-end flag
+This function returns @code{(point-max)} if @var{flag} is greater than
+0, @code{(point-min)} otherwise.  The argument @var{flag} must be a
+number.
+@end defun
+
+@defun buffer-size &optional buffer
+This function returns the total number of characters in the current
+buffer.  In the absence of any narrowing (@pxref{Narrowing}),
+@code{point-max} returns a value one larger than this.
+
+If you specify a buffer, @var{buffer}, then the value is the
+size of @var{buffer}.
+
+@example
+@group
+(buffer-size)
+     @result{} 35
+@end group
+@group
+(point-max)
+     @result{} 36
+@end group
+@end example
+@end defun
+
+@node Motion
+@section Motion
+@cindex motion by chars, words, lines, lists
+
+  Motion functions change the value of point, either relative to the
+current value of point, relative to the beginning or end of the buffer,
+or relative to the edges of the selected window.  @xref{Point}.
+
+@menu
+* Character Motion::       Moving in terms of characters.
+* Word Motion::            Moving in terms of words.
+* Buffer End Motion::      Moving to the beginning or end of the buffer.
+* Text Lines::             Moving in terms of lines of text.
+* Screen Lines::           Moving in terms of lines as displayed.
+* List Motion::            Moving by parsing lists and sexps.
+* Skipping Characters::    Skipping characters belonging to a certain set.
+@end menu
+
+@node Character Motion
+@subsection Motion by Characters
+
+  These functions move point based on a count of characters.
+@code{goto-char} is the fundamental primitive; the other functions use
+that.
+
+@deffn Command goto-char position
+This function sets point in the current buffer to the value
+@var{position}.  If @var{position} is less than 1, it moves point to the
+beginning of the buffer.  If @var{position} is greater than the length
+of the buffer, it moves point to the end.
+
+If narrowing is in effect, @var{position} still counts from the
+beginning of the buffer, but point cannot go outside the accessible
+portion.  If @var{position} is out of range, @code{goto-char} moves
+point to the beginning or the end of the accessible portion.
+
+When this function is called interactively, @var{position} is the
+numeric prefix argument, if provided; otherwise it is read from the
+minibuffer.
+
+@code{goto-char} returns @var{position}.
+@end deffn
+
+@deffn Command forward-char &optional count
+@c @kindex beginning-of-buffer
+@c @kindex end-of-buffer
+This function moves point @var{count} characters forward, towards the
+end of the buffer (or backward, towards the beginning of the buffer, if
+@var{count} is negative).  If @var{count} is @code{nil}, the default
+is 1.
+
+If this attempts to move past the beginning or end of the buffer (or
+the limits of the accessible portion, when narrowing is in effect), it
+signals an error with error symbol @code{beginning-of-buffer} or
+@code{end-of-buffer}.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+@end deffn
+
+@deffn Command backward-char &optional count
+This is just like @code{forward-char} except that it moves
+in the opposite direction.
+@end deffn
+
+@node Word Motion
+@subsection Motion by Words
+
+  These functions for parsing words use the syntax table to decide
+whether a given character is part of a word.  @xref{Syntax Tables}.
+
+@deffn Command forward-word &optional count
+This function moves point forward @var{count} words (or backward if
+@var{count} is negative).  If @var{count} is @code{nil}, it moves
+forward one word.
+
+``Moving one word'' means moving until point crosses a
+word-constituent character and then encounters a word-separator
+character.  However, this function cannot move point past the boundary
+of the accessible portion of the buffer, or across a field boundary
+(@pxref{Fields}).  The most common case of a field boundary is the end
+of the prompt in the minibuffer.
+
+If it is possible to move @var{count} words, without being stopped
+prematurely by the buffer boundary or a field boundary, the value is
+@code{t}.  Otherwise, the return value is @code{nil} and point stops at
+the buffer boundary or field boundary.
+
+If @code{inhibit-field-text-motion} is non-@code{nil},
+this function ignores field boundaries.
+
+In an interactive call, @var{count} is specified by the numeric prefix
+argument.  If @var{count} is omitted or @code{nil}, it defaults to 1.
+@end deffn
+
+@deffn Command backward-word &optional count
+This function is just like @code{forward-word}, except that it moves
+backward until encountering the front of a word, rather than forward.
+@end deffn
+
+@defvar words-include-escapes
+@c Emacs 19 feature
+This variable affects the behavior of @code{forward-word} and everything
+that uses it.  If it is non-@code{nil}, then characters in the
+``escape'' and ``character quote'' syntax classes count as part of
+words.  Otherwise, they do not.
+@end defvar
+
+@defvar inhibit-field-text-motion
+If this variable is non-@code{nil}, certain motion functions including
+@code{forward-word}, @code{forward-sentence}, and
+@code{forward-paragraph} ignore field boundaries.
+@end defvar
+
+@node Buffer End Motion
+@subsection Motion to an End of the Buffer
+@cindex move to beginning or end of buffer
+
+  To move point to the beginning of the buffer, write:
+
+@example
+@group
+(goto-char (point-min))
+@end group
+@end example
+
+@noindent
+Likewise, to move to the end of the buffer, use:
+
+@example
+@group
+(goto-char (point-max))
+@end group
+@end example
+
+  Here are two commands that users use to do these things.  They are
+documented here to warn you not to use them in Lisp programs, because
+they set the mark and display messages in the echo area.
+
+@deffn Command beginning-of-buffer &optional n
+This function moves point to the beginning of the buffer (or the limits
+of the accessible portion, when narrowing is in effect), setting the
+mark at the previous position (except in Transient Mark mode, if
+the mark is already active, it does not set the mark.)
+
+If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the
+way from the beginning of the accessible portion of the buffer.  In an
+interactive call, @var{n} is the numeric prefix argument, if provided;
+otherwise @var{n} defaults to @code{nil}.
+
+@strong{Warning:} Don't use this function in Lisp programs!
+@end deffn
+
+@deffn Command end-of-buffer &optional n
+This function moves point to the end of the buffer (or the limits of
+the accessible portion, when narrowing is in effect), setting the mark
+at the previous position (except in Transient Mark mode when the mark
+is already active).  If @var{n} is non-@code{nil}, then it puts point
+@var{n} tenths of the way from the end of the accessible portion of
+the buffer.
+
+In an interactive call, @var{n} is the numeric prefix argument,
+if provided; otherwise @var{n} defaults to @code{nil}.
+
+@strong{Warning:} Don't use this function in Lisp programs!
+@end deffn
+
+@node Text Lines
+@subsection Motion by Text Lines
+@cindex lines
+
+  Text lines are portions of the buffer delimited by newline characters,
+which are regarded as part of the previous line.  The first text line
+begins at the beginning of the buffer, and the last text line ends at
+the end of the buffer whether or not the last character is a newline.
+The division of the buffer into text lines is not affected by the width
+of the window, by line continuation in display, or by how tabs and
+control characters are displayed.
+
+@deffn Command goto-line line
+This function moves point to the front of the @var{line}th line,
+counting from line 1 at beginning of the buffer.  If @var{line} is less
+than 1, it moves point to the beginning of the buffer.  If @var{line} is
+greater than the number of lines in the buffer, it moves point to the
+end of the buffer---that is, the @emph{end of the last line} of the
+buffer.  This is the only case in which @code{goto-line} does not
+necessarily move to the beginning of a line.
+
+If narrowing is in effect, then @var{line} still counts from the
+beginning of the buffer, but point cannot go outside the accessible
+portion.  So @code{goto-line} moves point to the beginning or end of the
+accessible portion, if the line number specifies an inaccessible
+position.
+
+The return value of @code{goto-line} is the difference between
+@var{line} and the line number of the line to which point actually was
+able to move (in the full buffer, before taking account of narrowing).
+Thus, the value is positive if the scan encounters the real end of the
+buffer before finding the specified line.  The value is zero if scan
+encounters the end of the accessible portion but not the real end of the
+buffer.
+
+In an interactive call, @var{line} is the numeric prefix argument if
+one has been provided.  Otherwise @var{line} is read in the minibuffer.
+@end deffn
+
+@deffn Command beginning-of-line &optional count
+This function moves point to the beginning of the current line.  With an
+argument @var{count} not @code{nil} or 1, it moves forward
+@var{count}@minus{}1 lines and then to the beginning of the line.
+
+This function does not move point across a field boundary
+(@pxref{Fields}) unless doing so would move beyond there to a
+different line; therefore, if @var{count} is @code{nil} or 1, and
+point starts at a field boundary, point does not move.  To ignore
+field boundaries, either bind @code{inhibit-field-text-motion} to
+@code{t}, or use the @code{forward-line} function instead.  For
+instance, @code{(forward-line 0)} does the same thing as
+@code{(beginning-of-line)}, except that it ignores field boundaries.
+
+If this function reaches the end of the buffer (or of the accessible
+portion, if narrowing is in effect), it positions point there.  No error
+is signaled.
+@end deffn
+
+@defun line-beginning-position &optional count
+Return the position that @code{(beginning-of-line @var{count})}
+would move to.
+@end defun
+
+@deffn Command end-of-line &optional count
+This function moves point to the end of the current line.  With an
+argument @var{count} not @code{nil} or 1, it moves forward
+@var{count}@minus{}1 lines and then to the end of the line.
+
+This function does not move point across a field boundary
+(@pxref{Fields}) unless doing so would move beyond there to a
+different line; therefore, if @var{count} is @code{nil} or 1, and
+point starts at a field boundary, point does not move.  To ignore
+field boundaries, bind @code{inhibit-field-text-motion} to @code{t}.
+
+If this function reaches the end of the buffer (or of the accessible
+portion, if narrowing is in effect), it positions point there.  No error
+is signaled.
+@end deffn
+
+@defun line-end-position &optional count
+Return the position that @code{(end-of-line @var{count})}
+would move to.
+@end defun
+
+@deffn Command forward-line &optional count
+@cindex beginning of line
+This function moves point forward @var{count} lines, to the beginning of
+the line.  If @var{count} is negative, it moves point
+@minus{}@var{count} lines backward, to the beginning of a line.  If
+@var{count} is zero, it moves point to the beginning of the current
+line.  If @var{count} is @code{nil}, that means 1.
+
+If @code{forward-line} encounters the beginning or end of the buffer (or
+of the accessible portion) before finding that many lines, it sets point
+there.  No error is signaled.
+
+@code{forward-line} returns the difference between @var{count} and the
+number of lines actually moved.  If you attempt to move down five lines
+from the beginning of a buffer that has only three lines, point stops at
+the end of the last line, and the value will be 2.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+@end deffn
+
+@defun count-lines start end
+@cindex lines in region
+@anchor{Definition of count-lines}
+This function returns the number of lines between the positions
+@var{start} and @var{end} in the current buffer.  If @var{start} and
+@var{end} are equal, then it returns 0.  Otherwise it returns at least
+1, even if @var{start} and @var{end} are on the same line.  This is
+because the text between them, considered in isolation, must contain at
+least one line unless it is empty.
+
+Here is an example of using @code{count-lines}:
+
+@example
+@group
+(defun current-line ()
+  "Return the vertical position of point@dots{}"
+  (+ (count-lines (window-start) (point))
+     (if (= (current-column) 0) 1 0)))
+@end group
+@end example
+@end defun
+
+@defun line-number-at-pos &optional pos
+@cindex line number
+This function returns the line number in the current buffer
+corresponding to the buffer position @var{pos}.  If @var{pos} is @code{nil}
+or omitted, the current buffer position is used.
+@end defun
+
+@ignore
+@c ================
+The @code{previous-line} and @code{next-line} commands are functions
+that should not be used in programs.  They are for users and are
+mentioned here only for completeness.
+
+@deffn Command previous-line count
+@cindex goal column
+This function moves point up @var{count} lines (down if @var{count}
+is negative).  In moving, it attempts to keep point in the ``goal column''
+(normally the same column that it was at the beginning of the move).
+
+If there is no character in the target line exactly under the current
+column, point is positioned after the character in that line which
+spans this column, or at the end of the line if it is not long enough.
+
+If it attempts to move beyond the top or bottom of the buffer (or clipped
+region), then point is positioned in the goal column in the top or
+bottom line.  No error is signaled.
+
+In an interactive call, @var{count} will be the numeric
+prefix argument.
+
+The command @code{set-goal-column} can be used to create a semipermanent
+goal column to which this command always moves.  Then it does not try to
+move vertically.
+
+If you are thinking of using this in a Lisp program, consider using
+@code{forward-line} with a negative argument instead.  It is usually easier
+to use and more reliable (no dependence on goal column, etc.).
+@end deffn
+
+@deffn Command next-line count
+This function moves point down @var{count} lines (up if @var{count}
+is negative).  In moving, it attempts to keep point in the ``goal column''
+(normally the same column that it was at the beginning of the move).
+
+If there is no character in the target line exactly under the current
+column, point is positioned after the character in that line which
+spans this column, or at the end of the line if it is not long enough.
+
+If it attempts to move beyond the top or bottom of the buffer (or clipped
+region), then point is positioned in the goal column in the top or
+bottom line.  No error is signaled.
+
+In the case where the @var{count} is 1, and point is on the last
+line of the buffer (or clipped region), a new empty line is inserted at the
+end of the buffer (or clipped region) and point moved there.
+
+In an interactive call, @var{count} will be the numeric
+prefix argument.
+
+The command @code{set-goal-column} can be used to create a semipermanent
+goal column to which this command always moves.  Then it does not try to
+move vertically.
+
+If you are thinking of using this in a Lisp program, consider using
+@code{forward-line} instead.  It is usually easier
+to use and more reliable (no dependence on goal column, etc.).
+@end deffn
+
+@c ================
+@end ignore
+
+  Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
+These functions do not move point, but test whether it is already at the
+beginning or end of a line.
+
+@node Screen Lines
+@subsection Motion by Screen Lines
+
+  The line functions in the previous section count text lines, delimited
+only by newline characters.  By contrast, these functions count screen
+lines, which are defined by the way the text appears on the screen.  A
+text line is a single screen line if it is short enough to fit the width
+of the selected window, but otherwise it may occupy several screen
+lines.
+
+  In some cases, text lines are truncated on the screen rather than
+continued onto additional screen lines.  In these cases,
+@code{vertical-motion} moves point much like @code{forward-line}.
+@xref{Truncation}.
+
+  Because the width of a given string depends on the flags that control
+the appearance of certain characters, @code{vertical-motion} behaves
+differently, for a given piece of text, depending on the buffer it is
+in, and even on the selected window (because the width, the truncation
+flag, and display table may vary between windows).  @xref{Usual
+Display}.
+
+  These functions scan text to determine where screen lines break, and
+thus take time proportional to the distance scanned.  If you intend to
+use them heavily, Emacs provides caches which may improve the
+performance of your code.  @xref{Truncation, cache-long-line-scans}.
+
+@defun vertical-motion count &optional window
+This function moves point to the start of the screen line @var{count}
+screen lines down from the screen line containing point.  If @var{count}
+is negative, it moves up instead.
+
+@code{vertical-motion} returns the number of screen lines over which it
+moved point.  The value may be less in absolute value than @var{count}
+if the beginning or end of the buffer was reached.
+
+The window @var{window} is used for obtaining parameters such as the
+width, the horizontal scrolling, and the display table.  But
+@code{vertical-motion} always operates on the current buffer, even if
+@var{window} currently displays some other buffer.
+@end defun
+
+@defun count-screen-lines &optional beg end count-final-newline window
+This function returns the number of screen lines in the text from
+@var{beg} to @var{end}.  The number of screen lines may be different
+from the number of actual lines, due to line continuation, the display
+table, etc.  If @var{beg} and @var{end} are @code{nil} or omitted,
+they default to the beginning and end of the accessible portion of the
+buffer.
+
+If the region ends with a newline, that is ignored unless the optional
+third argument @var{count-final-newline} is non-@code{nil}.
+
+The optional fourth argument @var{window} specifies the window for
+obtaining parameters such as width, horizontal scrolling, and so on.
+The default is to use the selected window's parameters.
+
+Like @code{vertical-motion}, @code{count-screen-lines} always uses the
+current buffer, regardless of which buffer is displayed in
+@var{window}.  This makes possible to use @code{count-screen-lines} in
+any buffer, whether or not it is currently displayed in some window.
+@end defun
+
+@deffn Command move-to-window-line count
+This function moves point with respect to the text currently displayed
+in the selected window.  It moves point to the beginning of the screen
+line @var{count} screen lines from the top of the window.  If
+@var{count} is negative, that specifies a position
+@w{@minus{}@var{count}} lines from the bottom (or the last line of the
+buffer, if the buffer ends above the specified screen position).
+
+If @var{count} is @code{nil}, then point moves to the beginning of the
+line in the middle of the window.  If the absolute value of @var{count}
+is greater than the size of the window, then point moves to the place
+that would appear on that screen line if the window were tall enough.
+This will probably cause the next redisplay to scroll to bring that
+location onto the screen.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+
+The value returned is the window line number point has moved to, with
+the top line in the window numbered 0.
+@end deffn
+
+@defun compute-motion from frompos to topos width offsets window
+This function scans the current buffer, calculating screen positions.
+It scans the buffer forward from position @var{from}, assuming that is
+at screen coordinates @var{frompos}, to position @var{to} or coordinates
+@var{topos}, whichever comes first.  It returns the ending buffer
+position and screen coordinates.
+
+The coordinate arguments @var{frompos} and @var{topos} are cons cells of
+the form @code{(@var{hpos} . @var{vpos})}.
+
+The argument @var{width} is the number of columns available to display
+text; this affects handling of continuation lines.  @code{nil} means
+the actual number of usable text columns in the window, which is
+equivalent to the value returned by @code{(window-width window)}.
+
+The argument @var{offsets} is either @code{nil} or a cons cell of the
+form @code{(@var{hscroll} . @var{tab-offset})}.  Here @var{hscroll} is
+the number of columns not being displayed at the left margin; most
+callers get this by calling @code{window-hscroll}.  Meanwhile,
+@var{tab-offset} is the offset between column numbers on the screen and
+column numbers in the buffer.  This can be nonzero in a continuation
+line, when the previous screen lines' widths do not add up to a multiple
+of @code{tab-width}.  It is always zero in a non-continuation line.
+
+The window @var{window} serves only to specify which display table to
+use.  @code{compute-motion} always operates on the current buffer,
+regardless of what buffer is displayed in @var{window}.
+
+The return value is a list of five elements:
+
+@example
+(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin})
+@end example
+
+@noindent
+Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
+is the vertical screen position, and @var{hpos} is the horizontal screen
+position.
+
+The result @var{prevhpos} is the horizontal position one character back
+from @var{pos}.  The result @var{contin} is @code{t} if the last line
+was continued after (or within) the previous character.
+
+For example, to find the buffer position of column @var{col} of screen line
+@var{line} of a certain window, pass the window's display start location
+as @var{from} and the window's upper-left coordinates as @var{frompos}.
+Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
+the end of the accessible portion of the buffer, and pass @var{line} and
+@var{col} as @var{topos}.  Here's a function that does this:
+
+@example
+(defun coordinates-of-position (col line)
+  (car (compute-motion (window-start)
+                       '(0 . 0)
+                       (point-max)
+                       (cons col line)
+                       (window-width)
+                       (cons (window-hscroll) 0)
+                       (selected-window))))
+@end example
+
+When you use @code{compute-motion} for the minibuffer, you need to use
+@code{minibuffer-prompt-width} to get the horizontal position of the
+beginning of the first screen line.  @xref{Minibuffer Contents}.
+@end defun
+
+@node List Motion
+@comment  node-name,  next,  previous,  up
+@subsection Moving over Balanced Expressions
+@cindex sexp motion
+@cindex Lisp expression motion
+@cindex list motion
+@cindex balanced parenthesis motion
+
+  Here are several functions concerned with balanced-parenthesis
+expressions (also called @dfn{sexps} in connection with moving across
+them in Emacs).  The syntax table controls how these functions interpret
+various characters; see @ref{Syntax Tables}.  @xref{Parsing
+Expressions}, for lower-level primitives for scanning sexps or parts of
+sexps.  For user-level commands, see @ref{Parentheses,, Commands for
+Editing with Parentheses, emacs, The GNU Emacs Manual}.
+
+@deffn Command forward-list &optional arg
+This function moves forward across @var{arg} (default 1) balanced groups of
+parentheses.  (Other syntactic entities such as words or paired string
+quotes are ignored.)
+@end deffn
+
+@deffn Command backward-list &optional arg
+This function moves backward across @var{arg} (default 1) balanced groups of
+parentheses.  (Other syntactic entities such as words or paired string
+quotes are ignored.)
+@end deffn
+
+@deffn Command up-list &optional arg
+This function moves forward out of @var{arg} (default 1) levels of parentheses.
+A negative argument means move backward but still to a less deep spot.
+@end deffn
+
+@deffn Command down-list &optional arg
+This function moves forward into @var{arg} (default 1) levels of
+parentheses.  A negative argument means move backward but still go
+deeper in parentheses (@minus{}@var{arg} levels).
+@end deffn
+
+@deffn Command forward-sexp &optional arg
+This function moves forward across @var{arg} (default 1) balanced expressions.
+Balanced expressions include both those delimited by parentheses and
+other kinds, such as words and string constants.
+@xref{Parsing Expressions}.  For example,
+
+@example
+@group
+---------- Buffer: foo ----------
+(concat@point{} "foo " (car x) y z)
+---------- Buffer: foo ----------
+@end group
+
+@group
+(forward-sexp 3)
+     @result{} nil
+
+---------- Buffer: foo ----------
+(concat "foo " (car x) y@point{} z)
+---------- Buffer: foo ----------
+@end group
+@end example
+@end deffn
+
+@deffn Command backward-sexp &optional arg
+This function moves backward across @var{arg} (default 1) balanced expressions.
+@end deffn
+
+@deffn Command beginning-of-defun &optional arg
+This function moves back to the @var{arg}th beginning of a defun.  If
+@var{arg} is negative, this actually moves forward, but it still moves
+to the beginning of a defun, not to the end of one.  @var{arg} defaults
+to 1.
+@end deffn
+
+@deffn Command end-of-defun &optional arg
+This function moves forward to the @var{arg}th end of a defun.  If
+@var{arg} is negative, this actually moves backward, but it still moves
+to the end of a defun, not to the beginning of one.  @var{arg} defaults
+to 1.
+@end deffn
+
+@defopt defun-prompt-regexp
+If non-@code{nil}, this buffer-local variable holds a regular
+expression that specifies what text can appear before the
+open-parenthesis that starts a defun.  That is to say, a defun begins
+on a line that starts with a match for this regular expression,
+followed by a character with open-parenthesis syntax.
+@end defopt
+
+@defopt open-paren-in-column-0-is-defun-start
+If this variable's value is non-@code{nil}, an open parenthesis in
+column 0 is considered to be the start of a defun.  If it is
+@code{nil}, an open parenthesis in column 0 has no special meaning.
+The default is @code{t}.
+@end defopt
+
+@defvar beginning-of-defun-function
+If non-@code{nil}, this variable holds a function for finding the
+beginning of a defun.  The function @code{beginning-of-defun}
+calls this function instead of using its normal method.
+@end defvar
+
+@defvar end-of-defun-function
+If non-@code{nil}, this variable holds a function for finding the end of
+a defun.  The function @code{end-of-defun} calls this function instead
+of using its normal method.
+@end defvar
+
+@node Skipping Characters
+@comment  node-name,  next,  previous,  up
+@subsection Skipping Characters
+@cindex skipping characters
+
+  The following two functions move point over a specified set of
+characters.  For example, they are often used to skip whitespace.  For
+related functions, see @ref{Motion and Syntax}.
+
+These functions convert the set string to multibyte if the buffer is
+multibyte, and they convert it to unibyte if the buffer is unibyte, as
+the search functions do (@pxref{Searching and Matching}).
+
+@defun skip-chars-forward character-set &optional limit
+This function moves point in the current buffer forward, skipping over a
+given set of characters.  It examines the character following point,
+then advances point if the character matches @var{character-set}.  This
+continues until it reaches a character that does not match.  The
+function returns the number of characters moved over.
+
+The argument @var{character-set} is a string, like the inside of a
+@samp{[@dots{}]} in a regular expression except that @samp{]} does not
+terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.
+Thus, @code{"a-zA-Z"} skips over all letters, stopping before the
+first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before
+the first letter.  See @xref{Regular Expressions}.  Character classes
+can also be used, e.g. @code{"[:alnum:]"}.  See @pxref{Char Classes}.
+
+If @var{limit} is supplied (it must be a number or a marker), it
+specifies the maximum position in the buffer that point can be skipped
+to.  Point will stop at or before @var{limit}.
+
+In the following example, point is initially located directly before the
+@samp{T}.  After the form is evaluated, point is located at the end of
+that line (between the @samp{t} of @samp{hat} and the newline).  The
+function skips all letters and spaces, but not newlines.
+
+@example
+@group
+---------- Buffer: foo ----------
+I read "@point{}The cat in the hat
+comes back" twice.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(skip-chars-forward "a-zA-Z ")
+     @result{} nil
+
+---------- Buffer: foo ----------
+I read "The cat in the hat@point{}
+comes back" twice.
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defun
+
+@defun skip-chars-backward character-set &optional limit
+This function moves point backward, skipping characters that match
+@var{character-set}, until @var{limit}.  It is just like
+@code{skip-chars-forward} except for the direction of motion.
+
+The return value indicates the distance traveled.  It is an integer that
+is zero or less.
+@end defun
+
+@node Excursions
+@section Excursions
+@cindex excursion
+
+  It is often useful to move point ``temporarily'' within a localized
+portion of the program, or to switch buffers temporarily.  This is
+called an @dfn{excursion}, and it is done with the @code{save-excursion}
+special form.  This construct initially remembers the identity of the
+current buffer, and its values of point and the mark, and restores them
+after the completion of the excursion.
+
+  The forms for saving and restoring the configuration of windows are
+described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
+Configurations}).
+
+@defspec save-excursion body@dots{}
+@cindex mark excursion
+@cindex point excursion
+The @code{save-excursion} special form saves the identity of the current
+buffer and the values of point and the mark in it, evaluates
+@var{body}, and finally restores the buffer and its saved values of
+point and the mark.  All three saved values are restored even in case of
+an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
+
+The @code{save-excursion} special form is the standard way to switch
+buffers or move point within one part of a program and avoid affecting
+the rest of the program.  It is used more than 4000 times in the Lisp
+sources of Emacs.
+
+@code{save-excursion} does not save the values of point and the mark for
+other buffers, so changes in other buffers remain in effect after
+@code{save-excursion} exits.
+
+@cindex window excursions
+Likewise, @code{save-excursion} does not restore window-buffer
+correspondences altered by functions such as @code{switch-to-buffer}.
+One way to restore these correspondences, and the selected window, is to
+use @code{save-window-excursion} inside @code{save-excursion}
+(@pxref{Window Configurations}).
+
+The value returned by @code{save-excursion} is the result of the last
+form in @var{body}, or @code{nil} if no body forms were given.
+
+@example
+@group
+(save-excursion @var{forms})
+@equiv{}
+(let ((old-buf (current-buffer))
+      (old-pnt (point-marker))
+@end group
+      (old-mark (copy-marker (mark-marker))))
+  (unwind-protect
+      (progn @var{forms})
+    (set-buffer old-buf)
+@group
+    (goto-char old-pnt)
+    (set-marker (mark-marker) old-mark)))
+@end group
+@end example
+@end defspec
+
+  @strong{Warning:} Ordinary insertion of text adjacent to the saved
+point value relocates the saved value, just as it relocates all markers.
+More precisely, the saved value is a marker with insertion type
+@code{nil}.  @xref{Marker Insertion Types}.  Therefore, when the saved
+point value is restored, it normally comes before the inserted text.
+
+  Although @code{save-excursion} saves the location of the mark, it does
+not prevent functions which modify the buffer from setting
+@code{deactivate-mark}, and thus causing the deactivation of the mark
+after the command finishes.  @xref{The Mark}.
+
+@node Narrowing
+@section Narrowing
+@cindex narrowing
+@cindex restriction (in a buffer)
+@cindex accessible portion (of a buffer)
+
+  @dfn{Narrowing} means limiting the text addressable by Emacs editing
+commands to a limited range of characters in a buffer.  The text that
+remains addressable is called the @dfn{accessible portion} of the
+buffer.
+
+  Narrowing is specified with two buffer positions which become the
+beginning and end of the accessible portion.  For most editing commands
+and most Emacs primitives, these positions replace the values of the
+beginning and end of the buffer.  While narrowing is in effect, no text
+outside the accessible portion is displayed, and point cannot move
+outside the accessible portion.
+
+  Values such as positions or line numbers, which usually count from the
+beginning of the buffer, do so despite narrowing, but the functions
+which use them refuse to operate on text that is inaccessible.
+
+  The commands for saving buffers are unaffected by narrowing; they save
+the entire buffer regardless of any narrowing.
+
+@deffn Command narrow-to-region start end
+This function sets the accessible portion of the current buffer to start
+at @var{start} and end at @var{end}.  Both arguments should be character
+positions.
+
+In an interactive call, @var{start} and @var{end} are set to the bounds
+of the current region (point and the mark, with the smallest first).
+@end deffn
+
+@deffn Command narrow-to-page &optional move-count
+This function sets the accessible portion of the current buffer to
+include just the current page.  An optional first argument
+@var{move-count} non-@code{nil} means to move forward or backward by
+@var{move-count} pages and then narrow to one page.  The variable
+@code{page-delimiter} specifies where pages start and end
+(@pxref{Standard Regexps}).
+
+In an interactive call, @var{move-count} is set to the numeric prefix
+argument.
+@end deffn
+
+@deffn Command widen
+@cindex widening
+This function cancels any narrowing in the current buffer, so that the
+entire contents are accessible.  This is called @dfn{widening}.
+It is equivalent to the following expression:
+
+@example
+(narrow-to-region 1 (1+ (buffer-size)))
+@end example
+@end deffn
+
+@defspec save-restriction body@dots{}
+This special form saves the current bounds of the accessible portion,
+evaluates the @var{body} forms, and finally restores the saved bounds,
+thus restoring the same state of narrowing (or absence thereof) formerly
+in effect.  The state of narrowing is restored even in the event of an
+abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
+Therefore, this construct is a clean way to narrow a buffer temporarily.
+
+The value returned by @code{save-restriction} is that returned by the
+last form in @var{body}, or @code{nil} if no body forms were given.
+
+@c Wordy to avoid overfull hbox.  --rjc 16mar92
+@strong{Caution:} it is easy to make a mistake when using the
+@code{save-restriction} construct.  Read the entire description here
+before you try it.
+
+If @var{body} changes the current buffer, @code{save-restriction} still
+restores the restrictions on the original buffer (the buffer whose
+restrictions it saved from), but it does not restore the identity of the
+current buffer.
+
+@code{save-restriction} does @emph{not} restore point and the mark; use
+@code{save-excursion} for that.  If you use both @code{save-restriction}
+and @code{save-excursion} together, @code{save-excursion} should come
+first (on the outside).  Otherwise, the old point value would be
+restored with temporary narrowing still in effect.  If the old point
+value were outside the limits of the temporary narrowing, this would
+fail to restore it accurately.
+
+Here is a simple example of correct use of @code{save-restriction}:
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the contents of foo
+This is the contents of foo
+This is the contents of foo@point{}
+---------- Buffer: foo ----------
+@end group
+
+@group
+(save-excursion
+  (save-restriction
+    (goto-char 1)
+    (forward-line 2)
+    (narrow-to-region 1 (point))
+    (goto-char (point-min))
+    (replace-string "foo" "bar")))
+
+---------- Buffer: foo ----------
+This is the contents of bar
+This is the contents of bar
+This is the contents of foo@point{}
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defspec
+
+@ignore
+   arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87
+@end ignore
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
new file mode 100644
index 00000000000..f7be990b85e
--- /dev/null
+++ b/doc/lispref/processes.texi
@@ -0,0 +1,2561 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/processes
+@node Processes, Display, Abbrevs, Top
+@chapter Processes
+@cindex child process
+@cindex parent process
+@cindex subprocess
+@cindex process
+
+  In the terminology of operating systems, a @dfn{process} is a space in
+which a program can execute.  Emacs runs in a process.  Emacs Lisp
+programs can invoke other programs in processes of their own.  These are
+called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
+which is their @dfn{parent process}.
+
+  A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
+depending on how it is created.  When you create a synchronous
+subprocess, the Lisp program waits for the subprocess to terminate
+before continuing execution.  When you create an asynchronous
+subprocess, it can run in parallel with the Lisp program.  This kind of
+subprocess is represented within Emacs by a Lisp object which is also
+called a ``process.''  Lisp programs can use this object to communicate
+with the subprocess or to control it.  For example, you can send
+signals, obtain status information, receive output from the process, or
+send input to it.
+
+@defun processp object
+This function returns @code{t} if @var{object} is a process,
+@code{nil} otherwise.
+@end defun
+
+@menu
+* Subprocess Creation::      Functions that start subprocesses.
+* Shell Arguments::          Quoting an argument to pass it to a shell.
+* Synchronous Processes::    Details of using synchronous subprocesses.
+* Asynchronous Processes::   Starting up an asynchronous subprocess.
+* Deleting Processes::       Eliminating an asynchronous subprocess.
+* Process Information::      Accessing run-status and other attributes.
+* Input to Processes::       Sending input to an asynchronous subprocess.
+* Signals to Processes::     Stopping, continuing or interrupting
+                               an asynchronous subprocess.
+* Output from Processes::    Collecting output from an asynchronous subprocess.
+* Sentinels::                Sentinels run when process run-status changes.
+* Query Before Exit::        Whether to query if exiting will kill a process.
+* Transaction Queues::	     Transaction-based communication with subprocesses.
+* Network::                  Opening network connections.
+* Network Servers::          Network servers let Emacs accept net connections.
+* Datagrams::                UDP network connections.
+* Low-Level Network::        Lower-level but more general function
+                               to create connections and servers.
+* Misc Network::             Additional relevant functions for network connections.
+* Byte Packing::             Using bindat to pack and unpack binary data.
+@end menu
+
+@node Subprocess Creation
+@section Functions that Create Subprocesses
+
+  There are three functions that create a new subprocess in which to run
+a program.  One of them, @code{start-process}, creates an asynchronous
+process and returns a process object (@pxref{Asynchronous Processes}).
+The other two, @code{call-process} and @code{call-process-region},
+create a synchronous process and do not return a process object
+(@pxref{Synchronous Processes}).
+
+  Synchronous and asynchronous processes are explained in the following
+sections.  Since the three functions are all called in a similar
+fashion, their common arguments are described here.
+
+@cindex execute program
+@cindex @code{PATH} environment variable
+@cindex @code{HOME} environment variable
+  In all cases, the function's @var{program} argument specifies the
+program to be run.  An error is signaled if the file is not found or
+cannot be executed.  If the file name is relative, the variable
+@code{exec-path} contains a list of directories to search.  Emacs
+initializes @code{exec-path} when it starts up, based on the value of
+the environment variable @code{PATH}.  The standard file name
+constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
+usual in @code{exec-path}, but environment variable substitutions
+(@samp{$HOME}, etc.) are not recognized; use
+@code{substitute-in-file-name} to perform them (@pxref{File Name
+Expansion}).  @code{nil} in this list refers to
+@code{default-directory}.
+
+  Executing a program can also try adding suffixes to the specified
+name:
+
+@defvar exec-suffixes
+This variable is a list of suffixes (strings) to try adding to the
+specified program file name.  The list should include @code{""} if you
+want the name to be tried exactly as specified.  The default value is
+system-dependent.
+@end defvar
+
+  @strong{Please note:} The argument @var{program} contains only the
+name of the program; it may not contain any command-line arguments.  You
+must use @var{args} to provide those.
+
+  Each of the subprocess-creating functions has a @var{buffer-or-name}
+argument which specifies where the standard output from the program will
+go.  It should be a buffer or a buffer name; if it is a buffer name,
+that will create the buffer if it does not already exist.  It can also
+be @code{nil}, which says to discard the output unless a filter function
+handles it.  (@xref{Filter Functions}, and @ref{Read and Print}.)
+Normally, you should avoid having multiple processes send output to the
+same buffer because their output would be intermixed randomly.
+
+@cindex program arguments
+  All three of the subprocess-creating functions have a @code{&rest}
+argument, @var{args}.  The @var{args} must all be strings, and they are
+supplied to @var{program} as separate command line arguments.  Wildcard
+characters and other shell constructs have no special meanings in these
+strings, since the strings are passed directly to the specified program.
+
+  The subprocess gets its current directory from the value of
+@code{default-directory} (@pxref{File Name Expansion}).
+
+@cindex environment variables, subprocesses
+  The subprocess inherits its environment from Emacs, but you can
+specify overrides for it with @code{process-environment}.  @xref{System
+Environment}.
+
+@defvar exec-directory
+@pindex movemail
+The value of this variable is a string, the name of a directory that
+contains programs that come with GNU Emacs, programs intended for Emacs
+to invoke.  The program @code{movemail} is an example of such a program;
+Rmail uses it to fetch new mail from an inbox.
+@end defvar
+
+@defopt exec-path
+The value of this variable is a list of directories to search for
+programs to run in subprocesses.  Each element is either the name of a
+directory (i.e., a string), or @code{nil}, which stands for the default
+directory (which is the value of @code{default-directory}).
+@cindex program directories
+
+The value of @code{exec-path} is used by @code{call-process} and
+@code{start-process} when the @var{program} argument is not an absolute
+file name.
+@end defopt
+
+@node Shell Arguments
+@section Shell Arguments
+@cindex arguments for shell commands
+@cindex shell command arguments
+
+  Lisp programs sometimes need to run a shell and give it a command
+that contains file names that were specified by the user.  These
+programs ought to be able to support any valid file name.  But the shell
+gives special treatment to certain characters, and if these characters
+occur in the file name, they will confuse the shell.  To handle these
+characters, use the function @code{shell-quote-argument}:
+
+@defun shell-quote-argument argument
+This function returns a string which represents, in shell syntax,
+an argument whose actual contents are @var{argument}.  It should
+work reliably to concatenate the return value into a shell command
+and then pass it to a shell for execution.
+
+Precisely what this function does depends on your operating system.  The
+function is designed to work with the syntax of your system's standard
+shell; if you use an unusual shell, you will need to redefine this
+function.
+
+@example
+;; @r{This example shows the behavior on GNU and Unix systems.}
+(shell-quote-argument "foo > bar")
+     @result{} "foo\\ \\>\\ bar"
+
+;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
+(shell-quote-argument "foo > bar")
+     @result{} "\"foo > bar\""
+@end example
+
+Here's an example of using @code{shell-quote-argument} to construct
+a shell command:
+
+@example
+(concat "diff -c "
+        (shell-quote-argument oldfile)
+        " "
+        (shell-quote-argument newfile))
+@end example
+@end defun
+
+@node Synchronous Processes
+@section Creating a Synchronous Process
+@cindex synchronous subprocess
+
+  After a @dfn{synchronous process} is created, Emacs waits for the
+process to terminate before continuing.  Starting Dired on GNU or
+Unix@footnote{On other systems, Emacs uses a Lisp emulation of
+@code{ls}; see @ref{Contents of Directories}.} is an example of this: it
+runs @code{ls} in a synchronous process, then modifies the output
+slightly.  Because the process is synchronous, the entire directory
+listing arrives in the buffer before Emacs tries to do anything with it.
+
+  While Emacs waits for the synchronous subprocess to terminate, the
+user can quit by typing @kbd{C-g}.  The first @kbd{C-g} tries to kill
+the subprocess with a @code{SIGINT} signal; but it waits until the
+subprocess actually terminates before quitting.  If during that time the
+user types another @kbd{C-g}, that kills the subprocess instantly with
+@code{SIGKILL} and quits immediately (except on MS-DOS, where killing
+other processes doesn't work).  @xref{Quitting}.
+
+  The synchronous subprocess functions return an indication of how the
+process terminated.
+
+  The output from a synchronous subprocess is generally decoded using a
+coding system, much like text read from a file.  The input sent to a
+subprocess by @code{call-process-region} is encoded using a coding
+system, much like text written into a file.  @xref{Coding Systems}.
+
+@defun call-process program &optional infile destination display &rest args
+This function calls @var{program} in a separate process and waits for
+it to finish.
+
+The standard input for the process comes from file @var{infile} if
+@var{infile} is not @code{nil}, and from the null device otherwise.
+The argument @var{destination} says where to put the process output.
+Here are the possibilities:
+
+@table @asis
+@item a buffer
+Insert the output in that buffer, before point.  This includes both the
+standard output stream and the standard error stream of the process.
+
+@item a string
+Insert the output in a buffer with that name, before point.
+
+@item @code{t}
+Insert the output in the current buffer, before point.
+
+@item @code{nil}
+Discard the output.
+
+@item 0
+Discard the output, and return @code{nil} immediately without waiting
+for the subprocess to finish.
+
+In this case, the process is not truly synchronous, since it can run in
+parallel with Emacs; but you can think of it as synchronous in that
+Emacs is essentially finished with the subprocess as soon as this
+function returns.
+
+MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
+work there.
+
+@item @code{(@var{real-destination} @var{error-destination})}
+Keep the standard output stream separate from the standard error stream;
+deal with the ordinary output as specified by @var{real-destination},
+and dispose of the error output according to @var{error-destination}.
+If @var{error-destination} is @code{nil}, that means to discard the
+error output, @code{t} means mix it with the ordinary output, and a
+string specifies a file name to redirect error output into.
+
+You can't directly specify a buffer to put the error output in; that is
+too difficult to implement.  But you can achieve this result by sending
+the error output to a temporary file and then inserting the file into a
+buffer.
+@end table
+
+If @var{display} is non-@code{nil}, then @code{call-process} redisplays
+the buffer as output is inserted.  (However, if the coding system chosen
+for decoding output is @code{undecided}, meaning deduce the encoding
+from the actual data, then redisplay sometimes cannot continue once
+non-@acronym{ASCII} characters are encountered.  There are fundamental
+reasons why it is hard to fix this; see @ref{Output from Processes}.)
+
+Otherwise the function @code{call-process} does no redisplay, and the
+results become visible on the screen only when Emacs redisplays that
+buffer in the normal course of events.
+
+The remaining arguments, @var{args}, are strings that specify command
+line arguments for the program.
+
+The value returned by @code{call-process} (unless you told it not to
+wait) indicates the reason for process termination.  A number gives the
+exit status of the subprocess; 0 means success, and any other value
+means failure.  If the process terminated with a signal,
+@code{call-process} returns a string describing the signal.
+
+In the examples below, the buffer @samp{foo} is current.
+
+@smallexample
+@group
+(call-process "pwd" nil t)
+     @result{} 0
+
+---------- Buffer: foo ----------
+/usr/user/lewis/manual
+---------- Buffer: foo ----------
+@end group
+
+@group
+(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
+     @result{} 0
+
+---------- Buffer: bar ----------
+lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+
+---------- Buffer: bar ----------
+@end group
+@end smallexample
+
+Here is a good example of the use of @code{call-process}, which used to
+be found in the definition of @code{insert-directory}:
+
+@smallexample
+@group
+(call-process insert-directory-program nil t nil @var{switches}
+              (if full-directory-p
+                  (concat (file-name-as-directory file) ".")
+                file))
+@end group
+@end smallexample
+@end defun
+
+@defun process-file program &optional infile buffer display &rest args
+This function processes files synchronously in a separate process.  It
+is similar to @code{call-process} but may invoke a file handler based
+on the value of the variable @code{default-directory}.  The current
+working directory of the subprocess is @code{default-directory}.
+
+The arguments are handled in almost the same way as for
+@code{call-process}, with the following differences:
+
+Some file handlers may not support all combinations and forms of the
+arguments @var{infile}, @var{buffer}, and @var{display}.  For example,
+some file handlers might behave as if @var{display} were @code{nil},
+regardless of the value actually passed.  As another example, some
+file handlers might not support separating standard output and error
+output by way of the @var{buffer} argument.
+
+If a file handler is invoked, it determines the program to run based
+on the first argument @var{program}.  For instance, consider that a
+handler for remote files is invoked.  Then the path that is used for
+searching the program might be different than @code{exec-path}.
+
+The second argument @var{infile} may invoke a file handler.  The file
+handler could be different from the handler chosen for the
+@code{process-file} function itself.  (For example,
+@code{default-directory} could be on a remote host, whereas
+@var{infile} is on another remote host.  Or @code{default-directory}
+could be non-special, whereas @var{infile} is on a remote host.)
+
+If @var{buffer} is a list of the form @code{(@var{real-destination}
+@var{error-destination})}, and @var{error-destination} names a file,
+then the same remarks as for @var{infile} apply.
+
+The remaining arguments (@var{args}) will be passed to the process
+verbatim.  Emacs is not involved in processing file names that are
+present in @var{args}.  To avoid confusion, it may be best to avoid
+absolute file names in @var{args}, but rather to specify all file
+names as relative to @code{default-directory}.  The function
+@code{file-relative-name} is useful for constructing such relative
+file names.
+@end defun
+
+@defun call-process-region start end program &optional delete destination display &rest args
+This function sends the text from @var{start} to @var{end} as
+standard input to a process running @var{program}.  It deletes the text
+sent if @var{delete} is non-@code{nil}; this is useful when
+@var{destination} is @code{t}, to insert the output in the current
+buffer in place of the input.
+
+The arguments @var{destination} and @var{display} control what to do
+with the output from the subprocess, and whether to update the display
+as it comes in.  For details, see the description of
+@code{call-process}, above.  If @var{destination} is the integer 0,
+@code{call-process-region} discards the output and returns @code{nil}
+immediately, without waiting for the subprocess to finish (this only
+works if asynchronous subprocesses are supported).
+
+The remaining arguments, @var{args}, are strings that specify command
+line arguments for the program.
+
+The return value of @code{call-process-region} is just like that of
+@code{call-process}: @code{nil} if you told it to return without
+waiting; otherwise, a number or string which indicates how the
+subprocess terminated.
+
+In the following example, we use @code{call-process-region} to run the
+@code{cat} utility, with standard input being the first five characters
+in buffer @samp{foo} (the word @samp{input}).  @code{cat} copies its
+standard input into its standard output.  Since the argument
+@var{destination} is @code{t}, this output is inserted in the current
+buffer.
+
+@smallexample
+@group
+---------- Buffer: foo ----------
+input@point{}
+---------- Buffer: foo ----------
+@end group
+
+@group
+(call-process-region 1 6 "cat" nil t)
+     @result{} 0
+
+---------- Buffer: foo ----------
+inputinput@point{}
+---------- Buffer: foo ----------
+@end group
+@end smallexample
+
+  The @code{shell-command-on-region} command uses
+@code{call-process-region} like this:
+
+@smallexample
+@group
+(call-process-region
+ start end
+ shell-file-name      ; @r{Name of program.}
+ nil                  ; @r{Do not delete region.}
+ buffer               ; @r{Send output to @code{buffer}.}
+ nil                  ; @r{No redisplay during output.}
+ "-c" command)        ; @r{Arguments for the shell.}
+@end group
+@end smallexample
+@end defun
+
+@defun call-process-shell-command command &optional infile destination display &rest args
+This function executes the shell command @var{command} synchronously
+in a separate process.  The final arguments @var{args} are additional
+arguments to add at the end of @var{command}.  The other arguments
+are handled as in @code{call-process}.
+@end defun
+
+@defun process-file-shell-command command &optional infile destination display &rest args
+This function is like @code{call-process-shell-command}, but uses
+@code{process-file} internally.  Depending on @code{default-directory},
+@var{command} can be executed also on remote hosts.
+@end defun
+
+@defun shell-command-to-string command
+This function executes @var{command} (a string) as a shell command,
+then returns the command's output as a string.
+@end defun
+
+@node Asynchronous Processes
+@section Creating an Asynchronous Process
+@cindex asynchronous subprocess
+
+  After an @dfn{asynchronous process} is created, Emacs and the subprocess
+both continue running immediately.  The process thereafter runs
+in parallel with Emacs, and the two can communicate with each other
+using the functions described in the following sections.  However,
+communication is only partially asynchronous: Emacs sends data to the
+process only when certain functions are called, and Emacs accepts data
+from the process only when Emacs is waiting for input or for a time
+delay.
+
+  Here we describe how to create an asynchronous process.
+
+@defun start-process name buffer-or-name program &rest args
+This function creates a new asynchronous subprocess and starts the
+program @var{program} running in it.  It returns a process object that
+stands for the new subprocess in Lisp.  The argument @var{name}
+specifies the name for the process object; if a process with this name
+already exists, then @var{name} is modified (by appending @samp{<1>},
+etc.) to be unique.  The buffer @var{buffer-or-name} is the buffer to
+associate with the process.
+
+The remaining arguments, @var{args}, are strings that specify command
+line arguments for the program.
+
+In the example below, the first process is started and runs (rather,
+sleeps) for 100 seconds.  Meanwhile, the second process is started, and
+given the name @samp{my-process<1>} for the sake of uniqueness.  It
+inserts the directory listing at the end of the buffer @samp{foo},
+before the first process finishes.  Then it finishes, and a message to
+that effect is inserted in the buffer.  Much later, the first process
+finishes, and another message is inserted in the buffer for it.
+
+@smallexample
+@group
+(start-process "my-process" "foo" "sleep" "100")
+     @result{} #<process my-process>
+@end group
+
+@group
+(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+     @result{} #<process my-process<1>>
+
+---------- Buffer: foo ----------
+total 2
+lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
+-rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon
+
+Process my-process<1> finished
+
+Process my-process finished
+---------- Buffer: foo ----------
+@end group
+@end smallexample
+@end defun
+
+@defun start-file-process name buffer-or-name program &rest args
+Like @code{start-process}, this function starts a new asynchronous
+subprocess running @var{program} in it, and returns its process
+object---when @code{default-directory} is not a magic file name.
+
+If @code{default-directory} is magic, the function invokes its file
+handler instead.  This handler ought to run @var{program}, perhaps on
+the local host, perhaps on a remote host that corresponds to
+@code{default-directory}.  In the latter case, the local part of
+@code{default-directory} becomes the working directory of the process.
+
+This function does not try to invoke file name handlers for
+@var{program} or for the @var{program-args}.
+
+Depending on the implementation of the file handler, it might not be
+possible to apply @code{process-filter} or @code{process-sentinel} to
+the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}).
+
+Some file handlers may not support @code{start-file-process} (for
+example @code{ange-ftp-hook-function}).  In such cases, the function
+does nothing and returns @code{nil}.
+@end defun
+
+@defun start-process-shell-command name buffer-or-name command &rest command-args
+This function is like @code{start-process} except that it uses a shell
+to execute the specified command.  The argument @var{command} is a shell
+command name, and @var{command-args} are the arguments for the shell
+command.  The variable @code{shell-file-name} specifies which shell to
+use.
+
+The point of running a program through the shell, rather than directly
+with @code{start-process}, is so that you can employ shell features such
+as wildcards in the arguments.  It follows that if you include an
+arbitrary user-specified arguments in the command, you should quote it
+with @code{shell-quote-argument} first, so that any special shell
+characters do @emph{not} have their special shell meanings.  @xref{Shell
+Arguments}.
+@end defun
+
+@defun start-file-process-shell-command name buffer-or-name command &rest command-args
+This function is like @code{start-process-shell-command}, but uses
+@code{start-file-process} internally.  By this, @var{command} can be
+executed also on remote hosts, depending on @code{default-directory}.
+@end defun
+
+@defvar process-connection-type
+@cindex pipes
+@cindex @acronym{PTY}s
+This variable controls the type of device used to communicate with
+asynchronous subprocesses.  If it is non-@code{nil}, then @acronym{PTY}s are
+used, when available.  Otherwise, pipes are used.
+
+@acronym{PTY}s are usually preferable for processes visible to the user, as
+in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
+etc.) to work between the process and its children, whereas pipes do
+not.  For subprocesses used for internal purposes by programs, it is
+often better to use a pipe, because they are more efficient.  In
+addition, the total number of @acronym{PTY}s is limited on many systems and
+it is good not to waste them.
+
+The value of @code{process-connection-type} takes effect when
+@code{start-process} is called.  So you can specify how to communicate
+with one subprocess by binding the variable around the call to
+@code{start-process}.
+
+@smallexample
+@group
+(let ((process-connection-type nil))  ; @r{Use a pipe.}
+  (start-process @dots{}))
+@end group
+@end smallexample
+
+To determine whether a given subprocess actually got a pipe or a
+@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
+Information}).
+@end defvar
+
+@node Deleting Processes
+@section Deleting Processes
+@cindex deleting processes
+
+  @dfn{Deleting a process} disconnects Emacs immediately from the
+subprocess.  Processes are deleted automatically after they terminate,
+but not necessarily right away.  You can delete a process explicitly
+at any time.  If you delete a terminated process explicitly before it
+is deleted automatically, no harm results.  Deleting a running
+process sends a signal to terminate it (and its child processes if
+any), and calls the process sentinel if it has one.  @xref{Sentinels}.
+
+  When a process is deleted, the process object itself continues to
+exist as long as other Lisp objects point to it.  All the Lisp
+primitives that work on process objects accept deleted processes, but
+those that do I/O or send signals will report an error.  The process
+mark continues to point to the same place as before, usually into a
+buffer where output from the process was being inserted.
+
+@defopt delete-exited-processes
+This variable controls automatic deletion of processes that have
+terminated (due to calling @code{exit} or to a signal).  If it is
+@code{nil}, then they continue to exist until the user runs
+@code{list-processes}.  Otherwise, they are deleted immediately after
+they exit.
+@end defopt
+
+@defun delete-process process
+This function deletes a process, killing it with a @code{SIGKILL}
+signal.  The argument may be a process, the name of a process, a
+buffer, or the name of a buffer.  (A buffer or buffer-name stands for
+the process that @code{get-buffer-process} returns.)  Calling
+@code{delete-process} on a running process terminates it, updates the
+process status, and runs the sentinel (if any) immediately.  If the
+process has already terminated, calling @code{delete-process} has no
+effect on its status, or on the running of its sentinel (which will
+happen sooner or later).
+
+@smallexample
+@group
+(delete-process "*shell*")
+     @result{} nil
+@end group
+@end smallexample
+@end defun
+
+@node Process Information
+@section Process Information
+
+  Several functions return information about processes.
+@code{list-processes} is provided for interactive use.
+
+@deffn Command list-processes &optional query-only
+This command displays a listing of all living processes.  In addition,
+it finally deletes any process whose status was @samp{Exited} or
+@samp{Signaled}.  It returns @code{nil}.
+
+If @var{query-only} is non-@code{nil} then it lists only processes
+whose query flag is non-@code{nil}.  @xref{Query Before Exit}.
+@end deffn
+
+@defun process-list
+This function returns a list of all processes that have not been deleted.
+
+@smallexample
+@group
+(process-list)
+     @result{} (#<process display-time> #<process shell>)
+@end group
+@end smallexample
+@end defun
+
+@defun get-process name
+This function returns the process named @var{name}, or @code{nil} if
+there is none.  An error is signaled if @var{name} is not a string.
+
+@smallexample
+@group
+(get-process "shell")
+     @result{} #<process shell>
+@end group
+@end smallexample
+@end defun
+
+@defun process-command process
+This function returns the command that was executed to start
+@var{process}.  This is a list of strings, the first string being the
+program executed and the rest of the strings being the arguments that
+were given to the program.
+
+@smallexample
+@group
+(process-command (get-process "shell"))
+     @result{} ("/bin/csh" "-i")
+@end group
+@end smallexample
+@end defun
+
+@defun process-id process
+This function returns the @acronym{PID} of @var{process}.  This is an
+integer that distinguishes the process @var{process} from all other
+processes running on the same computer at the current time.  The
+@acronym{PID} of a process is chosen by the operating system kernel when the
+process is started and remains constant as long as the process exists.
+@end defun
+
+@defun process-name process
+This function returns the name of @var{process}.
+@end defun
+
+@defun process-status process-name
+This function returns the status of @var{process-name} as a symbol.
+The argument @var{process-name} must be a process, a buffer, a
+process name (string) or a buffer name (string).
+
+The possible values for an actual subprocess are:
+
+@table @code
+@item run
+for a process that is running.
+@item stop
+for a process that is stopped but continuable.
+@item exit
+for a process that has exited.
+@item signal
+for a process that has received a fatal signal.
+@item open
+for a network connection that is open.
+@item closed
+for a network connection that is closed.  Once a connection
+is closed, you cannot reopen it, though you might be able to open
+a new connection to the same place.
+@item connect
+for a non-blocking connection that is waiting to complete.
+@item failed
+for a non-blocking connection that has failed to complete.
+@item listen
+for a network server that is listening.
+@item nil
+if @var{process-name} is not the name of an existing process.
+@end table
+
+@smallexample
+@group
+(process-status "shell")
+     @result{} run
+@end group
+@group
+(process-status (get-buffer "*shell*"))
+     @result{} run
+@end group
+@group
+x
+     @result{} #<process xx<1>>
+(process-status x)
+     @result{} exit
+@end group
+@end smallexample
+
+For a network connection, @code{process-status} returns one of the symbols
+@code{open} or @code{closed}.  The latter means that the other side
+closed the connection, or Emacs did @code{delete-process}.
+@end defun
+
+@defun process-exit-status process
+This function returns the exit status of @var{process} or the signal
+number that killed it.  (Use the result of @code{process-status} to
+determine which of those it is.)  If @var{process} has not yet
+terminated, the value is 0.
+@end defun
+
+@defun process-tty-name process
+This function returns the terminal name that @var{process} is using for
+its communication with Emacs---or @code{nil} if it is using pipes
+instead of a terminal (see @code{process-connection-type} in
+@ref{Asynchronous Processes}).
+@end defun
+
+@defun process-coding-system process
+@anchor{Coding systems for a subprocess}
+This function returns a cons cell describing the coding systems in use
+for decoding output from @var{process} and for encoding input to
+@var{process} (@pxref{Coding Systems}).  The value has this form:
+
+@example
+(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
+@end example
+@end defun
+
+@defun set-process-coding-system process &optional decoding-system encoding-system
+This function specifies the coding systems to use for subsequent output
+from and input to @var{process}.  It will use @var{decoding-system} to
+decode subprocess output, and @var{encoding-system} to encode subprocess
+input.
+@end defun
+
+  Every process also has a property list that you can use to store
+miscellaneous values associated with the process.
+
+@defun process-get process propname
+This function returns the value of the @var{propname} property
+of @var{process}.
+@end defun
+
+@defun process-put process propname value
+This function sets the value of the @var{propname} property
+of @var{process} to @var{value}.
+@end defun
+
+@defun process-plist process
+This function returns the process plist of @var{process}.
+@end defun
+
+@defun set-process-plist process plist
+This function sets the process plist of @var{process} to @var{plist}.
+@end defun
+
+@node Input to Processes
+@section Sending Input to Processes
+@cindex process input
+
+  Asynchronous subprocesses receive input when it is sent to them by
+Emacs, which is done with the functions in this section.  You must
+specify the process to send input to, and the input data to send.  The
+data appears on the ``standard input'' of the subprocess.
+
+  Some operating systems have limited space for buffered input in a
+@acronym{PTY}.  On these systems, Emacs sends an @acronym{EOF}
+periodically amidst the other characters, to force them through.  For
+most programs, these @acronym{EOF}s do no harm.
+
+  Subprocess input is normally encoded using a coding system before the
+subprocess receives it, much like text written into a file.  You can use
+@code{set-process-coding-system} to specify which coding system to use
+(@pxref{Process Information}).  Otherwise, the coding system comes from
+@code{coding-system-for-write}, if that is non-@code{nil}; or else from
+the defaulting mechanism (@pxref{Default Coding Systems}).
+
+  Sometimes the system is unable to accept input for that process,
+because the input buffer is full.  When this happens, the send functions
+wait a short while, accepting output from subprocesses, and then try
+again.  This gives the subprocess a chance to read more of its pending
+input and make space in the buffer.  It also allows filters, sentinels
+and timers to run---so take account of that in writing your code.
+
+  In these functions, the @var{process} argument can be a process or
+the name of a process, or a buffer or buffer name (which stands
+for a process via @code{get-buffer-process}).  @code{nil} means
+the current buffer's process.
+
+@defun process-send-string process string
+This function sends @var{process} the contents of @var{string} as
+standard input.  If it is @code{nil}, the current buffer's process is used.
+
+  The function returns @code{nil}.
+
+@smallexample
+@group
+(process-send-string "shell<1>" "ls\n")
+     @result{} nil
+@end group
+
+
+@group
+---------- Buffer: *shell* ----------
+...
+introduction.texi               syntax-tables.texi~
+introduction.texi~              text.texi
+introduction.txt                text.texi~
+...
+---------- Buffer: *shell* ----------
+@end group
+@end smallexample
+@end defun
+
+@defun process-send-region process start end
+This function sends the text in the region defined by @var{start} and
+@var{end} as standard input to @var{process}.
+
+An error is signaled unless both @var{start} and @var{end} are
+integers or markers that indicate positions in the current buffer.  (It
+is unimportant which number is larger.)
+@end defun
+
+@defun process-send-eof &optional process
+This function makes @var{process} see an end-of-file in its
+input.  The @acronym{EOF} comes after any text already sent to it.
+
+The function returns @var{process}.
+
+@smallexample
+@group
+(process-send-eof "shell")
+     @result{} "shell"
+@end group
+@end smallexample
+@end defun
+
+@defun process-running-child-p process
+This function will tell you whether a subprocess has given control of
+its terminal to its own child process.  The value is @code{t} if this is
+true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
+that this is not so.
+@end defun
+
+@node Signals to Processes
+@section Sending Signals to Processes
+@cindex process signals
+@cindex sending signals
+@cindex signals
+
+  @dfn{Sending a signal} to a subprocess is a way of interrupting its
+activities.  There are several different signals, each with its own
+meaning.  The set of signals and their names is defined by the operating
+system.  For example, the signal @code{SIGINT} means that the user has
+typed @kbd{C-c}, or that some analogous thing has happened.
+
+  Each signal has a standard effect on the subprocess.  Most signals
+kill the subprocess, but some stop or resume execution instead.  Most
+signals can optionally be handled by programs; if the program handles
+the signal, then we can say nothing in general about its effects.
+
+  You can send signals explicitly by calling the functions in this
+section.  Emacs also sends signals automatically at certain times:
+killing a buffer sends a @code{SIGHUP} signal to all its associated
+processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
+processes.  (@code{SIGHUP} is a signal that usually indicates that the
+user hung up the phone.)
+
+  Each of the signal-sending functions takes two optional arguments:
+@var{process} and @var{current-group}.
+
+  The argument @var{process} must be either a process, a process
+name, a buffer, a buffer name, or @code{nil}.  A buffer or buffer name
+stands for a process through @code{get-buffer-process}.  @code{nil}
+stands for the process associated with the current buffer.  An error
+is signaled if @var{process} does not identify a process.
+
+  The argument @var{current-group} is a flag that makes a difference
+when you are running a job-control shell as an Emacs subprocess.  If it
+is non-@code{nil}, then the signal is sent to the current process-group
+of the terminal that Emacs uses to communicate with the subprocess.  If
+the process is a job-control shell, this means the shell's current
+subjob.  If it is @code{nil}, the signal is sent to the process group of
+the immediate subprocess of Emacs.  If the subprocess is a job-control
+shell, this is the shell itself.
+
+  The flag @var{current-group} has no effect when a pipe is used to
+communicate with the subprocess, because the operating system does not
+support the distinction in the case of pipes.  For the same reason,
+job-control shells won't work when a pipe is used.  See
+@code{process-connection-type} in @ref{Asynchronous Processes}.
+
+@defun interrupt-process &optional process current-group
+This function interrupts the process @var{process} by sending the
+signal @code{SIGINT}.  Outside of Emacs, typing the ``interrupt
+character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
+others) sends this signal.  When the argument @var{current-group} is
+non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
+on the terminal by which Emacs talks to the subprocess.
+@end defun
+
+@defun kill-process &optional process current-group
+This function kills the process @var{process} by sending the
+signal @code{SIGKILL}.  This signal kills the subprocess immediately,
+and cannot be handled by the subprocess.
+@end defun
+
+@defun quit-process &optional process current-group
+This function sends the signal @code{SIGQUIT} to the process
+@var{process}.  This signal is the one sent by the ``quit
+character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
+Emacs.
+@end defun
+
+@defun stop-process &optional process current-group
+This function stops the process @var{process} by sending the
+signal @code{SIGTSTP}.  Use @code{continue-process} to resume its
+execution.
+
+Outside of Emacs, on systems with job control, the ``stop character''
+(usually @kbd{C-z}) normally sends this signal.  When
+@var{current-group} is non-@code{nil}, you can think of this function as
+``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
+subprocess.
+@end defun
+
+@defun continue-process &optional process current-group
+This function resumes execution of the process @var{process} by sending
+it the signal @code{SIGCONT}.  This presumes that @var{process} was
+stopped previously.
+@end defun
+
+@c Emacs 19 feature
+@defun signal-process process signal
+This function sends a signal to process @var{process}.  The argument
+@var{signal} specifies which signal to send; it should be an integer.
+
+The @var{process} argument can be a system process @acronym{ID}; that
+allows you to send signals to processes that are not children of
+Emacs.
+@end defun
+
+@node Output from Processes
+@section Receiving Output from Processes
+@cindex process output
+@cindex output from processes
+
+  There are two ways to receive the output that a subprocess writes to
+its standard output stream.  The output can be inserted in a buffer,
+which is called the associated buffer of the process, or a function
+called the @dfn{filter function} can be called to act on the output.  If
+the process has no buffer and no filter function, its output is
+discarded.
+
+  When a subprocess terminates, Emacs reads any pending output,
+then stops reading output from that subprocess.  Therefore, if the
+subprocess has children that are still live and still producing
+output, Emacs won't receive that output.
+
+  Output from a subprocess can arrive only while Emacs is waiting: when
+reading terminal input, in @code{sit-for} and @code{sleep-for}
+(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
+Output}).  This minimizes the problem of timing errors that usually
+plague parallel programming.  For example, you can safely create a
+process and only then specify its buffer or filter function; no output
+can arrive before you finish, if the code in between does not call any
+primitive that waits.
+
+@defvar process-adaptive-read-buffering
+On some systems, when Emacs reads the output from a subprocess, the
+output data is read in very small blocks, potentially resulting in
+very poor performance.  This behavior can be remedied to some extent
+by setting the variable @var{process-adaptive-read-buffering} to a
+non-@code{nil} value (the default), as it will automatically delay reading
+from such processes, thus allowing them to produce more output before
+Emacs tries to read it.
+@end defvar
+
+  It is impossible to separate the standard output and standard error
+streams of the subprocess, because Emacs normally spawns the subprocess
+inside a pseudo-TTY, and a pseudo-TTY has only one output channel.  If
+you want to keep the output to those streams separate, you should
+redirect one of them to a file---for example, by using an appropriate
+shell command.
+
+@menu
+* Process Buffers::         If no filter, output is put in a buffer.
+* Filter Functions::        Filter functions accept output from the process.
+* Decoding Output::         Filters can get unibyte or multibyte strings.
+* Accepting Output::        How to wait until process output arrives.
+@end menu
+
+@node Process Buffers
+@subsection Process Buffers
+
+  A process can (and usually does) have an @dfn{associated buffer},
+which is an ordinary Emacs buffer that is used for two purposes: storing
+the output from the process, and deciding when to kill the process.  You
+can also use the buffer to identify a process to operate on, since in
+normal practice only one process is associated with any given buffer.
+Many applications of processes also use the buffer for editing input to
+be sent to the process, but this is not built into Emacs Lisp.
+
+  Unless the process has a filter function (@pxref{Filter Functions}),
+its output is inserted in the associated buffer.  The position to insert
+the output is determined by the @code{process-mark}, which is then
+updated to point to the end of the text just inserted.  Usually, but not
+always, the @code{process-mark} is at the end of the buffer.
+
+@defun process-buffer process
+This function returns the associated buffer of the process
+@var{process}.
+
+@smallexample
+@group
+(process-buffer (get-process "shell"))
+     @result{} #<buffer *shell*>
+@end group
+@end smallexample
+@end defun
+
+@defun process-mark process
+This function returns the process marker for @var{process}, which is the
+marker that says where to insert output from the process.
+
+If @var{process} does not have a buffer, @code{process-mark} returns a
+marker that points nowhere.
+
+Insertion of process output in a buffer uses this marker to decide where
+to insert, and updates it to point after the inserted text.  That is why
+successive batches of output are inserted consecutively.
+
+Filter functions normally should use this marker in the same fashion
+as is done by direct insertion of output in the buffer.  A good
+example of a filter function that uses @code{process-mark} is found at
+the end of the following section.
+
+When the user is expected to enter input in the process buffer for
+transmission to the process, the process marker separates the new input
+from previous output.
+@end defun
+
+@defun set-process-buffer process buffer
+This function sets the buffer associated with @var{process} to
+@var{buffer}.  If @var{buffer} is @code{nil}, the process becomes
+associated with no buffer.
+@end defun
+
+@defun get-buffer-process buffer-or-name
+This function returns a nondeleted process associated with the buffer
+specified by @var{buffer-or-name}.  If there are several processes
+associated with it, this function chooses one (currently, the one most
+recently created, but don't count on that).  Deletion of a process
+(see @code{delete-process}) makes it ineligible for this function to
+return.
+
+It is usually a bad idea to have more than one process associated with
+the same buffer.
+
+@smallexample
+@group
+(get-buffer-process "*shell*")
+     @result{} #<process shell>
+@end group
+@end smallexample
+
+Killing the process's buffer deletes the process, which kills the
+subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
+@end defun
+
+@node Filter Functions
+@subsection Process Filter Functions
+@cindex filter function
+@cindex process filter
+
+  A process @dfn{filter function} is a function that receives the
+standard output from the associated process.  If a process has a filter,
+then @emph{all} output from that process is passed to the filter.  The
+process buffer is used directly for output from the process only when
+there is no filter.
+
+  The filter function can only be called when Emacs is waiting for
+something, because process output arrives only at such times.  Emacs
+waits when reading terminal input, in @code{sit-for} and
+@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
+(@pxref{Accepting Output}).
+
+  A filter function must accept two arguments: the associated process
+and a string, which is output just received from it.  The function is
+then free to do whatever it chooses with the output.
+
+  Quitting is normally inhibited within a filter function---otherwise,
+the effect of typing @kbd{C-g} at command level or to quit a user
+command would be unpredictable.  If you want to permit quitting inside
+a filter function, bind @code{inhibit-quit} to @code{nil}.  In most
+cases, the right way to do this is with the macro
+@code{with-local-quit}.  @xref{Quitting}.
+
+  If an error happens during execution of a filter function, it is
+caught automatically, so that it doesn't stop the execution of whatever
+program was running when the filter function was started.  However, if
+@code{debug-on-error} is non-@code{nil}, the error-catching is turned
+off.  This makes it possible to use the Lisp debugger to debug the
+filter function.  @xref{Debugger}.
+
+  Many filter functions sometimes or always insert the text in the
+process's buffer, mimicking the actions of Emacs when there is no
+filter.  Such filter functions need to use @code{set-buffer} in order to
+be sure to insert in that buffer.  To avoid setting the current buffer
+semipermanently, these filter functions must save and restore the
+current buffer.  They should also update the process marker, and in some
+cases update the value of point.  Here is how to do these things:
+
+@smallexample
+@group
+(defun ordinary-insertion-filter (proc string)
+  (with-current-buffer (process-buffer proc)
+    (let ((moving (= (point) (process-mark proc))))
+@end group
+@group
+      (save-excursion
+        ;; @r{Insert the text, advancing the process marker.}
+        (goto-char (process-mark proc))
+        (insert string)
+        (set-marker (process-mark proc) (point)))
+      (if moving (goto-char (process-mark proc))))))
+@end group
+@end smallexample
+
+@noindent
+The reason to use @code{with-current-buffer}, rather than using
+@code{save-excursion} to save and restore the current buffer, is so as
+to preserve the change in point made by the second call to
+@code{goto-char}.
+
+  To make the filter force the process buffer to be visible whenever new
+text arrives, insert the following line just before the
+@code{with-current-buffer} construct:
+
+@smallexample
+(display-buffer (process-buffer proc))
+@end smallexample
+
+  To force point to the end of the new output, no matter where it was
+previously, eliminate the variable @code{moving} and call
+@code{goto-char} unconditionally.
+
+  In earlier Emacs versions, every filter function that did regular
+expression searching or matching had to explicitly save and restore the
+match data.  Now Emacs does this automatically for filter functions;
+they never need to do it explicitly.  @xref{Match Data}.
+
+  A filter function that writes the output into the buffer of the
+process should check whether the buffer is still alive.  If it tries to
+insert into a dead buffer, it will get an error.  The expression
+@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
+if the buffer is dead.
+
+  The output to the function may come in chunks of any size.  A program
+that produces the same output twice in a row may send it as one batch of
+200 characters one time, and five batches of 40 characters the next.  If
+the filter looks for certain text strings in the subprocess output, make
+sure to handle the case where one of these strings is split across two
+or more batches of output.
+
+@defun set-process-filter process filter
+This function gives @var{process} the filter function @var{filter}.  If
+@var{filter} is @code{nil}, it gives the process no filter.
+@end defun
+
+@defun process-filter process
+This function returns the filter function of @var{process}, or @code{nil}
+if it has none.
+@end defun
+
+  Here is an example of use of a filter function:
+
+@smallexample
+@group
+(defun keep-output (process output)
+   (setq kept (cons output kept)))
+     @result{} keep-output
+@end group
+@group
+(setq kept nil)
+     @result{} nil
+@end group
+@group
+(set-process-filter (get-process "shell") 'keep-output)
+     @result{} keep-output
+@end group
+@group
+(process-send-string "shell" "ls ~/other\n")
+     @result{} nil
+kept
+     @result{} ("lewis@@slug[8] % "
+@end group
+@group
+"FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
+address.txt             backup.psf              kolstad.psf
+backup.bib~             david.mss               resume-Dec-86.mss~
+backup.err              david.psf               resume-Dec.psf
+backup.mss              dland                   syllabus.mss
+"
+"#backups.mss#          backup.mss~             kolstad.mss
+")
+@end group
+@end smallexample
+
+@ignore   @c The code in this example doesn't show the right way to do things.
+Here is another, more realistic example, which demonstrates how to use
+the process mark to do insertion in the same fashion as is done when
+there is no filter function:
+
+@smallexample
+@group
+;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
+;;   @r{and make sure that buffer is shown in some window.}
+(defun my-process-filter (proc str)
+  (let ((cur (selected-window))
+        (pop-up-windows t))
+    (pop-to-buffer my-shell-buffer)
+@end group
+@group
+    (goto-char (point-max))
+    (insert str)
+    (set-marker (process-mark proc) (point-max))
+    (select-window cur)))
+@end group
+@end smallexample
+@end ignore
+
+@node Decoding Output
+@subsection Decoding Process Output
+@cindex decode process output
+
+  When Emacs writes process output directly into a multibyte buffer,
+it decodes the output according to the process output coding system.
+If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
+converts the unibyte output to multibyte using
+@code{string-to-multibyte}, and inserts the resulting multibyte text.
+
+  You can use @code{set-process-coding-system} to specify which coding
+system to use (@pxref{Process Information}).  Otherwise, the coding
+system comes from @code{coding-system-for-read}, if that is
+non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
+Coding Systems}).
+
+  @strong{Warning:} Coding systems such as @code{undecided} which
+determine the coding system from the data do not work entirely
+reliably with asynchronous subprocess output.  This is because Emacs
+has to process asynchronous subprocess output in batches, as it
+arrives.  Emacs must try to detect the proper coding system from one
+batch at a time, and this does not always work.  Therefore, if at all
+possible, specify a coding system that determines both the character
+code conversion and the end of line conversion---that is, one like
+@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
+
+@cindex filter multibyte flag, of process
+@cindex process filter multibyte flag
+  When Emacs calls a process filter function, it provides the process
+output as a multibyte string or as a unibyte string according to the
+process's filter multibyte flag.  If the flag is non-@code{nil}, Emacs
+decodes the output according to the process output coding system to
+produce a multibyte string, and passes that to the process.  If the
+flag is @code{nil}, Emacs puts the output into a unibyte string, with
+no decoding, and passes that.
+
+  When you create a process, the filter multibyte flag takes its
+initial value from @code{default-enable-multibyte-characters}.  If you
+want to change the flag later on, use
+@code{set-process-filter-multibyte}.
+
+@defun set-process-filter-multibyte process multibyte
+This function sets the filter multibyte flag of @var{process}
+to @var{multibyte}.
+@end defun
+
+@defun process-filter-multibyte-p process
+This function returns the filter multibyte flag of @var{process}.
+@end defun
+
+@node Accepting Output
+@subsection Accepting Output from Processes
+@cindex accept input from processes
+
+  Output from asynchronous subprocesses normally arrives only while
+Emacs is waiting for some sort of external event, such as elapsed time
+or terminal input.  Occasionally it is useful in a Lisp program to
+explicitly permit output to arrive at a specific point, or even to wait
+until output arrives from a process.
+
+@defun accept-process-output &optional process seconds millisec just-this-one
+This function allows Emacs to read pending output from processes.  The
+output is inserted in the associated buffers or given to their filter
+functions.  If @var{process} is non-@code{nil} then this function does
+not return until some output has been received from @var{process}.
+
+@c Emacs 19 feature
+The arguments @var{seconds} and @var{millisec} let you specify timeout
+periods.  The former specifies a period measured in seconds and the
+latter specifies one measured in milliseconds.  The two time periods
+thus specified are added together, and @code{accept-process-output}
+returns after that much time, whether or not there has been any
+subprocess output.
+
+The argument @var{millisec} is semi-obsolete nowadays because
+@var{seconds} can be a floating point number to specify waiting a
+fractional number of seconds.  If @var{seconds} is 0, the function
+accepts whatever output is pending but does not wait.
+
+@c Emacs 22.1 feature
+If @var{process} is a process, and the argument @var{just-this-one} is
+non-@code{nil}, only output from that process is handled, suspending output
+from other processes until some output has been received from that
+process or the timeout expires.  If @var{just-this-one} is an integer,
+also inhibit running timers.  This feature is generally not
+recommended, but may be necessary for specific applications, such as
+speech synthesis.
+
+The function @code{accept-process-output} returns non-@code{nil} if it
+did get some output, or @code{nil} if the timeout expired before output
+arrived.
+@end defun
+
+@node Sentinels
+@section Sentinels: Detecting Process Status Changes
+@cindex process sentinel
+@cindex sentinel (of process)
+
+  A @dfn{process sentinel} is a function that is called whenever the
+associated process changes status for any reason, including signals
+(whether sent by Emacs or caused by the process's own actions) that
+terminate, stop, or continue the process.  The process sentinel is
+also called if the process exits.  The sentinel receives two
+arguments: the process for which the event occurred, and a string
+describing the type of event.
+
+  The string describing the event looks like one of the following:
+
+@itemize @bullet
+@item
+@code{"finished\n"}.
+
+@item
+@code{"exited abnormally with code @var{exitcode}\n"}.
+
+@item
+@code{"@var{name-of-signal}\n"}.
+
+@item
+@code{"@var{name-of-signal} (core dumped)\n"}.
+@end itemize
+
+  A sentinel runs only while Emacs is waiting (e.g., for terminal
+input, or for time to elapse, or for process output).  This avoids the
+timing errors that could result from running them at random places in
+the middle of other Lisp programs.  A program can wait, so that
+sentinels will run, by calling @code{sit-for} or @code{sleep-for}
+(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
+Output}).  Emacs also allows sentinels to run when the command loop is
+reading input.  @code{delete-process} calls the sentinel when it
+terminates a running process.
+
+  Emacs does not keep a queue of multiple reasons to call the sentinel
+of one process; it records just the current status and the fact that
+there has been a change.  Therefore two changes in status, coming in
+quick succession, can call the sentinel just once.  However, process
+termination will always run the sentinel exactly once.  This is
+because the process status can't change again after termination.
+
+  Emacs explicitly checks for output from the process before running
+the process sentinel.  Once the sentinel runs due to process
+termination, no further output can arrive from the process.
+
+  A sentinel that writes the output into the buffer of the process
+should check whether the buffer is still alive.  If it tries to insert
+into a dead buffer, it will get an error.  If the buffer is dead,
+@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
+
+  Quitting is normally inhibited within a sentinel---otherwise, the
+effect of typing @kbd{C-g} at command level or to quit a user command
+would be unpredictable.  If you want to permit quitting inside a
+sentinel, bind @code{inhibit-quit} to @code{nil}.  In most cases, the
+right way to do this is with the macro @code{with-local-quit}.
+@xref{Quitting}.
+
+  If an error happens during execution of a sentinel, it is caught
+automatically, so that it doesn't stop the execution of whatever
+programs was running when the sentinel was started.  However, if
+@code{debug-on-error} is non-@code{nil}, the error-catching is turned
+off.  This makes it possible to use the Lisp debugger to debug the
+sentinel.  @xref{Debugger}.
+
+  While a sentinel is running, the process sentinel is temporarily
+set to @code{nil} so that the sentinel won't run recursively.
+For this reason it is not possible for a sentinel to specify
+a new sentinel.
+
+  In earlier Emacs versions, every sentinel that did regular expression
+searching or matching had to explicitly save and restore the match data.
+Now Emacs does this automatically for sentinels; they never need to do
+it explicitly.  @xref{Match Data}.
+
+@defun set-process-sentinel process sentinel
+This function associates @var{sentinel} with @var{process}.  If
+@var{sentinel} is @code{nil}, then the process will have no sentinel.
+The default behavior when there is no sentinel is to insert a message in
+the process's buffer when the process status changes.
+
+Changes in process sentinel take effect immediately---if the sentinel
+is slated to be run but has not been called yet, and you specify a new
+sentinel, the eventual call to the sentinel will use the new one.
+
+@smallexample
+@group
+(defun msg-me (process event)
+   (princ
+     (format "Process: %s had the event `%s'" process event)))
+(set-process-sentinel (get-process "shell") 'msg-me)
+     @result{} msg-me
+@end group
+@group
+(kill-process (get-process "shell"))
+     @print{} Process: #<process shell> had the event `killed'
+     @result{} #<process shell>
+@end group
+@end smallexample
+@end defun
+
+@defun process-sentinel process
+This function returns the sentinel of @var{process}, or @code{nil} if it
+has none.
+@end defun
+
+@defun waiting-for-user-input-p
+While a sentinel or filter function is running, this function returns
+non-@code{nil} if Emacs was waiting for keyboard input from the user at
+the time the sentinel or filter function was called, @code{nil} if it
+was not.
+@end defun
+
+@node Query Before Exit
+@section Querying Before Exit
+
+  When Emacs exits, it terminates all its subprocesses by sending them
+the @code{SIGHUP} signal.  Because subprocesses may be doing
+valuable work, Emacs normally asks the user to confirm that it is ok
+to terminate them.  Each process has a query flag which, if
+non-@code{nil}, says that Emacs should ask for confirmation before
+exiting and thus killing that process.  The default for the query flag
+is @code{t}, meaning @emph{do} query.
+
+@defun process-query-on-exit-flag process
+This returns the query flag of @var{process}.
+@end defun
+
+@defun set-process-query-on-exit-flag process flag
+This function sets the query flag of @var{process} to @var{flag}.  It
+returns @var{flag}.
+
+@smallexample
+@group
+;; @r{Don't query about the shell process}
+(set-process-query-on-exit-flag (get-process "shell") nil)
+     @result{} t
+@end group
+@end smallexample
+@end defun
+
+@defun process-kill-without-query process &optional do-query
+This function clears the query flag of @var{process}, so that
+Emacs will not query the user on account of that process.
+
+Actually, the function does more than that: it returns the old value of
+the process's query flag, and sets the query flag to @var{do-query}.
+Please don't use this function to do those things any more---please
+use the newer, cleaner functions @code{process-query-on-exit-flag} and
+@code{set-process-query-on-exit-flag} in all but the simplest cases.
+The only way you should use @code{process-kill-without-query} nowadays
+is like this:
+
+@smallexample
+@group
+;; @r{Don't query about the shell process}
+(process-kill-without-query (get-process "shell"))
+@end group
+@end smallexample
+@end defun
+
+@node Transaction Queues
+@section Transaction Queues
+@cindex transaction queue
+
+You can use a @dfn{transaction queue} to communicate with a subprocess
+using transactions.  First use @code{tq-create} to create a transaction
+queue communicating with a specified process.  Then you can call
+@code{tq-enqueue} to send a transaction.
+
+@defun tq-create process
+This function creates and returns a transaction queue communicating with
+@var{process}.  The argument @var{process} should be a subprocess
+capable of sending and receiving streams of bytes.  It may be a child
+process, or it may be a TCP connection to a server, possibly on another
+machine.
+@end defun
+
+@defun tq-enqueue queue question regexp closure fn &optional delay-question
+This function sends a transaction to queue @var{queue}.  Specifying the
+queue has the effect of specifying the subprocess to talk to.
+
+The argument @var{question} is the outgoing message that starts the
+transaction.  The argument @var{fn} is the function to call when the
+corresponding answer comes back; it is called with two arguments:
+@var{closure}, and the answer received.
+
+The argument @var{regexp} is a regular expression that should match
+text at the end of the entire answer, but nothing before; that's how
+@code{tq-enqueue} determines where the answer ends.
+
+If the argument @var{delay-question} is non-nil, delay sending this
+question until the process has finished replying to any previous
+questions.  This produces more reliable results with some processes.
+
+The return value of @code{tq-enqueue} itself is not meaningful.
+@end defun
+
+@defun tq-close queue
+Shut down transaction queue @var{queue}, waiting for all pending transactions
+to complete, and then terminate the connection or child process.
+@end defun
+
+Transaction queues are implemented by means of a filter function.
+@xref{Filter Functions}.
+
+@node Network
+@section Network Connections
+@cindex network connection
+@cindex TCP
+@cindex UDP
+
+  Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
+connections to other processes on the same machine or other machines.
+A network connection is handled by Lisp much like a subprocess, and is
+represented by a process object.  However, the process you are
+communicating with is not a child of the Emacs process, so it has no
+process @acronym{ID}, and you can't kill it or send it signals.  All you
+can do is send and receive data.  @code{delete-process} closes the
+connection, but does not kill the program at the other end; that
+program must decide what to do about closure of the connection.
+
+  Lisp programs can listen for connections by creating network
+servers.  A network server is also represented by a kind of process
+object, but unlike a network connection, the network server never
+transfers data itself.  When it receives a connection request, it
+creates a new network connection to represent the connection just
+made.  (The network connection inherits certain information, including
+the process plist, from the server.)  The network server then goes
+back to listening for more connection requests.
+
+  Network connections and servers are created by calling
+@code{make-network-process} with an argument list consisting of
+keyword/argument pairs, for example @code{:server t} to create a
+server process, or @code{:type 'datagram} to create a datagram
+connection.  @xref{Low-Level Network}, for details.  You can also use
+the @code{open-network-stream} function described below.
+
+  You can distinguish process objects representing network connections
+and servers from those representing subprocesses with the
+@code{process-status} function.  The possible status values for
+network connections are @code{open}, @code{closed}, @code{connect},
+and @code{failed}.  For a network server, the status is always
+@code{listen}.  None of those values is possible for a real
+subprocess.  @xref{Process Information}.
+
+  You can stop and resume operation of a network process by calling
+@code{stop-process} and @code{continue-process}.  For a server
+process, being stopped means not accepting new connections.  (Up to 5
+connection requests will be queued for when you resume the server; you
+can increase this limit, unless it is imposed by the operating
+system.)  For a network stream connection, being stopped means not
+processing input (any arriving input waits until you resume the
+connection).  For a datagram connection, some number of packets may be
+queued but input may be lost.  You can use the function
+@code{process-command} to determine whether a network connection or
+server is stopped; a non-@code{nil} value means yes.
+
+@defun open-network-stream name buffer-or-name host service
+This function opens a TCP connection, and returns a process object
+that represents the connection.
+
+The @var{name} argument specifies the name for the process object.  It
+is modified as necessary to make it unique.
+
+The @var{buffer-or-name} argument is the buffer to associate with the
+connection.  Output from the connection is inserted in the buffer,
+unless you specify a filter function to handle the output.  If
+@var{buffer-or-name} is @code{nil}, it means that the connection is not
+associated with any buffer.
+
+The arguments @var{host} and @var{service} specify where to connect to;
+@var{host} is the host name (a string), and @var{service} is the name of
+a defined network service (a string) or a port number (an integer).
+@end defun
+
+@defun process-contact process &optional key
+This function returns information about how a network process was set
+up.  For a connection, when @var{key} is @code{nil}, it returns
+@code{(@var{hostname} @var{service})} which specifies what you
+connected to.
+
+If @var{key} is @code{t}, the value is the complete status information
+for the connection or server; that is, the list of keywords and values
+specified in @code{make-network-process}, except that some of the
+values represent the current status instead of what you specified:
+
+@table @code
+@item :buffer
+The associated value is the process buffer.
+@item :filter
+The associated value is the process filter function.
+@item :sentinel
+The associated value is the process sentinel function.
+@item :remote
+In a connection, the address in internal format of the remote peer.
+@item :local
+The local address, in internal format.
+@item :service
+In a server, if you specified @code{t} for @var{service},
+this value is the actual port number.
+@end table
+
+@code{:local} and @code{:remote} are included even if they were not
+specified explicitly in @code{make-network-process}.
+
+If @var{key} is a keyword, the function returns the value corresponding
+to that keyword.
+
+For an ordinary child process, this function always returns @code{t}.
+@end defun
+
+@node Network Servers
+@section Network Servers
+@cindex network servers
+
+  You create a server by calling @code{make-network-process} with
+@code{:server t}.  The server will listen for connection requests from
+clients.  When it accepts a client connection request, that creates a
+new network connection, itself a process object, with the following
+parameters:
+
+@itemize @bullet
+@item
+The connection's process name is constructed by concatenating the
+server process' @var{name} with a client identification string.  The
+client identification string for an IPv4 connection looks like
+@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}.  Otherwise, it is a
+unique number in brackets, as in @samp{<@var{nnn}>}.  The number
+is unique for each connection in the Emacs session.
+
+@item
+If the server's filter is non-@code{nil}, the connection process does
+not get a separate process buffer; otherwise, Emacs creates a new
+buffer for the purpose.  The buffer name is the server's buffer name
+or process name, concatenated with the client identification string.
+
+The server's process buffer value is never used directly by Emacs, but
+it is passed to the log function, which can log connections by
+inserting text there.
+
+@item
+The communication type and the process filter and sentinel are
+inherited from those of the server.  The server never directly
+uses its filter and sentinel; their sole purpose is to initialize
+connections made to the server.
+
+@item
+The connection's process contact info is set according to the client's
+addressing information (typically an IP address and a port number).
+This information is associated with the @code{process-contact}
+keywords @code{:host}, @code{:service}, @code{:remote}.
+
+@item
+The connection's local address is set up according to the port
+number used for the connection.
+
+@item
+The client process' plist is initialized from the server's plist.
+@end itemize
+
+@node Datagrams
+@section Datagrams
+@cindex datagrams
+
+  A datagram connection communicates with individual packets rather
+than streams of data.  Each call to @code{process-send} sends one
+datagram packet (@pxref{Input to Processes}), and each datagram
+received results in one call to the filter function.
+
+  The datagram connection doesn't have to talk with the same remote
+peer all the time.  It has a @dfn{remote peer address} which specifies
+where to send datagrams to.  Each time an incoming datagram is passed
+to the filter function, the peer address is set to the address that
+datagram came from; that way, if the filter function sends a datagram,
+it will go back to that place.  You can specify the remote peer
+address when you create the datagram connection using the
+@code{:remote} keyword.  You can change it later on by calling
+@code{set-process-datagram-address}.
+
+@defun process-datagram-address process
+If @var{process} is a datagram connection or server, this function
+returns its remote peer address.
+@end defun
+
+@defun set-process-datagram-address process address
+If @var{process} is a datagram connection or server, this function
+sets its remote peer address to @var{address}.
+@end defun
+
+@node Low-Level Network
+@section Low-Level Network Access
+
+  You can also create network connections by operating at a lower
+level than that of @code{open-network-stream}, using
+@code{make-network-process}.
+
+@menu
+* Proc: Network Processes.   Using @code{make-network-process}.
+* Options: Network Options.  Further control over network connections.
+* Features: Network Feature Testing.
+                             Determining which network features work on
+                               the machine you are using.
+@end menu
+
+@node Network Processes
+@subsection @code{make-network-process}
+
+   The basic function for creating network connections and network
+servers is @code{make-network-process}.  It can do either of those
+jobs, depending on the arguments you give it.
+
+@defun make-network-process &rest args
+This function creates a network connection or server and returns the
+process object that represents it.  The arguments @var{args} are a
+list of keyword/argument pairs.  Omitting a keyword is always
+equivalent to specifying it with value @code{nil}, except for
+@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}.  Here
+are the meaningful keywords:
+
+@table @asis
+@item :name @var{name}
+Use the string @var{name} as the process name.  It is modified if
+necessary to make it unique.
+
+@item :type @var{type}
+Specify the communication type.  A value of @code{nil} specifies a
+stream connection (the default); @code{datagram} specifies a datagram
+connection.  Both connections and servers can be of either type.
+
+@item :server @var{server-flag}
+If @var{server-flag} is non-@code{nil}, create a server.  Otherwise,
+create a connection.  For a stream type server, @var{server-flag} may
+be an integer which then specifies the length of the queue of pending
+connections to the server.  The default queue length is 5.
+
+@item :host @var{host}
+Specify the host to connect to.  @var{host} should be a host name or
+Internet address, as a string, or the symbol @code{local} to specify
+the local host.  If you specify @var{host} for a server, it must
+specify a valid address for the local host, and only clients
+connecting to that address will be accepted.
+
+@item :service @var{service}
+@var{service} specifies a port number to connect to, or, for a server,
+the port number to listen on.  It should be a service name that
+translates to a port number, or an integer specifying the port number
+directly.  For a server, it can also be @code{t}, which means to let
+the system select an unused port number.
+
+@item :family @var{family}
+@var{family} specifies the address (and protocol) family for
+communication.  @code{nil} means determine the proper address family
+automatically for the given @var{host} and @var{service}.
+@code{local} specifies a Unix socket, in which case @var{host} is
+ignored.  @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6
+respectively.
+
+@item :local @var{local-address}
+For a server process, @var{local-address} is the address to listen on.
+It overrides @var{family}, @var{host} and @var{service}, and you
+may as well not specify them.
+
+@item :remote @var{remote-address}
+For a connection, @var{remote-address} is the address to connect to.
+It overrides @var{family}, @var{host} and @var{service}, and you
+may as well not specify them.
+
+For a datagram server, @var{remote-address} specifies the initial
+setting of the remote datagram address.
+
+The format of @var{local-address} or @var{remote-address} depends on
+the address family:
+
+@itemize -
+@item
+An IPv4 address is represented as a five-element vector of four 8-bit
+integers and one 16-bit integer
+@code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to
+numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number
+@var{p}.
+
+@item
+An IPv6 address is represented as a nine-element vector of 16-bit
+integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
+@var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address
+@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and
+port number @var{p}.
+
+@item
+A local address is represented as a string which specifies the address
+in the local address space.
+
+@item
+An ``unsupported family'' address is represented by a cons
+@code{(@var{f} . @var{av})}, where @var{f} is the family number and
+@var{av} is a vector specifying the socket address using one element
+per address data byte.  Do not rely on this format in portable code,
+as it may depend on implementation defined constants, data sizes, and
+data structure alignment.
+@end itemize
+
+@item :nowait @var{bool}
+If @var{bool} is non-@code{nil} for a stream connection, return
+without waiting for the connection to complete.  When the connection
+succeeds or fails, Emacs will call the sentinel function, with a
+second argument matching @code{"open"} (if successful) or
+@code{"failed"}.  The default is to block, so that
+@code{make-network-process} does not return until the connection
+has succeeded or failed.
+
+@item :stop @var{stopped}
+Start the network connection or server in the `stopped' state if
+@var{stopped} is non-@code{nil}.
+
+@item :buffer @var{buffer}
+Use @var{buffer} as the process buffer.
+
+@item :coding @var{coding}
+Use @var{coding} as the coding system for this process.  To specify
+different coding systems for decoding data from the connection and for
+encoding data sent to it, specify @code{(@var{decoding} .
+@var{encoding})} for @var{coding}.
+
+If you don't specify this keyword at all, the default
+is to determine the coding systems from the data.
+
+@item :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.
+@xref{Query Before Exit}.
+
+@item :filter @var{filter}
+Initialize the process filter to @var{filter}.
+
+@item :filter-multibyte @var{bool}
+If @var{bool} is non-@code{nil}, strings given to the process filter
+are multibyte, otherwise they are unibyte.  If you don't specify this
+keyword at all, the default is that the strings are multibyte if
+@code{default-enable-multibyte-characters} is non-@code{nil}.
+
+@item :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}.
+
+@item :log @var{log}
+Initialize the log function of a server process to @var{log}.  The log
+function is called each time the server accepts a network connection
+from a client.  The arguments passed to the log function are
+@var{server}, @var{connection}, and @var{message}, where @var{server}
+is the server process, @var{connection} is the new process for the
+connection, and @var{message} is a string describing what has
+happened.
+
+@item :plist @var{plist}
+Initialize the process plist to @var{plist}.
+@end table
+
+The original argument list, modified with the actual connection
+information, is available via the @code{process-contact} function.
+@end defun
+
+@node Network Options
+@subsection Network Options
+
+  The following network options can be specified when you create a
+network process.  Except for @code{:reuseaddr}, you can also set or
+modify these options later, using @code{set-network-process-option}.
+
+  For a server process, the options specified with
+@code{make-network-process} are not inherited by the client
+connections, so you will need to set the necessary options for each
+child connection as it is created.
+
+@table @asis
+@item :bindtodevice @var{device-name}
+If @var{device-name} is a non-empty string identifying a network
+interface name (see @code{network-interface-list}), only handle
+packets received on that interface.  If @var{device-name} is @code{nil}
+(the default), handle packets received on any interface.
+
+Using this option may require special privileges on some systems.
+
+@item :broadcast @var{broadcast-flag}
+If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
+process will receive datagram packet sent to a broadcast address, and
+be able to send packets to a broadcast address.  Ignored for a stream
+connection.
+
+@item :dontroute @var{dontroute-flag}
+If @var{dontroute-flag} is non-@code{nil}, the process can only send
+to hosts on the same network as the local host.
+
+@item :keepalive @var{keepalive-flag}
+If @var{keepalive-flag} is non-@code{nil} for a stream connection,
+enable exchange of low-level keep-alive messages.
+
+@item :linger @var{linger-arg}
+If @var{linger-arg} is non-@code{nil}, wait for successful
+transmission of all queued packets on the connection before it is
+deleted (see @code{delete-process}).  If @var{linger-arg} is an
+integer, it specifies the maximum time in seconds to wait for queued
+packets to be sent before closing the connection.  Default is
+@code{nil} which means to discard unsent queued packets when the
+process is deleted.
+
+@item :oobinline @var{oobinline-flag}
+If @var{oobinline-flag} is non-@code{nil} for a stream connection,
+receive out-of-band data in the normal data stream.  Otherwise, ignore
+out-of-band data.
+
+@item :priority @var{priority}
+Set the priority for packets sent on this connection to the integer
+@var{priority}.  The interpretation of this number is protocol
+specific, such as setting the TOS (type of service) field on IP
+packets sent on this connection.  It may also have system dependent
+effects, such as selecting a specific output queue on the network
+interface.
+
+@item :reuseaddr @var{reuseaddr-flag}
+If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
+server process, allow this server to reuse a specific port number (see
+@code{:service}) unless another process on this host is already
+listening on that port.  If @var{reuseaddr-flag} is @code{nil}, there
+may be a period of time after the last use of that port (by any
+process on the host), where it is not possible to make a new server on
+that port.
+@end table
+
+@defun set-network-process-option process option value
+This function sets or modifies a network option for network process
+@var{process}.  See @code{make-network-process} for details of options
+@var{option} and their corresponding values @var{value}.
+
+The current setting of an option is available via the
+@code{process-contact} function.
+@end defun
+
+@node Network Feature Testing
+@subsection Testing Availability of Network Features
+
+  To test for the availability of a given network feature, use
+@code{featurep} like this:
+
+@example
+(featurep 'make-network-process '(@var{keyword} @var{value}))
+@end example
+
+@noindent
+The result of the first form is @code{t} if it works to specify
+@var{keyword} with value @var{value} in @code{make-network-process}.
+The result of the second form is @code{t} if @var{keyword} is
+supported by @code{make-network-process}.  Here are some of the
+@var{keyword}---@var{value} pairs you can test in
+this way.
+
+@table @code
+@item (:nowait t)
+Non-@code{nil} if non-blocking connect is supported.
+@item (:type datagram)
+Non-@code{nil} if datagrams are supported.
+@item (:family local)
+Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
+@item (:family ipv6)
+Non-@code{nil} if IPv6 is supported.
+@item (:service t)
+Non-@code{nil} if the system can select the port for a server.
+@end table
+
+  To test for the availability of a given network option, use
+@code{featurep} like this:
+
+@example
+(featurep 'make-network-process '@var{keyword})
+@end example
+
+@noindent
+Here are some of the options you can test in this way.
+
+@table @code
+@item :bindtodevice
+@itemx :broadcast
+@itemx :dontroute
+@itemx :keepalive
+@itemx :linger
+@itemx :oobinline
+@itemx :priority
+@itemx :reuseaddr
+That particular network option is supported by
+@code{make-network-process} and @code{set-network-process-option}.
+@end table
+
+@node Misc Network
+@section Misc Network Facilities
+
+  These additional functions are useful for creating and operating
+on network connections.
+
+@defun network-interface-list
+This function returns a list describing the network interfaces
+of the machine you are using.  The value is an alist whose
+elements have the form @code{(@var{name} . @var{address})}.
+@var{address} has the same form as the @var{local-address}
+and @var{remote-address} arguments to @code{make-network-process}.
+@end defun
+
+@defun network-interface-info ifname
+This function returns information about the network interface named
+@var{ifname}.  The value is a list of the form
+@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
+
+@table @var
+@item addr
+The Internet protocol address.
+@item bcast
+The broadcast address.
+@item netmask
+The network mask.
+@item hwaddr
+The layer 2 address (Ethernet MAC address, for instance).
+@item flags
+The current flags of the interface.
+@end table
+@end defun
+
+@defun format-network-address address &optional omit-port
+This function converts the Lisp representation of a network address to
+a string.
+
+A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]}
+represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port
+number @var{p}.  @code{format-network-address} converts that to the
+string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
+
+A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e}
+@var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along
+with a port number.  @code{format-network-address} converts that to
+the string
+@code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}.
+
+If the vector does not include the port number, @var{p}, or if
+@var{omit-port} is non-@code{nil}, the result does not include the
+@code{:@var{p}} suffix.
+@end defun
+
+@node Byte Packing
+@section Packing and Unpacking Byte Arrays
+@cindex byte packing and unpacking
+
+  This section describes how to pack and unpack arrays of bytes,
+usually for binary network protocols.  These functions convert byte arrays
+to alists, and vice versa.  The byte array can be represented as a
+unibyte string or as a vector of integers, while the alist associates
+symbols either with fixed-size objects or with recursive sub-alists.
+
+@cindex serializing
+@cindex deserializing
+@cindex packing
+@cindex unpacking
+  Conversion from byte arrays to nested alists is also known as
+@dfn{deserializing} or @dfn{unpacking}, while going in the opposite
+direction is also known as @dfn{serializing} or @dfn{packing}.
+
+@menu
+* Bindat Spec::         Describing data layout.
+* Bindat Functions::    Doing the unpacking and packing.
+* Bindat Examples::     Samples of what bindat.el can do for you!
+@end menu
+
+@node Bindat Spec
+@subsection Describing Data Layout
+
+  To control unpacking and packing, you write a @dfn{data layout
+specification}, a special nested list describing named and typed
+@dfn{fields}.  This specification controls length of each field to be
+processed, and how to pack or unpack it.  We normally keep bindat specs
+in variables whose names end in @samp{-bindat-spec}; that kind of name
+is automatically recognized as ``risky.''
+
+@cindex endianness
+@cindex big endian
+@cindex little endian
+@cindex network byte ordering
+  A field's @dfn{type} describes the size (in bytes) of the object
+that the field represents and, in the case of multibyte fields, how
+the bytes are ordered within the field.  The two possible orderings
+are ``big endian'' (also known as ``network byte ordering'') and
+``little endian.''  For instance, the number @code{#x23cd} (decimal
+9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
+and in little endian, @code{#xcd} @code{#x23}.  Here are the possible
+type values:
+
+@table @code
+@item u8
+@itemx byte
+Unsigned byte, with length 1.
+
+@item u16
+@itemx word
+@itemx short
+Unsigned integer in network byte order, with length 2.
+
+@item u24
+Unsigned integer in network byte order, with length 3.
+
+@item u32
+@itemx dword
+@itemx long
+Unsigned integer in network byte order, with length 4.
+Note: These values may be limited by Emacs' integer implementation limits.
+
+@item u16r
+@itemx u24r
+@itemx u32r
+Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
+
+@item str @var{len}
+String of length @var{len}.
+
+@item strz @var{len}
+Zero-terminated string, in a fixed-size field with length @var{len}.
+
+@item vec @var{len} [@var{type}]
+Vector of @var{len} elements of type @var{type}, or bytes if not
+@var{type} is specified.
+The @var{type} is any of the simple types above, or another vector
+specified as a list @code{(vec @var{len} [@var{type}])}.
+
+@item ip
+Four-byte vector representing an Internet address.  For example:
+@code{[127 0 0 1]} for localhost.
+
+@item bits @var{len}
+List of set bits in @var{len} bytes.  The bytes are taken in big
+endian order and the bits are numbered starting with @code{8 *
+@var{len} @minus{} 1} and ending with zero.  For example: @code{bits
+2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
+@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
+
+@item (eval @var{form})
+@var{form} is a Lisp expression evaluated at the moment the field is
+unpacked or packed.  The result of the evaluation should be one of the
+above-listed type specifications.
+@end table
+
+For a fixed-size field, the length @var{len} is given as an integer
+specifying the number of bytes in the field.
+
+When the length of a field is not fixed, it typically depends on the
+value of a preceding field.  In this case, the length @var{len} can be
+given either as a list @code{(@var{name} ...)} identifying a
+@dfn{field name} in the format specified for @code{bindat-get-field}
+below, or by an expression @code{(eval @var{form})} where @var{form}
+should evaluate to an integer, specifying the field length.
+
+A field specification generally has the form @code{([@var{name}]
+@var{handler})}.  The square braces indicate that @var{name} is
+optional.  (Don't use names that are symbols meaningful as type
+specifications (above) or handler specifications (below), since that
+would be ambiguous.)  @var{name} can be a symbol or the expression
+@code{(eval @var{form})}, in which case @var{form} should evaluate to
+a symbol.
+
+@var{handler} describes how to unpack or pack the field and can be one
+of the following:
+
+@table @code
+@item @var{type}
+Unpack/pack this field according to the type specification @var{type}.
+
+@item eval @var{form}
+Evaluate @var{form}, a Lisp expression, for side-effect only.  If the
+field name is specified, the value is bound to that field name.
+
+@item fill @var{len}
+Skip @var{len} bytes.  In packing, this leaves them unchanged,
+which normally means they remain zero.  In unpacking, this means
+they are ignored.
+
+@item align @var{len}
+Skip to the next multiple of @var{len} bytes.
+
+@item struct @var{spec-name}
+Process @var{spec-name} as a sub-specification.  This describes a
+structure nested within another structure.
+
+@item union @var{form} (@var{tag} @var{spec})@dots{}
+@c ??? I don't see how one would actually  use this.
+@c ??? what kind of expression would be useful for @var{form}?
+Evaluate @var{form}, a Lisp expression, find the first @var{tag}
+that matches it, and process its associated data layout specification
+@var{spec}.  Matching can occur in one of three ways:
+
+@itemize
+@item
+If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
+@var{expr} with the variable @code{tag} dynamically bound to the value
+of @var{form}.  A non-@code{nil} result indicates a match.
+
+@item
+@var{tag} matches if it is @code{equal} to the value of @var{form}.
+
+@item
+@var{tag} matches unconditionally if it is @code{t}.
+@end itemize
+
+@item repeat @var{count} @var{field-specs}@dots{}
+Process the @var{field-specs} recursively, in order, then repeat
+starting from the first one, processing all the specs @var{count}
+times overall.  The @var{count} is given using the same formats as a
+field length---if an @code{eval} form is used, it is evaluated just once.
+For correct operation, each spec in @var{field-specs} must include a name.
+@end table
+
+For the @code{(eval @var{form})} forms used in a bindat specification,
+the @var{form} can access and update these dynamically bound variables
+during evaluation:
+
+@table @code
+@item last
+Value of the last field processed.
+
+@item bindat-raw
+The data as a byte array.
+
+@item bindat-idx
+Current index (within @code{bindat-raw}) for unpacking or packing.
+
+@item struct
+The alist containing the structured data that have been unpacked so
+far, or the entire structure being packed.  You can use
+@code{bindat-get-field} to access specific fields of this structure.
+
+@item count
+@itemx index
+Inside a @code{repeat} block, these contain the maximum number of
+repetitions (as specified by the @var{count} parameter), and the
+current repetition number (counting from 0).  Setting @code{count} to
+zero will terminate the inner-most repeat block after the current
+repetition has completed.
+@end table
+
+@node Bindat Functions
+@subsection Functions to Unpack and Pack Bytes
+
+  In the following documentation, @var{spec} refers to a data layout
+specification, @code{bindat-raw} to a byte array, and @var{struct} to an
+alist representing unpacked field data.
+
+@defun bindat-unpack spec bindat-raw &optional bindat-idx
+This function unpacks data from the unibyte string or byte
+array @code{bindat-raw}
+according to @var{spec}.  Normally this starts unpacking at the
+beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
+specifies a zero-based starting position to use instead.
+
+The value is an alist or nested alist in which each element describes
+one unpacked field.
+@end defun
+
+@defun bindat-get-field struct &rest name
+This function selects a field's data from the nested alist
+@var{struct}.  Usually @var{struct} was returned by
+@code{bindat-unpack}.  If @var{name} corresponds to just one argument,
+that means to extract a top-level field value.  Multiple @var{name}
+arguments specify repeated lookup of sub-structures.  An integer name
+acts as an array index.
+
+For example, if @var{name} is @code{(a b 2 c)}, that means to find
+field @code{c} in the third element of subfield @code{b} of field
+@code{a}.  (This corresponds to @code{struct.a.b[2].c} in C.)
+@end defun
+
+  Although packing and unpacking operations change the organization of
+data (in memory), they preserve the data's @dfn{total length}, which is
+the sum of all the fields' lengths, in bytes.  This value is not
+generally inherent in either the specification or alist alone; instead,
+both pieces of information contribute to its calculation.  Likewise, the
+length of a string or array being unpacked may be longer than the data's
+total length as described by the specification.
+
+@defun bindat-length spec struct
+This function returns the total length of the data in @var{struct},
+according to @var{spec}.
+@end defun
+
+@defun bindat-pack spec struct &optional bindat-raw bindat-idx
+This function returns a byte array packed according to @var{spec} from
+the data in the alist @var{struct}.  Normally it creates and fills a
+new byte array starting at the beginning.  However, if @var{bindat-raw}
+is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
+pack into.  If @var{bindat-idx} is non-@code{nil}, it specifies the starting
+offset for packing into @code{bindat-raw}.
+
+When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
+meets or exceeds the total length to avoid an out-of-range error.
+@end defun
+
+@defun bindat-ip-to-string ip
+Convert the Internet address vector @var{ip} to a string in the usual
+dotted notation.
+
+@example
+(bindat-ip-to-string [127 0 0 1])
+     @result{} "127.0.0.1"
+@end example
+@end defun
+
+@node Bindat Examples
+@subsection Examples of Byte Unpacking and Packing
+
+  Here is a complete example of byte unpacking and packing:
+
+@lisp
+(defvar fcookie-index-spec
+  '((:version  u32)
+    (:count    u32)
+    (:longest  u32)
+    (:shortest u32)
+    (:flags    u32)
+    (:delim    u8)
+    (:ignored  fill 3)
+    (:offset   repeat (:count)
+               (:foo u32)))
+  "Description of a fortune cookie index file's contents.")
+
+(defun fcookie (cookies &optional index)
+  "Display a random fortune cookie from file COOKIES.
+Optional second arg INDEX specifies the associated index
+filename, which is by default constructed by appending
+\".dat\" to COOKIES.  Display cookie text in possibly
+new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
+is COOKIES without the directory part."
+  (interactive "fCookies file: ")
+  (let* ((info (with-temp-buffer
+                 (insert-file-contents-literally
+                  (or index (concat cookies ".dat")))
+                 (bindat-unpack fcookie-index-spec
+                                (buffer-string))))
+         (sel (random (bindat-get-field info :count)))
+         (beg (cdar (bindat-get-field info :offset sel)))
+         (end (or (cdar (bindat-get-field info
+                                          :offset (1+ sel)))
+                  (nth 7 (file-attributes cookies)))))
+    (switch-to-buffer
+     (get-buffer-create
+      (format "*Fortune Cookie: %s*"
+              (file-name-nondirectory cookies))))
+    (erase-buffer)
+    (insert-file-contents-literally
+     cookies nil beg (- end 3))))
+
+(defun fcookie-create-index (cookies &optional index delim)
+  "Scan file COOKIES, and write out its index file.
+Optional second arg INDEX specifies the index filename,
+which is by default constructed by appending \".dat\" to
+COOKIES.  Optional third arg DELIM specifies the unibyte
+character which, when found on a line of its own in
+COOKIES, indicates the border between entries."
+  (interactive "fCookies file: ")
+  (setq delim (or delim ?%))
+  (let ((delim-line (format "\n%c\n" delim))
+        (count 0)
+        (max 0)
+        min p q len offsets)
+    (unless (= 3 (string-bytes delim-line))
+      (error "Delimiter cannot be represented in one byte"))
+    (with-temp-buffer
+      (insert-file-contents-literally cookies)
+      (while (and (setq p (point))
+                  (search-forward delim-line (point-max) t)
+                  (setq len (- (point) 3 p)))
+        (setq count (1+ count)
+              max (max max len)
+              min (min (or min max) len)
+              offsets (cons (1- p) offsets))))
+    (with-temp-buffer
+      (set-buffer-multibyte nil)
+      (insert
+       (bindat-pack
+        fcookie-index-spec
+        `((:version . 2)
+          (:count . ,count)
+          (:longest . ,max)
+          (:shortest . ,min)
+          (:flags . 0)
+          (:delim . ,delim)
+          (:offset . ,(mapcar (lambda (o)
+                                (list (cons :foo o)))
+                              (nreverse offsets))))))
+      (let ((coding-system-for-write 'raw-text-unix))
+        (write-file (or index (concat cookies ".dat")))))))
+@end lisp
+
+Following is an example of defining and unpacking a complex structure.
+Consider the following C structures:
+
+@example
+struct header @{
+    unsigned long    dest_ip;
+    unsigned long    src_ip;
+    unsigned short   dest_port;
+    unsigned short   src_port;
+@};
+
+struct data @{
+    unsigned char    type;
+    unsigned char    opcode;
+    unsigned short   length;  /* In network byte order */
+    unsigned char    id[8];   /* null-terminated string  */
+    unsigned char    data[/* (length + 3) & ~3 */];
+@};
+
+struct packet @{
+    struct header    header;
+    unsigned long    counters[2];  /* In little endian order */
+    unsigned char    items;
+    unsigned char    filler[3];
+    struct data      item[/* items */];
+
+@};
+@end example
+
+The corresponding data layout specification:
+
+@lisp
+(setq header-spec
+      '((dest-ip   ip)
+        (src-ip    ip)
+        (dest-port u16)
+        (src-port  u16)))
+
+(setq data-spec
+      '((type      u8)
+        (opcode    u8)
+        (length    u16)  ;; network byte order
+        (id        strz 8)
+        (data      vec (length))
+        (align     4)))
+
+(setq packet-spec
+      '((header    struct header-spec)
+        (counters  vec 2 u32r)   ;; little endian order
+        (items     u8)
+        (fill      3)
+        (item      repeat (items)
+                   (struct data-spec))))
+@end lisp
+
+A binary data representation:
+
+@lisp
+(setq binary-data
+      [ 192 168 1 100 192 168 1 101 01 28 21 32
+        160 134 1 0 5 1 0 0 2 0 0 0
+        2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
+        1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
+@end lisp
+
+The corresponding decoded structure:
+
+@lisp
+(setq decoded (bindat-unpack packet-spec binary-data))
+     @result{}
+((header
+  (dest-ip   . [192 168 1 100])
+  (src-ip    . [192 168 1 101])
+  (dest-port . 284)
+  (src-port  . 5408))
+ (counters . [100000 261])
+ (items . 2)
+ (item ((data . [1 2 3 4 5])
+        (id . "ABCDEF")
+        (length . 5)
+        (opcode . 3)
+        (type . 2))
+       ((data . [6 7 8 9 10 11 12])
+        (id . "BCDEFG")
+        (length . 7)
+        (opcode . 4)
+        (type . 1))))
+@end lisp
+
+Fetching data from this structure:
+
+@lisp
+(bindat-get-field decoded 'item 1 'id)
+     @result{} "BCDEFG"
+@end lisp
+
+@ignore
+   arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
+@end ignore
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
new file mode 100644
index 00000000000..70926478ea7
--- /dev/null
+++ b/doc/lispref/searching.texi
@@ -0,0 +1,1766 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/searching
+@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
+@chapter Searching and Matching
+@cindex searching
+
+  GNU Emacs provides two ways to search through a buffer for specified
+text: exact string searches and regular expression searches.  After a
+regular expression search, you can examine the @dfn{match data} to
+determine which text matched the whole regular expression or various
+portions of it.
+
+@menu
+* String Search::         Search for an exact match.
+* Searching and Case::    Case-independent or case-significant searching.
+* Regular Expressions::   Describing classes of strings.
+* Regexp Search::         Searching for a match for a regexp.
+* POSIX Regexps::         Searching POSIX-style for the longest match.
+* Match Data::            Finding out which part of the text matched,
+                            after a string or regexp search.
+* Search and Replace::	  Commands that loop, searching and replacing.
+* Standard Regexps::      Useful regexps for finding sentences, pages,...
+@end menu
+
+  The @samp{skip-chars@dots{}} functions also perform a kind of searching.
+@xref{Skipping Characters}.  To search for changes in character
+properties, see @ref{Property Search}.
+
+@node String Search
+@section Searching for Strings
+@cindex string search
+
+  These are the primitive functions for searching through the text in a
+buffer.  They are meant for use in programs, but you may call them
+interactively.  If you do so, they prompt for the search string; the
+arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
+is 1.
+
+  These search functions convert the search string to multibyte if the
+buffer is multibyte; they convert the search string to unibyte if the
+buffer is unibyte.  @xref{Text Representations}.
+
+@deffn Command search-forward string &optional limit noerror repeat
+This function searches forward from point for an exact match for
+@var{string}.  If successful, it sets point to the end of the occurrence
+found, and returns the new value of point.  If no match is found, the
+value and side effects depend on @var{noerror} (see below).
+@c Emacs 19 feature
+
+In the following example, point is initially at the beginning of the
+line.  Then @code{(search-forward "fox")} moves point after the last
+letter of @samp{fox}:
+
+@example
+@group
+---------- Buffer: foo ----------
+@point{}The quick brown fox jumped over the lazy dog.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(search-forward "fox")
+     @result{} 20
+
+---------- Buffer: foo ----------
+The quick brown fox@point{} jumped over the lazy dog.
+---------- Buffer: foo ----------
+@end group
+@end example
+
+The argument @var{limit} specifies the upper bound to the search.  (It
+must be a position in the current buffer.)  No match extending after
+that position is accepted.  If @var{limit} is omitted or @code{nil}, it
+defaults to the end of the accessible portion of the buffer.
+
+@kindex search-failed
+What happens when the search fails depends on the value of
+@var{noerror}.  If @var{noerror} is @code{nil}, a @code{search-failed}
+error is signaled.  If @var{noerror} is @code{t}, @code{search-forward}
+returns @code{nil} and does nothing.  If @var{noerror} is neither
+@code{nil} nor @code{t}, then @code{search-forward} moves point to the
+upper bound and returns @code{nil}.  (It would be more consistent now to
+return the new position of point in that case, but some existing
+programs may depend on a value of @code{nil}.)
+
+The argument @var{noerror} only affects valid searches which fail to
+find a match.  Invalid arguments cause errors regardless of
+@var{noerror}.
+
+If @var{repeat} is supplied (it must be a positive number), then the
+search is repeated that many times (each time starting at the end of the
+previous time's match).  If these successive searches succeed, the
+function succeeds, moving point and returning its new value.  Otherwise
+the search fails, with results depending on the value of
+@var{noerror}, as described above.
+@end deffn
+
+@deffn Command search-backward string &optional limit noerror repeat
+This function searches backward from point for @var{string}.  It is
+just like @code{search-forward} except that it searches backwards and
+leaves point at the beginning of the match.
+@end deffn
+
+@deffn Command word-search-forward string &optional limit noerror repeat
+@c  @cindex word search   Redundant
+This function searches forward from point for a ``word'' match for
+@var{string}.  If it finds a match, it sets point to the end of the
+match found, and returns the new value of point.
+@c Emacs 19 feature
+
+Word matching regards @var{string} as a sequence of words, disregarding
+punctuation that separates them.  It searches the buffer for the same
+sequence of words.  Each word must be distinct in the buffer (searching
+for the word @samp{ball} does not match the word @samp{balls}), but the
+details of punctuation and spacing are ignored (searching for @samp{ball
+boy} does match @samp{ball.  Boy!}).
+
+In this example, point is initially at the beginning of the buffer; the
+search leaves it between the @samp{y} and the @samp{!}.
+
+@example
+@group
+---------- Buffer: foo ----------
+@point{}He said "Please!  Find
+the ball boy!"
+---------- Buffer: foo ----------
+@end group
+
+@group
+(word-search-forward "Please find the ball, boy.")
+     @result{} 35
+
+---------- Buffer: foo ----------
+He said "Please!  Find
+the ball boy@point{}!"
+---------- Buffer: foo ----------
+@end group
+@end example
+
+If @var{limit} is non-@code{nil}, it must be a position in the current
+buffer; it specifies the upper bound to the search.  The match found
+must not extend after that position.
+
+If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
+an error if the search fails.  If @var{noerror} is @code{t}, then it
+returns @code{nil} instead of signaling an error.  If @var{noerror} is
+neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
+end of the accessible portion of the buffer) and returns @code{nil}.
+
+If @var{repeat} is non-@code{nil}, then the search is repeated that many
+times.  Point is positioned at the end of the last match.
+@end deffn
+
+@deffn Command word-search-backward string &optional limit noerror repeat
+This function searches backward from point for a word match to
+@var{string}.  This function is just like @code{word-search-forward}
+except that it searches backward and normally leaves point at the
+beginning of the match.
+@end deffn
+
+@node Searching and Case
+@section Searching and Case
+@cindex searching and case
+
+  By default, searches in Emacs ignore the case of the text they are
+searching through; if you specify searching for @samp{FOO}, then
+@samp{Foo} or @samp{foo} is also considered a match.  This applies to
+regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
+@samp{A} or @samp{b} or @samp{B}.
+
+  If you do not want this feature, set the variable
+@code{case-fold-search} to @code{nil}.  Then all letters must match
+exactly, including case.  This is a buffer-local variable; altering the
+variable affects only the current buffer.  (@xref{Intro to
+Buffer-Local}.)  Alternatively, you may change the value of
+@code{default-case-fold-search}, which is the default value of
+@code{case-fold-search} for buffers that do not override it.
+
+  Note that the user-level incremental search feature handles case
+distinctions differently.  When given a lower case letter, it looks for
+a match of either case, but when given an upper case letter, it looks
+for an upper case letter only.  But this has nothing to do with the
+searching functions used in Lisp code.
+
+@defopt case-replace
+This variable determines whether the higher level replacement
+functions should preserve case.  If the variable is @code{nil}, that
+means to use the replacement text verbatim.  A non-@code{nil} value
+means to convert the case of the replacement text according to the
+text being replaced.
+
+This variable is used by passing it as an argument to the function
+@code{replace-match}.  @xref{Replacing Match}.
+@end defopt
+
+@defopt case-fold-search
+This buffer-local variable determines whether searches should ignore
+case.  If the variable is @code{nil} they do not ignore case; otherwise
+they do ignore case.
+@end defopt
+
+@defvar default-case-fold-search
+The value of this variable is the default value for
+@code{case-fold-search} in buffers that do not override it.  This is the
+same as @code{(default-value 'case-fold-search)}.
+@end defvar
+
+@node Regular Expressions
+@section Regular Expressions
+@cindex regular expression
+@cindex regexp
+
+  A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
+denotes a (possibly infinite) set of strings.  Searching for matches for
+a regexp is a very powerful operation.  This section explains how to write
+regexps; the following section says how to search for them.
+
+@findex re-builder
+@cindex regular expressions, developing
+  For convenient interactive development of regular expressions, you
+can use the @kbd{M-x re-builder} command.  It provides a convenient
+interface for creating regular expressions, by giving immediate visual
+feedback in a separate buffer.  As you edit the regexp, all its
+matches in the target buffer are highlighted.  Each parenthesized
+sub-expression of the regexp is shown in a distinct face, which makes
+it easier to verify even very complex regexps.
+
+@menu
+* Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Example::          Illustrates regular expression syntax.
+* Regexp Functions::        Functions for operating on regular expressions.
+@end menu
+
+@node Syntax of Regexps
+@subsection Syntax of Regular Expressions
+
+  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 that matches that character
+and nothing else.  The special characters are @samp{.}, @samp{*},
+@samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new
+special characters will be defined in the future.  The character
+@samp{]} is special if it ends a character alternative (see later).
+The character @samp{-} is special inside a character alternative.  A
+@samp{[:} and balancing @samp{:]} enclose a character class inside a
+character alternative.  Any other character appearing in a regular
+expression is ordinary, unless a @samp{\} precedes it.
+
+  For example, @samp{f} is not a special character, so it is ordinary, and
+therefore @samp{f} is a regular expression that matches the string
+@samp{f} and no other string.  (It does @emph{not} match the string
+@samp{fg}, but it does match a @emph{part} of that string.)  Likewise,
+@samp{o} is a regular expression that matches only @samp{o}.@refill
+
+  Any two regular expressions @var{a} and @var{b} can be concatenated.  The
+result is a regular expression that 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 more powerful, you
+need to use one of the special regular expression constructs.
+
+@menu
+* Regexp Special::      Special characters in regular expressions.
+* Char Classes::        Character classes used in regular expressions.
+* Regexp Backslash::    Backslash-sequences in regular expressions.
+@end menu
+
+@node Regexp Special
+@subsubsection Special Characters in Regular Expressions
+
+  Here is a list of the characters that are special in a regular
+expression.
+
+@need 800
+@table @asis
+@item @samp{.}@: @r{(Period)}
+@cindex @samp{.} in regexp
+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 @samp{*}
+@cindex @samp{*} in regexp
+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 the hope that that will
+make 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.
+
+@strong{Warning:} Nested repetition operators can run for an
+indefinitely long time, if they lead to ambiguous matching.  For
+example, trying to match the regular expression @samp{\(x+y*\)*a}
+against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could
+take hours before it ultimately fails.  Emacs must try each way of
+grouping the @samp{x}s before concluding that none of them can work.
+Even worse, @samp{\(x*\)*} can match the null string in infinitely
+many ways, so it causes an infinite loop.  To avoid these problems,
+check nested repetitions carefully, to make sure that they do not
+cause combinatorial explosions in backtracking.
+
+@item @samp{+}
+@cindex @samp{+} in regexp
+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 @samp{?}
+@cindex @samp{?} in regexp
+is a postfix operator, similar to @samp{*} except that it must match the
+preceding expression either once or not at all.  For example,
+@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
+
+@item @samp{*?}, @samp{+?}, @samp{??}
+These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
+and @samp{?}.  Where those operators match the largest possible
+substring (consistent with matching the entire containing expression),
+the non-greedy variants match the smallest possible substring
+(consistent with matching the entire containing expression).
+
+For example, the regular expression @samp{c[ad]*a} when applied to the
+string @samp{cdaaada} matches the whole string; but the regular
+expression @samp{c[ad]*?a}, applied to that same string, matches just
+@samp{cda}.  (The smallest possible match here for @samp{[ad]*?} that
+permits the whole expression to match is @samp{d}.)
+
+@item @samp{[ @dots{} ]}
+@cindex character alternative (in regexp)
+@cindex @samp{[} in regexp
+@cindex @samp{]} in regexp
+is a @dfn{character alternative}, which begins with @samp{[} and is
+terminated by @samp{]}.  In the simplest case, the characters between
+the two brackets are what this character alternative 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 alternative, 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 alternative.  A completely different set of characters is
+special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
+
+To include a @samp{]} in a character alternative, 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 character alternative, or put it after a range.  Thus, @samp{[]-]}
+matches both @samp{]} and @samp{-}.
+
+To include @samp{^} in a character alternative, put it anywhere but at
+the beginning.
+
+The beginning and end of a range of multibyte characters must be in
+the same character set (@pxref{Character Sets}).  Thus,
+@code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a}
+with grave accent) is in the Emacs character set for Latin-1 but the
+character 0x97c (@samp{u} with diaeresis) is in the Emacs character
+set for Latin-2.  (We use Lisp string syntax to write that example,
+and a few others in the next few paragraphs, in order to include hex
+escape sequences in them.)
+
+If a range starts with a unibyte character @var{c} and ends with a
+multibyte character @var{c2}, the range is divided into two parts: one
+is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
+@var{c1} is the first character of the charset to which @var{c2}
+belongs.
+
+You cannot always match all non-@acronym{ASCII} characters with the regular
+expression @code{"[\200-\377]"}.  This works when searching a unibyte
+buffer or string (@pxref{Text Representations}), but not in a multibyte
+buffer or string, because many non-@acronym{ASCII} characters have codes
+above octal 0377.  However, the regular expression @code{"[^\000-\177]"}
+does match all non-@acronym{ASCII} characters (see below regarding @samp{^}),
+in both multibyte and unibyte representations, because only the
+@acronym{ASCII} characters are excluded.
+
+A character alternative can also specify named
+character classes (@pxref{Char Classes}).  This is a POSIX feature whose
+syntax is @samp{[:@var{class}:]}.  Using a character class is equivalent
+to mentioning each of the characters in that class; but the latter is
+not feasible in practice, since some classes include thousands of
+different characters.
+
+@item @samp{[^ @dots{} ]}
+@cindex @samp{^} in regexp
+@samp{[^} begins a @dfn{complemented character alternative}.  This
+matches any character except the ones specified.  Thus,
+@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
+digits.
+
+@samp{^} is not special in a character alternative 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 alternative 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 @samp{^}
+@cindex beginning of line in regexp
+When matching a buffer, @samp{^} matches the empty string, but only at the
+beginning of a line in the text being matched (or the beginning of the
+accessible portion of the buffer).  Otherwise it fails to match
+anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at the
+beginning of a line.
+
+When matching a string instead of a buffer, @samp{^} matches at the
+beginning of the string or after a newline character.
+
+For historical compatibility reasons, @samp{^} can be used only at the
+beginning of the regular expression, or after @samp{\(}, @samp{\(?:}
+or @samp{\|}.
+
+@item @samp{$}
+@cindex @samp{$} in regexp
+@cindex end of line in regexp
+is similar to @samp{^} but matches only at the end of a line (or the
+end of the accessible portion of the buffer).  Thus, @samp{x+$}
+matches a string of one @samp{x} or more at the end of a line.
+
+When matching a string instead of a buffer, @samp{$} matches at the end
+of the string or before a newline character.
+
+For historical compatibility reasons, @samp{$} can be used only at the
+end of the regular expression, or before @samp{\)} or @samp{\|}.
+
+@item @samp{\}
+@cindex @samp{\} in regexp
+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.
+
+Note that @samp{\} also has special meaning in the read syntax of Lisp
+strings (@pxref{String Type}), and must be quoted with @samp{\}.  For
+example, the regular expression that matches the @samp{\} character is
+@samp{\\}.  To write a Lisp string that contains the characters
+@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
+@samp{\}.  Therefore, the read syntax for a regular expression matching
+@samp{\} is @code{"\\\\"}.@refill
+@end table
+
+@strong{Please 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; quote the
+special character anyway, regardless of where it appears.@refill
+
+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.
+
+In practice, most @samp{]} that occur in regular expressions close a
+character alternative and hence are special.  However, occasionally a
+regular expression may try to match a complex pattern of literal
+@samp{[} and @samp{]}.  In such situations, it sometimes may be
+necessary to carefully parse the regexp from the start to determine
+which square brackets enclose a character alternative.  For example,
+@samp{[^][]]} consists of the complemented character alternative
+@samp{[^][]} (which matches any single character that is not a square
+bracket), followed by a literal @samp{]}.
+
+The exact rules are that at the beginning of a regexp, @samp{[} is
+special and @samp{]} not.  This lasts until the first unquoted
+@samp{[}, after which we are in a character alternative; @samp{[} is
+no longer special (except when it starts a character class) but @samp{]}
+is special, unless it immediately follows the special @samp{[} or that
+@samp{[} followed by a @samp{^}.  This lasts until the next special
+@samp{]} that does not end a character class.  This ends the character
+alternative and restores the ordinary syntax of regular expressions;
+an unquoted @samp{[} is special again and a @samp{]} not.
+
+@node Char Classes
+@subsubsection Character Classes
+@cindex character classes in regexp
+
+  Here is a table of the classes you can use in a character alternative,
+and what they mean:
+
+@table @samp
+@item [:ascii:]
+This matches any @acronym{ASCII} character (codes 0--127).
+@item [:alnum:]
+This matches any letter or digit.  (At present, for multibyte
+characters, it matches anything that has word syntax.)
+@item [:alpha:]
+This matches any letter.  (At present, for multibyte characters, it
+matches anything that has word syntax.)
+@item [:blank:]
+This matches space and tab only.
+@item [:cntrl:]
+This matches any @acronym{ASCII} control character.
+@item [:digit:]
+This matches @samp{0} through @samp{9}.  Thus, @samp{[-+[:digit:]]}
+matches any digit, as well as @samp{+} and @samp{-}.
+@item [:graph:]
+This matches graphic characters---everything except @acronym{ASCII} control
+characters, space, and the delete character.
+@item [:lower:]
+This matches any lower-case letter, as determined by
+the current case table (@pxref{Case Tables}).
+@item [:multibyte:]
+This matches any multibyte character (@pxref{Text Representations}).
+@item [:nonascii:]
+This matches any non-@acronym{ASCII} character.
+@item [:print:]
+This matches printing characters---everything except @acronym{ASCII} control
+characters and the delete character.
+@item [:punct:]
+This matches any punctuation character.  (At present, for multibyte
+characters, it matches anything that has non-word syntax.)
+@item [:space:]
+This matches any character that has whitespace syntax
+(@pxref{Syntax Class Table}).
+@item [:unibyte:]
+This matches any unibyte character (@pxref{Text Representations}).
+@item [:upper:]
+This matches any upper-case letter, as determined by
+the current case table (@pxref{Case Tables}).
+@item [:word:]
+This matches any character that has word syntax (@pxref{Syntax Class
+Table}).
+@item [:xdigit:]
+This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
+through @samp{f} and @samp{A} through @samp{F}.
+@end table
+
+@node Regexp Backslash
+@subsubsection Backslash Constructs in Regular Expressions
+
+  For the most part, @samp{\} followed by any character matches only
+that character.  However, there are several exceptions: certain
+two-character sequences starting with @samp{\} that have special
+meanings.  (The character after the @samp{\} in such a sequence is
+always ordinary when used on its own.)  Here is a table of the special
+@samp{\} constructs.
+
+@table @samp
+@item \|
+@cindex @samp{|} in regexp
+@cindex regexp alternative
+specifies an alternative.
+Two regular expressions @var{a} and @var{b} with @samp{\|} in
+between form an expression that matches anything that either @var{a} or
+@var{b} matches.@refill
+
+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
+
+If you need full backtracking capability to handle multiple uses of
+@samp{\|}, use the POSIX regular expression functions (@pxref{POSIX
+Regexps}).
+
+@item \@{@var{m}\@}
+is a postfix operator that repeats the previous pattern exactly @var{m}
+times.  Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
+and nothing else.  @samp{c[ad]\@{3\@}r} matches string such as
+@samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
+
+@item \@{@var{m},@var{n}\@}
+is a more general postfix operator that specifies repetition with a
+minimum of @var{m} repeats and a maximum of @var{n} repeats.  If @var{m}
+is omitted, the minimum is 0; if @var{n} is omitted, there is no
+maximum.
+
+For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
+@samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
+nothing else.@*
+@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.	@*
+@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.	@*
+@samp{\@{1,\@}} is equivalent to @samp{+}.
+
+@item \( @dots{} \)
+@cindex @samp{(} in regexp
+@cindex @samp{)} in regexp
+@cindex regexp grouping
+is a grouping construct that serves three purposes:
+
+@enumerate
+@item
+To enclose a set of @samp{\|} alternatives for other operations.  Thus,
+the regular expression @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{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
+number (zero or more) of @samp{na} strings.
+
+@item
+To record a matched substring for future reference with
+@samp{\@var{digit}} (see below).
+@end enumerate
+
+This last application is not a consequence of the idea of a
+parenthetical grouping; it is a separate feature that was assigned as a
+second meaning to the same @samp{\( @dots{} \)} construct because, in
+practice, there was usually no conflict between the two meanings.  But
+occasionally there is a conflict, and that led to the introduction of
+shy groups.
+
+@item \(?: @dots{} \)
+is the @dfn{shy group} construct.  A shy group serves the first two
+purposes of an ordinary group (controlling the nesting of other
+operators), but it does not get a number, so you cannot refer back to
+its value with @samp{\@var{digit}}.
+
+Shy groups are particularly useful for mechanically-constructed regular
+expressions because they can be added automatically without altering the
+numbering of any ordinary, non-shy groups.
+
+@item \(?@var{num}: @dots{} \)
+is the @dfn{explicitly numbered group} construct.  Normal groups get
+their number implicitly, based on their position, which can be
+inconvenient.  This construct allows you to force a particular group
+number.  There is no particular restriction on the numbering,
+e.g.@: you can have several groups with the same number in which case
+the last one to match (i.e.@: the rightmost match) will win.
+Implicitly numbered groups always get the smallest integer larger than
+the one of any previous group.
+
+@item \@var{digit}
+matches the same text that matched the @var{digit}th occurrence of a
+grouping (@samp{\( @dots{} \)}) construct.
+
+In other words, after the end of a group, the matcher remembers the
+beginning and end of the text matched by that group.  Later on in the
+regular expression you can use @samp{\} followed by @var{digit} to
+match that same text, whatever it may have been.
+
+The strings matching the first nine grouping constructs appearing in
+the entire regular expression passed to a search or matching function
+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 grouping 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 @samp{\( @dots{} \)} construct matches more than once (which can
+happen, for instance, if it is followed by @samp{*}), only the last
+match is recorded.
+
+If a particular grouping construct in the regular expression was never
+matched---for instance, if it appears inside of an alternative that
+wasn't used, or inside of a repetition that repeated zero times---then
+the corresponding @samp{\@var{digit}} construct never matches
+anything.  To use an artificial example,, @samp{\(foo\(b*\)\|lose\)\2}
+cannot match @samp{lose}: the second alternative inside the larger
+group matches it, but then @samp{\2} is undefined and can't match
+anything.  But it can match @samp{foobb}, because the first
+alternative matches @samp{foob} and @samp{\2} matches @samp{b}.
+
+@item \w
+@cindex @samp{\w} in regexp
+matches any word-constituent character.  The editor syntax table
+determines which characters these are.  @xref{Syntax Tables}.
+
+@item \W
+@cindex @samp{\W} in regexp
+matches any character that is not a word constituent.
+
+@item \s@var{code}
+@cindex @samp{\s} in regexp
+matches any character whose syntax is @var{code}.  Here @var{code} is a
+character that represents a syntax code: thus, @samp{w} for word
+constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
+etc.  To represent whitespace syntax, use either @samp{-} or a space
+character.  @xref{Syntax Class Table}, for a list of syntax codes and
+the characters that stand for them.
+
+@item \S@var{code}
+@cindex @samp{\S} in regexp
+matches any character whose syntax is not @var{code}.
+
+@item \c@var{c}
+matches any character whose category is @var{c}.  Here @var{c} is a
+character that represents a category: thus, @samp{c} for Chinese
+characters or @samp{g} for Greek characters in the standard category
+table.
+
+@item \C@var{c}
+matches any character whose category is not @var{c}.
+@end table
+
+  The following regular expression constructs match the empty string---that is,
+they don't use up any characters---but whether they match depends on the
+context.  For all, the beginning and end of the accessible portion of
+the buffer are treated as if they were the actual beginning and end of
+the buffer.
+
+@table @samp
+@item \`
+@cindex @samp{\`} in regexp
+matches the empty string, but only at the beginning
+of the buffer or string being matched against.
+
+@item \'
+@cindex @samp{\'} in regexp
+matches the empty string, but only at the end of
+the buffer or string being matched against.
+
+@item \=
+@cindex @samp{\=} in regexp
+matches the empty string, but only at point.
+(This construct is not defined when matching against a string.)
+
+@item \b
+@cindex @samp{\b} in regexp
+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 (or string)
+regardless of what text appears next to it.
+
+@item \B
+@cindex @samp{\B} in regexp
+matches the empty string, but @emph{not} at the beginning or
+end of a word, nor at the beginning or end of the buffer (or string).
+
+@item \<
+@cindex @samp{\<} in regexp
+matches the empty string, but only at the beginning of a word.
+@samp{\<} matches at the beginning of the buffer (or string) only if a
+word-constituent character follows.
+
+@item \>
+@cindex @samp{\>} in regexp
+matches the empty string, but only at the end of a word.  @samp{\>}
+matches at the end of the buffer (or string) only if the contents end
+with a word-constituent character.
+
+@item \_<
+@cindex @samp{\_<} in regexp
+matches the empty string, but only at the beginning of a symbol.  A
+symbol is a sequence of one or more word or symbol constituent
+characters.  @samp{\_<} matches at the beginning of the buffer (or
+string) only if a symbol-constituent character follows.
+
+@item \_>
+@cindex @samp{\_>} in regexp
+matches the empty string, but only at the end of a symbol.  @samp{\_>}
+matches at the end of the buffer (or string) only if the contents end
+with a symbol-constituent character.
+@end table
+
+@kindex invalid-regexp
+  Not every string is a valid regular expression.  For example, a string
+that ends inside a character alternative without terminating @samp{]}
+is invalid, and so is a string that ends with a single @samp{\}.  If
+an invalid regular expression is passed to any of the search functions,
+an @code{invalid-regexp} error is signaled.
+
+@node Regexp Example
+@comment  node-name,  next,  previous,  up
+@subsection Complex Regexp Example
+
+  Here is a complicated regexp which was formerly used by Emacs to
+recognize the end of a sentence together with any whitespace that
+follows.  (Nowadays Emacs uses a similar but more complex default
+regexp constructed by the function @code{sentence-end}.
+@xref{Standard Regexps}.)
+
+  First, we show the regexp as a string in Lisp syntax to distinguish
+spaces from tab characters.  The string constant begins and ends with a
+double-quote.  @samp{\"} stands for a double-quote as part of the
+string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
+tab and @samp{\n} for a newline.
+
+@example
+"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
+@end example
+
+@noindent
+In contrast, if you evaluate this string, you will see the following:
+
+@example
+@group
+"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
+     @result{} "[.?!][]\"')@}]*\\($\\| $\\|  \\|@ @ \\)[
+]*"
+@end group
+@end example
+
+@noindent
+In this output, tab and newline appear as themselves.
+
+  This regular expression contains four parts in succession and can be
+deciphered as follows:
+
+@table @code
+@item [.?!]
+The first part of the pattern is a character alternative that matches
+any one of three characters: period, question mark, and exclamation
+mark.  The match must begin with one of these three characters.  (This
+is one point where the new default regexp used by Emacs differs from
+the old.  The new value also allows some non-@acronym{ASCII}
+characters that end a sentence without any following whitespace.)
+
+@item []\"')@}]*
+The second part of the pattern matches any closing braces and quotation
+marks, zero or more of them, that may follow the period, question mark
+or exclamation mark.  The @code{\"} is Lisp syntax for a double-quote in
+a string.  The @samp{*} at the end indicates that the immediately
+preceding regular expression (a character alternative, in this case) may be
+repeated zero or more times.
+
+@item \\($\\|@ $\\|\t\\|@ @ \\)
+The third part of the pattern matches the whitespace that follows the
+end of a sentence: the end of a line (optionally with a space), or a
+tab, or two spaces.  The double backslashes mark the parentheses and
+vertical bars as regular expression syntax; the parentheses delimit a
+group and the vertical bars separate alternatives.  The dollar sign is
+used to match the end of a line.
+
+@item [ \t\n]*
+Finally, the last part of the pattern matches any additional whitespace
+beyond the minimum needed to end a sentence.
+@end table
+
+@node Regexp Functions
+@subsection Regular Expression Functions
+
+  These functions operate on regular expressions.
+
+@defun regexp-quote string
+This function returns a regular expression whose only exact match is
+@var{string}.  Using this regular expression in @code{looking-at} will
+succeed only if the next characters in the buffer are @var{string};
+using it in a search function will succeed if the text being searched
+contains @var{string}.
+
+This allows you to request an exact string match or search when calling
+a function that wants a regular expression.
+
+@example
+@group
+(regexp-quote "^The cat$")
+     @result{} "\\^The cat\\$"
+@end group
+@end example
+
+One use of @code{regexp-quote} is to combine an exact string match with
+context described as a regular expression.  For example, this searches
+for the string that is the value of @var{string}, surrounded by
+whitespace:
+
+@example
+@group
+(re-search-forward
+ (concat "\\s-" (regexp-quote string) "\\s-"))
+@end group
+@end example
+@end defun
+
+@defun regexp-opt strings &optional paren
+This function returns an efficient regular expression that will match
+any of the strings in the list @var{strings}.  This is useful when you
+need to make matching or searching as fast as possible---for example,
+for Font Lock mode.
+
+If the optional argument @var{paren} is non-@code{nil}, then the
+returned regular expression is always enclosed by at least one
+parentheses-grouping construct.  If @var{paren} is @code{words}, then
+that construct is additionally surrounded by @samp{\<} and @samp{\>}.
+
+This simplified definition of @code{regexp-opt} produces a
+regular expression which is equivalent to the actual value
+(but not as efficient):
+
+@example
+(defun regexp-opt (strings paren)
+  (let ((open-paren (if paren "\\(" ""))
+        (close-paren (if paren "\\)" "")))
+    (concat open-paren
+            (mapconcat 'regexp-quote strings "\\|")
+            close-paren)))
+@end example
+@end defun
+
+@defun regexp-opt-depth regexp
+This function returns the total number of grouping constructs
+(parenthesized expressions) in @var{regexp}.  (This does not include
+shy groups.)
+@end defun
+
+@node Regexp Search
+@section Regular Expression Searching
+@cindex regular expression searching
+@cindex regexp searching
+@cindex searching for regexp
+
+  In GNU Emacs, you can search for the next match for a regular
+expression either incrementally or not.  For incremental search
+commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
+The GNU Emacs Manual}.  Here we describe only the search functions
+useful in programs.  The principal one is @code{re-search-forward}.
+
+  These search functions convert the regular expression to multibyte if
+the buffer is multibyte; they convert the regular expression to unibyte
+if the buffer is unibyte.  @xref{Text Representations}.
+
+@deffn Command re-search-forward regexp &optional limit noerror repeat
+This function searches forward in the current buffer for a string of
+text that is matched by the regular expression @var{regexp}.  The
+function skips over any amount of text that is not matched by
+@var{regexp}, and leaves point at the end of the first match found.
+It returns the new value of point.
+
+If @var{limit} is non-@code{nil}, it must be a position in the current
+buffer.  It specifies the upper bound to the search.  No match
+extending after that position is accepted.
+
+If @var{repeat} is supplied, it must be a positive number; the search
+is repeated that many times; each repetition starts at the end of the
+previous match.  If all these successive searches succeed, the search
+succeeds, moving point and returning its new value.  Otherwise the
+search fails.  What @code{re-search-forward} does when the search
+fails depends on the value of @var{noerror}:
+
+@table @asis
+@item @code{nil}
+Signal a @code{search-failed} error.
+@item @code{t}
+Do nothing and return @code{nil}.
+@item anything else
+Move point to @var{limit} (or the end of the accessible portion of the
+buffer) and return @code{nil}.
+@end table
+
+In the following example, point is initially before the @samp{T}.
+Evaluating the search call moves point to the end of that line (between
+the @samp{t} of @samp{hat} and the newline).
+
+@example
+@group
+---------- Buffer: foo ----------
+I read "@point{}The cat in the hat
+comes back" twice.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(re-search-forward "[a-z]+" nil t 5)
+     @result{} 27
+
+---------- Buffer: foo ----------
+I read "The cat in the hat@point{}
+comes back" twice.
+---------- Buffer: foo ----------
+@end group
+@end example
+@end deffn
+
+@deffn Command re-search-backward regexp &optional limit noerror repeat
+This function searches backward in the current buffer for a string of
+text that is matched by the regular expression @var{regexp}, leaving
+point at the beginning of the first text found.
+
+This function is analogous to @code{re-search-forward}, but they are not
+simple mirror images.  @code{re-search-forward} finds the match whose
+beginning is as close as possible to the starting point.  If
+@code{re-search-backward} were a perfect mirror image, it would find the
+match whose end is as close as possible.  However, in fact it finds the
+match whose beginning is as close as possible (and yet ends before the
+starting point).  The reason for this is that matching a regular
+expression at a given spot always works from beginning to end, and
+starts at a specified beginning position.
+
+A true mirror-image of @code{re-search-forward} would require a special
+feature for matching regular expressions from end to beginning.  It's
+not worth the trouble of implementing that.
+@end deffn
+
+@defun string-match regexp string &optional start
+This function returns the index of the start of the first match for
+the regular expression @var{regexp} in @var{string}, or @code{nil} if
+there is no match.  If @var{start} is non-@code{nil}, the search starts
+at that index in @var{string}.
+
+For example,
+
+@example
+@group
+(string-match
+ "quick" "The quick brown fox jumped quickly.")
+     @result{} 4
+@end group
+@group
+(string-match
+ "quick" "The quick brown fox jumped quickly." 8)
+     @result{} 27
+@end group
+@end example
+
+@noindent
+The index of the first character of the
+string is 0, the index of the second character is 1, and so on.
+
+After this function returns, the index of the first character beyond
+the match is available as @code{(match-end 0)}.  @xref{Match Data}.
+
+@example
+@group
+(string-match
+ "quick" "The quick brown fox jumped quickly." 8)
+     @result{} 27
+@end group
+
+@group
+(match-end 0)
+     @result{} 32
+@end group
+@end example
+@end defun
+
+@defun looking-at regexp
+This function determines whether the text in the current buffer directly
+following point matches the regular expression @var{regexp}.  ``Directly
+following'' means precisely that: the search is ``anchored'' and it can
+succeed only starting with the first character following point.  The
+result is @code{t} if so, @code{nil} otherwise.
+
+This function does not move point, but it updates the match data, which
+you can access using @code{match-beginning} and @code{match-end}.
+@xref{Match Data}.
+
+In this example, point is located directly before the @samp{T}.  If it
+were anywhere else, the result would be @code{nil}.
+
+@example
+@group
+---------- Buffer: foo ----------
+I read "@point{}The cat in the hat
+comes back" twice.
+---------- Buffer: foo ----------
+
+(looking-at "The cat in the hat$")
+     @result{} t
+@end group
+@end example
+@end defun
+
+@defun looking-back regexp &optional limit
+This function returns @code{t} if @var{regexp} matches text before
+point, ending at point, and @code{nil} otherwise.
+
+Because regular expression matching works only going forward, this is
+implemented by searching backwards from point for a match that ends at
+point.  That can be quite slow if it has to search a long distance.
+You can bound the time required by specifying @var{limit}, which says
+not to search before @var{limit}.  In this case, the match that is
+found must begin at or after @var{limit}.
+
+@example
+@group
+---------- Buffer: foo ----------
+I read "@point{}The cat in the hat
+comes back" twice.
+---------- Buffer: foo ----------
+
+(looking-back "read \"" 3)
+     @result{} t
+(looking-back "read \"" 4)
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defvar search-spaces-regexp
+If this variable is non-@code{nil}, it should be a regular expression
+that says how to search for whitespace.  In that case, any group of
+spaces in a regular expression being searched for stands for use of
+this regular expression.  However, spaces inside of constructs such as
+@samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by
+@code{search-spaces-regexp}.
+
+Since this variable affects all regular expression search and match
+constructs, you should bind it temporarily for as small as possible
+a part of the code.
+@end defvar
+
+@node POSIX Regexps
+@section POSIX Regular Expression Searching
+
+  The usual regular expression functions do backtracking when necessary
+to handle the @samp{\|} and repetition constructs, but they continue
+this only until they find @emph{some} match.  Then they succeed and
+report the first match found.
+
+  This section describes alternative search functions which perform the
+full backtracking specified by the POSIX standard for regular expression
+matching.  They continue backtracking until they have tried all
+possibilities and found all matches, so they can report the longest
+match, as required by POSIX.  This is much slower, so use these
+functions only when you really need the longest match.
+
+  The POSIX search and match functions do not properly support the
+non-greedy repetition operators.  This is because POSIX backtracking
+conflicts with the semantics of non-greedy repetition.
+
+@defun posix-search-forward regexp &optional limit noerror repeat
+This is like @code{re-search-forward} except that it performs the full
+backtracking specified by the POSIX standard for regular expression
+matching.
+@end defun
+
+@defun posix-search-backward regexp &optional limit noerror repeat
+This is like @code{re-search-backward} except that it performs the full
+backtracking specified by the POSIX standard for regular expression
+matching.
+@end defun
+
+@defun posix-looking-at regexp
+This is like @code{looking-at} except that it performs the full
+backtracking specified by the POSIX standard for regular expression
+matching.
+@end defun
+
+@defun posix-string-match regexp string &optional start
+This is like @code{string-match} except that it performs the full
+backtracking specified by the POSIX standard for regular expression
+matching.
+@end defun
+
+@node Match Data
+@section The Match Data
+@cindex match data
+
+  Emacs keeps track of the start and end positions of the segments of
+text found during a search; this is called the @dfn{match data}.
+Thanks to the match data, you can search for a complex pattern, such
+as a date in a mail message, and then extract parts of the match under
+control of the pattern.
+
+  Because the match data normally describe the most recent search only,
+you must be careful not to do another search inadvertently between the
+search you wish to refer back to and the use of the match data.  If you
+can't avoid another intervening search, you must save and restore the
+match data around it, to prevent it from being overwritten.
+
+@menu
+* Replacing Match::	  Replacing a substring that was matched.
+* Simple Match Data::     Accessing single items of match data,
+			    such as where a particular subexpression started.
+* Entire Match Data::     Accessing the entire match data at once, as a list.
+* Saving Match Data::     Saving and restoring the match data.
+@end menu
+
+@node Replacing Match
+@subsection Replacing the Text that Matched
+@cindex replace matched text
+
+  This function replaces all or part of the text matched by the last
+search.  It works by means of the match data.
+
+@cindex case in replacements
+@defun replace-match replacement &optional fixedcase literal string subexp
+This function replaces the text in the buffer (or in @var{string}) that
+was matched by the last search.  It replaces that text with
+@var{replacement}.
+
+If you did the last search in a buffer, you should specify @code{nil}
+for @var{string} and make sure that the current buffer when you call
+@code{replace-match} is the one in which you did the searching or
+matching.  Then @code{replace-match} does the replacement by editing
+the buffer; it leaves point at the end of the replacement text, and
+returns @code{t}.
+
+If you did the search in a string, pass the same string as @var{string}.
+Then @code{replace-match} does the replacement by constructing and
+returning a new string.
+
+If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses
+the replacement text without case conversion; otherwise, it converts
+the replacement text depending upon the capitalization of the text to
+be replaced.  If the original text is all upper case, this converts
+the replacement text to upper case.  If all words of the original text
+are capitalized, this capitalizes all the words of the replacement
+text.  If all the words are one-letter and they are all upper case,
+they are treated as capitalized words rather than all-upper-case
+words.
+
+If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
+exactly as it is, the only alterations being case changes as needed.
+If it is @code{nil} (the default), then the character @samp{\} is treated
+specially.  If a @samp{\} appears in @var{replacement}, then it must be
+part of one of the following sequences:
+
+@table @asis
+@item @samp{\&}
+@cindex @samp{&} in replacement
+@samp{\&} stands for the entire text being replaced.
+
+@item @samp{\@var{n}}
+@cindex @samp{\@var{n}} in replacement
+@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
+matched the @var{n}th subexpression in the original regexp.
+Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
+If the @var{n}th subexpression never matched, an empty string is substituted.
+
+@item @samp{\\}
+@cindex @samp{\} in replacement
+@samp{\\} stands for a single @samp{\} in the replacement text.
+@end table
+
+These substitutions occur after case conversion, if any,
+so the strings they substitute are never case-converted.
+
+If @var{subexp} is non-@code{nil}, that says to replace just
+subexpression number @var{subexp} of the regexp that was matched, not
+the entire match.  For example, after matching @samp{foo \(ba*r\)},
+calling @code{replace-match} with 1 as @var{subexp} means to replace
+just the text that matched @samp{\(ba*r\)}.
+@end defun
+
+@node Simple Match Data
+@subsection Simple Match Data Access
+
+  This section explains how to use the match data to find out what was
+matched by the last search or match operation, if it succeeded.
+
+  You can ask about the entire matching text, or about a particular
+parenthetical subexpression of a regular expression.  The @var{count}
+argument in the functions below specifies which.  If @var{count} is
+zero, you are asking about the entire match.  If @var{count} is
+positive, it specifies which subexpression you want.
+
+  Recall that the subexpressions of a regular expression are those
+expressions grouped with escaped parentheses, @samp{\(@dots{}\)}.  The
+@var{count}th subexpression is found by counting occurrences of
+@samp{\(} from the beginning of the whole regular expression.  The first
+subexpression is numbered 1, the second 2, and so on.  Only regular
+expressions can have subexpressions---after a simple string search, the
+only information available is about the entire match.
+
+  Every successful search sets the match data.  Therefore, you should
+query the match data immediately after searching, before calling any
+other function that might perform another search.  Alternatively, you
+may save and restore the match data (@pxref{Saving Match Data}) around
+the call to functions that could perform another search.
+
+  A search which fails may or may not alter the match data.  In the
+past, a failing search did not do this, but we may change it in the
+future.  So don't try to rely on the value of the match data after
+a failing search.
+
+@defun match-string count &optional in-string
+This function returns, as a string, the text matched in the last search
+or match operation.  It returns the entire text if @var{count} is zero,
+or just the portion corresponding to the @var{count}th parenthetical
+subexpression, if @var{count} is positive.
+
+If the last such operation was done against a string with
+@code{string-match}, then you should pass the same string as the
+argument @var{in-string}.  After a buffer search or match,
+you should omit @var{in-string} or pass @code{nil} for it; but you
+should make sure that the current buffer when you call
+@code{match-string} is the one in which you did the searching or
+matching.
+
+The value is @code{nil} if @var{count} is out of range, or for a
+subexpression inside a @samp{\|} alternative that wasn't used or a
+repetition that repeated zero times.
+@end defun
+
+@defun match-string-no-properties count &optional in-string
+This function is like @code{match-string} except that the result
+has no text properties.
+@end defun
+
+@defun match-beginning count
+This function returns the position of the start of text matched by the
+last regular expression searched for, or a subexpression of it.
+
+If @var{count} is zero, then the value is the position of the start of
+the entire match.  Otherwise, @var{count} specifies a subexpression in
+the regular expression, and the value of the function is the starting
+position of the match for that subexpression.
+
+The value is @code{nil} for a subexpression inside a @samp{\|}
+alternative that wasn't used or a repetition that repeated zero times.
+@end defun
+
+@defun match-end count
+This function is like @code{match-beginning} except that it returns the
+position of the end of the match, rather than the position of the
+beginning.
+@end defun
+
+  Here is an example of using the match data, with a comment showing the
+positions within the text:
+
+@example
+@group
+(string-match "\\(qu\\)\\(ick\\)"
+              "The quick fox jumped quickly.")
+              ;0123456789
+     @result{} 4
+@end group
+
+@group
+(match-string 0 "The quick fox jumped quickly.")
+     @result{} "quick"
+(match-string 1 "The quick fox jumped quickly.")
+     @result{} "qu"
+(match-string 2 "The quick fox jumped quickly.")
+     @result{} "ick"
+@end group
+
+@group
+(match-beginning 1)       ; @r{The beginning of the match}
+     @result{} 4                 ;   @r{with @samp{qu} is at index 4.}
+@end group
+
+@group
+(match-beginning 2)       ; @r{The beginning of the match}
+     @result{} 6                 ;   @r{with @samp{ick} is at index 6.}
+@end group
+
+@group
+(match-end 1)             ; @r{The end of the match}
+     @result{} 6                 ;   @r{with @samp{qu} is at index 6.}
+
+(match-end 2)             ; @r{The end of the match}
+     @result{} 9                 ;   @r{with @samp{ick} is at index 9.}
+@end group
+@end example
+
+  Here is another example.  Point is initially located at the beginning
+of the line.  Searching moves point to between the space and the word
+@samp{in}.  The beginning of the entire match is at the 9th character of
+the buffer (@samp{T}), and the beginning of the match for the first
+subexpression is at the 13th character (@samp{c}).
+
+@example
+@group
+(list
+  (re-search-forward "The \\(cat \\)")
+  (match-beginning 0)
+  (match-beginning 1))
+    @result{} (9 9 13)
+@end group
+
+@group
+---------- Buffer: foo ----------
+I read "The cat @point{}in the hat comes back" twice.
+        ^   ^
+        9  13
+---------- Buffer: foo ----------
+@end group
+@end example
+
+@noindent
+(In this case, the index returned is a buffer position; the first
+character of the buffer counts as 1.)
+
+@node Entire Match Data
+@subsection Accessing the Entire Match Data
+
+  The functions @code{match-data} and @code{set-match-data} read or
+write the entire match data, all at once.
+
+@defun match-data &optional integers reuse reseat
+This function returns a list of positions (markers or integers) that
+record all the information on what text the last search matched.
+Element zero is the position of the beginning of the match for the
+whole expression; element one is the position of the end of the match
+for the expression.  The next two elements are the positions of the
+beginning and end of the match for the first subexpression, and so on.
+In general, element
+@ifnottex
+number 2@var{n}
+@end ifnottex
+@tex
+number {\mathsurround=0pt $2n$}
+@end tex
+corresponds to @code{(match-beginning @var{n})}; and
+element
+@ifnottex
+number 2@var{n} + 1
+@end ifnottex
+@tex
+number {\mathsurround=0pt $2n+1$}
+@end tex
+corresponds to @code{(match-end @var{n})}.
+
+Normally all the elements are markers or @code{nil}, but if
+@var{integers} is non-@code{nil}, that means to use integers instead
+of markers.  (In that case, the buffer itself is appended as an
+additional element at the end of the list, to facilitate complete
+restoration of the match data.)  If the last match was done on a
+string with @code{string-match}, then integers are always used,
+since markers can't point into a string.
+
+If @var{reuse} is non-@code{nil}, it should be a list.  In that case,
+@code{match-data} stores the match data in @var{reuse}.  That is,
+@var{reuse} is destructively modified.  @var{reuse} does not need to
+have the right length.  If it is not long enough to contain the match
+data, it is extended.  If it is too long, the length of @var{reuse}
+stays the same, but the elements that were not used are set to
+@code{nil}.  The purpose of this feature is to reduce the need for
+garbage collection.
+
+If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
+are reseated to point to nowhere.
+
+As always, there must be no possibility of intervening searches between
+the call to a search function and the call to @code{match-data} that is
+intended to access the match data for that search.
+
+@example
+@group
+(match-data)
+     @result{}  (#<marker at 9 in foo>
+          #<marker at 17 in foo>
+          #<marker at 13 in foo>
+          #<marker at 17 in foo>)
+@end group
+@end example
+@end defun
+
+@defun set-match-data match-list &optional reseat
+This function sets the match data from the elements of @var{match-list},
+which should be a list that was the value of a previous call to
+@code{match-data}.  (More precisely, anything that has the same format
+will work.)
+
+If @var{match-list} refers to a buffer that doesn't exist, you don't get
+an error; that sets the match data in a meaningless but harmless way.
+
+If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
+are reseated to point to nowhere.
+
+@findex store-match-data
+@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
+@end defun
+
+@node Saving Match Data
+@subsection Saving and Restoring the Match Data
+
+  When you call a function that may do a search, you may need to save
+and restore the match data around that call, if you want to preserve the
+match data from an earlier search for later use.  Here is an example
+that shows the problem that arises if you fail to save the match data:
+
+@example
+@group
+(re-search-forward "The \\(cat \\)")
+     @result{} 48
+(foo)                   ; @r{Perhaps @code{foo} does}
+                        ;   @r{more searching.}
+(match-end 0)
+     @result{} 61              ; @r{Unexpected result---not 48!}
+@end group
+@end example
+
+  You can save and restore the match data with @code{save-match-data}:
+
+@defmac save-match-data body@dots{}
+This macro executes @var{body}, saving and restoring the match
+data around it.  The return value is the value of the last form in
+@var{body}.
+@end defmac
+
+  You could use @code{set-match-data} together with @code{match-data} to
+imitate the effect of the special form @code{save-match-data}.  Here is
+how:
+
+@example
+@group
+(let ((data (match-data)))
+  (unwind-protect
+      @dots{}   ; @r{Ok to change the original match data.}
+    (set-match-data data)))
+@end group
+@end example
+
+  Emacs automatically saves and restores the match data when it runs
+process filter functions (@pxref{Filter Functions}) and process
+sentinels (@pxref{Sentinels}).
+
+@ignore
+  Here is a function which restores the match data provided the buffer
+associated with it still exists.
+
+@smallexample
+@group
+(defun restore-match-data (data)
+@c It is incorrect to split the first line of a doc string.
+@c If there's a problem here, it should be solved in some other way.
+  "Restore the match data DATA unless the buffer is missing."
+  (catch 'foo
+    (let ((d data))
+@end group
+      (while d
+        (and (car d)
+             (null (marker-buffer (car d)))
+@group
+             ;; @file{match-data} @r{buffer is deleted.}
+             (throw 'foo nil))
+        (setq d (cdr d)))
+      (set-match-data data))))
+@end group
+@end smallexample
+@end ignore
+
+@node Search and Replace
+@section Search and Replace
+@cindex replacement after search
+@cindex searching and replacing
+
+  If you want to find all matches for a regexp in part of the buffer,
+and replace them, the best way is to write an explicit loop using
+@code{re-search-forward} and @code{replace-match}, like this:
+
+@example
+(while (re-search-forward "foo[ \t]+bar" nil t)
+  (replace-match "foobar"))
+@end example
+
+@noindent
+@xref{Replacing Match,, Replacing the Text that Matched}, for a
+description of @code{replace-match}.
+
+  However, replacing matches in a string is more complex, especially
+if you want to do it efficiently.  So Emacs provides a function to do
+this.
+
+@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
+This function copies @var{string} and searches it for matches for
+@var{regexp}, and replaces them with @var{rep}.  It returns the
+modified copy.  If @var{start} is non-@code{nil}, the search for
+matches starts at that index in @var{string}, so matches starting
+before that index are not changed.
+
+This function uses @code{replace-match} to do the replacement, and it
+passes the optional arguments @var{fixedcase}, @var{literal} and
+@var{subexp} along to @code{replace-match}.
+
+Instead of a string, @var{rep} can be a function.  In that case,
+@code{replace-regexp-in-string} calls @var{rep} for each match,
+passing the text of the match as its sole argument.  It collects the
+value @var{rep} returns and passes that to @code{replace-match} as the
+replacement string.  The match-data at this point are the result
+of matching @var{regexp} against a substring of @var{string}.
+@end defun
+
+  If you want to write a command along the lines of @code{query-replace},
+you can use @code{perform-replace} to do the work.
+
+@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
+This function is the guts of @code{query-replace} and related
+commands.  It searches for occurrences of @var{from-string} in the
+text between positions @var{start} and @var{end} and replaces some or
+all of them.  If @var{start} is @code{nil} (or omitted), point is used
+instead, and the end of the buffer's accessible portion is used for
+@var{end}.
+
+If @var{query-flag} is @code{nil}, it replaces all
+occurrences; otherwise, it asks the user what to do about each one.
+
+If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
+considered a regular expression; otherwise, it must match literally.  If
+@var{delimited-flag} is non-@code{nil}, then only replacements
+surrounded by word boundaries are considered.
+
+The argument @var{replacements} specifies what to replace occurrences
+with.  If it is a string, that string is used.  It can also be a list of
+strings, to be used in cyclic order.
+
+If @var{replacements} is a cons cell, @code{(@var{function}
+. @var{data})}, this means to call @var{function} after each match to
+get the replacement text.  This function is called with two arguments:
+@var{data}, and the number of replacements already made.
+
+If @var{repeat-count} is non-@code{nil}, it should be an integer.  Then
+it specifies how many times to use each of the strings in the
+@var{replacements} list before advancing cyclically to the next one.
+
+If @var{from-string} contains upper-case letters, then
+@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
+it uses the @code{replacements} without altering the case of them.
+
+Normally, the keymap @code{query-replace-map} defines the possible
+user responses for queries.  The argument @var{map}, if
+non-@code{nil}, specifies a keymap to use instead of
+@code{query-replace-map}.
+@end defun
+
+@defvar query-replace-map
+This variable holds a special keymap that defines the valid user
+responses for @code{perform-replace} and the commands that use it, as
+well as @code{y-or-n-p} and @code{map-y-or-n-p}.  This map is unusual
+in two ways:
+
+@itemize @bullet
+@item
+The ``key bindings'' are not commands, just symbols that are meaningful
+to the functions that use this map.
+
+@item
+Prefix keys are not supported; each key binding must be for a
+single-event key sequence.  This is because the functions don't use
+@code{read-key-sequence} to get the input; instead, they read a single
+event and look it up ``by hand.''
+@end itemize
+@end defvar
+
+Here are the meaningful ``bindings'' for @code{query-replace-map}.
+Several of them are meaningful only for @code{query-replace} and
+friends.
+
+@table @code
+@item act
+Do take the action being considered---in other words, ``yes.''
+
+@item skip
+Do not take action for this question---in other words, ``no.''
+
+@item exit
+Answer this question ``no,'' and give up on the entire series of
+questions, assuming that the answers will be ``no.''
+
+@item act-and-exit
+Answer this question ``yes,'' and give up on the entire series of
+questions, assuming that subsequent answers will be ``no.''
+
+@item act-and-show
+Answer this question ``yes,'' but show the results---don't advance yet
+to the next question.
+
+@item automatic
+Answer this question and all subsequent questions in the series with
+``yes,'' without further user interaction.
+
+@item backup
+Move back to the previous place that a question was asked about.
+
+@item edit
+Enter a recursive edit to deal with this question---instead of any
+other action that would normally be taken.
+
+@item delete-and-edit
+Delete the text being considered, then enter a recursive edit to replace
+it.
+
+@item recenter
+Redisplay and center the window, then ask the same question again.
+
+@item quit
+Perform a quit right away.  Only @code{y-or-n-p} and related functions
+use this answer.
+
+@item help
+Display some help, then ask again.
+@end table
+
+@node Standard Regexps
+@section Standard Regular Expressions Used in Editing
+@cindex regexps used standardly in editing
+@cindex standard regexps used in editing
+
+  This section describes some variables that hold regular expressions
+used for certain purposes in editing:
+
+@defvar page-delimiter
+This is the regular expression describing line-beginnings that separate
+pages.  The default value is @code{"^\014"} (i.e., @code{"^^L"} or
+@code{"^\C-l"}); this matches a line that starts with a formfeed
+character.
+@end defvar
+
+  The following two regular expressions should @emph{not} assume the
+match always starts at the beginning of a line; they should not use
+@samp{^} to anchor the match.  Most often, the paragraph commands do
+check for a match only at the beginning of a line, which means that
+@samp{^} would be superfluous.  When there is a nonzero left margin,
+they accept matches that start after the left margin.  In that case, a
+@samp{^} would be incorrect.  However, a @samp{^} is harmless in modes
+where a left margin is never used.
+
+@defvar paragraph-separate
+This is the regular expression for recognizing the beginning of a line
+that separates paragraphs.  (If you change this, you may have to
+change @code{paragraph-start} also.)  The default value is
+@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
+spaces, tabs, and form feeds (after its left margin).
+@end defvar
+
+@defvar paragraph-start
+This is the regular expression for recognizing the beginning of a line
+that starts @emph{or} separates paragraphs.  The default value is
+@w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
+whitespace or starting with a form feed (after its left margin).
+@end defvar
+
+@defvar sentence-end
+If non-@code{nil}, the value should be a regular expression describing
+the end of a sentence, including the whitespace following the
+sentence.  (All paragraph boundaries also end sentences, regardless.)
+
+If the value is @code{nil}, the default, then the function
+@code{sentence-end} has to construct the regexp.  That is why you
+should always call the function @code{sentence-end} to obtain the
+regexp to be used to recognize the end of a sentence.
+@end defvar
+
+@defun sentence-end
+This function returns the value of the variable @code{sentence-end},
+if non-@code{nil}.  Otherwise it returns a default value based on the
+values of the variables @code{sentence-end-double-space}
+(@pxref{Definition of sentence-end-double-space}),
+@code{sentence-end-without-period} and
+@code{sentence-end-without-space}.
+@end defun
+
+@ignore
+   arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f
+@end ignore
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
new file mode 100644
index 00000000000..7e66549412b
--- /dev/null
+++ b/doc/lispref/sequences.texi
@@ -0,0 +1,734 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/sequences
+@node Sequences Arrays Vectors, Hash Tables, Lists, Top
+@chapter Sequences, Arrays, and Vectors
+@cindex sequence
+
+  Recall that the @dfn{sequence} type is the union of two other Lisp
+types: lists and arrays.  In other words, any list is a sequence, and
+any array is a sequence.  The common property that all sequences have is
+that each is an ordered collection of elements.
+
+  An @dfn{array} is a single primitive object that has a slot for each
+of its elements.  All the elements are accessible in constant time, but
+the length of an existing array cannot be changed.  Strings, vectors,
+char-tables and bool-vectors are the four types of arrays.
+
+  A list is a sequence of elements, but it is not a single primitive
+object; it is made of cons cells, one cell per element.  Finding the
+@var{n}th element requires looking through @var{n} cons cells, so
+elements farther from the beginning of the list take longer to access.
+But it is possible to add elements to the list, or remove elements.
+
+  The following diagram shows the relationship between these types:
+
+@example
+@group
+          _____________________________________________
+         |                                             |
+         |          Sequence                           |
+         |  ______   ________________________________  |
+         | |      | |                                | |
+         | | List | |             Array              | |
+         | |      | |    ________       ________     | |
+         | |______| |   |        |     |        |    | |
+         |          |   | Vector |     | String |    | |
+         |          |   |________|     |________|    | |
+         |          |  ____________   _____________  | |
+         |          | |            | |             | | |
+         |          | | Char-table | | Bool-vector | | |
+         |          | |____________| |_____________| | |
+         |          |________________________________| |
+         |_____________________________________________|
+@end group
+@end example
+
+  The elements of vectors and lists may be any Lisp objects.  The
+elements of strings are all characters.
+
+@menu
+* Sequence Functions::    Functions that accept any kind of sequence.
+* Arrays::                Characteristics of arrays in Emacs Lisp.
+* Array Functions::       Functions specifically for arrays.
+* Vectors::               Special characteristics of Emacs Lisp vectors.
+* Vector Functions::      Functions specifically for vectors.
+* Char-Tables::           How to work with char-tables.
+* Bool-Vectors::          How to work with bool-vectors.
+@end menu
+
+@node Sequence Functions
+@section Sequences
+
+  In Emacs Lisp, a @dfn{sequence} is either a list or an array.  The
+common property of all sequences is that they are ordered collections of
+elements.  This section describes functions that accept any kind of
+sequence.
+
+@defun sequencep object
+Returns @code{t} if @var{object} is a list, vector, string,
+bool-vector, or char-table, @code{nil} otherwise.
+@end defun
+
+@defun length sequence
+@cindex string length
+@cindex list length
+@cindex vector length
+@cindex sequence length
+@cindex char-table length
+This function returns the number of elements in @var{sequence}.  If
+@var{sequence} is a dotted list, a @code{wrong-type-argument} error is
+signaled.  Circular lists may cause an infinite loop.  For a
+char-table, the value returned is always one more than the maximum
+Emacs character code.
+
+@xref{Definition of safe-length}, for the related function @code{safe-length}.
+
+@example
+@group
+(length '(1 2 3))
+    @result{} 3
+@end group
+@group
+(length ())
+    @result{} 0
+@end group
+@group
+(length "foobar")
+    @result{} 6
+@end group
+@group
+(length [1 2 3])
+    @result{} 3
+@end group
+@group
+(length (make-bool-vector 5 nil))
+    @result{} 5
+@end group
+@end example
+@end defun
+
+@noindent
+See also @code{string-bytes}, in @ref{Text Representations}.
+
+@defun elt sequence index
+@cindex elements of sequences
+This function returns the element of @var{sequence} indexed by
+@var{index}.  Legitimate values of @var{index} are integers ranging
+from 0 up to one less than the length of @var{sequence}.  If
+@var{sequence} is a list, out-of-range values behave as for
+@code{nth}.  @xref{Definition of nth}.  Otherwise, out-of-range values
+trigger an @code{args-out-of-range} error.
+
+@example
+@group
+(elt [1 2 3 4] 2)
+     @result{} 3
+@end group
+@group
+(elt '(1 2 3 4) 2)
+     @result{} 3
+@end group
+@group
+;; @r{We use @code{string} to show clearly which character @code{elt} returns.}
+(string (elt "1234" 2))
+     @result{} "3"
+@end group
+@group
+(elt [1 2 3 4] 4)
+     @error{} Args out of range: [1 2 3 4], 4
+@end group
+@group
+(elt [1 2 3 4] -1)
+     @error{} Args out of range: [1 2 3 4], -1
+@end group
+@end example
+
+This function generalizes @code{aref} (@pxref{Array Functions}) and
+@code{nth} (@pxref{Definition of nth}).
+@end defun
+
+@defun copy-sequence sequence
+@cindex copying sequences
+Returns a copy of @var{sequence}.  The copy is the same type of object
+as the original sequence, and it has the same elements in the same order.
+
+Storing a new element into the copy does not affect the original
+@var{sequence}, and vice versa.  However, the elements of the new
+sequence are not copies; they are identical (@code{eq}) to the elements
+of the original.  Therefore, changes made within these elements, as
+found via the copied sequence, are also visible in the original
+sequence.
+
+If the sequence is a string with text properties, the property list in
+the copy is itself a copy, not shared with the original's property
+list.  However, the actual values of the properties are shared.
+@xref{Text Properties}.
+
+This function does not work for dotted lists.  Trying to copy a
+circular list may cause an infinite loop.
+
+See also @code{append} in @ref{Building Lists}, @code{concat} in
+@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions},
+for other ways to copy sequences.
+
+@example
+@group
+(setq bar '(1 2))
+     @result{} (1 2)
+@end group
+@group
+(setq x (vector 'foo bar))
+     @result{} [foo (1 2)]
+@end group
+@group
+(setq y (copy-sequence x))
+     @result{} [foo (1 2)]
+@end group
+
+@group
+(eq x y)
+     @result{} nil
+@end group
+@group
+(equal x y)
+     @result{} t
+@end group
+@group
+(eq (elt x 1) (elt y 1))
+     @result{} t
+@end group
+
+@group
+;; @r{Replacing an element of one sequence.}
+(aset x 0 'quux)
+x @result{} [quux (1 2)]
+y @result{} [foo (1 2)]
+@end group
+
+@group
+;; @r{Modifying the inside of a shared element.}
+(setcar (aref x 1) 69)
+x @result{} [quux (69 2)]
+y @result{} [foo (69 2)]
+@end group
+@end example
+@end defun
+
+@node Arrays
+@section Arrays
+@cindex array
+
+  An @dfn{array} object has slots that hold a number of other Lisp
+objects, called the elements of the array.  Any element of an array may
+be accessed in constant time.  In contrast, an element of a list
+requires access time that is proportional to the position of the element
+in the list.
+
+  Emacs defines four types of array, all one-dimensional: @dfn{strings},
+@dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.  A vector is a
+general array; its elements can be any Lisp objects.  A string is a
+specialized array; its elements must be characters.  Each type of array
+has its own read syntax.
+@xref{String Type}, and @ref{Vector Type}.
+
+  All four kinds of array share these characteristics:
+
+@itemize @bullet
+@item
+The first element of an array has index zero, the second element has
+index 1, and so on.  This is called @dfn{zero-origin} indexing.  For
+example, an array of four elements has indices 0, 1, 2, @w{and 3}.
+
+@item
+The length of the array is fixed once you create it; you cannot
+change the length of an existing array.
+
+@item
+For purposes of evaluation, the array is a constant---in other words,
+it evaluates to itself.
+
+@item
+The elements of an array may be referenced or changed with the functions
+@code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
+@end itemize
+
+    When you create an array, other than a char-table, you must specify
+its length.  You cannot specify the length of a char-table, because that
+is determined by the range of character codes.
+
+  In principle, if you want an array of text characters, you could use
+either a string or a vector.  In practice, we always choose strings for
+such applications, for four reasons:
+
+@itemize @bullet
+@item
+They occupy one-fourth the space of a vector of the same elements.
+
+@item
+Strings are printed in a way that shows the contents more clearly
+as text.
+
+@item
+Strings can hold text properties.  @xref{Text Properties}.
+
+@item
+Many of the specialized editing and I/O facilities of Emacs accept only
+strings.  For example, you cannot insert a vector of characters into a
+buffer the way you can insert a string.  @xref{Strings and Characters}.
+@end itemize
+
+  By contrast, for an array of keyboard input characters (such as a key
+sequence), a vector may be necessary, because many keyboard input
+characters are outside the range that will fit in a string.  @xref{Key
+Sequence Input}.
+
+@node Array Functions
+@section Functions that Operate on Arrays
+
+  In this section, we describe the functions that accept all types of
+arrays.
+
+@defun arrayp object
+This function returns @code{t} if @var{object} is an array (i.e., a
+vector, a string, a bool-vector or a char-table).
+
+@example
+@group
+(arrayp [a])
+     @result{} t
+(arrayp "asdf")
+     @result{} t
+(arrayp (syntax-table))    ;; @r{A char-table.}
+     @result{} t
+@end group
+@end example
+@end defun
+
+@defun aref array index
+@cindex array elements
+This function returns the @var{index}th element of @var{array}.  The
+first element is at index zero.
+
+@example
+@group
+(setq primes [2 3 5 7 11 13])
+     @result{} [2 3 5 7 11 13]
+(aref primes 4)
+     @result{} 11
+@end group
+@group
+(aref "abcdefg" 1)
+     @result{} 98           ; @r{@samp{b} is @acronym{ASCII} code 98.}
+@end group
+@end example
+
+See also the function @code{elt}, in @ref{Sequence Functions}.
+@end defun
+
+@defun aset array index object
+This function sets the @var{index}th element of @var{array} to be
+@var{object}.  It returns @var{object}.
+
+@example
+@group
+(setq w [foo bar baz])
+     @result{} [foo bar baz]
+(aset w 0 'fu)
+     @result{} fu
+w
+     @result{} [fu bar baz]
+@end group
+
+@group
+(setq x "asdfasfd")
+     @result{} "asdfasfd"
+(aset x 3 ?Z)
+     @result{} 90
+x
+     @result{} "asdZasfd"
+@end group
+@end example
+
+If @var{array} is a string and @var{object} is not a character, a
+@code{wrong-type-argument} error results.  The function converts a
+unibyte string to multibyte if necessary to insert a character.
+@end defun
+
+@defun fillarray array object
+This function fills the array @var{array} with @var{object}, so that
+each element of @var{array} is @var{object}.  It returns @var{array}.
+
+@example
+@group
+(setq a [a b c d e f g])
+     @result{} [a b c d e f g]
+(fillarray a 0)
+     @result{} [0 0 0 0 0 0 0]
+a
+     @result{} [0 0 0 0 0 0 0]
+@end group
+@group
+(setq s "When in the course")
+     @result{} "When in the course"
+(fillarray s ?-)
+     @result{} "------------------"
+@end group
+@end example
+
+If @var{array} is a string and @var{object} is not a character, a
+@code{wrong-type-argument} error results.
+@end defun
+
+The general sequence functions @code{copy-sequence} and @code{length}
+are often useful for objects known to be arrays.  @xref{Sequence Functions}.
+
+@node Vectors
+@section Vectors
+@cindex vector (type)
+
+  Arrays in Lisp, like arrays in most languages, are blocks of memory
+whose elements can be accessed in constant time.  A @dfn{vector} is a
+general-purpose array of specified length; its elements can be any Lisp
+objects.  (By contrast, a string can hold only characters as elements.)
+Vectors in Emacs are used for obarrays (vectors of symbols), and as part
+of keymaps (vectors of commands).  They are also used internally as part
+of the representation of a byte-compiled function; if you print such a
+function, you will see a vector in it.
+
+  In Emacs Lisp, the indices of the elements of a vector start from zero
+and count up from there.
+
+  Vectors are printed with square brackets surrounding the elements.
+Thus, a vector whose elements are the symbols @code{a}, @code{b} and
+@code{a} is printed as @code{[a b a]}.  You can write vectors in the
+same way in Lisp input.
+
+  A vector, like a string or a number, is considered a constant for
+evaluation: the result of evaluating it is the same vector.  This does
+not evaluate or even examine the elements of the vector.
+@xref{Self-Evaluating Forms}.
+
+  Here are examples illustrating these principles:
+
+@example
+@group
+(setq avector [1 two '(three) "four" [five]])
+     @result{} [1 two (quote (three)) "four" [five]]
+(eval avector)
+     @result{} [1 two (quote (three)) "four" [five]]
+(eq avector (eval avector))
+     @result{} t
+@end group
+@end example
+
+@node Vector Functions
+@section Functions for Vectors
+
+  Here are some functions that relate to vectors:
+
+@defun vectorp object
+This function returns @code{t} if @var{object} is a vector.
+
+@example
+@group
+(vectorp [a])
+     @result{} t
+(vectorp "asdf")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun vector &rest objects
+This function creates and returns a vector whose elements are the
+arguments, @var{objects}.
+
+@example
+@group
+(vector 'foo 23 [bar baz] "rats")
+     @result{} [foo 23 [bar baz] "rats"]
+(vector)
+     @result{} []
+@end group
+@end example
+@end defun
+
+@defun make-vector length object
+This function returns a new vector consisting of @var{length} elements,
+each initialized to @var{object}.
+
+@example
+@group
+(setq sleepy (make-vector 9 'Z))
+     @result{} [Z Z Z Z Z Z Z Z Z]
+@end group
+@end example
+@end defun
+
+@defun vconcat &rest sequences
+@cindex copying vectors
+This function returns a new vector containing all the elements of the
+@var{sequences}.  The arguments @var{sequences} may be true lists,
+vectors, strings or bool-vectors.  If no @var{sequences} are given, an
+empty vector is returned.
+
+The value is a newly constructed vector that is not @code{eq} to any
+existing vector.
+
+@example
+@group
+(setq a (vconcat '(A B C) '(D E F)))
+     @result{} [A B C D E F]
+(eq a (vconcat a))
+     @result{} nil
+@end group
+@group
+(vconcat)
+     @result{} []
+(vconcat [A B C] "aa" '(foo (6 7)))
+     @result{} [A B C 97 97 foo (6 7)]
+@end group
+@end example
+
+The @code{vconcat} function also allows byte-code function objects as
+arguments.  This is a special feature to make it easy to access the entire
+contents of a byte-code function object.  @xref{Byte-Code Objects}.
+
+In Emacs versions before 21, the @code{vconcat} function allowed
+integers as arguments, converting them to strings of digits, but that
+feature has been eliminated.  The proper way to convert an integer to
+a decimal number in this way is with @code{format} (@pxref{Formatting
+Strings}) or @code{number-to-string} (@pxref{String Conversion}).
+
+For other concatenation functions, see @code{mapconcat} in @ref{Mapping
+Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
+in @ref{Building Lists}.
+@end defun
+
+  The @code{append} function also provides a way to convert a vector into a
+list with the same elements:
+
+@example
+@group
+(setq avector [1 two (quote (three)) "four" [five]])
+     @result{} [1 two (quote (three)) "four" [five]]
+(append avector nil)
+     @result{} (1 two (quote (three)) "four" [five])
+@end group
+@end example
+
+@node Char-Tables
+@section Char-Tables
+@cindex char-tables
+@cindex extra slots of char-table
+
+  A char-table is much like a vector, except that it is indexed by
+character codes.  Any valid character code, without modifiers, can be
+used as an index in a char-table.  You can access a char-table's
+elements with @code{aref} and @code{aset}, as with any array.  In
+addition, a char-table can have @dfn{extra slots} to hold additional
+data not associated with particular character codes.  Char-tables are
+constants when evaluated.
+
+@cindex subtype of char-table
+  Each char-table has a @dfn{subtype} which is a symbol.  The subtype
+has two purposes: to distinguish char-tables meant for different uses,
+and to control the number of extra slots.  For example, display tables
+are char-tables with @code{display-table} as the subtype, and syntax
+tables are char-tables with @code{syntax-table} as the subtype.  A valid
+subtype must have a @code{char-table-extra-slots} property which is an
+integer between 0 and 10.  This integer specifies the number of
+@dfn{extra slots} in the char-table.
+
+@cindex parent of char-table
+  A char-table can have a @dfn{parent}, which is another char-table.  If
+it does, then whenever the char-table specifies @code{nil} for a
+particular character @var{c}, it inherits the value specified in the
+parent.  In other words, @code{(aref @var{char-table} @var{c})} returns
+the value from the parent of @var{char-table} if @var{char-table} itself
+specifies @code{nil}.
+
+@cindex default value of char-table
+  A char-table can also have a @dfn{default value}.  If so, then
+@code{(aref @var{char-table} @var{c})} returns the default value
+whenever the char-table does not specify any other non-@code{nil} value.
+
+@defun make-char-table subtype &optional init
+Return a newly created char-table, with subtype @var{subtype}.  Each
+element is initialized to @var{init}, which defaults to @code{nil}.  You
+cannot alter the subtype of a char-table after the char-table is
+created.
+
+There is no argument to specify the length of the char-table, because
+all char-tables have room for any valid character code as an index.
+@end defun
+
+@defun char-table-p object
+This function returns @code{t} if @var{object} is a char-table,
+otherwise @code{nil}.
+@end defun
+
+@defun char-table-subtype char-table
+This function returns the subtype symbol of @var{char-table}.
+@end defun
+
+@defun set-char-table-default char-table char new-default
+This function sets the default value of generic character @var{char}
+in @var{char-table} to @var{new-default}.
+
+There is no special function to access default values in a char-table.
+To do that, use @code{char-table-range} (see below).
+@end defun
+
+@defun char-table-parent char-table
+This function returns the parent of @var{char-table}.  The parent is
+always either @code{nil} or another char-table.
+@end defun
+
+@defun set-char-table-parent char-table new-parent
+This function sets the parent of @var{char-table} to @var{new-parent}.
+@end defun
+
+@defun char-table-extra-slot char-table n
+This function returns the contents of extra slot @var{n} of
+@var{char-table}.  The number of extra slots in a char-table is
+determined by its subtype.
+@end defun
+
+@defun set-char-table-extra-slot char-table n value
+This function stores @var{value} in extra slot @var{n} of
+@var{char-table}.
+@end defun
+
+  A char-table can specify an element value for a single character code;
+it can also specify a value for an entire character set.
+
+@defun char-table-range char-table range
+This returns the value specified in @var{char-table} for a range of
+characters @var{range}.  Here are the possibilities for @var{range}:
+
+@table @asis
+@item @code{nil}
+Refers to the default value.
+
+@item @var{char}
+Refers to the element for character @var{char}
+(supposing @var{char} is a valid character code).
+
+@item @var{charset}
+Refers to the value specified for the whole character set
+@var{charset} (@pxref{Character Sets}).
+
+@item @var{generic-char}
+A generic character stands for a character set, or a row of a
+character set; specifying the generic character as argument is
+equivalent to specifying the character set name.  @xref{Splitting
+Characters}, for a description of generic characters.
+@end table
+@end defun
+
+@defun set-char-table-range char-table range value
+This function sets the value in @var{char-table} for a range of
+characters @var{range}.  Here are the possibilities for @var{range}:
+
+@table @asis
+@item @code{nil}
+Refers to the default value.
+
+@item @code{t}
+Refers to the whole range of character codes.
+
+@item @var{char}
+Refers to the element for character @var{char}
+(supposing @var{char} is a valid character code).
+
+@item @var{charset}
+Refers to the value specified for the whole character set
+@var{charset} (@pxref{Character Sets}).
+
+@item @var{generic-char}
+A generic character stands for a character set; specifying the generic
+character as argument is equivalent to specifying the character set
+name.  @xref{Splitting Characters}, for a description of generic characters.
+@end table
+@end defun
+
+@defun map-char-table function char-table
+This function calls @var{function} for each element of @var{char-table}.
+@var{function} is called with two arguments, a key and a value.  The key
+is a possible @var{range} argument for @code{char-table-range}---either
+a valid character or a generic character---and the value is
+@code{(char-table-range @var{char-table} @var{key})}.
+
+Overall, the key-value pairs passed to @var{function} describe all the
+values stored in @var{char-table}.
+
+The return value is always @code{nil}; to make this function useful,
+@var{function} should have side effects.  For example,
+here is how to examine each element of the syntax table:
+
+@example
+(let (accumulator)
+  (map-char-table
+   #'(lambda (key value)
+       (setq accumulator
+             (cons (list key value) accumulator)))
+   (syntax-table))
+  accumulator)
+@result{}
+((475008 nil) (474880 nil) (474752 nil) (474624 nil)
+ ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
+@end example
+@end defun
+
+@node Bool-Vectors
+@section Bool-vectors
+@cindex Bool-vectors
+
+  A bool-vector is much like a vector, except that it stores only the
+values @code{t} and @code{nil}.  If you try to store any non-@code{nil}
+value into an element of the bool-vector, the effect is to store
+@code{t} there.  As with all arrays, bool-vector indices start from 0,
+and the length cannot be changed once the bool-vector is created.
+Bool-vectors are constants when evaluated.
+
+  There are two special functions for working with bool-vectors; aside
+from that, you manipulate them with same functions used for other kinds
+of arrays.
+
+@defun make-bool-vector length initial
+Return a new bool-vector of @var{length} elements,
+each one initialized to @var{initial}.
+@end defun
+
+@defun bool-vector-p object
+This returns @code{t} if @var{object} is a bool-vector,
+and @code{nil} otherwise.
+@end defun
+
+  Here is an example of creating, examining, and updating a
+bool-vector.  Note that the printed form represents up to 8 boolean
+values as a single character.
+
+@example
+(setq bv (make-bool-vector 5 t))
+     @result{} #&5"^_"
+(aref bv 1)
+     @result{} t
+(aset bv 3 nil)
+     @result{} nil
+bv
+     @result{} #&5"^W"
+@end example
+
+@noindent
+These results make sense because the binary codes for control-_ and
+control-W are 11111 and 10111, respectively.
+
+@ignore
+   arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386
+@end ignore
diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile
new file mode 100644
index 00000000000..b373d00bebf
--- /dev/null
+++ b/doc/lispref/spellfile
@@ -0,0 +1,738 @@
+ARPA
+Abbrev
+Acknowledgements
+Alan
+Arnold
+Autoloading
+BAppend
+Backquote
+Beeping
+Beverly
+Boyes
+Brian
+CL
+CSWKg
+Carl
+Carroll
+Chris
+Cleanups
+DEC
+DStandard
+Dan
+Dired's
+Disassembly
+Duff
+EMAC
+EMACSLOADPATH
+Eckelkamp
+Edward
+Eirik
+Emacses
+Eric
+Erlebacher
+Fcar
+Fcdr
+Fcons
+Fcoordinates
+Feval
+Frazzle
+Frederick
+Fri
+Gardiner
+Gentlemen
+HAL
+HATTED
+HS
+HU
+Hanchrow
+Hartzell
+Hess
+Hewlett
+IBM
+ISBN
+Impl
+Interning
+Ithought
+J's
+Jacobson
+Jak
+Joe
+Jones
+Jr
+Jul
+Keymaps
+Kimmo
+Kirman
+Knighten
+Korz
+Krawitz
+LTsHm
+LaLiberte
+LaTeX
+Lammens
+Local'
+MAC
+MONIES
+MSS
+Maclisp
+Magill
+Marick
+Matthew
+Minibuf
+Misc
+Miscellany
+Mocklisp
+Montanaro
+Myers
+NFS
+Nathan
+Nope
+OS
+OSITIONS
+Oct
+Ovwrt
+PURESIZE
+Packard
+Qlistp
+Qnil
+RMAIL
+Raul
+Resizing
+Robbins
+Rockwell
+SCO
+SIGCONT
+SIGHUP
+SIGINT
+SIGKILL
+SIGQUIT
+SIGTSTP
+SLOAD
+Scoordinates
+Set'
+Setcar
+Setcdr
+Shinichirou
+Snarf
+Sor
+SourceFile
+Stops'
+Subprocess
+Sugou
+Sunview
+Suominen
+T's
+TCP
+ThXs
+Tharp
+Thu
+Trost
+UCB
+UNEVALLED
+UNGCPRO
+UniPlus
+UniSoft's
+VMS
+Vip
+Void'
+Warren
+Welty
+Wethought
+Wilding
+Worley
+Wright
+XDVI
+XFASTINT
+XINT
+XWINDOW
+Xs
+Yo
+Zuhn
+aB
+aa
+aaa
+abbrevname
+abbrevs
+abc
+abcdefg
+abcxyz
+abd
+above'
+abracadabra
+address'
+after'
+alist
+alists
+anchored'
+and'
+ar
+aref
+arg'th
+argdecl
+arith
+arrayp
+arrow'
+asa
+asdZasfd
+asdf
+asdfasfd
+aset
+assoc
+assq
+at'
+aug
+autoload
+automatic'
+automatically'
+avector
+bBuffer
+bFrobnicate
+ba
+back'
+bananana
+barfoo
+barx
+bballs
+before'
+beforep
+bfoo
+bil
+binding's
+bish
+bobp
+bolp
+bottommost
+boundp
+brief'
+buf
+buffer'
+bufferp
+buttercup
+ca
+caaaar
+caaar
+caddaar
+cadr
+callable
+cbreak
+ce
+cell'
+cells'
+cf
+chaprm
+character'
+childp
+chistory
+ck
+column'
+commandp
+concat
+cond
+conses
+consing
+consp
+constant'
+contains'
+continuable
+convert'
+copyleft
+correct'
+counterintuitive
+cr
+creatable
+customie
+deactivate
+deactivated
+deassigns
+decrement'
+deffnx
+definition'
+defmacro
+defsubr
+deletable
+deletion'
+delq
+depiction
+descendents
+deselecting
+destructive'
+destructively'
+diffs
+ding
+directory'
+dired
+dirname
+disassembler
+dland
+docfile
+docstring
+doesnt
+dont
+down'
+downcasing
+downloadable
+dribble
+dup
+ef
+efg
+electric'
+elided
+elt
+enablement
+endkeyfun
+endrecfun
+environment'
+eobp
+eof
+eol
+eolp
+eq
+eqlsign
+erminal
+erste
+etags
+eval
+evalled
+evals
+evaluate'
+excess'
+exec
+exitcode
+expression'
+extendible
+extra'
+fails'
+fascist
+fboundp
+featurep
+ff
+fg
+fi
+file'
+filespec
+filesystems
+fillarray
+firstchar
+firstonly
+fixedcase
+fixit
+fixup
+floatp
+fmakunbound
+fns
+fo
+fol
+folded'
+following'
+fooba
+foobaz
+foox
+for'
+formfeed
+forms'
+forw
+forwa
+found'
+frob
+from'
+front'
+fset
+fstab
+ftp
+fu
+funtions
+garbles
+gc
+gcpro
+gd
+getenv
+getprv
+gid
+gnuemacs
+gp
+grep
+gtr
+halves'
+hand'
+hashes'
+hd
+hexadecimal
+hf
+hfil
+hookvar
+horsechestnut
+hostname
+hpux
+hscroll
+ibmapa
+ick
+id
+idiom
+ii
+indrm
+inode
+input'
+inputinput
+inserting'
+integerp
+intermixed
+ints
+inturned
+irreversibly
+jum
+keymapp
+kill'
+killed'
+killp
+kludge
+kolstad
+language'
+lastchar
+lcl
+ledit
+leif
+lessp
+level'
+lewis
+library'
+link'
+lisplib
+listexp
+loadable
+loadst
+loadup
+logand
+logior
+lognot
+logxor
+long'
+loop's
+lru
+lrwxrwxrwx
+ls
+lsh
+m's
+macroexpand
+makunbound
+malloc
+mapatoms
+mapconcat
+mapvar
+mark'
+marker's
+markerp
+mathsurround
+medit
+memq
+mh
+mim
+mini
+minibuffer's
+minibuffers
+misalignment
+misnamed
+mode's
+modename
+modes'
+mods
+modtime
+mqueue
+msg
+multicharacter
+myfile
+nCount
+nXExpression
+na
+name's
+natnump
+nb
+nbBuffer
+nconc
+newdef
+newelt
+newname
+nextrecfun
+nfsusr
+ninett
+nlines
+nlinks
+nlistp
+noconfirm
+nodigits
+noerror
+noforce
+nomessage
+nominees
+nomsg
+nonblank
+nonconstant
+nondestructive
+nondirectory
+nonidentical
+noninteractive
+noninteractively
+nonletter
+nonletters
+nonlocally
+nonoverlapping
+nonprinting
+nonselected
+nonsequentially
+nonvoid
+nonwarranty
+nonwritable
+noop
+noprint
+norecord
+normal'
+noselect
+nosuffix
+nots
+noundo
+nr
+nreverse
+ns
+nsRename
+nth
+nthcdr
+num
+number'
+numberp
+nums
+obarray
+obarrays
+object'
+oldbuf
+olddef
+oldname
+oo
+oops
+op
+or'
+otl
+out'
+over'
+overful
+overfullrule
+overstrike
+overstriking
+overstruck
+p'
+paren
+part'
+passwd
+pe
+ped
+perverse
+pid
+plist
+pnt
+pointer'
+pointm
+pos
+preallocate
+predicale
+preload
+prepend
+prepended
+prepends
+pretty'
+prin
+princ
+print'
+printenv
+printer'
+proc
+process'
+processp
+programmer'
+prolog
+protect'
+ps
+psf
+psychotherapy
+pty
+purecopy
+qu
+quux
+rassq
+reader'
+readin
+rebind
+rec
+rechecking
+recursively'
+recycler'
+redo
+redrawing
+redraws
+redump
+reenabled
+reexposed
+reg
+region'
+reindent
+reindents
+reinitialization
+reinitialize
+reinitialized
+reinstall
+reinstalled
+resize
+resized
+resizes
+reversibly
+reworded
+rhetorical
+right'
+ring'
+risky
+rmailedit
+rms
+rplaca
+rplacd
+rtu
+runnable
+rw
+rwxrwxrwx
+sDescribe
+sans
+se
+searching'
+section'
+seed'
+sequence'
+sequencep
+setp
+setplist
+setprv
+settable
+setuid
+sexp
+sexps
+shape'
+shell's
+sideline
+special'
+specpdl
+st
+stanford
+startkeyfun
+str
+stringp
+stty
+subcategories
+subcommands
+subexp
+subform
+subforms
+subjob
+submap
+subprocesses
+subr
+subr'
+subroutine'
+subrp
+subrs
+subwindows
+sugar'
+suid
+supersession
+suspension'
+symbolp
+symlink
+syms
+syntatic
+tabname
+temacs
+temporarily'
+tempvar
+tenths
+termcap
+termcaps
+terminfo
+termscript
+termtype
+terpri
+text'
+textrm
+textsl
+texttt
+than'
+the'
+tildes
+time's
+to'
+towars
+transportable
+txt
+types'
+uid
+unbind
+unbinding
+unbinds
+unchanged'
+unclutters
+undefine
+undefines
+underfull
+undo's
+undodata
+unevaluated'
+unexec
+unexpand
+unhesitatingly
+uninterned
+unisoft
+unpaired
+unread
+unreadable
+unreading
+unsaved
+untyped
+ununderline
+up'
+uptime
+usecount
+used'
+user'
+userlock
+usg
+val
+varbind
+varname
+varref
+vars
+varset
+vb
+vconcat
+vectorp
+vfil
+vi
+vn
+voidness
+vrs
+vt
+window'
+windowing
+windowp
+wrapped'
+xSpecify
+xcoord
+xcssun
+xemacs
+xenix
+xf
+xfirst
+xoff
+xon
+xx
+xxxxx
+xxxxxxxxx
+xy
+xyz
+ycoord
+yes'
+zA
+zap
+zerop
diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
new file mode 100644
index 00000000000..7356c119a1e
--- /dev/null
+++ b/doc/lispref/streams.texi
@@ -0,0 +1,837 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/streams
+@node Read and Print, Minibuffers, Debugging, Top
+@comment  node-name,  next,  previous,  up
+@chapter Reading and Printing Lisp Objects
+
+  @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
+objects to textual form and vice versa.  They use the printed
+representations and read syntax described in @ref{Lisp Data Types}.
+
+  This chapter describes the Lisp functions for reading and printing.
+It also describes @dfn{streams}, which specify where to get the text (if
+reading) or where to put it (if printing).
+
+@menu
+* Streams Intro::     Overview of streams, reading and printing.
+* Input Streams::     Various data types that can be used as input streams.
+* Input Functions::   Functions to read Lisp objects from text.
+* Output Streams::    Various data types that can be used as output streams.
+* Output Functions::  Functions to print Lisp objects as text.
+* Output Variables::  Variables that control what the printing functions do.
+@end menu
+
+@node Streams Intro
+@section Introduction to Reading and Printing
+@cindex Lisp reader
+@cindex printing
+@cindex reading
+
+  @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
+form and producing a corresponding Lisp object.  This is how Lisp
+programs get into Lisp from files of Lisp code.  We call the text the
+@dfn{read syntax} of the object.  For example, the text @samp{(a .@: 5)}
+is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
+@sc{cdr} is the number 5.
+
+  @dfn{Printing} a Lisp object means producing text that represents that
+object---converting the object to its @dfn{printed representation}
+(@pxref{Printed Representation}).  Printing the cons cell described
+above produces the text @samp{(a .@: 5)}.
+
+  Reading and printing are more or less inverse operations: printing the
+object that results from reading a given piece of text often produces
+the same text, and reading the text that results from printing an object
+usually produces a similar-looking object.  For example, printing the
+symbol @code{foo} produces the text @samp{foo}, and reading that text
+returns the symbol @code{foo}.  Printing a list whose elements are
+@code{a} and @code{b} produces the text @samp{(a b)}, and reading that
+text produces a list (but not the same list) with elements @code{a}
+and @code{b}.
+
+  However, these two operations are not precisely inverse to each other.
+There are three kinds of exceptions:
+
+@itemize @bullet
+@item
+Printing can produce text that cannot be read.  For example, buffers,
+windows, frames, subprocesses and markers print as text that starts
+with @samp{#}; if you try to read this text, you get an error.  There is
+no way to read those data types.
+
+@item
+One object can have multiple textual representations.  For example,
+@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
+@samp{(a .@: (b))} represent the same list.  Reading will accept any of
+the alternatives, but printing must choose one of them.
+
+@item
+Comments can appear at certain points in the middle of an object's
+read sequence without affecting the result of reading it.
+@end itemize
+
+@node Input Streams
+@section Input Streams
+@cindex stream (for reading)
+@cindex input stream
+
+  Most of the Lisp functions for reading text take an @dfn{input stream}
+as an argument.  The input stream specifies where or how to get the
+characters of the text to be read.  Here are the possible types of input
+stream:
+
+@table @asis
+@item @var{buffer}
+@cindex buffer input stream
+The input characters are read from @var{buffer}, starting with the
+character directly after point.  Point advances as characters are read.
+
+@item @var{marker}
+@cindex marker input stream
+The input characters are read from the buffer that @var{marker} is in,
+starting with the character directly after the marker.  The marker
+position advances as characters are read.  The value of point in the
+buffer has no effect when the stream is a marker.
+
+@item @var{string}
+@cindex string input stream
+The input characters are taken from @var{string}, starting at the first
+character in the string and using as many characters as required.
+
+@item @var{function}
+@cindex function input stream
+The input characters are generated by @var{function}, which must support
+two kinds of calls:
+
+@itemize @bullet
+@item
+When it is called with no arguments, it should return the next character.
+
+@item
+When it is called with one argument (always a character), @var{function}
+should save the argument and arrange to return it on the next call.
+This is called @dfn{unreading} the character; it happens when the Lisp
+reader reads one character too many and wants to ``put it back where it
+came from.''  In this case, it makes no difference what value
+@var{function} returns.
+@end itemize
+
+@item @code{t}
+@cindex @code{t} input stream
+@code{t} used as a stream means that the input is read from the
+minibuffer.  In fact, the minibuffer is invoked once and the text
+given by the user is made into a string that is then used as the
+input stream.  If Emacs is running in batch mode, standard input is used
+instead of the minibuffer.  For example,
+@example
+(message "%s" (read t))
+@end example
+will read a Lisp expression from standard input and print the result
+to standard output.
+
+@item @code{nil}
+@cindex @code{nil} input stream
+@code{nil} supplied as an input stream means to use the value of
+@code{standard-input} instead; that value is the @dfn{default input
+stream}, and must be a non-@code{nil} input stream.
+
+@item @var{symbol}
+A symbol as input stream is equivalent to the symbol's function
+definition (if any).
+@end table
+
+  Here is an example of reading from a stream that is a buffer, showing
+where point is located before and after:
+
+@example
+@group
+---------- Buffer: foo ----------
+This@point{} is the contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(read (get-buffer "foo"))
+     @result{} is
+@end group
+@group
+(read (get-buffer "foo"))
+     @result{} the
+@end group
+
+@group
+---------- Buffer: foo ----------
+This is the@point{} contents of foo.
+---------- Buffer: foo ----------
+@end group
+@end example
+
+@noindent
+Note that the first read skips a space.  Reading skips any amount of
+whitespace preceding the significant text.
+
+  Here is an example of reading from a stream that is a marker,
+initially positioned at the beginning of the buffer shown.  The value
+read is the symbol @code{This}.
+
+@example
+@group
+
+---------- Buffer: foo ----------
+This is the contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
+     @result{} #<marker at 1 in foo>
+@end group
+@group
+(read m)
+     @result{} This
+@end group
+@group
+m
+     @result{} #<marker at 5 in foo>   ;; @r{Before the first space.}
+@end group
+@end example
+
+  Here we read from the contents of a string:
+
+@example
+@group
+(read "(When in) the course")
+     @result{} (When in)
+@end group
+@end example
+
+  The following example reads from the minibuffer.  The
+prompt is: @w{@samp{Lisp expression: }}.  (That is always the prompt
+used when you read from the stream @code{t}.)  The user's input is shown
+following the prompt.
+
+@example
+@group
+(read t)
+     @result{} 23
+---------- Buffer: Minibuffer ----------
+Lisp expression: @kbd{23 @key{RET}}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+  Finally, here is an example of a stream that is a function, named
+@code{useless-stream}.  Before we use the stream, we initialize the
+variable @code{useless-list} to a list of characters.  Then each call to
+the function @code{useless-stream} obtains the next character in the list
+or unreads a character by adding it to the front of the list.
+
+@example
+@group
+(setq useless-list (append "XY()" nil))
+     @result{} (88 89 40 41)
+@end group
+
+@group
+(defun useless-stream (&optional unread)
+  (if unread
+      (setq useless-list (cons unread useless-list))
+    (prog1 (car useless-list)
+           (setq useless-list (cdr useless-list)))))
+     @result{} useless-stream
+@end group
+@end example
+
+@noindent
+Now we read using the stream thus constructed:
+
+@example
+@group
+(read 'useless-stream)
+     @result{} XY
+@end group
+
+@group
+useless-list
+     @result{} (40 41)
+@end group
+@end example
+
+@noindent
+Note that the open and close parentheses remain in the list.  The Lisp
+reader encountered the open parenthesis, decided that it ended the
+input, and unread it.  Another attempt to read from the stream at this
+point would read @samp{()} and return @code{nil}.
+
+@defun get-file-char
+This function is used internally as an input stream to read from the
+input file opened by the function @code{load}.  Don't use this function
+yourself.
+@end defun
+
+@node Input Functions
+@section Input Functions
+
+  This section describes the Lisp functions and variables that pertain
+to reading.
+
+  In the functions below, @var{stream} stands for an input stream (see
+the previous section).  If @var{stream} is @code{nil} or omitted, it
+defaults to the value of @code{standard-input}.
+
+@kindex end-of-file
+  An @code{end-of-file} error is signaled if reading encounters an
+unterminated list, vector, or string.
+
+@defun read &optional stream
+This function reads one textual Lisp expression from @var{stream},
+returning it as a Lisp object.  This is the basic Lisp input function.
+@end defun
+
+@defun read-from-string string &optional start end
+@cindex string to object
+This function reads the first textual Lisp expression from the text in
+@var{string}.  It returns a cons cell whose @sc{car} is that expression,
+and whose @sc{cdr} is an integer giving the position of the next
+remaining character in the string (i.e., the first one not read).
+
+If @var{start} is supplied, then reading begins at index @var{start} in
+the string (where the first character is at index 0).  If you specify
+@var{end}, then reading is forced to stop just before that index, as if
+the rest of the string were not there.
+
+For example:
+
+@example
+@group
+(read-from-string "(setq x 55) (setq y 5)")
+     @result{} ((setq x 55) . 11)
+@end group
+@group
+(read-from-string "\"A short string\"")
+     @result{} ("A short string" . 16)
+@end group
+
+@group
+;; @r{Read starting at the first character.}
+(read-from-string "(list 112)" 0)
+     @result{} ((list 112) . 10)
+@end group
+@group
+;; @r{Read starting at the second character.}
+(read-from-string "(list 112)" 1)
+     @result{} (list . 5)
+@end group
+@group
+;; @r{Read starting at the seventh character,}
+;;   @r{and stopping at the ninth.}
+(read-from-string "(list 112)" 6 8)
+     @result{} (11 . 8)
+@end group
+@end example
+@end defun
+
+@defvar standard-input
+This variable holds the default input stream---the stream that
+@code{read} uses when the @var{stream} argument is @code{nil}.
+The default is @code{t}, meaning use the minibuffer.
+@end defvar
+
+@node Output Streams
+@section Output Streams
+@cindex stream (for printing)
+@cindex output stream
+
+  An output stream specifies what to do with the characters produced
+by printing.  Most print functions accept an output stream as an
+optional argument.  Here are the possible types of output stream:
+
+@table @asis
+@item @var{buffer}
+@cindex buffer output stream
+The output characters are inserted into @var{buffer} at point.
+Point advances as characters are inserted.
+
+@item @var{marker}
+@cindex marker output stream
+The output characters are inserted into the buffer that @var{marker}
+points into, at the marker position.  The marker position advances as
+characters are inserted.  The value of point in the buffer has no effect
+on printing when the stream is a marker, and this kind of printing
+does not move point (except that if the marker points at or before the
+position of point, point advances with the surrounding text, as
+usual).
+
+@item @var{function}
+@cindex function output stream
+The output characters are passed to @var{function}, which is responsible
+for storing them away.  It is called with a single character as
+argument, as many times as there are characters to be output, and
+is responsible for storing the characters wherever you want to put them.
+
+@item @code{t}
+@cindex @code{t} output stream
+The output characters are displayed in the echo area.
+
+@item @code{nil}
+@cindex @code{nil} output stream
+@code{nil} specified as an output stream means to use the value of
+@code{standard-output} instead; that value is the @dfn{default output
+stream}, and must not be @code{nil}.
+
+@item @var{symbol}
+A symbol as output stream is equivalent to the symbol's function
+definition (if any).
+@end table
+
+  Many of the valid output streams are also valid as input streams.  The
+difference between input and output streams is therefore more a matter
+of how you use a Lisp object, than of different types of object.
+
+  Here is an example of a buffer used as an output stream.  Point is
+initially located as shown immediately before the @samp{h} in
+@samp{the}.  At the end, point is located directly before that same
+@samp{h}.
+
+@cindex print example
+@example
+@group
+---------- Buffer: foo ----------
+This is t@point{}he contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+(print "This is the output" (get-buffer "foo"))
+     @result{} "This is the output"
+
+@group
+---------- Buffer: foo ----------
+This is t
+"This is the output"
+@point{}he contents of foo.
+---------- Buffer: foo ----------
+@end group
+@end example
+
+  Now we show a use of a marker as an output stream.  Initially, the
+marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
+the word @samp{the}.  At the end, the marker has advanced over the
+inserted text so that it remains positioned before the same @samp{h}.
+Note that the location of point, shown in the usual fashion, has no
+effect.
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the @point{}output
+---------- Buffer: foo ----------
+@end group
+
+@group
+(setq m (copy-marker 10))
+     @result{} #<marker at 10 in foo>
+@end group
+
+@group
+(print "More output for foo." m)
+     @result{} "More output for foo."
+@end group
+
+@group
+---------- Buffer: foo ----------
+This is t
+"More output for foo."
+he @point{}output
+---------- Buffer: foo ----------
+@end group
+
+@group
+m
+     @result{} #<marker at 34 in foo>
+@end group
+@end example
+
+  The following example shows output to the echo area:
+
+@example
+@group
+(print "Echo Area output" t)
+     @result{} "Echo Area output"
+---------- Echo Area ----------
+"Echo Area output"
+---------- Echo Area ----------
+@end group
+@end example
+
+  Finally, we show the use of a function as an output stream.  The
+function @code{eat-output} takes each character that it is given and
+conses it onto the front of the list @code{last-output} (@pxref{Building
+Lists}).  At the end, the list contains all the characters output, but
+in reverse order.
+
+@example
+@group
+(setq last-output nil)
+     @result{} nil
+@end group
+
+@group
+(defun eat-output (c)
+  (setq last-output (cons c last-output)))
+     @result{} eat-output
+@end group
+
+@group
+(print "This is the output" 'eat-output)
+     @result{} "This is the output"
+@end group
+
+@group
+last-output
+     @result{} (10 34 116 117 112 116 117 111 32 101 104
+    116 32 115 105 32 115 105 104 84 34 10)
+@end group
+@end example
+
+@noindent
+Now we can put the output in the proper order by reversing the list:
+
+@example
+@group
+(concat (nreverse last-output))
+     @result{} "
+\"This is the output\"
+"
+@end group
+@end example
+
+@noindent
+Calling @code{concat} converts the list to a string so you can see its
+contents more clearly.
+
+@node Output Functions
+@section Output Functions
+
+  This section describes the Lisp functions for printing Lisp
+objects---converting objects into their printed representation.
+
+@cindex @samp{"} in printing
+@cindex @samp{\} in printing
+@cindex quoting characters in printing
+@cindex escape characters in printing
+  Some of the Emacs printing functions add quoting characters to the
+output when necessary so that it can be read properly.  The quoting
+characters used are @samp{"} and @samp{\}; they distinguish strings from
+symbols, and prevent punctuation characters in strings and symbols from
+being taken as delimiters when reading.  @xref{Printed Representation},
+for full details.  You specify quoting or no quoting by the choice of
+printing function.
+
+  If the text is to be read back into Lisp, then you should print with
+quoting characters to avoid ambiguity.  Likewise, if the purpose is to
+describe a Lisp object clearly for a Lisp programmer.  However, if the
+purpose of the output is to look nice for humans, then it is usually
+better to print without quoting.
+
+  Lisp objects can refer to themselves.  Printing a self-referential
+object in the normal way would require an infinite amount of text, and
+the attempt could cause infinite recursion.  Emacs detects such
+recursion and prints @samp{#@var{level}} instead of recursively printing
+an object already being printed.  For example, here @samp{#0} indicates
+a recursive reference to the object at level 0 of the current print
+operation:
+
+@example
+(setq foo (list nil))
+     @result{} (nil)
+(setcar foo foo)
+     @result{} (#0)
+@end example
+
+  In the functions below, @var{stream} stands for an output stream.
+(See the previous section for a description of output streams.)  If
+@var{stream} is @code{nil} or omitted, it defaults to the value of
+@code{standard-output}.
+
+@defun print object &optional stream
+@cindex Lisp printer
+The @code{print} function is a convenient way of printing.  It outputs
+the printed representation of @var{object} to @var{stream}, printing in
+addition one newline before @var{object} and another after it.  Quoting
+characters are used.  @code{print} returns @var{object}.  For example:
+
+@example
+@group
+(progn (print 'The\ cat\ in)
+       (print "the hat")
+       (print " came back"))
+     @print{}
+     @print{} The\ cat\ in
+     @print{}
+     @print{} "the hat"
+     @print{}
+     @print{} " came back"
+     @result{} " came back"
+@end group
+@end example
+@end defun
+
+@defun prin1 object &optional stream
+This function outputs the printed representation of @var{object} to
+@var{stream}.  It does not print newlines to separate output as
+@code{print} does, but it does use quoting characters just like
+@code{print}.  It returns @var{object}.
+
+@example
+@group
+(progn (prin1 'The\ cat\ in)
+       (prin1 "the hat")
+       (prin1 " came back"))
+     @print{} The\ cat\ in"the hat"" came back"
+     @result{} " came back"
+@end group
+@end example
+@end defun
+
+@defun princ object &optional stream
+This function outputs the printed representation of @var{object} to
+@var{stream}.  It returns @var{object}.
+
+This function is intended to produce output that is readable by people,
+not by @code{read}, so it doesn't insert quoting characters and doesn't
+put double-quotes around the contents of strings.  It does not add any
+spacing between calls.
+
+@example
+@group
+(progn
+  (princ 'The\ cat)
+  (princ " in the \"hat\""))
+     @print{} The cat in the "hat"
+     @result{} " in the \"hat\""
+@end group
+@end example
+@end defun
+
+@defun terpri &optional stream
+@cindex newline in print
+This function outputs a newline to @var{stream}.  The name stands
+for ``terminate print.''
+@end defun
+
+@defun write-char character &optional stream
+This function outputs @var{character} to @var{stream}.  It returns
+@var{character}.
+@end defun
+
+@defun prin1-to-string object &optional noescape
+@cindex object to string
+This function returns a string containing the text that @code{prin1}
+would have printed for the same argument.
+
+@example
+@group
+(prin1-to-string 'foo)
+     @result{} "foo"
+@end group
+@group
+(prin1-to-string (mark-marker))
+     @result{} "#<marker at 2773 in strings.texi>"
+@end group
+@end example
+
+If @var{noescape} is non-@code{nil}, that inhibits use of quoting
+characters in the output.  (This argument is supported in Emacs versions
+19 and later.)
+
+@example
+@group
+(prin1-to-string "foo")
+     @result{} "\"foo\""
+@end group
+@group
+(prin1-to-string "foo" t)
+     @result{} "foo"
+@end group
+@end example
+
+See @code{format}, in @ref{Formatting Strings}, for other ways to obtain
+the printed representation of a Lisp object as a string.
+@end defun
+
+@defmac with-output-to-string body@dots{}
+This macro executes the @var{body} forms with @code{standard-output} set
+up to feed output into a string.  Then it returns that string.
+
+For example, if the current buffer name is @samp{foo},
+
+@example
+(with-output-to-string
+  (princ "The buffer is ")
+  (princ (buffer-name)))
+@end example
+
+@noindent
+returns @code{"The buffer is foo"}.
+@end defmac
+
+@node Output Variables
+@section Variables Affecting Output
+@cindex output-controlling variables
+
+@defvar standard-output
+The value of this variable is the default output stream---the stream
+that print functions use when the @var{stream} argument is @code{nil}.
+The default is @code{t}, meaning display in the echo area.
+@end defvar
+
+@defvar print-quoted
+If this is non-@code{nil}, that means to print quoted forms using
+abbreviated reader syntax.  @code{(quote foo)} prints as @code{'foo},
+@code{(function foo)} as @code{#'foo}, and backquoted forms print
+using modern backquote syntax.
+@end defvar
+
+@defvar print-escape-newlines
+@cindex @samp{\n} in print
+@cindex escape characters
+If this variable is non-@code{nil}, then newline characters in strings
+are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
+Normally these characters are printed as actual newlines and formfeeds.
+
+This variable affects the print functions @code{prin1} and @code{print}
+that print with quoting.  It does not affect @code{princ}.  Here is an
+example using @code{prin1}:
+
+@example
+@group
+(prin1 "a\nb")
+     @print{} "a
+     @print{} b"
+     @result{} "a
+b"
+@end group
+
+@group
+(let ((print-escape-newlines t))
+  (prin1 "a\nb"))
+     @print{} "a\nb"
+     @result{} "a
+b"
+@end group
+@end example
+
+@noindent
+In the second expression, the local binding of
+@code{print-escape-newlines} is in effect during the call to
+@code{prin1}, but not during the printing of the result.
+@end defvar
+
+@defvar print-escape-nonascii
+If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII}
+characters in strings are unconditionally printed as backslash sequences
+by the print functions @code{prin1} and @code{print} that print with
+quoting.
+
+Those functions also use backslash sequences for unibyte non-@acronym{ASCII}
+characters, regardless of the value of this variable, when the output
+stream is a multibyte buffer or a marker pointing into one.
+@end defvar
+
+@defvar print-escape-multibyte
+If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII}
+characters in strings are unconditionally printed as backslash sequences
+by the print functions @code{prin1} and @code{print} that print with
+quoting.
+
+Those functions also use backslash sequences for multibyte
+non-@acronym{ASCII} characters, regardless of the value of this variable,
+when the output stream is a unibyte buffer or a marker pointing into
+one.
+@end defvar
+
+@defvar print-length
+@cindex printing limits
+The value of this variable is the maximum number of elements to print in
+any list, vector or bool-vector.  If an object being printed has more
+than this many elements, it is abbreviated with an ellipsis.
+
+If the value is @code{nil} (the default), then there is no limit.
+
+@example
+@group
+(setq print-length 2)
+     @result{} 2
+@end group
+@group
+(print '(1 2 3 4 5))
+     @print{} (1 2 ...)
+     @result{} (1 2 ...)
+@end group
+@end example
+@end defvar
+
+@defvar print-level
+The value of this variable is the maximum depth of nesting of
+parentheses and brackets when printed.  Any list or vector at a depth
+exceeding this limit is abbreviated with an ellipsis.  A value of
+@code{nil} (which is the default) means no limit.
+@end defvar
+
+@defopt eval-expression-print-length
+@defoptx eval-expression-print-level
+These are the values for @code{print-length} and @code{print-level}
+used by @code{eval-expression}, and thus, indirectly, by many
+interactive evaluation commands (@pxref{Lisp Eval,, Evaluating
+Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}).
+@end defopt
+
+  These variables are used for detecting and reporting circular
+and shared structure:
+
+@defvar print-circle
+If non-@code{nil}, this variable enables detection of circular
+and shared structure in printing.
+@end defvar
+
+@defvar print-gensym
+If non-@code{nil}, this variable enables detection of uninterned symbols
+(@pxref{Creating Symbols}) in printing.  When this is enabled,
+uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
+reader to produce an uninterned symbol.
+@end defvar
+
+@defvar print-continuous-numbering
+If non-@code{nil}, that means number continuously across print calls.
+This affects the numbers printed for @samp{#@var{n}=} labels and
+@samp{#@var{m}#} references.
+
+Don't set this variable with @code{setq}; you should only bind it
+temporarily to @code{t} with @code{let}.  When you do that, you should
+also bind @code{print-number-table} to @code{nil}.
+@end defvar
+
+@defvar print-number-table
+This variable holds a vector used internally by printing to implement
+the @code{print-circle} feature.  You should not use it except
+to bind it to @code{nil} when you bind @code{print-continuous-numbering}.
+@end defvar
+
+@defvar float-output-format
+This variable specifies how to print floating point numbers.  Its
+default value is @code{nil}, meaning use the shortest output
+that represents the number without losing information.
+
+To control output format more precisely, you can put a string in this
+variable.  The string should hold a @samp{%}-specification to be used
+in the C function @code{sprintf}.  For further restrictions on what
+you can use, see the variable's documentation string.
+@end defvar
+
+@ignore
+   arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434
+@end ignore
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
new file mode 100644
index 00000000000..af5a2fa14d3
--- /dev/null
+++ b/doc/lispref/strings.texi
@@ -0,0 +1,1163 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/strings
+@node Strings and Characters, Lists, Numbers, Top
+@comment  node-name,  next,  previous,  up
+@chapter Strings and Characters
+@cindex strings
+@cindex character arrays
+@cindex characters
+@cindex bytes
+
+  A string in Emacs Lisp is an array that contains an ordered sequence
+of characters.  Strings are used as names of symbols, buffers, and
+files; to send messages to users; to hold text being copied between
+buffers; and for many other purposes.  Because strings are so important,
+Emacs Lisp has many functions expressly for manipulating them.  Emacs
+Lisp programs use strings more often than individual characters.
+
+  @xref{Strings of Events}, for special considerations for strings of
+keyboard character events.
+
+@menu
+* Basics: String Basics.      Basic properties of strings and characters.
+* Predicates for Strings::    Testing whether an object is a string or char.
+* Creating Strings::          Functions to allocate new strings.
+* Modifying Strings::         Altering the contents of an existing string.
+* Text Comparison::           Comparing characters or strings.
+* String Conversion::         Converting to and from characters and strings.
+* Formatting Strings::        @code{format}: Emacs's analogue of @code{printf}.
+* Case Conversion::           Case conversion functions.
+* Case Tables::		      Customizing case conversion.
+@end menu
+
+@node String Basics
+@section String and Character Basics
+
+  Characters are represented in Emacs Lisp as integers;
+whether an integer is a character or not is determined only by how it is
+used.  Thus, strings really contain integers.
+
+  The length of a string (like any array) is fixed, and cannot be
+altered once the string exists.  Strings in Lisp are @emph{not}
+terminated by a distinguished character code.  (By contrast, strings in
+C are terminated by a character with @acronym{ASCII} code 0.)
+
+  Since strings are arrays, and therefore sequences as well, you can
+operate on them with the general array and sequence functions.
+(@xref{Sequences Arrays Vectors}.)  For example, you can access or
+change individual characters in a string using the functions @code{aref}
+and @code{aset} (@pxref{Array Functions}).
+
+  There are two text representations for non-@acronym{ASCII} characters in
+Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
+Representations}).  An @acronym{ASCII} character always occupies one byte in a
+string; in fact, when a string is all @acronym{ASCII}, there is no real
+difference between the unibyte and multibyte representations.
+For most Lisp programming, you don't need to be concerned with these two
+representations.
+
+  Sometimes key sequences are represented as strings.  When a string is
+a key sequence, string elements in the range 128 to 255 represent meta
+characters (which are large integers) rather than character
+codes in the range 128 to 255.
+
+  Strings cannot hold characters that have the hyper, super or alt
+modifiers; they can hold @acronym{ASCII} control characters, but no other
+control characters.  They do not distinguish case in @acronym{ASCII} control
+characters.  If you want to store such characters in a sequence, such as
+a key sequence, you must use a vector instead of a string.
+@xref{Character Type}, for more information about the representation of meta
+and other modifiers for keyboard input characters.
+
+  Strings are useful for holding regular expressions.  You can also
+match regular expressions against strings with @code{string-match}
+(@pxref{Regexp Search}).  The functions @code{match-string}
+(@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing
+Match}) are useful for decomposing and modifying strings after
+matching regular expressions against them.
+
+  Like a buffer, a string can contain text properties for the characters
+in it, as well as the characters themselves.  @xref{Text Properties}.
+All the Lisp primitives that copy text from strings to buffers or other
+strings also copy the properties of the characters being copied.
+
+  @xref{Text}, for information about functions that display strings or
+copy them into buffers.  @xref{Character Type}, and @ref{String Type},
+for information about the syntax of characters and strings.
+@xref{Non-ASCII Characters}, for functions to convert between text
+representations and to encode and decode character codes.
+
+@node Predicates for Strings
+@section The Predicates for Strings
+
+For more information about general sequence and array predicates,
+see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
+
+@defun stringp object
+This function returns @code{t} if @var{object} is a string, @code{nil}
+otherwise.
+@end defun
+
+@defun string-or-null-p object
+This function returns @code{t} if @var{object} is a string or nil,
+@code{nil} otherwise.
+@end defun
+
+@defun char-or-string-p object
+This function returns @code{t} if @var{object} is a string or a
+character (i.e., an integer), @code{nil} otherwise.
+@end defun
+
+@node Creating Strings
+@section Creating Strings
+
+  The following functions create strings, either from scratch, or by
+putting strings together, or by taking them apart.
+
+@defun make-string count character
+This function returns a string made up of @var{count} repetitions of
+@var{character}.  If @var{count} is negative, an error is signaled.
+
+@example
+(make-string 5 ?x)
+     @result{} "xxxxx"
+(make-string 0 ?x)
+     @result{} ""
+@end example
+
+  Other functions to compare with this one include @code{char-to-string}
+(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and
+@code{make-list} (@pxref{Building Lists}).
+@end defun
+
+@defun string &rest characters
+This returns a string containing the characters @var{characters}.
+
+@example
+(string ?a ?b ?c)
+     @result{} "abc"
+@end example
+@end defun
+
+@defun substring string start &optional end
+This function returns a new string which consists of those characters
+from @var{string} in the range from (and including) the character at the
+index @var{start} up to (but excluding) the character at the index
+@var{end}.  The first character is at index zero.
+
+@example
+@group
+(substring "abcdefg" 0 3)
+     @result{} "abc"
+@end group
+@end example
+
+@noindent
+Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the
+index for @samp{c} is 2.  Thus, three letters, @samp{abc}, are copied
+from the string @code{"abcdefg"}.  The index 3 marks the character
+position up to which the substring is copied.  The character whose index
+is 3 is actually the fourth character in the string.
+
+A negative number counts from the end of the string, so that @minus{}1
+signifies the index of the last character of the string.  For example:
+
+@example
+@group
+(substring "abcdefg" -3 -1)
+     @result{} "ef"
+@end group
+@end example
+
+@noindent
+In this example, the index for @samp{e} is @minus{}3, the index for
+@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1.
+Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded.
+
+When @code{nil} is used for @var{end}, it stands for the length of the
+string.  Thus,
+
+@example
+@group
+(substring "abcdefg" -3 nil)
+     @result{} "efg"
+@end group
+@end example
+
+Omitting the argument @var{end} is equivalent to specifying @code{nil}.
+It follows that @code{(substring @var{string} 0)} returns a copy of all
+of @var{string}.
+
+@example
+@group
+(substring "abcdefg" 0)
+     @result{} "abcdefg"
+@end group
+@end example
+
+@noindent
+But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence
+Functions}).
+
+If the characters copied from @var{string} have text properties, the
+properties are copied into the new string also.  @xref{Text Properties}.
+
+@code{substring} also accepts a vector for the first argument.
+For example:
+
+@example
+(substring [a b (c) "d"] 1 3)
+     @result{} [b (c)]
+@end example
+
+A @code{wrong-type-argument} error is signaled if @var{start} is not
+an integer or if @var{end} is neither an integer nor @code{nil}.  An
+@code{args-out-of-range} error is signaled if @var{start} indicates a
+character following @var{end}, or if either integer is out of range
+for @var{string}.
+
+Contrast this function with @code{buffer-substring} (@pxref{Buffer
+Contents}), which returns a string containing a portion of the text in
+the current buffer.  The beginning of a string is at index 0, but the
+beginning of a buffer is at index 1.
+@end defun
+
+@defun substring-no-properties string &optional start end
+This works like @code{substring} but discards all text properties from
+the value.  Also, @var{start} may be omitted or @code{nil}, which is
+equivalent to 0.  Thus, @w{@code{(substring-no-properties
+@var{string})}} returns a copy of @var{string}, with all text
+properties removed.
+@end defun
+
+@defun concat &rest sequences
+@cindex copying strings
+@cindex concatenating strings
+This function returns a new string consisting of the characters in the
+arguments passed to it (along with their text properties, if any).  The
+arguments may be strings, lists of numbers, or vectors of numbers; they
+are not themselves changed.  If @code{concat} receives no arguments, it
+returns an empty string.
+
+@example
+(concat "abc" "-def")
+     @result{} "abc-def"
+(concat "abc" (list 120 121) [122])
+     @result{} "abcxyz"
+;; @r{@code{nil} is an empty sequence.}
+(concat "abc" nil "-def")
+     @result{} "abc-def"
+(concat "The " "quick brown " "fox.")
+     @result{} "The quick brown fox."
+(concat)
+     @result{} ""
+@end example
+
+@noindent
+The @code{concat} function always constructs a new string that is
+not @code{eq} to any existing string.
+
+In Emacs versions before 21, when an argument was an integer (not a
+sequence of integers), it was converted to a string of digits making up
+the decimal printed representation of the integer.  This obsolete usage
+no longer works.  The proper way to convert an integer to its decimal
+printed form is with @code{format} (@pxref{Formatting Strings}) or
+@code{number-to-string} (@pxref{String Conversion}).
+
+For information about other concatenation functions, see the
+description of @code{mapconcat} in @ref{Mapping Functions},
+@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building
+Lists}.
+@end defun
+
+@defun split-string string &optional separators omit-nulls
+This function splits @var{string} into substrings at matches for the
+regular expression @var{separators}.  Each match for @var{separators}
+defines a splitting point; the substrings between the splitting points
+are made into a list, which is the value returned by
+@code{split-string}.
+
+If @var{omit-nulls} is @code{nil}, the result contains null strings
+whenever there are two consecutive matches for @var{separators}, or a
+match is adjacent to the beginning or end of @var{string}.  If
+@var{omit-nulls} is @code{t}, these null strings are omitted from the
+result.
+
+If @var{separators} is @code{nil} (or omitted),
+the default is the value of @code{split-string-default-separators}.
+
+As a special case, when @var{separators} is @code{nil} (or omitted),
+null strings are always omitted from the result.  Thus:
+
+@example
+(split-string "  two words ")
+     @result{} ("two" "words")
+@end example
+
+The result is not @code{("" "two" "words" "")}, which would rarely be
+useful.  If you need such a result, use an explicit value for
+@var{separators}:
+
+@example
+(split-string "  two words "
+              split-string-default-separators)
+     @result{} ("" "two" "words" "")
+@end example
+
+More examples:
+
+@example
+(split-string "Soup is good food" "o")
+     @result{} ("S" "up is g" "" "d f" "" "d")
+(split-string "Soup is good food" "o" t)
+     @result{} ("S" "up is g" "d f" "d")
+(split-string "Soup is good food" "o+")
+     @result{} ("S" "up is g" "d f" "d")
+@end example
+
+Empty matches do count, except that @code{split-string} will not look
+for a final empty match when it already reached the end of the string
+using a non-empty match or when @var{string} is empty:
+
+@example
+(split-string "aooob" "o*")
+     @result{} ("" "a" "" "b" "")
+(split-string "ooaboo" "o*")
+     @result{} ("" "" "a" "b" "")
+(split-string "" "")
+     @result{} ("")
+@end example
+
+However, when @var{separators} can match the empty string,
+@var{omit-nulls} is usually @code{t}, so that the subtleties in the
+three previous examples are rarely relevant:
+
+@example
+(split-string "Soup is good food" "o*" t)
+     @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
+(split-string "Nice doggy!" "" t)
+     @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
+(split-string "" "" t)
+     @result{} nil
+@end example
+
+Somewhat odd, but predictable, behavior can occur for certain
+``non-greedy'' values of @var{separators} that can prefer empty
+matches over non-empty matches.  Again, such values rarely occur in
+practice:
+
+@example
+(split-string "ooo" "o*" t)
+     @result{} nil
+(split-string "ooo" "\\|o+" t)
+     @result{} ("o" "o" "o")
+@end example
+@end defun
+
+@defvar split-string-default-separators
+The default value of @var{separators} for @code{split-string}.  Its
+usual value is @w{@code{"[ \f\t\n\r\v]+"}}.
+@end defvar
+
+@node Modifying Strings
+@section Modifying Strings
+
+  The most basic way to alter the contents of an existing string is with
+@code{aset} (@pxref{Array Functions}).  @code{(aset @var{string}
+@var{idx} @var{char})} stores @var{char} into @var{string} at index
+@var{idx}.  Each character occupies one or more bytes, and if @var{char}
+needs a different number of bytes from the character already present at
+that index, @code{aset} signals an error.
+
+  A more powerful function is @code{store-substring}:
+
+@defun store-substring string idx obj
+This function alters part of the contents of the string @var{string}, by
+storing @var{obj} starting at index @var{idx}.  The argument @var{obj}
+may be either a character or a (smaller) string.
+
+Since it is impossible to change the length of an existing string, it is
+an error if @var{obj} doesn't fit within @var{string}'s actual length,
+or if any new character requires a different number of bytes from the
+character currently present at that point in @var{string}.
+@end defun
+
+  To clear out a string that contained a password, use
+@code{clear-string}:
+
+@defun clear-string string
+This makes @var{string} a unibyte string and clears its contents to
+zeros.  It may also change @var{string}'s length.
+@end defun
+
+@need 2000
+@node Text Comparison
+@section Comparison of Characters and Strings
+@cindex string equality
+
+@defun char-equal character1 character2
+This function returns @code{t} if the arguments represent the same
+character, @code{nil} otherwise.  This function ignores differences
+in case if @code{case-fold-search} is non-@code{nil}.
+
+@example
+(char-equal ?x ?x)
+     @result{} t
+(let ((case-fold-search nil))
+  (char-equal ?x ?X))
+     @result{} nil
+@end example
+@end defun
+
+@defun string= string1 string2
+This function returns @code{t} if the characters of the two strings
+match exactly.  Symbols are also allowed as arguments, in which case
+their print names are used.
+Case is always significant, regardless of @code{case-fold-search}.
+
+@example
+(string= "abc" "abc")
+     @result{} t
+(string= "abc" "ABC")
+     @result{} nil
+(string= "ab" "ABC")
+     @result{} nil
+@end example
+
+The function @code{string=} ignores the text properties of the two
+strings.  When @code{equal} (@pxref{Equality Predicates}) compares two
+strings, it uses @code{string=}.
+
+For technical reasons, a unibyte and a multibyte string are
+@code{equal} if and only if they contain the same sequence of
+character codes and all these codes are either in the range 0 through
+127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
+However, when a unibyte string gets converted to a multibyte string,
+all characters with codes in the range 160 through 255 get converted
+to characters with higher codes, whereas @acronym{ASCII} characters
+remain unchanged.  Thus, a unibyte string and its conversion to
+multibyte are only @code{equal} if the string is all @acronym{ASCII}.
+Character codes 160 through 255 are not entirely proper in multibyte
+text, even though they can occur.  As a consequence, the situation
+where a unibyte and a multibyte string are @code{equal} without both
+being all @acronym{ASCII} is a technical oddity that very few Emacs
+Lisp programmers ever get confronted with.  @xref{Text
+Representations}.
+@end defun
+
+@defun string-equal string1 string2
+@code{string-equal} is another name for @code{string=}.
+@end defun
+
+@cindex lexical comparison
+@defun string< string1 string2
+@c (findex string< causes problems for permuted index!!)
+This function compares two strings a character at a time.  It
+scans both the strings at the same time to find the first pair of corresponding
+characters that do not match.  If the lesser character of these two is
+the character from @var{string1}, then @var{string1} is less, and this
+function returns @code{t}.  If the lesser character is the one from
+@var{string2}, then @var{string1} is greater, and this function returns
+@code{nil}.  If the two strings match entirely, the value is @code{nil}.
+
+Pairs of characters are compared according to their character codes.
+Keep in mind that lower case letters have higher numeric values in the
+@acronym{ASCII} character set than their upper case counterparts; digits and
+many punctuation characters have a lower numeric value than upper case
+letters.  An @acronym{ASCII} character is less than any non-@acronym{ASCII}
+character; a unibyte non-@acronym{ASCII} character is always less than any
+multibyte non-@acronym{ASCII} character (@pxref{Text Representations}).
+
+@example
+@group
+(string< "abc" "abd")
+     @result{} t
+(string< "abd" "abc")
+     @result{} nil
+(string< "123" "abc")
+     @result{} t
+@end group
+@end example
+
+When the strings have different lengths, and they match up to the
+length of @var{string1}, then the result is @code{t}.  If they match up
+to the length of @var{string2}, the result is @code{nil}.  A string of
+no characters is less than any other string.
+
+@example
+@group
+(string< "" "abc")
+     @result{} t
+(string< "ab" "abc")
+     @result{} t
+(string< "abc" "")
+     @result{} nil
+(string< "abc" "ab")
+     @result{} nil
+(string< "" "")
+     @result{} nil
+@end group
+@end example
+
+Symbols are also allowed as arguments, in which case their print names
+are used.
+@end defun
+
+@defun string-lessp string1 string2
+@code{string-lessp} is another name for @code{string<}.
+@end defun
+
+@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
+This function compares the specified part of @var{string1} with the
+specified part of @var{string2}.  The specified part of @var{string1}
+runs from index @var{start1} up to index @var{end1} (@code{nil} means
+the end of the string).  The specified part of @var{string2} runs from
+index @var{start2} up to index @var{end2} (@code{nil} means the end of
+the string).
+
+The strings are both converted to multibyte for the comparison
+(@pxref{Text Representations}) so that a unibyte string and its
+conversion to multibyte are always regarded as equal.  If
+@var{ignore-case} is non-@code{nil}, then case is ignored, so that
+upper case letters can be equal to lower case letters.
+
+If the specified portions of the two strings match, the value is
+@code{t}.  Otherwise, the value is an integer which indicates how many
+leading characters agree, and which string is less.  Its absolute value
+is one plus the number of characters that agree at the beginning of the
+two strings.  The sign is negative if @var{string1} (or its specified
+portion) is less.
+@end defun
+
+@defun assoc-string key alist &optional case-fold
+This function works like @code{assoc}, except that @var{key} must be a
+string or symbol, and comparison is done using @code{compare-strings}.
+Symbols are converted to strings before testing.
+If @var{case-fold} is non-@code{nil}, it ignores case differences.
+Unlike @code{assoc}, this function can also match elements of the alist
+that are strings or symbols rather than conses.  In particular, @var{alist} can
+be a list of strings or symbols rather than an actual alist.
+@xref{Association Lists}.
+@end defun
+
+  See also the @code{compare-buffer-substrings} function in
+@ref{Comparing Text}, for a way to compare text in buffers.  The
+function @code{string-match}, which matches a regular expression
+against a string, can be used for a kind of string comparison; see
+@ref{Regexp Search}.
+
+@node String Conversion
+@comment  node-name,  next,  previous,  up
+@section Conversion of Characters and Strings
+@cindex conversion of strings
+
+  This section describes functions for conversions between characters,
+strings and integers.  @code{format} (@pxref{Formatting Strings})
+and @code{prin1-to-string}
+(@pxref{Output Functions}) can also convert Lisp objects into strings.
+@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
+string representation of a Lisp object into an object.  The functions
+@code{string-make-multibyte} and @code{string-make-unibyte} convert the
+text representation of a string (@pxref{Converting Representations}).
+
+  @xref{Documentation}, for functions that produce textual descriptions
+of text characters and general input events
+(@code{single-key-description} and @code{text-char-description}).  These
+are used primarily for making help messages.
+
+@defun char-to-string character
+@cindex character to string
+This function returns a new string containing one character,
+@var{character}.  This function is semi-obsolete because the function
+@code{string} is more general.  @xref{Creating Strings}.
+@end defun
+
+@defun string-to-char string
+@cindex string to character
+  This function returns the first character in @var{string}.  If the
+string is empty, the function returns 0.  The value is also 0 when the
+first character of @var{string} is the null character, @acronym{ASCII} code
+0.
+
+@example
+(string-to-char "ABC")
+     @result{} 65
+
+(string-to-char "xyz")
+     @result{} 120
+(string-to-char "")
+     @result{} 0
+@group
+(string-to-char "\000")
+     @result{} 0
+@end group
+@end example
+
+This function may be eliminated in the future if it does not seem useful
+enough to retain.
+@end defun
+
+@defun number-to-string number
+@cindex integer to string
+@cindex integer to decimal
+This function returns a string consisting of the printed base-ten
+representation of @var{number}, which may be an integer or a floating
+point number.  The returned value starts with a minus sign if the argument is
+negative.
+
+@example
+(number-to-string 256)
+     @result{} "256"
+@group
+(number-to-string -23)
+     @result{} "-23"
+@end group
+(number-to-string -23.5)
+     @result{} "-23.5"
+@end example
+
+@cindex int-to-string
+@code{int-to-string} is a semi-obsolete alias for this function.
+
+See also the function @code{format} in @ref{Formatting Strings}.
+@end defun
+
+@defun string-to-number string &optional base
+@cindex string to number
+This function returns the numeric value of the characters in
+@var{string}.  If @var{base} is non-@code{nil}, it must be an integer
+between 2 and 16 (inclusive), and integers are converted in that base.
+If @var{base} is @code{nil}, then base ten is used.  Floating point
+conversion only works in base ten; we have not implemented other
+radices for floating point numbers, because that would be much more
+work and does not seem useful.  If @var{string} looks like an integer
+but its value is too large to fit into a Lisp integer,
+@code{string-to-number} returns a floating point result.
+
+The parsing skips spaces and tabs at the beginning of @var{string},
+then reads as much of @var{string} as it can interpret as a number in
+the given base.  (On some systems it ignores other whitespace at the
+beginning, not just spaces and tabs.)  If the first character after
+the ignored whitespace is neither a digit in the given base, nor a
+plus or minus sign, nor the leading dot of a floating point number,
+this function returns 0.
+
+@example
+(string-to-number "256")
+     @result{} 256
+(string-to-number "25 is a perfect square.")
+     @result{} 25
+(string-to-number "X256")
+     @result{} 0
+(string-to-number "-4.5")
+     @result{} -4.5
+(string-to-number "1e5")
+     @result{} 100000.0
+@end example
+
+@findex string-to-int
+@code{string-to-int} is an obsolete alias for this function.
+@end defun
+
+  Here are some other functions that can convert to or from a string:
+
+@table @code
+@item concat
+@code{concat} can convert a vector or a list into a string.
+@xref{Creating Strings}.
+
+@item vconcat
+@code{vconcat} can convert a string into a vector.  @xref{Vector
+Functions}.
+
+@item append
+@code{append} can convert a string into a list.  @xref{Building Lists}.
+@end table
+
+@node Formatting Strings
+@comment  node-name,  next,  previous,  up
+@section Formatting Strings
+@cindex formatting strings
+@cindex strings, formatting them
+
+  @dfn{Formatting} means constructing a string by substitution of
+computed values at various places in a constant string.  This constant string
+controls how the other values are printed, as well as where they appear;
+it is called a @dfn{format string}.
+
+  Formatting is often useful for computing messages to be displayed.  In
+fact, the functions @code{message} and @code{error} provide the same
+formatting feature described here; they differ from @code{format} only
+in how they use the result of formatting.
+
+@defun format string &rest objects
+This function returns a new string that is made by copying
+@var{string} and then replacing any format specification
+in the copy with encodings of the corresponding @var{objects}.  The
+arguments @var{objects} are the computed values to be formatted.
+
+The characters in @var{string}, other than the format specifications,
+are copied directly into the output, including their text properties,
+if any.
+@end defun
+
+@cindex @samp{%} in format
+@cindex format specification
+  A format specification is a sequence of characters beginning with a
+@samp{%}.  Thus, if there is a @samp{%d} in @var{string}, the
+@code{format} function replaces it with the printed representation of
+one of the values to be formatted (one of the arguments @var{objects}).
+For example:
+
+@example
+@group
+(format "The value of fill-column is %d." fill-column)
+     @result{} "The value of fill-column is 72."
+@end group
+@end example
+
+  Since @code{format} interprets @samp{%} characters as format
+specifications, you should @emph{never} pass an arbitrary string as
+the first argument.  This is particularly true when the string is
+generated by some Lisp code.  Unless the string is @emph{known} to
+never include any @samp{%} characters, pass @code{"%s"}, described
+below, as the first argument, and the string as the second, like this:
+
+@example
+  (format "%s" @var{arbitrary-string})
+@end example
+
+  If @var{string} contains more than one format specification, the
+format specifications correspond to successive values from
+@var{objects}.  Thus, the first format specification in @var{string}
+uses the first such value, the second format specification uses the
+second such value, and so on.  Any extra format specifications (those
+for which there are no corresponding values) cause an error.  Any
+extra values to be formatted are ignored.
+
+  Certain format specifications require values of particular types.  If
+you supply a value that doesn't fit the requirements, an error is
+signaled.
+
+  Here is a table of valid format specifications:
+
+@table @samp
+@item %s
+Replace the specification with the printed representation of the object,
+made without quoting (that is, using @code{princ}, not
+@code{prin1}---@pxref{Output Functions}).  Thus, strings are represented
+by their contents alone, with no @samp{"} characters, and symbols appear
+without @samp{\} characters.
+
+If the object is a string, its text properties are
+copied into the output.  The text properties of the @samp{%s} itself
+are also copied, but those of the object take priority.
+
+@item %S
+Replace the specification with the printed representation of the object,
+made with quoting (that is, using @code{prin1}---@pxref{Output
+Functions}).  Thus, strings are enclosed in @samp{"} characters, and
+@samp{\} characters appear where necessary before special characters.
+
+@item %o
+@cindex integer to octal
+Replace the specification with the base-eight representation of an
+integer.
+
+@item %d
+Replace the specification with the base-ten representation of an
+integer.
+
+@item %x
+@itemx %X
+@cindex integer to hexadecimal
+Replace the specification with the base-sixteen representation of an
+integer.  @samp{%x} uses lower case and @samp{%X} uses upper case.
+
+@item %c
+Replace the specification with the character which is the value given.
+
+@item %e
+Replace the specification with the exponential notation for a floating
+point number.
+
+@item %f
+Replace the specification with the decimal-point notation for a floating
+point number.
+
+@item %g
+Replace the specification with notation for a floating point number,
+using either exponential notation or decimal-point notation, whichever
+is shorter.
+
+@item %%
+Replace the specification with a single @samp{%}.  This format
+specification is unusual in that it does not use a value.  For example,
+@code{(format "%% %d" 30)} returns @code{"% 30"}.
+@end table
+
+  Any other format character results in an @samp{Invalid format
+operation} error.
+
+  Here are several examples:
+
+@example
+@group
+(format "The name of this buffer is %s." (buffer-name))
+     @result{} "The name of this buffer is strings.texi."
+
+(format "The buffer object prints as %s." (current-buffer))
+     @result{} "The buffer object prints as strings.texi."
+
+(format "The octal value of %d is %o,
+         and the hex value is %x." 18 18 18)
+     @result{} "The octal value of 18 is 22,
+         and the hex value is 12."
+@end group
+@end example
+
+@cindex field width
+@cindex padding
+  A specification can have a @dfn{width}, which is a signed decimal
+number between the @samp{%} and the specification character.  If the
+printed representation of the object contains fewer characters than
+this width, @code{format} extends it with padding.  The padding goes
+on the left if the width is positive (or starts with zero) and on the
+right if the width is negative.  The padding character is normally a
+space, but it's @samp{0} if the width starts with a zero.
+
+  Some of these conventions are ignored for specification characters
+for which they do not make sense.  That is, @samp{%s}, @samp{%S} and
+@samp{%c} accept a width starting with 0, but still pad with
+@emph{spaces} on the left.  Also, @samp{%%} accepts a width, but
+ignores it.  Here are some examples of padding:
+
+@example
+(format "%06d is padded on the left with zeros" 123)
+     @result{} "000123 is padded on the left with zeros"
+
+(format "%-6d is padded on the right" 123)
+     @result{} "123    is padded on the right"
+@end example
+
+@noindent
+If the width is too small, @code{format} does not truncate the
+object's printed representation.  Thus, you can use a width to specify
+a minimum spacing between columns with no risk of losing information.
+
+  In the following three examples, @samp{%7s} specifies a minimum
+width of 7.  In the first case, the string inserted in place of
+@samp{%7s} has only 3 letters, it needs 4 blank spaces as padding.  In
+the second case, the string @code{"specification"} is 13 letters wide
+but is not truncated.  In the third case, the padding is on the right.
+
+@smallexample
+@group
+(format "The word `%7s' actually has %d letters in it."
+        "foo" (length "foo"))
+     @result{} "The word `    foo' actually has 3 letters in it."
+@end group
+
+@group
+(format "The word `%7s' actually has %d letters in it."
+        "specification" (length "specification"))
+     @result{} "The word `specification' actually has 13 letters in it."
+@end group
+
+@group
+(format "The word `%-7s' actually has %d letters in it."
+        "foo" (length "foo"))
+     @result{} "The word `foo    ' actually has 3 letters in it."
+@end group
+@end smallexample
+
+@cindex precision in format specifications
+  All the specification characters allow an optional @dfn{precision}
+before the character (after the width, if present).  The precision is
+a decimal-point @samp{.} followed by a digit-string.  For the
+floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the
+precision specifies how many decimal places to show; if zero, the
+decimal-point itself is also omitted.  For @samp{%s} and @samp{%S},
+the precision truncates the string to the given width, so @samp{%.3s}
+shows only the first three characters of the representation for
+@var{object}.  Precision has no effect for other specification
+characters.
+
+@cindex flags in format specifications
+  Immediately after the @samp{%} and before the optional width and
+precision, you can put certain ``flag'' characters.
+
+  @samp{+} as a flag inserts a plus sign before a positive number, so
+that it always has a sign.  A space character as flag inserts a space
+before a positive number.  (Otherwise, positive numbers start with the
+first digit.)  Either of these two flags ensures that positive numbers
+and negative numbers use the same number of columns.  These flags are
+ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if
+both flags are used, the @samp{+} takes precedence.
+
+  The flag @samp{#} specifies an ``alternate form'' which depends on
+the format in use.  For @samp{%o} it ensures that the result begins
+with a @samp{0}.  For @samp{%x} and @samp{%X}, it prefixes the result
+with @samp{0x} or @samp{0X}.  For @samp{%e}, @samp{%f}, and @samp{%g},
+the @samp{#} flag means include a decimal point even if the precision
+is zero.
+
+@node Case Conversion
+@comment node-name, next, previous, up
+@section Case Conversion in Lisp
+@cindex upper case
+@cindex lower case
+@cindex character case
+@cindex case conversion in Lisp
+
+  The character case functions change the case of single characters or
+of the contents of strings.  The functions normally convert only
+alphabetic characters (the letters @samp{A} through @samp{Z} and
+@samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other
+characters are not altered.  You can specify a different case
+conversion mapping by specifying a case table (@pxref{Case Tables}).
+
+  These functions do not modify the strings that are passed to them as
+arguments.
+
+  The examples below use the characters @samp{X} and @samp{x} which have
+@acronym{ASCII} codes 88 and 120 respectively.
+
+@defun downcase string-or-char
+This function converts a character or a string to lower case.
+
+When the argument to @code{downcase} is a string, the function creates
+and returns a new string in which each letter in the argument that is
+upper case is converted to lower case.  When the argument to
+@code{downcase} is a character, @code{downcase} returns the
+corresponding lower case character.  This value is an integer.  If the
+original character is lower case, or is not a letter, then the value
+equals the original character.
+
+@example
+(downcase "The cat in the hat")
+     @result{} "the cat in the hat"
+
+(downcase ?X)
+     @result{} 120
+@end example
+@end defun
+
+@defun upcase string-or-char
+This function converts a character or a string to upper case.
+
+When the argument to @code{upcase} is a string, the function creates
+and returns a new string in which each letter in the argument that is
+lower case is converted to upper case.
+
+When the argument to @code{upcase} is a character, @code{upcase}
+returns the corresponding upper case character.  This value is an integer.
+If the original character is upper case, or is not a letter, then the
+value returned equals the original character.
+
+@example
+(upcase "The cat in the hat")
+     @result{} "THE CAT IN THE HAT"
+
+(upcase ?x)
+     @result{} 88
+@end example
+@end defun
+
+@defun capitalize string-or-char
+@cindex capitalization
+This function capitalizes strings or characters.  If
+@var{string-or-char} is a string, the function creates and returns a new
+string, whose contents are a copy of @var{string-or-char} in which each
+word has been capitalized.  This means that the first character of each
+word is converted to upper case, and the rest are converted to lower
+case.
+
+The definition of a word is any sequence of consecutive characters that
+are assigned to the word constituent syntax class in the current syntax
+table (@pxref{Syntax Class Table}).
+
+When the argument to @code{capitalize} is a character, @code{capitalize}
+has the same result as @code{upcase}.
+
+@example
+@group
+(capitalize "The cat in the hat")
+     @result{} "The Cat In The Hat"
+@end group
+
+@group
+(capitalize "THE 77TH-HATTED CAT")
+     @result{} "The 77th-Hatted Cat"
+@end group
+
+@group
+(capitalize ?x)
+     @result{} 88
+@end group
+@end example
+@end defun
+
+@defun upcase-initials string-or-char
+If @var{string-or-char} is a string, this function capitalizes the
+initials of the words in @var{string-or-char}, without altering any
+letters other than the initials.  It returns a new string whose
+contents are a copy of @var{string-or-char}, in which each word has
+had its initial letter converted to upper case.
+
+The definition of a word is any sequence of consecutive characters that
+are assigned to the word constituent syntax class in the current syntax
+table (@pxref{Syntax Class Table}).
+
+When the argument to @code{upcase-initials} is a character,
+@code{upcase-initials} has the same result as @code{upcase}.
+
+@example
+@group
+(upcase-initials "The CAT in the hAt")
+     @result{} "The CAT In The HAt"
+@end group
+@end example
+@end defun
+
+  @xref{Text Comparison}, for functions that compare strings; some of
+them ignore case differences, or can optionally ignore case differences.
+
+@node Case Tables
+@section The Case Table
+
+  You can customize case conversion by installing a special @dfn{case
+table}.  A case table specifies the mapping between upper case and lower
+case letters.  It affects both the case conversion functions for Lisp
+objects (see the previous section) and those that apply to text in the
+buffer (@pxref{Case Changes}).  Each buffer has a case table; there is
+also a standard case table which is used to initialize the case table
+of new buffers.
+
+  A case table is a char-table (@pxref{Char-Tables}) whose subtype is
+@code{case-table}.  This char-table maps each character into the
+corresponding lower case character.  It has three extra slots, which
+hold related tables:
+
+@table @var
+@item upcase
+The upcase table maps each character into the corresponding upper
+case character.
+@item canonicalize
+The canonicalize table maps all of a set of case-related characters
+into a particular member of that set.
+@item equivalences
+The equivalences table maps each one of a set of case-related characters
+into the next character in that set.
+@end table
+
+  In simple cases, all you need to specify is the mapping to lower-case;
+the three related tables will be calculated automatically from that one.
+
+  For some languages, upper and lower case letters are not in one-to-one
+correspondence.  There may be two different lower case letters with the
+same upper case equivalent.  In these cases, you need to specify the
+maps for both lower case and upper case.
+
+  The extra table @var{canonicalize} maps each character to a canonical
+equivalent; any two characters that are related by case-conversion have
+the same canonical equivalent character.  For example, since @samp{a}
+and @samp{A} are related by case-conversion, they should have the same
+canonical equivalent character (which should be either @samp{a} for both
+of them, or @samp{A} for both of them).
+
+  The extra table @var{equivalences} is a map that cyclically permutes
+each equivalence class (of characters with the same canonical
+equivalent).  (For ordinary @acronym{ASCII}, this would map @samp{a} into
+@samp{A} and @samp{A} into @samp{a}, and likewise for each set of
+equivalent characters.)
+
+  When you construct a case table, you can provide @code{nil} for
+@var{canonicalize}; then Emacs fills in this slot from the lower case
+and upper case mappings.  You can also provide @code{nil} for
+@var{equivalences}; then Emacs fills in this slot from
+@var{canonicalize}.  In a case table that is actually in use, those
+components are non-@code{nil}.  Do not try to specify @var{equivalences}
+without also specifying @var{canonicalize}.
+
+  Here are the functions for working with case tables:
+
+@defun case-table-p object
+This predicate returns non-@code{nil} if @var{object} is a valid case
+table.
+@end defun
+
+@defun set-standard-case-table table
+This function makes @var{table} the standard case table, so that it will
+be used in any buffers created subsequently.
+@end defun
+
+@defun standard-case-table
+This returns the standard case table.
+@end defun
+
+@defun current-case-table
+This function returns the current buffer's case table.
+@end defun
+
+@defun set-case-table table
+This sets the current buffer's case table to @var{table}.
+@end defun
+
+@defmac with-case-table table body@dots{}
+The @code{with-case-table} macro saves the current case table, makes
+@var{table} the current case table, evaluates the @var{body} forms,
+and finally restores the case table.  The return value is the value of
+the last form in @var{body}.  The case table is restored even in case
+of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
+Exits}).
+@end defmac
+
+  Some language environments may modify the case conversions of
+@acronym{ASCII} characters; for example, in the Turkish language
+environment, the @acronym{ASCII} character @samp{I} is downcased into
+a Turkish ``dotless i''.  This can interfere with code that requires
+ordinary ASCII case conversion, such as implementations of
+@acronym{ASCII}-based network protocols.  In that case, use the
+@code{with-case-table} macro with the variable @var{ascii-case-table},
+which stores the unmodified case table for the @acronym{ASCII}
+character set.
+
+@defvar ascii-case-table
+The case table for the @acronym{ASCII} character set.  This should not be
+modified by any language environment settings.
+@end defvar
+
+  The following three functions are convenient subroutines for packages
+that define non-@acronym{ASCII} character sets.  They modify the specified
+case table @var{case-table}; they also modify the standard syntax table.
+@xref{Syntax Tables}.  Normally you would use these functions to change
+the standard case table.
+
+@defun set-case-syntax-pair uc lc case-table
+This function specifies a pair of corresponding letters, one upper case
+and one lower case.
+@end defun
+
+@defun set-case-syntax-delims l r case-table
+This function makes characters @var{l} and @var{r} a matching pair of
+case-invariant delimiters.
+@end defun
+
+@defun set-case-syntax char syntax case-table
+This function makes @var{char} case-invariant, with syntax
+@var{syntax}.
+@end defun
+
+@deffn Command describe-buffer-case-table
+This command displays a description of the contents of the current
+buffer's case table.
+@end deffn
+
+@ignore
+   arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4
+@end ignore
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
new file mode 100644
index 00000000000..7234a75bd59
--- /dev/null
+++ b/doc/lispref/symbols.texi
@@ -0,0 +1,598 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/symbols
+@node Symbols, Evaluation, Hash Tables, Top
+@chapter Symbols
+@cindex symbol
+
+  A @dfn{symbol} is an object with a unique name.  This chapter
+describes symbols, their components, their property lists, and how they
+are created and interned.  Separate chapters describe the use of symbols
+as variables and as function names; see @ref{Variables}, and
+@ref{Functions}.  For the precise read syntax for symbols, see
+@ref{Symbol Type}.
+
+  You can test whether an arbitrary Lisp object is a symbol
+with @code{symbolp}:
+
+@defun symbolp object
+This function returns @code{t} if @var{object} is a symbol, @code{nil}
+otherwise.
+@end defun
+
+@menu
+* Symbol Components::        Symbols have names, values, function definitions
+                               and property lists.
+* Definitions::              A definition says how a symbol will be used.
+* Creating Symbols::         How symbols are kept unique.
+* Property Lists::           Each symbol has a property list
+                               for recording miscellaneous information.
+@end menu
+
+@node Symbol Components, Definitions, Symbols, Symbols
+@section Symbol Components
+@cindex symbol components
+
+  Each symbol has four components (or ``cells''), each of which
+references another object:
+
+@table @asis
+@item Print name
+@cindex print name cell
+The @dfn{print name cell} holds a string that names the symbol for
+reading and printing.  See @code{symbol-name} in @ref{Creating Symbols}.
+
+@item Value
+@cindex value cell
+The @dfn{value cell} holds the current value of the symbol as a
+variable.  When a symbol is used as a form, the value of the form is the
+contents of the symbol's value cell.  See @code{symbol-value} in
+@ref{Accessing Variables}.
+
+@item Function
+@cindex function cell
+The @dfn{function cell} holds the function definition of the symbol.
+When a symbol is used as a function, its function definition is used in
+its place.  This cell is also used to make a symbol stand for a keymap
+or a keyboard macro, for editor command execution.  Because each symbol
+has separate value and function cells, variables names and function names do
+not conflict.  See @code{symbol-function} in @ref{Function Cells}.
+
+@item Property list
+@cindex property list cell
+The @dfn{property list cell} holds the property list of the symbol.  See
+@code{symbol-plist} in @ref{Property Lists}.
+@end table
+
+  The print name cell always holds a string, and cannot be changed.  The
+other three cells can be set individually to any specified Lisp object.
+
+  The print name cell holds the string that is the name of the symbol.
+Since symbols are represented textually by their names, it is important
+not to have two symbols with the same name.  The Lisp reader ensures
+this: every time it reads a symbol, it looks for an existing symbol with
+the specified name before it creates a new one.  (In GNU Emacs Lisp,
+this lookup uses a hashing algorithm and an obarray; see @ref{Creating
+Symbols}.)
+
+  The value cell holds the symbol's value as a variable
+(@pxref{Variables}).  That is what you get if you evaluate the symbol as
+a Lisp expression (@pxref{Evaluation}).  Any Lisp object is a legitimate
+value.  Certain symbols have values that cannot be changed; these
+include @code{nil} and @code{t}, and any symbol whose name starts with
+@samp{:} (those are called @dfn{keywords}).  @xref{Constant Variables}.
+
+  We often refer to ``the function @code{foo}'' when we really mean
+the function stored in the function cell of the symbol @code{foo}.  We
+make the distinction explicit only when necessary.  In normal
+usage, the function cell usually contains a function
+(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
+Lisp interpreter expects to see there (@pxref{Evaluation}).  Keyboard
+macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and
+autoload objects (@pxref{Autoloading}) are also sometimes stored in
+the function cells of symbols.
+
+  The property list cell normally should hold a correctly formatted
+property list (@pxref{Property Lists}), as a number of functions expect
+to see a property list there.
+
+  The function cell or the value cell may be @dfn{void}, which means
+that the cell does not reference any object.  (This is not the same
+thing as holding the symbol @code{void}, nor the same as holding the
+symbol @code{nil}.)  Examining a function or value cell that is void
+results in an error, such as @samp{Symbol's value as variable is void}.
+
+  The four functions @code{symbol-name}, @code{symbol-value},
+@code{symbol-plist}, and @code{symbol-function} return the contents of
+the four cells of a symbol.  Here as an example we show the contents of
+the four cells of the symbol @code{buffer-file-name}:
+
+@example
+(symbol-name 'buffer-file-name)
+     @result{} "buffer-file-name"
+(symbol-value 'buffer-file-name)
+     @result{} "/gnu/elisp/symbols.texi"
+(symbol-function 'buffer-file-name)
+     @result{} #<subr buffer-file-name>
+(symbol-plist 'buffer-file-name)
+     @result{} (variable-documentation 29529)
+@end example
+
+@noindent
+Because this symbol is the variable which holds the name of the file
+being visited in the current buffer, the value cell contents we see are
+the name of the source file of this chapter of the Emacs Lisp Manual.
+The property list cell contains the list @code{(variable-documentation
+29529)} which tells the documentation functions where to find the
+documentation string for the variable @code{buffer-file-name} in the
+@file{DOC-@var{version}} file.  (29529 is the offset from the beginning
+of the @file{DOC-@var{version}} file to where that documentation string
+begins---see @ref{Documentation Basics}.)  The function cell contains
+the function for returning the name of the file.
+@code{buffer-file-name} names a primitive function, which has no read
+syntax and prints in hash notation (@pxref{Primitive Function Type}).  A
+symbol naming a function written in Lisp would have a lambda expression
+(or a byte-code object) in this cell.
+
+@node Definitions, Creating Symbols, Symbol Components, Symbols
+@section Defining Symbols
+@cindex definitions of symbols
+
+  A @dfn{definition} in Lisp is a special form that announces your
+intention to use a certain symbol in a particular way.  In Emacs Lisp,
+you can define a symbol as a variable, or define it as a function (or
+macro), or both independently.
+
+  A definition construct typically specifies a value or meaning for the
+symbol for one kind of use, plus documentation for its meaning when used
+in this way.  Thus, when you define a symbol as a variable, you can
+supply an initial value for the variable, plus documentation for the
+variable.
+
+  @code{defvar} and @code{defconst} are special forms that define a
+symbol as a global variable.  They are documented in detail in
+@ref{Defining Variables}.  For defining user option variables that can
+be customized, use @code{defcustom} (@pxref{Customization}).
+
+  @code{defun} defines a symbol as a function, creating a lambda
+expression and storing it in the function cell of the symbol.  This
+lambda expression thus becomes the function definition of the symbol.
+(The term ``function definition,'' meaning the contents of the function
+cell, is derived from the idea that @code{defun} gives the symbol its
+definition as a function.)  @code{defsubst} and @code{defalias} are two
+other ways of defining a function.  @xref{Functions}.
+
+  @code{defmacro} defines a symbol as a macro.  It creates a macro
+object and stores it in the function cell of the symbol.  Note that a
+given symbol can be a macro or a function, but not both at once, because
+both macro and function definitions are kept in the function cell, and
+that cell can hold only one Lisp object at any given time.
+@xref{Macros}.
+
+  In Emacs Lisp, a definition is not required in order to use a symbol
+as a variable or function.  Thus, you can make a symbol a global
+variable with @code{setq}, whether you define it first or not.  The real
+purpose of definitions is to guide programmers and programming tools.
+They inform programmers who read the code that certain symbols are
+@emph{intended} to be used as variables, or as functions.  In addition,
+utilities such as @file{etags} and @file{make-docfile} recognize
+definitions, and add appropriate information to tag tables and the
+@file{DOC-@var{version}} file.  @xref{Accessing Documentation}.
+
+@node Creating Symbols, Property Lists, Definitions, Symbols
+@section Creating and Interning Symbols
+@cindex reading symbols
+
+  To understand how symbols are created in GNU Emacs Lisp, you must know
+how Lisp reads them.  Lisp must ensure that it finds the same symbol
+every time it reads the same set of characters.  Failure to do so would
+cause complete confusion.
+
+@cindex symbol name hashing
+@cindex hashing
+@cindex obarray
+@cindex bucket (in obarray)
+  When the Lisp reader encounters a symbol, it reads all the characters
+of the name.  Then it ``hashes'' those characters to find an index in a
+table called an @dfn{obarray}.  Hashing is an efficient method of
+looking something up.  For example, instead of searching a telephone
+book cover to cover when looking up Jan Jones, you start with the J's
+and go from there.  That is a simple version of hashing.  Each element
+of the obarray is a @dfn{bucket} which holds all the symbols with a
+given hash code; to look for a given name, it is sufficient to look
+through all the symbols in the bucket for that name's hash code.  (The
+same idea is used for general Emacs hash tables, but they are a
+different data type; see @ref{Hash Tables}.)
+
+@cindex interning
+  If a symbol with the desired name is found, the reader uses that
+symbol.  If the obarray does not contain a symbol with that name, the
+reader makes a new symbol and adds it to the obarray.  Finding or adding
+a symbol with a certain name is called @dfn{interning} it, and the
+symbol is then called an @dfn{interned symbol}.
+
+  Interning ensures that each obarray has just one symbol with any
+particular name.  Other like-named symbols may exist, but not in the
+same obarray.  Thus, the reader gets the same symbols for the same
+names, as long as you keep reading with the same obarray.
+
+  Interning usually happens automatically in the reader, but sometimes
+other programs need to do it.  For example, after the @kbd{M-x} command
+obtains the command name as a string using the minibuffer, it then
+interns the string, to get the interned symbol with that name.
+
+@cindex symbol equality
+@cindex uninterned symbol
+  No obarray contains all symbols; in fact, some symbols are not in any
+obarray.  They are called @dfn{uninterned symbols}.  An uninterned
+symbol has the same four cells as other symbols; however, the only way
+to gain access to it is by finding it in some other object or as the
+value of a variable.
+
+  Creating an uninterned symbol is useful in generating Lisp code,
+because an uninterned symbol used as a variable in the code you generate
+cannot clash with any variables used in other Lisp programs.
+
+  In Emacs Lisp, an obarray is actually a vector.  Each element of the
+vector is a bucket; its value is either an interned symbol whose name
+hashes to that bucket, or 0 if the bucket is empty.  Each interned
+symbol has an internal link (invisible to the user) to the next symbol
+in the bucket.  Because these links are invisible, there is no way to
+find all the symbols in an obarray except using @code{mapatoms} (below).
+The order of symbols in a bucket is not significant.
+
+  In an empty obarray, every element is 0, so you can create an obarray
+with @code{(make-vector @var{length} 0)}.  @strong{This is the only
+valid way to create an obarray.}  Prime numbers as lengths tend
+to result in good hashing; lengths one less than a power of two are also
+good.
+
+  @strong{Do not try to put symbols in an obarray yourself.}  This does
+not work---only @code{intern} can enter a symbol in an obarray properly.
+
+@cindex CL note---symbol in obarrays
+@quotation
+@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
+several obarrays.
+@end quotation
+
+  Most of the functions below take a name and sometimes an obarray as
+arguments.  A @code{wrong-type-argument} error is signaled if the name
+is not a string, or if the obarray is not a vector.
+
+@defun symbol-name symbol
+This function returns the string that is @var{symbol}'s name.  For example:
+
+@example
+@group
+(symbol-name 'foo)
+     @result{} "foo"
+@end group
+@end example
+
+@strong{Warning:} Changing the string by substituting characters does
+change the name of the symbol, but fails to update the obarray, so don't
+do it!
+@end defun
+
+@defun make-symbol name
+This function returns a newly-allocated, uninterned symbol whose name is
+@var{name} (which must be a string).  Its value and function definition
+are void, and its property list is @code{nil}.  In the example below,
+the value of @code{sym} is not @code{eq} to @code{foo} because it is a
+distinct uninterned symbol whose name is also @samp{foo}.
+
+@example
+(setq sym (make-symbol "foo"))
+     @result{} foo
+(eq sym 'foo)
+     @result{} nil
+@end example
+@end defun
+
+@defun intern name &optional obarray
+This function returns the interned symbol whose name is @var{name}.  If
+there is no such symbol in the obarray @var{obarray}, @code{intern}
+creates a new one, adds it to the obarray, and returns it.  If
+@var{obarray} is omitted, the value of the global variable
+@code{obarray} is used.
+
+@example
+(setq sym (intern "foo"))
+     @result{} foo
+(eq sym 'foo)
+     @result{} t
+
+(setq sym1 (intern "foo" other-obarray))
+     @result{} foo
+(eq sym1 'foo)
+     @result{} nil
+@end example
+@end defun
+
+@cindex CL note---interning existing symbol
+@quotation
+@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
+in an obarray.  In Emacs Lisp, you cannot do this, because the argument
+to @code{intern} must be a string, not a symbol.
+@end quotation
+
+@defun intern-soft name &optional obarray
+This function returns the symbol in @var{obarray} whose name is
+@var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
+Therefore, you can use @code{intern-soft} to test whether a symbol with
+a given name is already interned.  If @var{obarray} is omitted, the
+value of the global variable @code{obarray} is used.
+
+The argument @var{name} may also be a symbol; in that case,
+the function returns @var{name} if @var{name} is interned
+in the specified obarray, and otherwise @code{nil}.
+
+@smallexample
+(intern-soft "frazzle")        ; @r{No such symbol exists.}
+     @result{} nil
+(make-symbol "frazzle")        ; @r{Create an uninterned one.}
+     @result{} frazzle
+@group
+(intern-soft "frazzle")        ; @r{That one cannot be found.}
+     @result{} nil
+@end group
+@group
+(setq sym (intern "frazzle"))  ; @r{Create an interned one.}
+     @result{} frazzle
+@end group
+@group
+(intern-soft "frazzle")        ; @r{That one can be found!}
+     @result{} frazzle
+@end group
+@group
+(eq sym 'frazzle)              ; @r{And it is the same one.}
+     @result{} t
+@end group
+@end smallexample
+@end defun
+
+@defvar obarray
+This variable is the standard obarray for use by @code{intern} and
+@code{read}.
+@end defvar
+
+@defun mapatoms function &optional obarray
+@anchor{Definition of mapatoms}
+This function calls @var{function} once with each symbol in the obarray
+@var{obarray}.  Then it returns @code{nil}.  If @var{obarray} is
+omitted, it defaults to the value of @code{obarray}, the standard
+obarray for ordinary symbols.
+
+@smallexample
+(setq count 0)
+     @result{} 0
+(defun count-syms (s)
+  (setq count (1+ count)))
+     @result{} count-syms
+(mapatoms 'count-syms)
+     @result{} nil
+count
+     @result{} 1871
+@end smallexample
+
+See @code{documentation} in @ref{Accessing Documentation}, for another
+example using @code{mapatoms}.
+@end defun
+
+@defun unintern symbol &optional obarray
+This function deletes @var{symbol} from the obarray @var{obarray}.  If
+@code{symbol} is not actually in the obarray, @code{unintern} does
+nothing.  If @var{obarray} is @code{nil}, the current obarray is used.
+
+If you provide a string instead of a symbol as @var{symbol}, it stands
+for a symbol name.  Then @code{unintern} deletes the symbol (if any) in
+the obarray which has that name.  If there is no such symbol,
+@code{unintern} does nothing.
+
+If @code{unintern} does delete a symbol, it returns @code{t}.  Otherwise
+it returns @code{nil}.
+@end defun
+
+@node Property Lists,, Creating Symbols, Symbols
+@section Property Lists
+@cindex property list
+@cindex plist
+
+  A @dfn{property list} (@dfn{plist} for short) is a list of paired
+elements stored in the property list cell of a symbol.  Each of the
+pairs associates a property name (usually a symbol) with a property or
+value.  Property lists are generally used to record information about a
+symbol, such as its documentation as a variable, the name of the file
+where it was defined, or perhaps even the grammatical class of the
+symbol (representing a word) in a language-understanding system.
+
+  Character positions in a string or buffer can also have property lists.
+@xref{Text Properties}.
+
+  The property names and values in a property list can be any Lisp
+objects, but the names are usually symbols.  Property list functions
+compare the property names using @code{eq}.  Here is an example of a
+property list, found on the symbol @code{progn} when the compiler is
+loaded:
+
+@example
+(lisp-indent-function 0 byte-compile byte-compile-progn)
+@end example
+
+@noindent
+Here @code{lisp-indent-function} and @code{byte-compile} are property
+names, and the other two elements are the corresponding values.
+
+@menu
+* Plists and Alists::           Comparison of the advantages of property
+                                  lists and association lists.
+* Symbol Plists::               Functions to access symbols' property lists.
+* Other Plists::                Accessing property lists stored elsewhere.
+@end menu
+
+@node Plists and Alists
+@subsection Property Lists and Association Lists
+@cindex plist vs. alist
+@cindex alist vs. plist
+
+@cindex property lists vs association lists
+  Association lists (@pxref{Association Lists}) are very similar to
+property lists.  In contrast to association lists, the order of the
+pairs in the property list is not significant since the property names
+must be distinct.
+
+  Property lists are better than association lists for attaching
+information to various Lisp function names or variables.  If your
+program keeps all of its associations in one association list, it will
+typically need to search that entire list each time it checks for an
+association.  This could be slow.  By contrast, if you keep the same
+information in the property lists of the function names or variables
+themselves, each search will scan only the length of one property list,
+which is usually short.  This is why the documentation for a variable is
+recorded in a property named @code{variable-documentation}.  The byte
+compiler likewise uses properties to record those functions needing
+special treatment.
+
+  However, association lists have their own advantages.  Depending on
+your application, it may be faster to add an association to the front of
+an association list than to update a property.  All properties for a
+symbol are stored in the same property list, so there is a possibility
+of a conflict between different uses of a property name.  (For this
+reason, it is a good idea to choose property names that are probably
+unique, such as by beginning the property name with the program's usual
+name-prefix for variables and functions.)  An association list may be
+used like a stack where associations are pushed on the front of the list
+and later discarded; this is not possible with a property list.
+
+@node Symbol Plists
+@subsection Property List Functions for Symbols
+
+@defun symbol-plist symbol
+This function returns the property list of @var{symbol}.
+@end defun
+
+@defun setplist symbol plist
+This function sets @var{symbol}'s property list to @var{plist}.
+Normally, @var{plist} should be a well-formed property list, but this is
+not enforced.  The return value is @var{plist}.
+
+@smallexample
+(setplist 'foo '(a 1 b (2 3) c nil))
+     @result{} (a 1 b (2 3) c nil)
+(symbol-plist 'foo)
+     @result{} (a 1 b (2 3) c nil)
+@end smallexample
+
+For symbols in special obarrays, which are not used for ordinary
+purposes, it may make sense to use the property list cell in a
+nonstandard fashion; in fact, the abbrev mechanism does so
+(@pxref{Abbrevs}).
+@end defun
+
+@defun get symbol property
+This function finds the value of the property named @var{property} in
+@var{symbol}'s property list.  If there is no such property, @code{nil}
+is returned.  Thus, there is no distinction between a value of
+@code{nil} and the absence of the property.
+
+The name @var{property} is compared with the existing property names
+using @code{eq}, so any object is a legitimate property.
+
+See @code{put} for an example.
+@end defun
+
+@defun put symbol property value
+This function puts @var{value} onto @var{symbol}'s property list under
+the property name @var{property}, replacing any previous property value.
+The @code{put} function returns @var{value}.
+
+@smallexample
+(put 'fly 'verb 'transitive)
+     @result{}'transitive
+(put 'fly 'noun '(a buzzing little bug))
+     @result{} (a buzzing little bug)
+(get 'fly 'verb)
+     @result{} transitive
+(symbol-plist 'fly)
+     @result{} (verb transitive noun (a buzzing little bug))
+@end smallexample
+@end defun
+
+@node Other Plists
+@subsection Property Lists Outside Symbols
+
+  These functions are useful for manipulating property lists
+that are stored in places other than symbols:
+
+@defun plist-get plist property
+This returns the value of the @var{property} property
+stored in the property list @var{plist}.  For example,
+
+@example
+(plist-get '(foo 4) 'foo)
+     @result{} 4
+(plist-get '(foo 4 bad) 'foo)
+     @result{} 4
+(plist-get '(foo 4 bad) 'bar)
+     @result{} @code{wrong-type-argument} error
+@end example
+
+It accepts a malformed @var{plist} argument and always returns @code{nil}
+if @var{property} is not found in the @var{plist}.  For example,
+
+@example
+(plist-get '(foo 4 bad) 'bar)
+     @result{} nil
+@end example
+@end defun
+
+@defun plist-put plist property value
+This stores @var{value} as the value of the @var{property} property in
+the property list @var{plist}.  It may modify @var{plist} destructively,
+or it may construct a new list structure without altering the old.  The
+function returns the modified property list, so you can store that back
+in the place where you got @var{plist}.  For example,
+
+@example
+(setq my-plist '(bar t foo 4))
+     @result{} (bar t foo 4)
+(setq my-plist (plist-put my-plist 'foo 69))
+     @result{} (bar t foo 69)
+(setq my-plist (plist-put my-plist 'quux '(a)))
+     @result{} (bar t foo 69 quux (a))
+@end example
+@end defun
+
+  You could define @code{put} in terms of @code{plist-put} as follows:
+
+@example
+(defun put (symbol prop value)
+  (setplist symbol
+            (plist-put (symbol-plist symbol) prop value)))
+@end example
+
+@defun lax-plist-get plist property
+Like @code{plist-get} except that it compares properties
+using @code{equal} instead of @code{eq}.
+@end defun
+
+@defun lax-plist-put plist property value
+Like @code{plist-put} except that it compares properties
+using @code{equal} instead of @code{eq}.
+@end defun
+
+@defun plist-member plist property
+This returns non-@code{nil} if @var{plist} contains the given
+@var{property}.  Unlike @code{plist-get}, this allows you to distinguish
+between a missing property and a property with the value @code{nil}.
+The value is actually the tail of @var{plist} whose @code{car} is
+@var{property}.
+@end defun
+
+@ignore
+   arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce
+@end ignore
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
new file mode 100644
index 00000000000..340f74632bd
--- /dev/null
+++ b/doc/lispref/syntax.texi
@@ -0,0 +1,1185 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/syntax
+@node Syntax Tables, Abbrevs, Searching and Matching, Top
+@chapter Syntax Tables
+@cindex parsing buffer text
+@cindex syntax table
+@cindex text parsing
+
+  A @dfn{syntax table} specifies the syntactic textual function of each
+character.  This information is used by the @dfn{parsing functions}, the
+complex movement commands, and others to determine where words, symbols,
+and other syntactic constructs begin and end.  The current syntax table
+controls the meaning of the word motion functions (@pxref{Word Motion})
+and the list motion functions (@pxref{List Motion}), as well as the
+functions in this chapter.
+
+@menu
+* Basics: Syntax Basics.     Basic concepts of syntax tables.
+* Desc: Syntax Descriptors.  How characters are classified.
+* Syntax Table Functions::   How to create, examine and alter syntax tables.
+* Syntax Properties::        Overriding syntax with text properties.
+* Motion and Syntax::	     Moving over characters with certain syntaxes.
+* Parsing Expressions::      Parsing balanced expressions
+                                using the syntax table.
+* Standard Syntax Tables::   Syntax tables used by various major modes.
+* Syntax Table Internals::   How syntax table information is stored.
+* Categories::               Another way of classifying character syntax.
+@end menu
+
+@node Syntax Basics
+@section Syntax Table Concepts
+
+@ifnottex
+  A @dfn{syntax table} provides Emacs with the information that
+determines the syntactic use of each character in a buffer.  This
+information is used by the parsing commands, the complex movement
+commands, and others to determine where words, symbols, and other
+syntactic constructs begin and end.  The current syntax table controls
+the meaning of the word motion functions (@pxref{Word Motion}) and the
+list motion functions (@pxref{List Motion}) as well as the functions in
+this chapter.
+@end ifnottex
+
+  A syntax table is a char-table (@pxref{Char-Tables}).  The element at
+index @var{c} describes the character with code @var{c}.  The element's
+value should be a list that encodes the syntax of the character in
+question.
+
+  Syntax tables are used only for moving across text, not for the Emacs
+Lisp reader.  Emacs Lisp uses built-in syntactic rules when reading Lisp
+expressions, and these rules cannot be changed.  (Some Lisp systems
+provide ways to redefine the read syntax, but we decided to leave this
+feature out of Emacs Lisp for simplicity.)
+
+  Each buffer has its own major mode, and each major mode has its own
+idea of the syntactic class of various characters.  For example, in Lisp
+mode, the character @samp{;} begins a comment, but in C mode, it
+terminates a statement.  To support these variations, Emacs makes the
+choice of syntax table local to each buffer.  Typically, each major
+mode has its own syntax table and installs that table in each buffer
+that uses that mode.  Changing this table alters the syntax in all
+those buffers as well as in any buffers subsequently put in that mode.
+Occasionally several similar modes share one syntax table.
+@xref{Example Major Modes}, for an example of how to set up a syntax
+table.
+
+A syntax table can inherit the data for some characters from the
+standard syntax table, while specifying other characters itself.  The
+``inherit'' syntax class means ``inherit this character's syntax from
+the standard syntax table.''  Just changing the standard syntax for a
+character affects all syntax tables that inherit from it.
+
+@defun syntax-table-p object
+This function returns @code{t} if @var{object} is a syntax table.
+@end defun
+
+@node Syntax Descriptors
+@section Syntax Descriptors
+@cindex syntax class
+
+  This section describes the syntax classes and flags that denote the
+syntax of a character, and how they are represented as a @dfn{syntax
+descriptor}, which is a Lisp string that you pass to
+@code{modify-syntax-entry} to specify the syntax you want.
+
+  The syntax table specifies a syntax class for each character.  There
+is no necessary relationship between the class of a character in one
+syntax table and its class in any other table.
+
+  Each class is designated by a mnemonic character, which serves as the
+name of the class when you need to specify a class.  Usually the
+designator character is one that is often assigned that class; however,
+its meaning as a designator is unvarying and independent of what syntax
+that character currently has.  Thus, @samp{\} as a designator character
+always gives ``escape character'' syntax, regardless of what syntax
+@samp{\} currently has.
+
+@cindex syntax descriptor
+  A syntax descriptor is a Lisp string that specifies a syntax class, a
+matching character (used only for the parenthesis classes) and flags.
+The first character is the designator for a syntax class.  The second
+character is the character to match; if it is unused, put a space there.
+Then come the characters for any desired flags.  If no matching
+character or flags are needed, one character is sufficient.
+
+  For example, the syntax descriptor for the character @samp{*} in C
+mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot
+unused, second character of a comment-starter, first character of a
+comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
+punctuation, matching character slot unused, first character of a
+comment-starter, second character of a comment-ender).
+
+@menu
+* Syntax Class Table::      Table of syntax classes.
+* Syntax Flags::            Additional flags each character can have.
+@end menu
+
+@node Syntax Class Table
+@subsection Table of Syntax Classes
+
+  Here is a table of syntax classes, the characters that stand for them,
+their meanings, and examples of their use.
+
+@deffn {Syntax class} @w{whitespace character}
+@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-})
+separate symbols and words from each other.  Typically, whitespace
+characters have no other syntactic significance, and multiple whitespace
+characters are syntactically equivalent to a single one.  Space, tab,
+newline and formfeed are classified as whitespace in almost all major
+modes.
+@end deffn
+
+@deffn {Syntax class} @w{word constituent}
+@dfn{Word constituents} (designated by @samp{w}) are parts of words in
+human languages, and are typically used in variable and command names
+in programs.  All upper- and lower-case letters, and the digits, are
+typically word constituents.
+@end deffn
+
+@deffn {Syntax class} @w{symbol constituent}
+@dfn{Symbol constituents} (designated by @samp{_}) are the extra
+characters that are used in variable and command names along with word
+constituents.  For example, the symbol constituents class is used in
+Lisp mode to indicate that certain characters may be part of symbol
+names even though they are not part of English words.  These characters
+are @samp{$&*+-_<>}.  In standard C, the only non-word-constituent
+character that is valid in symbols is underscore (@samp{_}).
+@end deffn
+
+@deffn {Syntax class} @w{punctuation character}
+@dfn{Punctuation characters} (designated by @samp{.}) are those
+characters that are used as punctuation in English, or are used in some
+way in a programming language to separate symbols from one another.
+Some programming language modes, such as Emacs Lisp mode, have no
+characters in this class since the few characters that are not symbol or
+word constituents all have other uses.  Other programming language modes,
+such as C mode, use punctuation syntax for operators.
+@end deffn
+
+@deffn {Syntax class} @w{open parenthesis character}
+@deffnx {Syntax class} @w{close parenthesis character}
+@cindex parenthesis syntax
+Open and close @dfn{parenthesis characters} are characters used in
+dissimilar pairs to surround sentences or expressions.  Such a grouping
+is begun with an open parenthesis character and terminated with a close.
+Each open parenthesis character matches a particular close parenthesis
+character, and vice versa.  Normally, Emacs indicates momentarily the
+matching open parenthesis when you insert a close parenthesis.
+@xref{Blinking}.
+
+The class of open parentheses is designated by @samp{(}, and that of
+close parentheses by @samp{)}.
+
+In English text, and in C code, the parenthesis pairs are @samp{()},
+@samp{[]}, and @samp{@{@}}.  In Emacs Lisp, the delimiters for lists and
+vectors (@samp{()} and @samp{[]}) are classified as parenthesis
+characters.
+@end deffn
+
+@deffn {Syntax class} @w{string quote}
+@dfn{String quote characters} (designated by @samp{"}) are used in
+many languages, including Lisp and C, to delimit string constants.  The
+same string quote character appears at the beginning and the end of a
+string.  Such quoted strings do not nest.
+
+The parsing facilities of Emacs consider a string as a single token.
+The usual syntactic meanings of the characters in the string are
+suppressed.
+
+The Lisp modes have two string quote characters: double-quote (@samp{"})
+and vertical bar (@samp{|}).  @samp{|} is not used in Emacs Lisp, but it
+is used in Common Lisp.  C also has two string quote characters:
+double-quote for strings, and single-quote (@samp{'}) for character
+constants.
+
+English text has no string quote characters because English is not a
+programming language.  Although quotation marks are used in English,
+we do not want them to turn off the usual syntactic properties of
+other characters in the quotation.
+@end deffn
+
+@deffn {Syntax class} @w{escape-syntax character}
+An @dfn{escape character} (designated by @samp{\}) starts an escape
+sequence such as is used in C string and character constants.  The
+character @samp{\} belongs to this class in both C and Lisp.  (In C, it
+is used thus only inside strings, but it turns out to cause no trouble
+to treat it this way throughout C code.)
+
+Characters in this class count as part of words if
+@code{words-include-escapes} is non-@code{nil}.  @xref{Word Motion}.
+@end deffn
+
+@deffn {Syntax class} @w{character quote}
+A @dfn{character quote character} (designated by @samp{/}) quotes the
+following character so that it loses its normal syntactic meaning.  This
+differs from an escape character in that only the character immediately
+following is ever affected.
+
+Characters in this class count as part of words if
+@code{words-include-escapes} is non-@code{nil}.  @xref{Word Motion}.
+
+This class is used for backslash in @TeX{} mode.
+@end deffn
+
+@deffn {Syntax class} @w{paired delimiter}
+@dfn{Paired delimiter characters} (designated by @samp{$}) are like
+string quote characters except that the syntactic properties of the
+characters between the delimiters are not suppressed.  Only @TeX{} mode
+uses a paired delimiter presently---the @samp{$} that both enters and
+leaves math mode.
+@end deffn
+
+@deffn {Syntax class} @w{expression prefix}
+An @dfn{expression prefix operator} (designated by @samp{'}) is used for
+syntactic operators that are considered as part of an expression if they
+appear next to one.  In Lisp modes, these characters include the
+apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in
+macros), and @samp{#} (used in the read syntax for certain data types).
+@end deffn
+
+@deffn {Syntax class} @w{comment starter}
+@deffnx {Syntax class} @w{comment ender}
+@cindex comment syntax
+The @dfn{comment starter} and @dfn{comment ender} characters are used in
+various languages to delimit comments.  These classes are designated
+by @samp{<} and @samp{>}, respectively.
+
+English text has no comment characters.  In Lisp, the semicolon
+(@samp{;}) starts a comment and a newline or formfeed ends one.
+@end deffn
+
+@deffn {Syntax class} @w{inherit standard syntax}
+This syntax class does not specify a particular syntax.  It says to look
+in the standard syntax table to find the syntax of this character.  The
+designator for this syntax class is @samp{@@}.
+@end deffn
+
+@deffn {Syntax class} @w{generic comment delimiter}
+A @dfn{generic comment delimiter} (designated by @samp{!}) starts
+or ends a special kind of comment.  @emph{Any} generic comment delimiter
+matches @emph{any} generic comment delimiter, but they cannot match
+a comment starter or comment ender; generic comment delimiters can only
+match each other.
+
+This syntax class is primarily meant for use with the
+@code{syntax-table} text property (@pxref{Syntax Properties}).  You can
+mark any range of characters as forming a comment, by giving the first
+and last characters of the range @code{syntax-table} properties
+identifying them as generic comment delimiters.
+@end deffn
+
+@deffn {Syntax class} @w{generic string delimiter}
+A @dfn{generic string delimiter} (designated by @samp{|}) starts or ends
+a string.  This class differs from the string quote class in that @emph{any}
+generic string delimiter can match any other generic string delimiter; but
+they do not match ordinary string quote characters.
+
+This syntax class is primarily meant for use with the
+@code{syntax-table} text property (@pxref{Syntax Properties}).  You can
+mark any range of characters as forming a string constant, by giving the
+first and last characters of the range @code{syntax-table} properties
+identifying them as generic string delimiters.
+@end deffn
+
+@node Syntax Flags
+@subsection Syntax Flags
+@cindex syntax flags
+
+  In addition to the classes, entries for characters in a syntax table
+can specify flags.  There are seven possible flags, represented by the
+characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{n},
+and @samp{p}.
+
+  All the flags except @samp{n} and @samp{p} are used to describe
+multi-character comment delimiters.  The digit flags indicate that a
+character can @emph{also} be part of a comment sequence, in addition to
+the syntactic properties associated with its character class.  The flags
+are independent of the class and each other for the sake of characters
+such as @samp{*} in C mode, which is a punctuation character, @emph{and}
+the second character of a start-of-comment sequence (@samp{/*}),
+@emph{and} the first character of an end-of-comment sequence
+(@samp{*/}).
+
+  Here is a table of the possible flags for a character @var{c},
+and what they mean:
+
+@itemize @bullet
+@item
+@samp{1} means @var{c} is the start of a two-character comment-start
+sequence.
+
+@item
+@samp{2} means @var{c} is the second character of such a sequence.
+
+@item
+@samp{3} means @var{c} is the start of a two-character comment-end
+sequence.
+
+@item
+@samp{4} means @var{c} is the second character of such a sequence.
+
+@item
+@c Emacs 19 feature
+@samp{b} means that @var{c} as a comment delimiter belongs to the
+alternative ``b'' comment style.
+
+Emacs supports two comment styles simultaneously in any one syntax
+table.  This is for the sake of C++.  Each style of comment syntax has
+its own comment-start sequence and its own comment-end sequence.  Each
+comment must stick to one style or the other; thus, if it starts with
+the comment-start sequence of style ``b,'' it must also end with the
+comment-end sequence of style ``b.''
+
+The two comment-start sequences must begin with the same character; only
+the second character may differ.  Mark the second character of the
+``b''-style comment-start sequence with the @samp{b} flag.
+
+A comment-end sequence (one or two characters) applies to the ``b''
+style if its first character has the @samp{b} flag set; otherwise, it
+applies to the ``a'' style.
+
+The appropriate comment syntax settings for C++ are as follows:
+
+@table @asis
+@item @samp{/}
+@samp{124b}
+@item @samp{*}
+@samp{23}
+@item newline
+@samp{>b}
+@end table
+
+This defines four comment-delimiting sequences:
+
+@table @asis
+@item @samp{/*}
+This is a comment-start sequence for ``a'' style because the
+second character, @samp{*}, does not have the @samp{b} flag.
+
+@item @samp{//}
+This is a comment-start sequence for ``b'' style because the second
+character, @samp{/}, does have the @samp{b} flag.
+
+@item @samp{*/}
+This is a comment-end sequence for ``a'' style because the first
+character, @samp{*}, does not have the @samp{b} flag.
+
+@item newline
+This is a comment-end sequence for ``b'' style, because the newline
+character has the @samp{b} flag.
+@end table
+
+@item
+@samp{n} on a comment delimiter character specifies
+that this kind of comment can be nested.  For a two-character
+comment delimiter, @samp{n} on either character makes it
+nestable.
+
+@item
+@c Emacs 19 feature
+@samp{p} identifies an additional ``prefix character'' for Lisp syntax.
+These characters are treated as whitespace when they appear between
+expressions.  When they appear within an expression, they are handled
+according to their usual syntax classes.
+
+The function @code{backward-prefix-chars} moves back over these
+characters, as well as over characters whose primary syntax class is
+prefix (@samp{'}).  @xref{Motion and Syntax}.
+@end itemize
+
+@node Syntax Table Functions
+@section Syntax Table Functions
+
+  In this section we describe functions for creating, accessing and
+altering syntax tables.
+
+@defun make-syntax-table &optional table
+This function creates a new syntax table, with all values initialized
+to @code{nil}.  If @var{table} is non-@code{nil}, it becomes the
+parent of the new syntax table, otherwise the standard syntax table is
+the parent.  Like all char-tables, a syntax table inherits from its
+parent.  Thus the original syntax of all characters in the returned
+syntax table is determined by the parent.  @xref{Char-Tables}.
+
+Most major mode syntax tables are created in this way.
+@end defun
+
+@defun copy-syntax-table &optional table
+This function constructs a copy of @var{table} and returns it.  If
+@var{table} is not supplied (or is @code{nil}), it returns a copy of the
+standard syntax table.  Otherwise, an error is signaled if @var{table} is
+not a syntax table.
+@end defun
+
+@deffn Command modify-syntax-entry char syntax-descriptor  &optional table
+This function sets the syntax entry for @var{char} according to
+@var{syntax-descriptor}.  The syntax is changed only for @var{table},
+which defaults to the current buffer's syntax table, and not in any
+other syntax table.  The argument @var{syntax-descriptor} specifies the
+desired syntax; this is a string beginning with a class designator
+character, and optionally containing a matching character and flags as
+well.  @xref{Syntax Descriptors}.
+
+This function always returns @code{nil}.  The old syntax information in
+the table for this character is discarded.
+
+An error is signaled if the first character of the syntax descriptor is not
+one of the seventeen syntax class designator characters.  An error is also
+signaled if @var{char} is not a character.
+
+@example
+@group
+@exdent @r{Examples:}
+
+;; @r{Put the space character in class whitespace.}
+(modify-syntax-entry ?\s " ")
+     @result{} nil
+@end group
+
+@group
+;; @r{Make @samp{$} an open parenthesis character,}
+;;   @r{with @samp{^} as its matching close.}
+(modify-syntax-entry ?$ "(^")
+     @result{} nil
+@end group
+
+@group
+;; @r{Make @samp{^} a close parenthesis character,}
+;;   @r{with @samp{$} as its matching open.}
+(modify-syntax-entry ?^ ")$")
+     @result{} nil
+@end group
+
+@group
+;; @r{Make @samp{/} a punctuation character,}
+;;   @r{the first character of a start-comment sequence,}
+;;   @r{and the second character of an end-comment sequence.}
+;;   @r{This is used in C mode.}
+(modify-syntax-entry ?/ ". 14")
+     @result{} nil
+@end group
+@end example
+@end deffn
+
+@defun char-syntax character
+This function returns the syntax class of @var{character}, represented
+by its mnemonic designator character.  This returns @emph{only} the
+class, not any matching parenthesis or flags.
+
+An error is signaled if @var{char} is not a character.
+
+The following examples apply to C mode.  The first example shows that
+the syntax class of space is whitespace (represented by a space).  The
+second example shows that the syntax of @samp{/} is punctuation.  This
+does not show the fact that it is also part of comment-start and -end
+sequences.  The third example shows that open parenthesis is in the class
+of open parentheses.  This does not show the fact that it has a matching
+character, @samp{)}.
+
+@example
+@group
+(string (char-syntax ?\s))
+     @result{} " "
+@end group
+
+@group
+(string (char-syntax ?/))
+     @result{} "."
+@end group
+
+@group
+(string (char-syntax ?\())
+     @result{} "("
+@end group
+@end example
+
+We use @code{string} to make it easier to see the character returned by
+@code{char-syntax}.
+@end defun
+
+@defun set-syntax-table table
+This function makes @var{table} the syntax table for the current buffer.
+It returns @var{table}.
+@end defun
+
+@defun syntax-table
+This function returns the current syntax table, which is the table for
+the current buffer.
+@end defun
+
+@defmac with-syntax-table @var{table} @var{body}@dots{}
+This macro executes @var{body} using @var{table} as the current syntax
+table.  It returns the value of the last form in @var{body}, after
+restoring the old current syntax table.
+
+Since each buffer has its own current syntax table, we should make that
+more precise: @code{with-syntax-table} temporarily alters the current
+syntax table of whichever buffer is current at the time the macro
+execution starts.  Other buffers are not affected.
+@end defmac
+
+@node Syntax Properties
+@section Syntax Properties
+@kindex syntax-table @r{(text property)}
+
+When the syntax table is not flexible enough to specify the syntax of
+a language, you can use @code{syntax-table} text properties to
+override the syntax table for specific character occurrences in the
+buffer.  @xref{Text Properties}.  You can use Font Lock mode to set
+@code{syntax-table} text properties.  @xref{Setting Syntax
+Properties}.
+
+The valid values of @code{syntax-table} text property are:
+
+@table @asis
+@item @var{syntax-table}
+If the property value is a syntax table, that table is used instead of
+the current buffer's syntax table to determine the syntax for this
+occurrence of the character.
+
+@item @code{(@var{syntax-code} . @var{matching-char})}
+A cons cell of this format specifies the syntax for this
+occurrence of the character.  (@pxref{Syntax Table Internals})
+
+@item @code{nil}
+If the property is @code{nil}, the character's syntax is determined from
+the current syntax table in the usual way.
+@end table
+
+@defvar parse-sexp-lookup-properties
+If this is non-@code{nil}, the syntax scanning functions pay attention
+to syntax text properties.  Otherwise they use only the current syntax
+table.
+@end defvar
+
+@node Motion and Syntax
+@section Motion and Syntax
+
+  This section describes functions for moving across characters that
+have certain syntax classes.
+
+@defun skip-syntax-forward syntaxes &optional limit
+This function moves point forward across characters having syntax
+classes mentioned in @var{syntaxes} (a string of syntax class
+characters).  It stops when it encounters the end of the buffer, or
+position @var{limit} (if specified), or a character it is not supposed
+to skip.
+
+If @var{syntaxes} starts with @samp{^}, then the function skips
+characters whose syntax is @emph{not} in @var{syntaxes}.
+
+The return value is the distance traveled, which is a nonnegative
+integer.
+@end defun
+
+@defun skip-syntax-backward syntaxes &optional limit
+This function moves point backward across characters whose syntax
+classes are mentioned in @var{syntaxes}.  It stops when it encounters
+the beginning of the buffer, or position @var{limit} (if specified), or
+a character it is not supposed to skip.
+
+If @var{syntaxes} starts with @samp{^}, then the function skips
+characters whose syntax is @emph{not} in @var{syntaxes}.
+
+The return value indicates the distance traveled.  It is an integer that
+is zero or less.
+@end defun
+
+@defun backward-prefix-chars
+This function moves point backward over any number of characters with
+expression prefix syntax.  This includes both characters in the
+expression prefix syntax class, and characters with the @samp{p} flag.
+@end defun
+
+@node Parsing Expressions
+@section Parsing Expressions
+
+  This section describes functions for parsing and scanning balanced
+expressions, also known as @dfn{sexps}.  Basically, a sexp is either a
+balanced parenthetical grouping, a string, or a symbol name (a
+sequence of characters whose syntax is either word constituent or
+symbol constituent).  However, characters whose syntax is expression
+prefix are treated as part of the sexp if they appear next to it.
+
+  The syntax table controls the interpretation of characters, so these
+functions can be used for Lisp expressions when in Lisp mode and for C
+expressions when in C mode.  @xref{List Motion}, for convenient
+higher-level functions for moving over balanced expressions.
+
+  A character's syntax controls how it changes the state of the
+parser, rather than describing the state itself.  For example, a
+string delimiter character toggles the parser state between
+``in-string'' and ``in-code,'' but the syntax of characters does not
+directly say whether they are inside a string.  For example (note that
+15 is the syntax code for generic string delimiters),
+
+@example
+(put-text-property 1 9 'syntax-table '(15 . nil))
+@end example
+
+@noindent
+does not tell Emacs that the first eight chars of the current buffer
+are a string, but rather that they are all string delimiters.  As a
+result, Emacs treats them as four consecutive empty string constants.
+
+@menu
+* Motion via Parsing::       Motion functions that work by parsing.
+* Position Parse::           Determining the syntactic state of a position.
+* Parser State::             How Emacs represents a syntactic state.
+* Low-Level Parsing::        Parsing across a specified region.
+* Control Parsing::          Parameters that affect parsing.
+@end menu
+
+@node Motion via Parsing
+@subsection Motion Commands Based on Parsing
+
+  This section describes simple point-motion functions that operate
+based on parsing expressions.
+
+@defun scan-lists from count depth
+This function scans forward @var{count} balanced parenthetical groupings
+from position @var{from}.  It returns the position where the scan stops.
+If @var{count} is negative, the scan moves backwards.
+
+If @var{depth} is nonzero, parenthesis depth counting begins from that
+value.  The only candidates for stopping are places where the depth in
+parentheses becomes zero; @code{scan-lists} counts @var{count} such
+places and then stops.  Thus, a positive value for @var{depth} means go
+out @var{depth} levels of parenthesis.
+
+Scanning ignores comments if @code{parse-sexp-ignore-comments} is
+non-@code{nil}.
+
+If the scan reaches the beginning or end of the buffer (or its
+accessible portion), and the depth is not zero, an error is signaled.
+If the depth is zero but the count is not used up, @code{nil} is
+returned.
+@end defun
+
+@defun scan-sexps from count
+This function scans forward @var{count} sexps from position @var{from}.
+It returns the position where the scan stops.  If @var{count} is
+negative, the scan moves backwards.
+
+Scanning ignores comments if @code{parse-sexp-ignore-comments} is
+non-@code{nil}.
+
+If the scan reaches the beginning or end of (the accessible part of) the
+buffer while in the middle of a parenthetical grouping, an error is
+signaled.  If it reaches the beginning or end between groupings but
+before count is used up, @code{nil} is returned.
+@end defun
+
+@defun forward-comment count
+This function moves point forward across @var{count} complete comments
+     (that is, including the starting delimiter and the terminating
+delimiter if any), plus any whitespace encountered on the way.  It
+moves backward if @var{count} is negative.  If it encounters anything
+other than a comment or whitespace, it stops, leaving point at the
+place where it stopped.  This includes (for instance) finding the end
+of a comment when moving forward and expecting the beginning of one.
+The function also stops immediately after moving over the specified
+number of complete comments.  If @var{count} comments are found as
+expected, with nothing except whitespace between them, it returns
+@code{t}; otherwise it returns @code{nil}.
+
+This function cannot tell whether the ``comments'' it traverses are
+embedded within a string.  If they look like comments, it treats them
+as comments.
+@end defun
+
+To move forward over all comments and whitespace following point, use
+@code{(forward-comment (buffer-size))}.  @code{(buffer-size)} is a good
+argument to use, because the number of comments in the buffer cannot
+exceed that many.
+
+@node Position Parse
+@subsection Finding the Parse State for a Position
+
+  For syntactic analysis, such as in indentation, often the useful
+thing is to compute the syntactic state corresponding to a given buffer
+position.  This function does that conveniently.
+
+@defun syntax-ppss &optional pos
+This function returns the parser state (see next section) that the
+parser would reach at position @var{pos} starting from the beginning
+of the buffer.  This is equivalent to @code{(parse-partial-sexp
+(point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache
+to speed up the computation.  Due to this optimization, the 2nd value
+(previous complete subexpression) and 6th value (minimum parenthesis
+depth) of the returned parser state are not meaningful.
+@end defun
+
+   @code{syntax-ppss} automatically hooks itself to
+@code{before-change-functions} to keep its cache consistent.  But
+updating can fail if @code{syntax-ppss} is called while
+@code{before-change-functions} is temporarily let-bound, or if the
+buffer is modified without obeying the hook, such as when using
+@code{inhibit-modification-hooks}.  For this reason, it is sometimes
+necessary to flush the cache manually.
+
+@defun syntax-ppss-flush-cache beg
+This function flushes the cache used by @code{syntax-ppss}, starting at
+position @var{beg}.
+@end defun
+
+  Major modes can make @code{syntax-ppss} run faster by specifying
+where it needs to start parsing.
+
+@defvar syntax-begin-function
+If this is non-@code{nil}, it should be a function that moves to an
+earlier buffer position where the parser state is equivalent to
+@code{nil}---in other words, a position outside of any comment,
+string, or parenthesis.  @code{syntax-ppss} uses it to further
+optimize its computations, when the cache gives no help.
+@end defvar
+
+@node Parser State
+@subsection Parser State
+@cindex parser state
+
+  A @dfn{parser state} is a list of ten elements describing the final
+state of parsing text syntactically as part of an expression.  The
+parsing functions in the following sections return a parser state as
+the value, and in some cases accept one as an argument also, so that
+you can resume parsing after it stops.  Here are the meanings of the
+elements of the parser state:
+
+@enumerate 0
+@item
+The depth in parentheses, counting from 0.  @strong{Warning:} this can
+be negative if there are more close parens than open parens between
+the start of the defun and point.
+
+@item
+@cindex innermost containing parentheses
+The character position of the start of the innermost parenthetical
+grouping containing the stopping point; @code{nil} if none.
+
+@item
+@cindex previous complete subexpression
+The character position of the start of the last complete subexpression
+terminated; @code{nil} if none.
+
+@item
+@cindex inside string
+Non-@code{nil} if inside a string.  More precisely, this is the
+character that will terminate the string, or @code{t} if a generic
+string delimiter character should terminate it.
+
+@item
+@cindex inside comment
+@code{t} if inside a comment (of either style),
+or the comment nesting level if inside a kind of comment
+that can be nested.
+
+@item
+@cindex quote character
+@code{t} if point is just after a quote character.
+
+@item
+The minimum parenthesis depth encountered during this scan.
+
+@item
+What kind of comment is active: @code{nil} for a comment of style
+``a'' or when not inside a comment, @code{t} for a comment of style
+``b,'' and @code{syntax-table} for a comment that should be ended by a
+generic comment delimiter character.
+
+@item
+The string or comment start position.  While inside a comment, this is
+the position where the comment began; while inside a string, this is the
+position where the string began.  When outside of strings and comments,
+this element is @code{nil}.
+
+@item
+Internal data for continuing the parsing.  The meaning of this
+data is subject to change; it is used if you pass this list
+as the @var{state} argument to another call.
+@end enumerate
+
+  Elements 1, 2, and 6 are ignored in a state which you pass as an
+argument to continue parsing, and elements 8 and 9 are used only in
+trivial cases.  Those elements serve primarily to convey information
+to the Lisp program which does the parsing.
+
+  One additional piece of useful information is available from a
+parser state using this function:
+
+@defun syntax-ppss-toplevel-pos state
+This function extracts, from parser state @var{state}, the last
+position scanned in the parse which was at top level in grammatical
+structure.  ``At top level'' means outside of any parentheses,
+comments, or strings.
+
+The value is @code{nil} if @var{state} represents a parse which has
+arrived at a top level position.
+@end defun
+
+  We have provided this access function rather than document how the
+data is represented in the state, because we plan to change the
+representation in the future.
+
+@node Low-Level Parsing
+@subsection Low-Level Parsing
+
+  The most basic way to use the expression parser is to tell it
+to start at a given position with a certain state, and parse up to
+a specified end position.
+
+@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment
+This function parses a sexp in the current buffer starting at
+@var{start}, not scanning past @var{limit}.  It stops at position
+@var{limit} or when certain criteria described below are met, and sets
+point to the location where parsing stops.  It returns a parser state
+describing the status of the parse at the point where it stops.
+
+@cindex parenthesis depth
+If the third argument @var{target-depth} is non-@code{nil}, parsing
+stops if the depth in parentheses becomes equal to @var{target-depth}.
+The depth starts at 0, or at whatever is given in @var{state}.
+
+If the fourth argument @var{stop-before} is non-@code{nil}, parsing
+stops when it comes to any character that starts a sexp.  If
+@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the
+start of a comment.  If @var{stop-comment} is the symbol
+@code{syntax-table}, parsing stops after the start of a comment or a
+string, or the end of a comment or a string, whichever comes first.
+
+If @var{state} is @code{nil}, @var{start} is assumed to be at the top
+level of parenthesis structure, such as the beginning of a function
+definition.  Alternatively, you might wish to resume parsing in the
+middle of the structure.  To do this, you must provide a @var{state}
+argument that describes the initial status of parsing.  The value
+returned by a previous call to @code{parse-partial-sexp} will do
+nicely.
+@end defun
+
+@node Control Parsing
+@subsection Parameters to Control Parsing
+
+@defvar multibyte-syntax-as-symbol
+If this variable is non-@code{nil}, @code{scan-sexps} treats all
+non-@acronym{ASCII} characters as symbol constituents regardless
+of what the syntax table says about them.  (However, text properties
+can still override the syntax.)
+@end defvar
+
+@defopt parse-sexp-ignore-comments
+@cindex skipping comments
+If the value is non-@code{nil}, then comments are treated as
+whitespace by the functions in this section and by @code{forward-sexp},
+@code{scan-lists} and @code{scan-sexps}.
+@end defopt
+
+@vindex parse-sexp-lookup-properties
+The behavior of @code{parse-partial-sexp} is also affected by
+@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).
+
+You can use @code{forward-comment} to move forward or backward over
+one comment or several comments.
+
+@node Standard Syntax Tables
+@section Some Standard Syntax Tables
+
+  Most of the major modes in Emacs have their own syntax tables.  Here
+are several of them:
+
+@defun standard-syntax-table
+This function returns the standard syntax table, which is the syntax
+table used in Fundamental mode.
+@end defun
+
+@defvar text-mode-syntax-table
+The value of this variable is the syntax table used in Text mode.
+@end defvar
+
+@defvar c-mode-syntax-table
+The value of this variable is the syntax table for C-mode buffers.
+@end defvar
+
+@defvar emacs-lisp-mode-syntax-table
+The value of this variable is the syntax table used in Emacs Lisp mode
+by editing commands.  (It has no effect on the Lisp @code{read}
+function.)
+@end defvar
+
+@node Syntax Table Internals
+@section Syntax Table Internals
+@cindex syntax table internals
+
+  Lisp programs don't usually work with the elements directly; the
+Lisp-level syntax table functions usually work with syntax descriptors
+(@pxref{Syntax Descriptors}).  Nonetheless, here we document the
+internal format.  This format is used mostly when manipulating
+syntax properties.
+
+  Each element of a syntax table is a cons cell of the form
+@code{(@var{syntax-code} . @var{matching-char})}.  The @sc{car},
+@var{syntax-code}, is an integer that encodes the syntax class, and any
+flags.  The @sc{cdr}, @var{matching-char}, is non-@code{nil} if
+a character to match was specified.
+
+  This table gives the value of @var{syntax-code} which corresponds
+to each syntactic type.
+
+@multitable @columnfractions .05 .3 .3 .31
+@item
+@tab
+@i{Integer} @i{Class}
+@tab
+@i{Integer} @i{Class}
+@tab
+@i{Integer} @i{Class}
+@item
+@tab
+0 @ @  whitespace
+@tab
+5 @ @  close parenthesis
+@tab
+10 @ @  character quote
+@item
+@tab
+1 @ @  punctuation
+@tab
+6 @ @  expression prefix
+@tab
+11 @ @  comment-start
+@item
+@tab
+2 @ @  word
+@tab
+7 @ @  string quote
+@tab
+12 @ @  comment-end
+@item
+@tab
+3 @ @  symbol
+@tab
+8 @ @  paired delimiter
+@tab
+13 @ @  inherit
+@item
+@tab
+4 @ @  open parenthesis
+@tab
+9 @ @  escape
+@tab
+14 @ @  generic comment
+@item
+@tab
+15 @  generic string
+@end multitable
+
+  For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
+(41 is the character code for @samp{)}.)
+
+  The flags are encoded in higher order bits, starting 16 bits from the
+least significant bit.  This table gives the power of two which
+corresponds to each syntax flag.
+
+@multitable @columnfractions .05 .3 .3 .3
+@item
+@tab
+@i{Prefix} @i{Flag}
+@tab
+@i{Prefix} @i{Flag}
+@tab
+@i{Prefix} @i{Flag}
+@item
+@tab
+@samp{1} @ @  @code{(lsh 1 16)}
+@tab
+@samp{4} @ @  @code{(lsh 1 19)}
+@tab
+@samp{b} @ @  @code{(lsh 1 21)}
+@item
+@tab
+@samp{2} @ @  @code{(lsh 1 17)}
+@tab
+@samp{p} @ @  @code{(lsh 1 20)}
+@tab
+@samp{n} @ @  @code{(lsh 1 22)}
+@item
+@tab
+@samp{3} @ @  @code{(lsh 1 18)}
+@end multitable
+
+@defun string-to-syntax @var{desc}
+This function returns the internal form corresponding to the syntax
+descriptor @var{desc}, a cons cell @code{(@var{syntax-code}
+. @var{matching-char})}.
+@end defun
+
+@defun syntax-after pos
+This function returns the syntax code of the character in the buffer
+after position @var{pos}, taking account of syntax properties as well
+as the syntax table.  If @var{pos} is outside the buffer's accessible
+portion (@pxref{Narrowing, accessible portion}), this function returns
+@code{nil}.
+@end defun
+
+@defun syntax-class syntax
+This function returns the syntax class of the syntax code
+@var{syntax}.  (It masks off the high 16 bits that hold the flags
+encoded in the syntax descriptor.)  If @var{syntax} is @code{nil}, it
+returns @code{nil}; this is so evaluating the expression
+
+@example
+(syntax-class (syntax-after pos))
+@end example
+
+@noindent
+where @code{pos} is outside the buffer's accessible portion, will
+yield @code{nil} without throwing errors or producing wrong syntax
+class codes.
+@end defun
+
+@node Categories
+@section Categories
+@cindex categories of characters
+@cindex character categories
+
+  @dfn{Categories} provide an alternate way of classifying characters
+syntactically.  You can define several categories as needed, then
+independently assign each character to one or more categories.  Unlike
+syntax classes, categories are not mutually exclusive; it is normal for
+one character to belong to several categories.
+
+@cindex category table
+  Each buffer has a @dfn{category table} which records which categories
+are defined and also which characters belong to each category.  Each
+category table defines its own categories, but normally these are
+initialized by copying from the standard categories table, so that the
+standard categories are available in all modes.
+
+  Each category has a name, which is an @acronym{ASCII} printing character in
+the range @w{@samp{ }} to @samp{~}.  You specify the name of a category
+when you define it with @code{define-category}.
+
+  The category table is actually a char-table (@pxref{Char-Tables}).
+The element of the category table at index @var{c} is a @dfn{category
+set}---a bool-vector---that indicates which categories character @var{c}
+belongs to.  In this category set, if the element at index @var{cat} is
+@code{t}, that means category @var{cat} is a member of the set, and that
+character @var{c} belongs to category @var{cat}.
+
+For the next three functions, the optional argument @var{table}
+defaults to the current buffer's category table.
+
+@defun define-category char docstring &optional table
+This function defines a new category, with name @var{char} and
+documentation @var{docstring}, for the category table @var{table}.
+@end defun
+
+@defun category-docstring category &optional table
+This function returns the documentation string of category @var{category}
+in category table @var{table}.
+
+@example
+(category-docstring ?a)
+     @result{} "ASCII"
+(category-docstring ?l)
+     @result{} "Latin"
+@end example
+@end defun
+
+@defun get-unused-category &optional table
+This function returns a category name (a character) which is not
+currently defined in @var{table}.  If all possible categories are in use
+in @var{table}, it returns @code{nil}.
+@end defun
+
+@defun category-table
+This function returns the current buffer's category table.
+@end defun
+
+@defun category-table-p object
+This function returns @code{t} if @var{object} is a category table,
+otherwise @code{nil}.
+@end defun
+
+@defun standard-category-table
+This function returns the standard category table.
+@end defun
+
+@defun copy-category-table &optional table
+This function constructs a copy of @var{table} and returns it.  If
+@var{table} is not supplied (or is @code{nil}), it returns a copy of the
+standard category table.  Otherwise, an error is signaled if @var{table}
+is not a category table.
+@end defun
+
+@defun set-category-table table
+This function makes @var{table} the category table for the current
+buffer.  It returns @var{table}.
+@end defun
+
+@defun make-category-table
+This creates and returns an empty category table.  In an empty category
+table, no categories have been allocated, and no characters belong to
+any categories.
+@end defun
+
+@defun make-category-set categories
+This function returns a new category set---a bool-vector---whose initial
+contents are the categories listed in the string @var{categories}.  The
+elements of @var{categories} should be category names; the new category
+set has @code{t} for each of those categories, and @code{nil} for all
+other categories.
+
+@example
+(make-category-set "al")
+     @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
+@end example
+@end defun
+
+@defun char-category-set char
+This function returns the category set for character @var{char} in the
+current buffer's category table.  This is the bool-vector which
+records which categories the character @var{char} belongs to.  The
+function @code{char-category-set} does not allocate storage, because
+it returns the same bool-vector that exists in the category table.
+
+@example
+(char-category-set ?a)
+     @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
+@end example
+@end defun
+
+@defun category-set-mnemonics category-set
+This function converts the category set @var{category-set} into a string
+containing the characters that designate the categories that are members
+of the set.
+
+@example
+(category-set-mnemonics (char-category-set ?a))
+     @result{} "al"
+@end example
+@end defun
+
+@defun modify-category-entry character category &optional table reset
+This function modifies the category set of @var{character} in category
+table @var{table} (which defaults to the current buffer's category
+table).
+
+Normally, it modifies the category set by adding @var{category} to it.
+But if @var{reset} is non-@code{nil}, then it deletes @var{category}
+instead.
+@end defun
+
+@deffn Command describe-categories &optional buffer-or-name
+This function describes the category specifications in the current
+category table.  It inserts the descriptions in a buffer, and then
+displays that buffer.  If @var{buffer-or-name} is non-@code{nil}, it
+describes the category table of that buffer instead.
+@end deffn
+
+@ignore
+   arch-tag: 4d914e96-0283-445c-9233-75d33662908c
+@end ignore
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
new file mode 100644
index 00000000000..430c48133ee
--- /dev/null
+++ b/doc/lispref/text.texi
@@ -0,0 +1,4303 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/text
+@node Text, Non-ASCII Characters, Markers, Top
+@chapter Text
+@cindex text
+
+  This chapter describes the functions that deal with the text in a
+buffer.  Most examine, insert, or delete text in the current buffer,
+often operating at point or on text adjacent to point.  Many are
+interactive.  All the functions that change the text provide for undoing
+the changes (@pxref{Undo}).
+
+  Many text-related functions operate on a region of text defined by two
+buffer positions passed in arguments named @var{start} and @var{end}.
+These arguments should be either markers (@pxref{Markers}) or numeric
+character positions (@pxref{Positions}).  The order of these arguments
+does not matter; it is all right for @var{start} to be the end of the
+region and @var{end} the beginning.  For example, @code{(delete-region 1
+10)} and @code{(delete-region 10 1)} are equivalent.  An
+@code{args-out-of-range} error is signaled if either @var{start} or
+@var{end} is outside the accessible portion of the buffer.  In an
+interactive call, point and the mark are used for these arguments.
+
+@cindex buffer contents
+  Throughout this chapter, ``text'' refers to the characters in the
+buffer, together with their properties (when relevant).  Keep in mind
+that point is always between two characters, and the cursor appears on
+the character after point.
+
+@menu
+* Near Point::       Examining text in the vicinity of point.
+* Buffer Contents::  Examining text in a general fashion.
+* Comparing Text::   Comparing substrings of buffers.
+* Insertion::        Adding new text to a buffer.
+* Commands for Insertion::  User-level commands to insert text.
+* Deletion::         Removing text from a buffer.
+* User-Level Deletion::     User-level commands to delete text.
+* The Kill Ring::    Where removed text sometimes is saved for later use.
+* Undo::             Undoing changes to the text of a buffer.
+* Maintaining Undo:: How to enable and disable undo information.
+			How to control how much information is kept.
+* Filling::          Functions for explicit filling.
+* Margins::          How to specify margins for filling commands.
+* Adaptive Fill::    Adaptive Fill mode chooses a fill prefix from context.
+* Auto Filling::     How auto-fill mode is implemented to break lines.
+* Sorting::          Functions for sorting parts of the buffer.
+* Columns::          Computing horizontal positions, and using them.
+* Indentation::      Functions to insert or adjust indentation.
+* Case Changes::     Case conversion of parts of the buffer.
+* Text Properties::  Assigning Lisp property lists to text characters.
+* Substitution::     Replacing a given character wherever it appears.
+* Transposition::    Swapping two portions of a buffer.
+* Registers::        How registers are implemented.  Accessing the text or
+                       position stored in a register.
+* Base 64::          Conversion to or from base 64 encoding.
+* MD5 Checksum::     Compute the MD5 "message digest"/"checksum".
+* Atomic Changes::   Installing several buffer changes "atomically".
+* Change Hooks::     Supplying functions to be run when text is changed.
+@end menu
+
+@node Near Point
+@section Examining Text Near Point
+@cindex text near point
+
+  Many functions are provided to look at the characters around point.
+Several simple functions are described here.  See also @code{looking-at}
+in @ref{Regexp Search}.
+
+In the following four functions, ``beginning'' or ``end'' of buffer
+refers to the beginning or end of the accessible portion.
+
+@defun char-after &optional position
+This function returns the character in the current buffer at (i.e.,
+immediately after) position @var{position}.  If @var{position} is out of
+range for this purpose, either before the beginning of the buffer, or at
+or beyond the end, then the value is @code{nil}.  The default for
+@var{position} is point.
+
+In the following example, assume that the first character in the
+buffer is @samp{@@}:
+
+@example
+@group
+(char-to-string (char-after 1))
+     @result{} "@@"
+@end group
+@end example
+@end defun
+
+@defun char-before &optional position
+This function returns the character in the current buffer immediately
+before position @var{position}.  If @var{position} is out of range for
+this purpose, either at or before the beginning of the buffer, or beyond
+the end, then the value is @code{nil}.  The default for
+@var{position} is point.
+@end defun
+
+@defun following-char
+This function returns the character following point in the current
+buffer.  This is similar to @code{(char-after (point))}.  However, if
+point is at the end of the buffer, then @code{following-char} returns 0.
+
+Remember that point is always between characters, and the cursor
+normally appears over the character following point.  Therefore, the
+character returned by @code{following-char} is the character the
+cursor is over.
+
+In this example, point is between the @samp{a} and the @samp{c}.
+
+@example
+@group
+---------- Buffer: foo ----------
+Gentlemen may cry ``Pea@point{}ce! Peace!,''
+but there is no peace.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(char-to-string (preceding-char))
+     @result{} "a"
+(char-to-string (following-char))
+     @result{} "c"
+@end group
+@end example
+@end defun
+
+@defun preceding-char
+This function returns the character preceding point in the current
+buffer.  See above, under @code{following-char}, for an example.  If
+point is at the beginning of the buffer, @code{preceding-char} returns
+0.
+@end defun
+
+@defun bobp
+This function returns @code{t} if point is at the beginning of the
+buffer.  If narrowing is in effect, this means the beginning of the
+accessible portion of the text.  See also @code{point-min} in
+@ref{Point}.
+@end defun
+
+@defun eobp
+This function returns @code{t} if point is at the end of the buffer.
+If narrowing is in effect, this means the end of accessible portion of
+the text.  See also @code{point-max} in @xref{Point}.
+@end defun
+
+@defun bolp
+This function returns @code{t} if point is at the beginning of a line.
+@xref{Text Lines}.  The beginning of the buffer (or of its accessible
+portion) always counts as the beginning of a line.
+@end defun
+
+@defun eolp
+This function returns @code{t} if point is at the end of a line.  The
+end of the buffer (or of its accessible portion) is always considered
+the end of a line.
+@end defun
+
+@node Buffer Contents
+@section Examining Buffer Contents
+
+  This section describes functions that allow a Lisp program to
+convert any portion of the text in the buffer into a string.
+
+@defun buffer-substring start end
+This function returns a string containing a copy of the text of the
+region defined by positions @var{start} and @var{end} in the current
+buffer.  If the arguments are not positions in the accessible portion of
+the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
+error.
+
+It is not necessary for @var{start} to be less than @var{end}; the
+arguments can be given in either order.  But most often the smaller
+argument is written first.
+
+Here's an example which assumes Font-Lock mode is not enabled:
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the contents of buffer foo
+
+---------- Buffer: foo ----------
+@end group
+
+@group
+(buffer-substring 1 10)
+     @result{} "This is t"
+@end group
+@group
+(buffer-substring (point-max) 10)
+     @result{} "he contents of buffer foo\n"
+@end group
+@end example
+
+If the text being copied has any text properties, these are copied into
+the string along with the characters they belong to.  @xref{Text
+Properties}.  However, overlays (@pxref{Overlays}) in the buffer and
+their properties are ignored, not copied.
+
+For example, if Font-Lock mode is enabled, you might get results like
+these:
+
+@example
+@group
+(buffer-substring 1 10)
+     @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
+@end group
+@end example
+@end defun
+
+@defun buffer-substring-no-properties start end
+This is like @code{buffer-substring}, except that it does not copy text
+properties, just the characters themselves.  @xref{Text Properties}.
+@end defun
+
+@defun filter-buffer-substring start end &optional delete noprops
+This function passes the buffer text between @var{start} and @var{end}
+through the filter functions specified by the variable
+@code{buffer-substring-filters}, and returns the value from the last
+filter function.  If @code{buffer-substring-filters} is @code{nil},
+the value is the unaltered text from the buffer, what
+@code{buffer-substring} would return.
+
+If @var{delete} is non-@code{nil}, this function deletes the text
+between @var{start} and @var{end} after copying it, like
+@code{delete-and-extract-region}.
+
+If @var{noprops} is non-@code{nil}, the final string returned does not
+include text properties, while the string passed through the filters
+still includes text properties from the buffer text.
+
+Lisp code should use this function instead of @code{buffer-substring},
+@code{buffer-substring-no-properties},
+or @code{delete-and-extract-region} when copying into user-accessible
+data structures such as the kill-ring, X clipboard, and registers.
+Major and minor modes can add functions to
+@code{buffer-substring-filters} to alter such text as it is copied out
+of the buffer.
+@end defun
+
+@defvar buffer-substring-filters
+This variable should be a list of functions that accept a single
+argument, a string, and return a string.
+@code{filter-buffer-substring} passes the buffer substring to the
+first function in this list, and the return value of each function is
+passed to the next function.  The return value of the last function is
+used as the return value of @code{filter-buffer-substring}.
+
+As a special convention, point is set to the start of the buffer text
+being operated on (i.e., the @var{start} argument for
+@code{filter-buffer-substring}) before these functions are called.
+
+If this variable is @code{nil}, no filtering is performed.
+@end defvar
+
+@defun buffer-string
+This function returns the contents of the entire accessible portion of
+the current buffer as a string.  It is equivalent to
+
+@example
+(buffer-substring (point-min) (point-max))
+@end example
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the contents of buffer foo
+
+---------- Buffer: foo ----------
+
+(buffer-string)
+     @result{} "This is the contents of buffer foo\n"
+@end group
+@end example
+@end defun
+
+@defun current-word &optional strict really-word
+This function returns the symbol (or word) at or near point, as a string.
+The return value includes no text properties.
+
+If the optional argument @var{really-word} is non-@code{nil}, it finds a
+word; otherwise, it finds a symbol (which includes both word
+characters and symbol constituent characters).
+
+If the optional argument @var{strict} is non-@code{nil}, then point
+must be in or next to the symbol or word---if no symbol or word is
+there, the function returns @code{nil}.  Otherwise, a nearby symbol or
+word on the same line is acceptable.
+@end defun
+
+@defun thing-at-point thing
+Return the @var{thing} around or next to point, as a string.
+
+The argument @var{thing} is a symbol which specifies a kind of syntactic
+entity.  Possibilities include @code{symbol}, @code{list}, @code{sexp},
+@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
+@code{whitespace}, @code{line}, @code{page}, and others.
+
+@example
+---------- Buffer: foo ----------
+Gentlemen may cry ``Pea@point{}ce! Peace!,''
+but there is no peace.
+---------- Buffer: foo ----------
+
+(thing-at-point 'word)
+     @result{} "Peace"
+(thing-at-point 'line)
+     @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
+(thing-at-point 'whitespace)
+     @result{} nil
+@end example
+@end defun
+
+@node Comparing Text
+@section Comparing Text
+@cindex comparing buffer text
+
+  This function lets you compare portions of the text in a buffer, without
+copying them into strings first.
+
+@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
+This function lets you compare two substrings of the same buffer or two
+different buffers.  The first three arguments specify one substring,
+giving a buffer (or a buffer name) and two positions within the
+buffer.  The last three arguments specify the other substring in the
+same way.  You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
+both to stand for the current buffer.
+
+The value is negative if the first substring is less, positive if the
+first is greater, and zero if they are equal.  The absolute value of
+the result is one plus the index of the first differing characters
+within the substrings.
+
+This function ignores case when comparing characters
+if @code{case-fold-search} is non-@code{nil}.  It always ignores
+text properties.
+
+Suppose the current buffer contains the text @samp{foobarbar
+haha!rara!}; then in this example the two substrings are @samp{rbar }
+and @samp{rara!}.  The value is 2 because the first substring is greater
+at the second character.
+
+@example
+(compare-buffer-substrings nil 6 11 nil 16 21)
+     @result{} 2
+@end example
+@end defun
+
+@node Insertion
+@section Inserting Text
+@cindex insertion of text
+@cindex text insertion
+
+@cindex insertion before point
+@cindex before point, insertion
+  @dfn{Insertion} means adding new text to a buffer.  The inserted text
+goes at point---between the character before point and the character
+after point.  Some insertion functions leave point before the inserted
+text, while other functions leave it after.  We call the former
+insertion @dfn{after point} and the latter insertion @dfn{before point}.
+
+  Insertion relocates markers that point at positions after the
+insertion point, so that they stay with the surrounding text
+(@pxref{Markers}).  When a marker points at the place of insertion,
+insertion may or may not relocate the marker, depending on the marker's
+insertion type (@pxref{Marker Insertion Types}).  Certain special
+functions such as @code{insert-before-markers} relocate all such markers
+to point after the inserted text, regardless of the markers' insertion
+type.
+
+  Insertion functions signal an error if the current buffer is
+read-only or if they insert within read-only text.
+
+  These functions copy text characters from strings and buffers along
+with their properties.  The inserted characters have exactly the same
+properties as the characters they were copied from.  By contrast,
+characters specified as separate arguments, not part of a string or
+buffer, inherit their text properties from the neighboring text.
+
+  The insertion functions convert text from unibyte to multibyte in
+order to insert in a multibyte buffer, and vice versa---if the text
+comes from a string or from a buffer.  However, they do not convert
+unibyte character codes 128 through 255 to multibyte characters, not
+even if the current buffer is a multibyte buffer.  @xref{Converting
+Representations}.
+
+@defun insert &rest args
+This function inserts the strings and/or characters @var{args} into the
+current buffer, at point, moving point forward.  In other words, it
+inserts the text before point.  An error is signaled unless all
+@var{args} are either strings or characters.  The value is @code{nil}.
+@end defun
+
+@defun insert-before-markers &rest args
+This function inserts the strings and/or characters @var{args} into the
+current buffer, at point, moving point forward.  An error is signaled
+unless all @var{args} are either strings or characters.  The value is
+@code{nil}.
+
+This function is unlike the other insertion functions in that it
+relocates markers initially pointing at the insertion point, to point
+after the inserted text.  If an overlay begins at the insertion point,
+the inserted text falls outside the overlay; if a nonempty overlay
+ends at the insertion point, the inserted text falls inside that
+overlay.
+@end defun
+
+@defun insert-char character count &optional inherit
+This function inserts @var{count} instances of @var{character} into the
+current buffer before point.  The argument @var{count} should be an
+integer, and @var{character} must be a character.  The value is @code{nil}.
+
+This function does not convert unibyte character codes 128 through 255
+to multibyte characters, not even if the current buffer is a multibyte
+buffer.  @xref{Converting Representations}.
+
+If @var{inherit} is non-@code{nil}, then the inserted characters inherit
+sticky text properties from the two characters before and after the
+insertion point.  @xref{Sticky Properties}.
+@end defun
+
+@defun insert-buffer-substring from-buffer-or-name &optional start end
+This function inserts a portion of buffer @var{from-buffer-or-name}
+(which must already exist) into the current buffer before point.  The
+text inserted is the region between @var{start} and @var{end}.  (These
+arguments default to the beginning and end of the accessible portion of
+that buffer.)  This function returns @code{nil}.
+
+In this example, the form is executed with buffer @samp{bar} as the
+current buffer.  We assume that buffer @samp{bar} is initially empty.
+
+@example
+@group
+---------- Buffer: foo ----------
+We hold these truths to be self-evident, that all
+---------- Buffer: foo ----------
+@end group
+
+@group
+(insert-buffer-substring "foo" 1 20)
+     @result{} nil
+
+---------- Buffer: bar ----------
+We hold these truth@point{}
+---------- Buffer: bar ----------
+@end group
+@end example
+@end defun
+
+@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
+This is like @code{insert-buffer-substring} except that it does not
+copy any text properties.
+@end defun
+
+  @xref{Sticky Properties}, for other insertion functions that inherit
+text properties from the nearby text in addition to inserting it.
+Whitespace inserted by indentation functions also inherits text
+properties.
+
+@node Commands for Insertion
+@section User-Level Insertion Commands
+
+  This section describes higher-level commands for inserting text,
+commands intended primarily for the user but useful also in Lisp
+programs.
+
+@deffn Command insert-buffer from-buffer-or-name
+This command inserts the entire accessible contents of
+@var{from-buffer-or-name} (which must exist) into the current buffer
+after point.  It leaves the mark after the inserted text.  The value
+is @code{nil}.
+@end deffn
+
+@deffn Command self-insert-command count
+@cindex character insertion
+@cindex self-insertion
+This command inserts the last character typed; it does so @var{count}
+times, before point, and returns @code{nil}.  Most printing characters
+are bound to this command.  In routine use, @code{self-insert-command}
+is the most frequently called function in Emacs, but programs rarely use
+it except to install it on a keymap.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+
+Self-insertion translates the input character through
+@code{translation-table-for-input}.  @xref{Translation of Characters}.
+
+This command calls @code{auto-fill-function} whenever that is
+non-@code{nil} and the character inserted is in the table
+@code{auto-fill-chars} (@pxref{Auto Filling}).
+
+@c Cross refs reworded to prevent overfull hbox.  --rjc 15mar92
+This command performs abbrev expansion if Abbrev mode is enabled and
+the inserted character does not have word-constituent
+syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)  It is also
+responsible for calling @code{blink-paren-function} when the inserted
+character has close parenthesis syntax (@pxref{Blinking}).
+
+Do not try substituting your own definition of
+@code{self-insert-command} for the standard one.  The editor command
+loop handles this function specially.
+@end deffn
+
+@deffn Command newline &optional number-of-newlines
+This command inserts newlines into the current buffer before point.
+If @var{number-of-newlines} is supplied, that many newline characters
+are inserted.
+
+@cindex newline and Auto Fill mode
+This function calls @code{auto-fill-function} if the current column
+number is greater than the value of @code{fill-column} and
+@var{number-of-newlines} is @code{nil}.  Typically what
+@code{auto-fill-function} does is insert a newline; thus, the overall
+result in this case is to insert two newlines at different places: one
+at point, and another earlier in the line.  @code{newline} does not
+auto-fill if @var{number-of-newlines} is non-@code{nil}.
+
+This command indents to the left margin if that is not zero.
+@xref{Margins}.
+
+The value returned is @code{nil}.  In an interactive call, @var{count}
+is the numeric prefix argument.
+@end deffn
+
+@defvar overwrite-mode
+This variable controls whether overwrite mode is in effect.  The value
+should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
+or @code{nil}.  @code{overwrite-mode-textual} specifies textual
+overwrite mode (treats newlines and tabs specially), and
+@code{overwrite-mode-binary} specifies binary overwrite mode (treats
+newlines and tabs like any other characters).
+@end defvar
+
+@node Deletion
+@section Deleting Text
+@cindex text deletion
+
+@cindex deleting text vs killing
+  Deletion means removing part of the text in a buffer, without saving
+it in the kill ring (@pxref{The Kill Ring}).  Deleted text can't be
+yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
+Some deletion functions do save text in the kill ring in some special
+cases.
+
+  All of the deletion functions operate on the current buffer.
+
+@deffn Command erase-buffer
+This function deletes the entire text of the current buffer
+(@emph{not} just the accessible portion), leaving it
+empty.  If the buffer is read-only, it signals a @code{buffer-read-only}
+error; if some of the text in it is read-only, it signals a
+@code{text-read-only} error.  Otherwise, it deletes the text without
+asking for any confirmation.  It returns @code{nil}.
+
+Normally, deleting a large amount of text from a buffer inhibits further
+auto-saving of that buffer ``because it has shrunk.''  However,
+@code{erase-buffer} does not do this, the idea being that the future
+text is not really related to the former text, and its size should not
+be compared with that of the former text.
+@end deffn
+
+@deffn Command delete-region start end
+This command deletes the text between positions @var{start} and
+@var{end} in the current buffer, and returns @code{nil}.  If point was
+inside the deleted region, its value afterward is @var{start}.
+Otherwise, point relocates with the surrounding text, as markers do.
+@end deffn
+
+@defun delete-and-extract-region start end
+This function deletes the text between positions @var{start} and
+@var{end} in the current buffer, and returns a string containing the
+text just deleted.
+
+If point was inside the deleted region, its value afterward is
+@var{start}.  Otherwise, point relocates with the surrounding text, as
+markers do.
+@end defun
+
+@deffn Command delete-char count &optional killp
+This command deletes @var{count} characters directly after point, or
+before point if @var{count} is negative.  If @var{killp} is
+non-@code{nil}, then it saves the deleted characters in the kill ring.
+
+In an interactive call, @var{count} is the numeric prefix argument, and
+@var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
+argument is supplied, the text is saved in the kill ring.  If no prefix
+argument is supplied, then one character is deleted, but not saved in
+the kill ring.
+
+The value returned is always @code{nil}.
+@end deffn
+
+@deffn Command delete-backward-char count &optional killp
+@cindex deleting previous char
+This command deletes @var{count} characters directly before point, or
+after point if @var{count} is negative.  If @var{killp} is
+non-@code{nil}, then it saves the deleted characters in the kill ring.
+
+In an interactive call, @var{count} is the numeric prefix argument, and
+@var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
+argument is supplied, the text is saved in the kill ring.  If no prefix
+argument is supplied, then one character is deleted, but not saved in
+the kill ring.
+
+The value returned is always @code{nil}.
+@end deffn
+
+@deffn Command backward-delete-char-untabify count &optional killp
+@cindex tab deletion
+This command deletes @var{count} characters backward, changing tabs
+into spaces.  When the next character to be deleted is a tab, it is
+first replaced with the proper number of spaces to preserve alignment
+and then one of those spaces is deleted instead of the tab.  If
+@var{killp} is non-@code{nil}, then the command saves the deleted
+characters in the kill ring.
+
+Conversion of tabs to spaces happens only if @var{count} is positive.
+If it is negative, exactly @minus{}@var{count} characters after point
+are deleted.
+
+In an interactive call, @var{count} is the numeric prefix argument, and
+@var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
+argument is supplied, the text is saved in the kill ring.  If no prefix
+argument is supplied, then one character is deleted, but not saved in
+the kill ring.
+
+The value returned is always @code{nil}.
+@end deffn
+
+@defopt backward-delete-char-untabify-method
+This option specifies how @code{backward-delete-char-untabify} should
+deal with whitespace.  Possible values include @code{untabify}, the
+default, meaning convert a tab to many spaces and delete one;
+@code{hungry}, meaning delete all tabs and spaces before point with
+one command; @code{all} meaning delete all tabs, spaces and newlines
+before point, and @code{nil}, meaning do nothing special for
+whitespace characters.
+@end defopt
+
+@node User-Level Deletion
+@section User-Level Deletion Commands
+
+  This section describes higher-level commands for deleting text,
+commands intended primarily for the user but useful also in Lisp
+programs.
+
+@deffn Command delete-horizontal-space &optional backward-only
+@cindex deleting whitespace
+This function deletes all spaces and tabs around point.  It returns
+@code{nil}.
+
+If @var{backward-only} is non-@code{nil}, the function deletes
+spaces and tabs before point, but not after point.
+
+In the following examples, we call @code{delete-horizontal-space} four
+times, once on each line, with point between the second and third
+characters on the line each time.
+
+@example
+@group
+---------- Buffer: foo ----------
+I @point{}thought
+I @point{}     thought
+We@point{} thought
+Yo@point{}u thought
+---------- Buffer: foo ----------
+@end group
+
+@group
+(delete-horizontal-space)   ; @r{Four times.}
+     @result{} nil
+
+---------- Buffer: foo ----------
+Ithought
+Ithought
+Wethought
+You thought
+---------- Buffer: foo ----------
+@end group
+@end example
+@end deffn
+
+@deffn Command delete-indentation &optional join-following-p
+This function joins the line point is on to the previous line, deleting
+any whitespace at the join and in some cases replacing it with one
+space.  If @var{join-following-p} is non-@code{nil},
+@code{delete-indentation} joins this line to the following line
+instead.  The function returns @code{nil}.
+
+If there is a fill prefix, and the second of the lines being joined
+starts with the prefix, then @code{delete-indentation} deletes the
+fill prefix before joining the lines.  @xref{Margins}.
+
+In the example below, point is located on the line starting
+@samp{events}, and it makes no difference if there are trailing spaces
+in the preceding line.
+
+@smallexample
+@group
+---------- Buffer: foo ----------
+When in the course of human
+@point{}    events, it becomes necessary
+---------- Buffer: foo ----------
+@end group
+
+(delete-indentation)
+     @result{} nil
+
+@group
+---------- Buffer: foo ----------
+When in the course of human@point{} events, it becomes necessary
+---------- Buffer: foo ----------
+@end group
+@end smallexample
+
+After the lines are joined, the function @code{fixup-whitespace} is
+responsible for deciding whether to leave a space at the junction.
+@end deffn
+
+@deffn Command fixup-whitespace
+This function replaces all the horizontal whitespace surrounding point
+with either one space or no space, according to the context.  It
+returns @code{nil}.
+
+At the beginning or end of a line, the appropriate amount of space is
+none.  Before a character with close parenthesis syntax, or after a
+character with open parenthesis or expression-prefix syntax, no space is
+also appropriate.  Otherwise, one space is appropriate.  @xref{Syntax
+Class Table}.
+
+In the example below, @code{fixup-whitespace} is called the first time
+with point before the word @samp{spaces} in the first line.  For the
+second invocation, point is directly after the @samp{(}.
+
+@smallexample
+@group
+---------- Buffer: foo ----------
+This has too many     @point{}spaces
+This has too many spaces at the start of (@point{}   this list)
+---------- Buffer: foo ----------
+@end group
+
+@group
+(fixup-whitespace)
+     @result{} nil
+(fixup-whitespace)
+     @result{} nil
+@end group
+
+@group
+---------- Buffer: foo ----------
+This has too many spaces
+This has too many spaces at the start of (this list)
+---------- Buffer: foo ----------
+@end group
+@end smallexample
+@end deffn
+
+@deffn Command just-one-space &optional n
+@comment !!SourceFile simple.el
+This command replaces any spaces and tabs around point with a single
+space, or @var{n} spaces if @var{n} is specified.  It returns
+@code{nil}.
+@end deffn
+
+@deffn Command delete-blank-lines
+This function deletes blank lines surrounding point.  If point is on a
+blank line with one or more blank lines before or after it, then all but
+one of them are deleted.  If point is on an isolated blank line, then it
+is deleted.  If point is on a nonblank line, the command deletes all
+blank lines immediately following it.
+
+A blank line is defined as a line containing only tabs and spaces.
+
+@code{delete-blank-lines} returns @code{nil}.
+@end deffn
+
+@node The Kill Ring
+@section The Kill Ring
+@cindex kill ring
+
+  @dfn{Kill functions} delete text like the deletion functions, but save
+it so that the user can reinsert it by @dfn{yanking}.  Most of these
+functions have @samp{kill-} in their name.  By contrast, the functions
+whose names start with @samp{delete-} normally do not save text for
+yanking (though they can still be undone); these are ``deletion''
+functions.
+
+  Most of the kill commands are primarily for interactive use, and are
+not described here.  What we do describe are the functions provided for
+use in writing such commands.  You can use these functions to write
+commands for killing text.  When you need to delete text for internal
+purposes within a Lisp function, you should normally use deletion
+functions, so as not to disturb the kill ring contents.
+@xref{Deletion}.
+
+  Killed text is saved for later yanking in the @dfn{kill ring}.  This
+is a list that holds a number of recent kills, not just the last text
+kill.  We call this a ``ring'' because yanking treats it as having
+elements in a cyclic order.  The list is kept in the variable
+@code{kill-ring}, and can be operated on with the usual functions for
+lists; there are also specialized functions, described in this section,
+that treat it as a ring.
+
+  Some people think this use of the word ``kill'' is unfortunate, since
+it refers to operations that specifically @emph{do not} destroy the
+entities ``killed.''  This is in sharp contrast to ordinary life, in
+which death is permanent and ``killed'' entities do not come back to
+life.  Therefore, other metaphors have been proposed.  For example, the
+term ``cut ring'' makes sense to people who, in pre-computer days, used
+scissors and paste to cut up and rearrange manuscripts.  However, it
+would be difficult to change the terminology now.
+
+@menu
+* Kill Ring Concepts::     What text looks like in the kill ring.
+* Kill Functions::         Functions that kill text.
+* Yanking::                How yanking is done.
+* Yank Commands::          Commands that access the kill ring.
+* Low-Level Kill Ring::	   Functions and variables for kill ring access.
+* Internals of Kill Ring:: Variables that hold kill ring data.
+@end menu
+
+@node Kill Ring Concepts
+@comment  node-name,  next,  previous,  up
+@subsection Kill Ring Concepts
+
+  The kill ring records killed text as strings in a list, most recent
+first.  A short kill ring, for example, might look like this:
+
+@example
+("some text" "a different piece of text" "even older text")
+@end example
+
+@noindent
+When the list reaches @code{kill-ring-max} entries in length, adding a
+new entry automatically deletes the last entry.
+
+  When kill commands are interwoven with other commands, each kill
+command makes a new entry in the kill ring.  Multiple kill commands in
+succession build up a single kill ring entry, which would be yanked as a
+unit; the second and subsequent consecutive kill commands add text to
+the entry made by the first one.
+
+  For yanking, one entry in the kill ring is designated the ``front'' of
+the ring.  Some yank commands ``rotate'' the ring by designating a
+different element as the ``front.''  But this virtual rotation doesn't
+change the list itself---the most recent entry always comes first in the
+list.
+
+@node Kill Functions
+@comment  node-name,  next,  previous,  up
+@subsection Functions for Killing
+
+  @code{kill-region} is the usual subroutine for killing text.  Any
+command that calls this function is a ``kill command'' (and should
+probably have @samp{kill} in its name).  @code{kill-region} puts the
+newly killed text in a new element at the beginning of the kill ring or
+adds it to the most recent element.  It determines automatically (using
+@code{last-command}) whether the previous command was a kill command,
+and if so appends the killed text to the most recent entry.
+
+@deffn Command kill-region start end &optional yank-handler
+This function kills the text in the region defined by @var{start} and
+@var{end}.  The text is deleted but saved in the kill ring, along with
+its text properties.  The value is always @code{nil}.
+
+In an interactive call, @var{start} and @var{end} are point and
+the mark.
+
+@c Emacs 19 feature
+If the buffer or text is read-only, @code{kill-region} modifies the kill
+ring just the same, then signals an error without modifying the buffer.
+This is convenient because it lets the user use a series of kill
+commands to copy text from a read-only buffer into the kill ring.
+
+If @var{yank-handler} is non-@code{nil}, this puts that value onto
+the string of killed text, as a @code{yank-handler} text property.
+@xref{Yanking}.  Note that if @var{yank-handler} is @code{nil}, any
+@code{yank-handler} properties present on the killed text are copied
+onto the kill ring, like other text properties.
+@end deffn
+
+@defopt kill-read-only-ok
+If this option is non-@code{nil}, @code{kill-region} does not signal an
+error if the buffer or text is read-only.  Instead, it simply returns,
+updating the kill ring but not changing the buffer.
+@end defopt
+
+@deffn Command copy-region-as-kill start end
+This command saves the region defined by @var{start} and @var{end} on
+the kill ring (including text properties), but does not delete the text
+from the buffer.  It returns @code{nil}.
+
+The command does not set @code{this-command} to @code{kill-region}, so a
+subsequent kill command does not append to the same kill ring entry.
+
+Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
+support Emacs 18.  For newer Emacs versions, it is better to use
+@code{kill-new} or @code{kill-append} instead.  @xref{Low-Level Kill
+Ring}.
+@end deffn
+
+@node Yanking
+@subsection Yanking
+
+  Yanking means inserting text from the kill ring, but it does
+not insert the text blindly.  Yank commands and some other commands
+use @code{insert-for-yank} to perform special processing on the
+text that they copy into the buffer.
+
+@defun insert-for-yank string
+This function normally works like @code{insert} except that it doesn't
+insert the text properties in the @code{yank-excluded-properties}
+list.  However, if any part of @var{string} has a non-@code{nil}
+@code{yank-handler} text property, that property can do various
+special processing on that part of the text being inserted.
+@end defun
+
+@defun insert-buffer-substring-as-yank buf &optional start end
+This function resembles @code{insert-buffer-substring} except that it
+doesn't insert the text properties in the
+@code{yank-excluded-properties} list.
+@end defun
+
+  You can put a @code{yank-handler} text property on all or part of
+the text to control how it will be inserted if it is yanked.  The
+@code{insert-for-yank} function looks for that property.  The property
+value must be a list of one to four elements, with the following
+format (where elements after the first may be omitted):
+
+@example
+(@var{function} @var{param} @var{noexclude} @var{undo})
+@end example
+
+  Here is what the elements do:
+
+@table @var
+@item function
+When @var{function} is present and non-@code{nil}, it is called instead of
+@code{insert} to insert the string.  @var{function} takes one
+argument---the string to insert.
+
+@item param
+If @var{param} is present and non-@code{nil}, it replaces @var{string}
+(or the part of @var{string} being processed) as the object passed to
+@var{function} (or @code{insert}); for example, if @var{function} is
+@code{yank-rectangle}, @var{param} should be a list of strings to
+insert as a rectangle.
+
+@item noexclude
+If @var{noexclude} is present and non-@code{nil}, the normal removal of the
+yank-excluded-properties is not performed; instead @var{function} is
+responsible for removing those properties.  This may be necessary
+if @var{function} adjusts point before or after inserting the object.
+
+@item undo
+If @var{undo} is present and non-@code{nil}, it is a function that will be
+called by @code{yank-pop} to undo the insertion of the current object.
+It is called with two arguments, the start and end of the current
+region.  @var{function} can set @code{yank-undo-function} to override
+the @var{undo} value.
+@end table
+
+@node Yank Commands
+@comment  node-name,  next,  previous,  up
+@subsection Functions for Yanking
+
+  This section describes higher-level commands for yanking, which are
+intended primarily for the user but useful also in Lisp programs.
+Both @code{yank} and @code{yank-pop} honor the
+@code{yank-excluded-properties} variable and @code{yank-handler} text
+property (@pxref{Yanking}).
+
+@deffn Command yank &optional arg
+@cindex inserting killed text
+This command inserts before point the text at the front of the
+kill ring.  It positions the mark at the beginning of that text, and
+point at the end.
+
+If @var{arg} is a non-@code{nil} list (which occurs interactively when
+the user types @kbd{C-u} with no digits), then @code{yank} inserts the
+text as described above, but puts point before the yanked text and
+puts the mark after it.
+
+If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
+most recently killed text---the @var{arg}th element of the kill ring
+list, counted cyclically from the front, which is considered the
+first element for this purpose.
+
+@code{yank} does not alter the contents of the kill ring, unless it
+used text provided by another program, in which case it pushes that text
+onto the kill ring.  However if @var{arg} is an integer different from
+one, it rotates the kill ring to place the yanked string at the front.
+
+@code{yank} returns @code{nil}.
+@end deffn
+
+@deffn Command yank-pop &optional arg
+This command replaces the just-yanked entry from the kill ring with a
+different entry from the kill ring.
+
+This is allowed only immediately after a @code{yank} or another
+@code{yank-pop}.  At such a time, the region contains text that was just
+inserted by yanking.  @code{yank-pop} deletes that text and inserts in
+its place a different piece of killed text.  It does not add the deleted
+text to the kill ring, since it is already in the kill ring somewhere.
+It does however rotate the kill ring to place the newly yanked string at
+the front.
+
+If @var{arg} is @code{nil}, then the replacement text is the previous
+element of the kill ring.  If @var{arg} is numeric, the replacement is
+the @var{arg}th previous kill.  If @var{arg} is negative, a more recent
+kill is the replacement.
+
+The sequence of kills in the kill ring wraps around, so that after the
+oldest one comes the newest one, and before the newest one goes the
+oldest.
+
+The return value is always @code{nil}.
+@end deffn
+
+@defvar yank-undo-function
+If this variable is non-@code{nil}, the function @code{yank-pop} uses
+its value instead of @code{delete-region} to delete the text
+inserted by the previous @code{yank} or
+@code{yank-pop} command.  The value must be a function of two
+arguments, the start and end of the current region.
+
+The function @code{insert-for-yank} automatically sets this variable
+according to the @var{undo} element of the @code{yank-handler}
+text property, if there is one.
+@end defvar
+
+@node Low-Level Kill Ring
+@subsection Low-Level Kill Ring
+
+  These functions and variables provide access to the kill ring at a
+lower level, but still convenient for use in Lisp programs, because they
+take care of interaction with window system selections
+(@pxref{Window System Selections}).
+
+@defun current-kill n &optional do-not-move
+The function @code{current-kill} rotates the yanking pointer, which
+designates the ``front'' of the kill ring, by @var{n} places (from newer
+kills to older ones), and returns the text at that place in the ring.
+
+If the optional second argument @var{do-not-move} is non-@code{nil},
+then @code{current-kill} doesn't alter the yanking pointer; it just
+returns the @var{n}th kill, counting from the current yanking pointer.
+
+If @var{n} is zero, indicating a request for the latest kill,
+@code{current-kill} calls the value of
+@code{interprogram-paste-function} (documented below) before
+consulting the kill ring.  If that value is a function and calling it
+returns a string, @code{current-kill} pushes that string onto the kill
+ring and returns it.  It also sets the yanking pointer to point to
+that new entry, regardless of the value of @var{do-not-move}.
+Otherwise, @code{current-kill} does not treat a zero value for @var{n}
+specially: it returns the entry pointed at by the yanking pointer and
+does not move the yanking pointer.
+@end defun
+
+@defun kill-new string &optional replace yank-handler
+This function pushes the text @var{string} onto the kill ring and
+makes the yanking pointer point to it.  It discards the oldest entry
+if appropriate.  It also invokes the value of
+@code{interprogram-cut-function} (see below).
+
+If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
+first element of the kill ring with @var{string}, rather than pushing
+@var{string} onto the kill ring.
+
+If @var{yank-handler} is non-@code{nil}, this puts that value onto
+the string of killed text, as a @code{yank-handler} property.
+@xref{Yanking}.  Note that if @var{yank-handler} is @code{nil}, then
+@code{kill-new} copies any @code{yank-handler} properties present on
+@var{string} onto the kill ring, as it does with other text properties.
+@end defun
+
+@defun kill-append string before-p &optional yank-handler
+This function appends the text @var{string} to the first entry in the
+kill ring and makes the yanking pointer point to the combined entry.
+Normally @var{string} goes at the end of the entry, but if
+@var{before-p} is non-@code{nil}, it goes at the beginning.  This
+function also invokes the value of @code{interprogram-cut-function}
+(see below).  This handles @var{yank-handler} just like
+@code{kill-new}, except that if @var{yank-handler} is different from
+the @code{yank-handler} property of the first entry of the kill ring,
+@code{kill-append} pushes the concatenated string onto the kill ring,
+instead of replacing the original first entry with it.
+@end defun
+
+@defvar interprogram-paste-function
+This variable provides a way of transferring killed text from other
+programs, when you are using a window system.  Its value should be
+@code{nil} or a function of no arguments.
+
+If the value is a function, @code{current-kill} calls it to get the
+``most recent kill.''  If the function returns a non-@code{nil} value,
+then that value is used as the ``most recent kill.''  If it returns
+@code{nil}, then the front of the kill ring is used.
+
+The normal use of this hook is to get the window system's primary
+selection as the most recent kill, even if the selection belongs to
+another application.  @xref{Window System Selections}.
+@end defvar
+
+@defvar interprogram-cut-function
+This variable provides a way of communicating killed text to other
+programs, when you are using a window system.  Its value should be
+@code{nil} or a function of one required and one optional argument.
+
+If the value is a function, @code{kill-new} and @code{kill-append} call
+it with the new first element of the kill ring as the first argument.
+The second, optional, argument has the same meaning as the @var{push}
+argument to @code{x-set-cut-buffer} (@pxref{Definition of
+x-set-cut-buffer}) and only affects the second and later cut buffers.
+
+The normal use of this hook is to set the window system's primary
+selection (and first cut buffer) from the newly killed text.
+@xref{Window System Selections}.
+@end defvar
+
+@node Internals of Kill Ring
+@comment  node-name,  next,  previous,  up
+@subsection Internals of the Kill Ring
+
+  The variable @code{kill-ring} holds the kill ring contents, in the
+form of a list of strings.  The most recent kill is always at the front
+of the list.
+
+  The @code{kill-ring-yank-pointer} variable points to a link in the
+kill ring list, whose @sc{car} is the text to yank next.  We say it
+identifies the ``front'' of the ring.  Moving
+@code{kill-ring-yank-pointer} to a different link is called
+@dfn{rotating the kill ring}.  We call the kill ring a ``ring'' because
+the functions that move the yank pointer wrap around from the end of the
+list to the beginning, or vice-versa.  Rotation of the kill ring is
+virtual; it does not change the value of @code{kill-ring}.
+
+  Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
+variables whose values are normally lists.  The word ``pointer'' in the
+name of the @code{kill-ring-yank-pointer} indicates that the variable's
+purpose is to identify one element of the list for use by the next yank
+command.
+
+  The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
+of the links in the kill ring list.  The element it identifies is the
+@sc{car} of that link.  Kill commands, which change the kill ring, also
+set this variable to the value of @code{kill-ring}.  The effect is to
+rotate the ring so that the newly killed text is at the front.
+
+  Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
+pointing to the second entry in the kill ring @code{("some text" "a
+different piece of text" "yet older text")}.
+
+@example
+@group
+kill-ring                  ---- kill-ring-yank-pointer
+  |                       |
+  |                       v
+  |     --- ---          --- ---      --- ---
+   --> |   |   |------> |   |   |--> |   |   |--> nil
+        --- ---          --- ---      --- ---
+         |                |            |
+         |                |            |
+         |                |             -->"yet older text"
+         |                |
+         |                 --> "a different piece of text"
+         |
+          --> "some text"
+@end group
+@end example
+
+@noindent
+This state of affairs might occur after @kbd{C-y} (@code{yank})
+immediately followed by @kbd{M-y} (@code{yank-pop}).
+
+@defvar kill-ring
+This variable holds the list of killed text sequences, most recently
+killed first.
+@end defvar
+
+@defvar kill-ring-yank-pointer
+This variable's value indicates which element of the kill ring is at the
+``front'' of the ring for yanking.  More precisely, the value is a tail
+of the value of @code{kill-ring}, and its @sc{car} is the kill string
+that @kbd{C-y} should yank.
+@end defvar
+
+@defopt kill-ring-max
+The value of this variable is the maximum length to which the kill
+ring can grow, before elements are thrown away at the end.  The default
+value for @code{kill-ring-max} is 60.
+@end defopt
+
+@node Undo
+@comment  node-name,  next,  previous,  up
+@section Undo
+@cindex redo
+
+  Most buffers have an @dfn{undo list}, which records all changes made
+to the buffer's text so that they can be undone.  (The buffers that
+don't have one are usually special-purpose buffers for which Emacs
+assumes that undoing is not useful.  In particular, any buffer whose
+name begins with a space has its undo recording off by default;
+see @ref{Buffer Names}.)  All the primitives that modify the
+text in the buffer automatically add elements to the front of the undo
+list, which is in the variable @code{buffer-undo-list}.
+
+@defvar buffer-undo-list
+This buffer-local variable's value is the undo list of the current
+buffer. A value of @code{t} disables the recording of undo information.
+@end defvar
+
+Here are the kinds of elements an undo list can have:
+
+@table @code
+@item @var{position}
+This kind of element records a previous value of point; undoing this
+element moves point to @var{position}.  Ordinary cursor motion does not
+make any sort of undo record, but deletion operations use these entries
+to record where point was before the command.
+
+@item (@var{beg} . @var{end})
+This kind of element indicates how to delete text that was inserted.
+Upon insertion, the text occupied the range @var{beg}--@var{end} in the
+buffer.
+
+@item (@var{text} . @var{position})
+This kind of element indicates how to reinsert text that was deleted.
+The deleted text itself is the string @var{text}.  The place to
+reinsert it is @code{(abs @var{position})}.  If @var{position} is
+positive, point was at the beginning of the deleted text, otherwise it
+was at the end.
+
+@item (t @var{high} . @var{low})
+This kind of element indicates that an unmodified buffer became
+modified.  The elements @var{high} and @var{low} are two integers, each
+recording 16 bits of the visited file's modification time as of when it
+was previously visited or saved.  @code{primitive-undo} uses those
+values to determine whether to mark the buffer as unmodified once again;
+it does so only if the file's modification time matches those numbers.
+
+@item (nil @var{property} @var{value} @var{beg} . @var{end})
+This kind of element records a change in a text property.
+Here's how you might undo the change:
+
+@example
+(put-text-property @var{beg} @var{end} @var{property} @var{value})
+@end example
+
+@item (@var{marker} . @var{adjustment})
+This kind of element records the fact that the marker @var{marker} was
+relocated due to deletion of surrounding text, and that it moved
+@var{adjustment} character positions.  Undoing this element moves
+@var{marker} @minus{} @var{adjustment} characters.
+
+@item (apply @var{funname} . @var{args})
+This is an extensible undo item, which is undone by calling
+@var{funname} with arguments @var{args}.
+
+@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
+This is an extensible undo item, which records a change limited to the
+range @var{beg} to @var{end}, which increased the size of the buffer
+by @var{delta}.  It is undone by calling @var{funname} with arguments
+@var{args}.
+
+This kind of element enables undo limited to a region to determine
+whether the element pertains to that region.
+
+@item nil
+This element is a boundary.  The elements between two boundaries are
+called a @dfn{change group}; normally, each change group corresponds to
+one keyboard command, and undo commands normally undo an entire group as
+a unit.
+@end table
+
+@defun undo-boundary
+This function places a boundary element in the undo list.  The undo
+command stops at such a boundary, and successive undo commands undo
+to earlier and earlier boundaries.  This function returns @code{nil}.
+
+The editor command loop automatically creates an undo boundary before
+each key sequence is executed.  Thus, each undo normally undoes the
+effects of one command.  Self-inserting input characters are an
+exception.  The command loop makes a boundary for the first such
+character; the next 19 consecutive self-inserting input characters do
+not make boundaries, and then the 20th does, and so on as long as
+self-inserting characters continue.
+
+All buffer modifications add a boundary whenever the previous undoable
+change was made in some other buffer.  This is to ensure that
+each command makes a boundary in each buffer where it makes changes.
+
+Calling this function explicitly is useful for splitting the effects of
+a command into more than one unit.  For example, @code{query-replace}
+calls @code{undo-boundary} after each replacement, so that the user can
+undo individual replacements one by one.
+@end defun
+
+@defvar undo-in-progress
+This variable is normally @code{nil}, but the undo commands bind it to
+@code{t}.  This is so that various kinds of change hooks can tell when
+they're being called for the sake of undoing.
+@end defvar
+
+@defun primitive-undo count list
+This is the basic function for undoing elements of an undo list.
+It undoes the first @var{count} elements of @var{list}, returning
+the rest of @var{list}.
+
+@code{primitive-undo} adds elements to the buffer's undo list when it
+changes the buffer.  Undo commands avoid confusion by saving the undo
+list value at the beginning of a sequence of undo operations.  Then the
+undo operations use and update the saved value.  The new elements added
+by undoing are not part of this saved value, so they don't interfere with
+continuing to undo.
+
+This function does not bind @code{undo-in-progress}.
+@end defun
+
+@node Maintaining Undo
+@section Maintaining Undo Lists
+
+  This section describes how to enable and disable undo information for
+a given buffer.  It also explains how the undo list is truncated
+automatically so it doesn't get too big.
+
+  Recording of undo information in a newly created buffer is normally
+enabled to start with; but if the buffer name starts with a space, the
+undo recording is initially disabled.  You can explicitly enable or
+disable undo recording with the following two functions, or by setting
+@code{buffer-undo-list} yourself.
+
+@deffn Command buffer-enable-undo &optional buffer-or-name
+This command enables recording undo information for buffer
+@var{buffer-or-name}, so that subsequent changes can be undone.  If no
+argument is supplied, then the current buffer is used.  This function
+does nothing if undo recording is already enabled in the buffer.  It
+returns @code{nil}.
+
+In an interactive call, @var{buffer-or-name} is the current buffer.
+You cannot specify any other buffer.
+@end deffn
+
+@deffn Command buffer-disable-undo &optional buffer-or-name
+@cindex disabling undo
+This function discards the undo list of @var{buffer-or-name}, and disables
+further recording of undo information.  As a result, it is no longer
+possible to undo either previous changes or any subsequent changes.  If
+the undo list of @var{buffer-or-name} is already disabled, this function
+has no effect.
+
+This function returns @code{nil}.
+@end deffn
+
+  As editing continues, undo lists get longer and longer.  To prevent
+them from using up all available memory space, garbage collection trims
+them back to size limits you can set.  (For this purpose, the ``size''
+of an undo list measures the cons cells that make up the list, plus the
+strings of deleted text.)  Three variables control the range of acceptable
+sizes: @code{undo-limit}, @code{undo-strong-limit} and
+@code{undo-outer-limit}.  In these variables, size is counted as the
+number of bytes occupied, which includes both saved text and other
+data.
+
+@defopt undo-limit
+This is the soft limit for the acceptable size of an undo list.  The
+change group at which this size is exceeded is the last one kept.
+@end defopt
+
+@defopt undo-strong-limit
+This is the upper limit for the acceptable size of an undo list.  The
+change group at which this size is exceeded is discarded itself (along
+with all older change groups).  There is one exception: the very latest
+change group is only discarded if it exceeds @code{undo-outer-limit}.
+@end defopt
+
+@defopt undo-outer-limit
+If at garbage collection time the undo info for the current command
+exceeds this limit, Emacs discards the info and displays a warning.
+This is a last ditch limit to prevent memory overflow.
+@end defopt
+
+@defopt undo-ask-before-discard
+If this variable is non-@code{nil}, when the undo info exceeds
+@code{undo-outer-limit}, Emacs asks in the echo area whether to
+discard the info.  The default value is @code{nil}, which means to
+discard it automatically.
+
+This option is mainly intended for debugging.  Garbage collection is
+inhibited while the question is asked, which means that Emacs might
+leak memory if the user waits too long before answering the question.
+@end defopt
+
+@node Filling
+@comment  node-name,  next,  previous,  up
+@section Filling
+@cindex filling text
+
+  @dfn{Filling} means adjusting the lengths of lines (by moving the line
+breaks) so that they are nearly (but no greater than) a specified
+maximum width.  Additionally, lines can be @dfn{justified}, which means
+inserting spaces to make the left and/or right margins line up
+precisely.  The width is controlled by the variable @code{fill-column}.
+For ease of reading, lines should be no longer than 70 or so columns.
+
+  You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
+automatically as you insert it, but changes to existing text may leave
+it improperly filled.  Then you must fill the text explicitly.
+
+  Most of the commands in this section return values that are not
+meaningful.  All the functions that do filling take note of the current
+left margin, current right margin, and current justification style
+(@pxref{Margins}).  If the current justification style is
+@code{none}, the filling functions don't actually do anything.
+
+  Several of the filling functions have an argument @var{justify}.
+If it is non-@code{nil}, that requests some kind of justification.  It
+can be @code{left}, @code{right}, @code{full}, or @code{center}, to
+request a specific style of justification.  If it is @code{t}, that
+means to use the current justification style for this part of the text
+(see @code{current-justification}, below).  Any other value is treated
+as @code{full}.
+
+  When you call the filling functions interactively, using a prefix
+argument implies the value @code{full} for @var{justify}.
+
+@deffn Command fill-paragraph justify
+This command fills the paragraph at or after point.  If
+@var{justify} is non-@code{nil}, each line is justified as well.
+It uses the ordinary paragraph motion commands to find paragraph
+boundaries.  @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
+@end deffn
+
+@deffn Command fill-region start end &optional justify nosqueeze to-eop
+This command fills each of the paragraphs in the region from @var{start}
+to @var{end}.  It justifies as well if @var{justify} is
+non-@code{nil}.
+
+If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
+other than line breaks untouched.  If @var{to-eop} is non-@code{nil},
+that means to keep filling to the end of the paragraph---or the next hard
+newline, if @code{use-hard-newlines} is enabled (see below).
+
+The variable @code{paragraph-separate} controls how to distinguish
+paragraphs.  @xref{Standard Regexps}.
+@end deffn
+
+@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
+This command fills each paragraph in the region according to its
+individual fill prefix.  Thus, if the lines of a paragraph were indented
+with spaces, the filled paragraph will remain indented in the same
+fashion.
+
+The first two arguments, @var{start} and @var{end}, are the beginning
+and end of the region to be filled.  The third and fourth arguments,
+@var{justify} and @var{citation-regexp}, are optional.  If
+@var{justify} is non-@code{nil}, the paragraphs are justified as
+well as filled.  If @var{citation-regexp} is non-@code{nil}, it means the
+function is operating on a mail message and therefore should not fill
+the header lines.  If @var{citation-regexp} is a string, it is used as
+a regular expression; if it matches the beginning of a line, that line
+is treated as a citation marker.
+
+Ordinarily, @code{fill-individual-paragraphs} regards each change in
+indentation as starting a new paragraph.  If
+@code{fill-individual-varying-indent} is non-@code{nil}, then only
+separator lines separate paragraphs.  That mode can handle indented
+paragraphs with additional indentation on the first line.
+@end deffn
+
+@defopt fill-individual-varying-indent
+This variable alters the action of @code{fill-individual-paragraphs} as
+described above.
+@end defopt
+
+@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
+This command considers a region of text as a single paragraph and fills
+it.  If the region was made up of many paragraphs, the blank lines
+between paragraphs are removed.  This function justifies as well as
+filling when @var{justify} is non-@code{nil}.
+
+If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
+other than line breaks untouched.  If @var{squeeze-after} is
+non-@code{nil}, it specifies a position in the region, and means don't
+canonicalize spaces before that position.
+
+In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
+choose a fill prefix by default.  @xref{Adaptive Fill}.
+@end deffn
+
+@deffn Command justify-current-line &optional how eop nosqueeze
+This command inserts spaces between the words of the current line so
+that the line ends exactly at @code{fill-column}.  It returns
+@code{nil}.
+
+The argument @var{how}, if non-@code{nil} specifies explicitly the style
+of justification.  It can be @code{left}, @code{right}, @code{full},
+@code{center}, or @code{none}.  If it is @code{t}, that means to do
+follow specified justification style (see @code{current-justification},
+below).  @code{nil} means to do full justification.
+
+If @var{eop} is non-@code{nil}, that means do only left-justification
+if @code{current-justification} specifies full justification.  This is
+used for the last line of a paragraph; even if the paragraph as a
+whole is fully justified, the last line should not be.
+
+If @var{nosqueeze} is non-@code{nil}, that means do not change interior
+whitespace.
+@end deffn
+
+@defopt default-justification
+This variable's value specifies the style of justification to use for
+text that doesn't specify a style with a text property.  The possible
+values are @code{left}, @code{right}, @code{full}, @code{center}, or
+@code{none}.  The default value is @code{left}.
+@end defopt
+
+@defun current-justification
+This function returns the proper justification style to use for filling
+the text around point.
+
+This returns the value of the @code{justification} text property at
+point, or the variable @var{default-justification} if there is no such
+text property.  However, it returns @code{nil} rather than @code{none}
+to mean ``don't justify''.
+@end defun
+
+@defopt sentence-end-double-space
+@anchor{Definition of sentence-end-double-space}
+If this variable is non-@code{nil}, a period followed by just one space
+does not count as the end of a sentence, and the filling functions
+avoid breaking the line at such a place.
+@end defopt
+
+@defopt sentence-end-without-period
+If this variable is non-@code{nil}, a sentence can end without a
+period.  This is used for languages like Thai, where sentences end
+with a double space but without a period.
+@end defopt
+
+@defopt sentence-end-without-space
+If this variable is non-@code{nil}, it should be a string of
+characters that can end a sentence without following spaces.
+@end defopt
+
+@defvar fill-paragraph-function
+This variable provides a way for major modes to override the filling of
+paragraphs.  If the value is non-@code{nil}, @code{fill-paragraph} calls
+this function to do the work.  If the function returns a non-@code{nil}
+value, @code{fill-paragraph} assumes the job is done, and immediately
+returns that value.
+
+The usual use of this feature is to fill comments in programming
+language modes.  If the function needs to fill a paragraph in the usual
+way, it can do so as follows:
+
+@example
+(let ((fill-paragraph-function nil))
+  (fill-paragraph arg))
+@end example
+@end defvar
+
+@defvar use-hard-newlines
+If this variable is non-@code{nil}, the filling functions do not delete
+newlines that have the @code{hard} text property.  These ``hard
+newlines'' act as paragraph separators.
+@end defvar
+
+@node Margins
+@section Margins for Filling
+
+@defopt fill-prefix
+This buffer-local variable, if non-@code{nil}, specifies a string of
+text that appears at the beginning of normal text lines and should be
+disregarded when filling them.  Any line that fails to start with the
+fill prefix is considered the start of a paragraph; so is any line
+that starts with the fill prefix followed by additional whitespace.
+Lines that start with the fill prefix but no additional whitespace are
+ordinary text lines that can be filled together.  The resulting filled
+lines also start with the fill prefix.
+
+The fill prefix follows the left margin whitespace, if any.
+@end defopt
+
+@defopt fill-column
+This buffer-local variable specifies the maximum width of filled lines.
+Its value should be an integer, which is a number of columns.  All the
+filling, justification, and centering commands are affected by this
+variable, including Auto Fill mode (@pxref{Auto Filling}).
+
+As a practical matter, if you are writing text for other people to
+read, you should set @code{fill-column} to no more than 70.  Otherwise
+the line will be too long for people to read comfortably, and this can
+make the text seem clumsy.
+@end defopt
+
+@defvar default-fill-column
+The value of this variable is the default value for @code{fill-column} in
+buffers that do not override it.  This is the same as
+@code{(default-value 'fill-column)}.
+
+The default value for @code{default-fill-column} is 70.
+@end defvar
+
+@deffn Command set-left-margin from to margin
+This sets the @code{left-margin} property on the text from @var{from} to
+@var{to} to the value @var{margin}.  If Auto Fill mode is enabled, this
+command also refills the region to fit the new margin.
+@end deffn
+
+@deffn Command set-right-margin from to margin
+This sets the @code{right-margin} property on the text from @var{from}
+to @var{to} to the value @var{margin}.  If Auto Fill mode is enabled,
+this command also refills the region to fit the new margin.
+@end deffn
+
+@defun current-left-margin
+This function returns the proper left margin value to use for filling
+the text around point.  The value is the sum of the @code{left-margin}
+property of the character at the start of the current line (or zero if
+none), and the value of the variable @code{left-margin}.
+@end defun
+
+@defun current-fill-column
+This function returns the proper fill column value to use for filling
+the text around point.  The value is the value of the @code{fill-column}
+variable, minus the value of the @code{right-margin} property of the
+character after point.
+@end defun
+
+@deffn Command move-to-left-margin &optional n force
+This function moves point to the left margin of the current line.  The
+column moved to is determined by calling the function
+@code{current-left-margin}.  If the argument @var{n} is non-@code{nil},
+@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
+
+If @var{force} is non-@code{nil}, that says to fix the line's
+indentation if that doesn't match the left margin value.
+@end deffn
+
+@defun delete-to-left-margin &optional from to
+This function removes left margin indentation from the text between
+@var{from} and @var{to}.  The amount of indentation to delete is
+determined by calling @code{current-left-margin}.  In no case does this
+function delete non-whitespace.  If @var{from} and @var{to} are omitted,
+they default to the whole buffer.
+@end defun
+
+@defun indent-to-left-margin
+This function adjusts the indentation at the beginning of the current
+line to the value specified by the variable @code{left-margin}.  (That
+may involve either inserting or deleting whitespace.)  This function
+is value of @code{indent-line-function} in Paragraph-Indent Text mode.
+@end defun
+
+@defvar left-margin
+This variable specifies the base left margin column.  In Fundamental
+mode, @kbd{C-j} indents to this column.  This variable automatically
+becomes buffer-local when set in any fashion.
+@end defvar
+
+@defvar fill-nobreak-predicate
+This variable gives major modes a way to specify not to break a line
+at certain places.  Its value should be a list of functions.  Whenever
+filling considers breaking the line at a certain place in the buffer,
+it calls each of these functions with no arguments and with point
+located at that place.  If any of the functions returns
+non-@code{nil}, then the line won't be broken there.
+@end defvar
+
+@node Adaptive Fill
+@section Adaptive Fill Mode
+@c @cindex Adaptive Fill mode  "adaptive-fill-mode" is adjacent.
+
+  When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
+prefix automatically from the text in each paragraph being filled
+rather than using a predetermined value.  During filling, this fill
+prefix gets inserted at the start of the second and subsequent lines
+of the paragraph as described in @ref{Filling}, and in @ref{Auto
+Filling}.
+
+@defopt adaptive-fill-mode
+Adaptive Fill mode is enabled when this variable is non-@code{nil}.
+It is @code{t} by default.
+@end defopt
+
+@defun fill-context-prefix from to
+This function implements the heart of Adaptive Fill mode; it chooses a
+fill prefix based on the text between @var{from} and @var{to},
+typically the start and end of a paragraph.  It does this by looking
+at the first two lines of the paragraph, based on the variables
+described below.
+@c The optional argument first-line-regexp is not documented
+@c because it exists for internal purposes and might be eliminated
+@c in the future.
+
+Usually, this function returns the fill prefix, a string.  However,
+before doing this, the function makes a final check (not specially
+mentioned in the following) that a line starting with this prefix
+wouldn't look like the start of a paragraph.  Should this happen, the
+function signals the anomaly by returning @code{nil} instead.
+
+In detail, @code{fill-context-prefix} does this:
+
+@enumerate
+@item
+It takes a candidate for the fill prefix from the first line---it
+tries first the function in @code{adaptive-fill-function} (if any),
+then the regular expression @code{adaptive-fill-regexp} (see below).
+The first non-@code{nil} result of these, or the empty string if
+they're both @code{nil}, becomes the first line's candidate.
+@item
+If the paragraph has as yet only one line, the function tests the
+validity of the prefix candidate just found.  The function then
+returns the candidate if it's valid, or a string of spaces otherwise.
+(see the description of @code{adaptive-fill-first-line-regexp} below).
+@item
+When the paragraph already has two lines, the function next looks for
+a prefix candidate on the second line, in just the same way it did for
+the first line.  If it doesn't find one, it returns @code{nil}.
+@item
+The function now compares the two candidate prefixes heuristically: if
+the non-whitespace characters in the line 2 candidate occur in the
+same order in the line 1 candidate, the function returns the line 2
+candidate.  Otherwise, it returns the largest initial substring which
+is common to both candidates (which might be the empty string).
+@end enumerate
+@end defun
+
+@defopt adaptive-fill-regexp
+Adaptive Fill mode matches this regular expression against the text
+starting after the left margin whitespace (if any) on a line; the
+characters it matches are that line's candidate for the fill prefix.
+
+The default value matches whitespace with certain punctuation
+characters intermingled.
+@end defopt
+
+@defopt adaptive-fill-first-line-regexp
+Used only in one-line paragraphs, this regular expression acts as an
+additional check of the validity of the one available candidate fill
+prefix: the candidate must match this regular expression, or match
+@code{comment-start-skip}.  If it doesn't, @code{fill-context-prefix}
+replaces the candidate with a string of spaces ``of the same width''
+as it.
+
+The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
+matches only a string of whitespace.  The effect of this default is to
+force the fill prefixes found in one-line paragraphs always to be pure
+whitespace.
+@end defopt
+
+@defopt adaptive-fill-function
+You can specify more complex ways of choosing a fill prefix
+automatically by setting this variable to a function.  The function is
+called with point after the left margin (if any) of a line, and it
+must preserve point.  It should return either ``that line's'' fill
+prefix or @code{nil}, meaning it has failed to determine a prefix.
+@end defopt
+
+@node Auto Filling
+@comment  node-name,  next,  previous,  up
+@section Auto Filling
+@cindex filling, automatic
+@cindex Auto Fill mode
+
+  Auto Fill mode is a minor mode that fills lines automatically as text
+is inserted.  This section describes the hook used by Auto Fill mode.
+For a description of functions that you can call explicitly to fill and
+justify existing text, see @ref{Filling}.
+
+  Auto Fill mode also enables the functions that change the margins and
+justification style to refill portions of the text.  @xref{Margins}.
+
+@defvar auto-fill-function
+The value of this buffer-local variable should be a function (of no
+arguments) to be called after self-inserting a character from the table
+@code{auto-fill-chars}.  It may be @code{nil}, in which case nothing
+special is done in that case.
+
+The value of @code{auto-fill-function} is @code{do-auto-fill} when
+Auto-Fill mode is enabled.  That is a function whose sole purpose is to
+implement the usual strategy for breaking a line.
+
+@quotation
+In older Emacs versions, this variable was named @code{auto-fill-hook},
+but since it is not called with the standard convention for hooks, it
+was renamed to @code{auto-fill-function} in version 19.
+@end quotation
+@end defvar
+
+@defvar normal-auto-fill-function
+This variable specifies the function to use for
+@code{auto-fill-function}, if and when Auto Fill is turned on.  Major
+modes can set buffer-local values for this variable to alter how Auto
+Fill works.
+@end defvar
+
+@defvar auto-fill-chars
+A char table of characters which invoke @code{auto-fill-function} when
+self-inserted---space and newline in most language environments.  They
+have an entry @code{t} in the table.
+@end defvar
+
+@node Sorting
+@section Sorting Text
+@cindex sorting text
+
+  The sorting functions described in this section all rearrange text in
+a buffer.  This is in contrast to the function @code{sort}, which
+rearranges the order of the elements of a list (@pxref{Rearrangement}).
+The values returned by these functions are not meaningful.
+
+@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
+This function is the general text-sorting routine that subdivides a
+buffer into records and then sorts them.  Most of the commands in this
+section use this function.
+
+To understand how @code{sort-subr} works, consider the whole accessible
+portion of the buffer as being divided into disjoint pieces called
+@dfn{sort records}.  The records may or may not be contiguous, but they
+must not overlap.  A portion of each sort record (perhaps all of it) is
+designated as the sort key.  Sorting rearranges the records in order by
+their sort keys.
+
+Usually, the records are rearranged in order of ascending sort key.
+If the first argument to the @code{sort-subr} function, @var{reverse},
+is non-@code{nil}, the sort records are rearranged in order of
+descending sort key.
+
+The next four arguments to @code{sort-subr} are functions that are
+called to move point across a sort record.  They are called many times
+from within @code{sort-subr}.
+
+@enumerate
+@item
+@var{nextrecfun} is called with point at the end of a record.  This
+function moves point to the start of the next record.  The first record
+is assumed to start at the position of point when @code{sort-subr} is
+called.  Therefore, you should usually move point to the beginning of
+the buffer before calling @code{sort-subr}.
+
+This function can indicate there are no more sort records by leaving
+point at the end of the buffer.
+
+@item
+@var{endrecfun} is called with point within a record.  It moves point to
+the end of the record.
+
+@item
+@var{startkeyfun} is called to move point from the start of a record to
+the start of the sort key.  This argument is optional; if it is omitted,
+the whole record is the sort key.  If supplied, the function should
+either return a non-@code{nil} value to be used as the sort key, or
+return @code{nil} to indicate that the sort key is in the buffer
+starting at point.  In the latter case, @var{endkeyfun} is called to
+find the end of the sort key.
+
+@item
+@var{endkeyfun} is called to move point from the start of the sort key
+to the end of the sort key.  This argument is optional.  If
+@var{startkeyfun} returns @code{nil} and this argument is omitted (or
+@code{nil}), then the sort key extends to the end of the record.  There
+is no need for @var{endkeyfun} if @var{startkeyfun} returns a
+non-@code{nil} value.
+@end enumerate
+
+The argument @var{predicate} is the function to use to compare keys.
+If keys are numbers, it defaults to @code{<}; otherwise it defaults to
+@code{string<}.
+
+As an example of @code{sort-subr}, here is the complete function
+definition for @code{sort-lines}:
+
+@example
+@group
+;; @r{Note that the first two lines of doc string}
+;; @r{are effectively one line when viewed by a user.}
+(defun sort-lines (reverse beg end)
+  "Sort lines in region alphabetically;\
+ argument means descending order.
+Called from a program, there are three arguments:
+@end group
+@group
+REVERSE (non-nil means reverse order),\
+ BEG and END (region to sort).
+The variable `sort-fold-case' determines\
+ whether alphabetic case affects
+the sort order."
+@end group
+@group
+  (interactive "P\nr")
+  (save-excursion
+    (save-restriction
+      (narrow-to-region beg end)
+      (goto-char (point-min))
+      (let ((inhibit-field-text-motion t))
+        (sort-subr reverse 'forward-line 'end-of-line)))))
+@end group
+@end example
+
+Here @code{forward-line} moves point to the start of the next record,
+and @code{end-of-line} moves point to the end of record.  We do not pass
+the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
+record is used as the sort key.
+
+The @code{sort-paragraphs} function is very much the same, except that
+its @code{sort-subr} call looks like this:
+
+@example
+@group
+(sort-subr reverse
+           (function
+             (lambda ()
+               (while (and (not (eobp))
+                      (looking-at paragraph-separate))
+                 (forward-line 1))))
+           'forward-paragraph)
+@end group
+@end example
+
+Markers pointing into any sort records are left with no useful
+position after @code{sort-subr} returns.
+@end defun
+
+@defopt sort-fold-case
+If this variable is non-@code{nil}, @code{sort-subr} and the other
+buffer sorting functions ignore case when comparing strings.
+@end defopt
+
+@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
+This command sorts the region between @var{start} and @var{end}
+alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
+If @var{reverse} is a negative integer, then sorting is in reverse
+order.
+
+Alphabetical sorting means that two sort keys are compared by
+comparing the first characters of each, the second characters of each,
+and so on.  If a mismatch is found, it means that the sort keys are
+unequal; the sort key whose character is less at the point of first
+mismatch is the lesser sort key.  The individual characters are compared
+according to their numerical character codes in the Emacs character set.
+
+The value of the @var{record-regexp} argument specifies how to divide
+the buffer into sort records.  At the end of each record, a search is
+done for this regular expression, and the text that matches it is taken
+as the next record.  For example, the regular expression @samp{^.+$},
+which matches lines with at least one character besides a newline, would
+make each such line into a sort record.  @xref{Regular Expressions}, for
+a description of the syntax and meaning of regular expressions.
+
+The value of the @var{key-regexp} argument specifies what part of each
+record is the sort key.  The @var{key-regexp} could match the whole
+record, or only a part.  In the latter case, the rest of the record has
+no effect on the sorted order of records, but it is carried along when
+the record moves to its new position.
+
+The @var{key-regexp} argument can refer to the text matched by a
+subexpression of @var{record-regexp}, or it can be a regular expression
+on its own.
+
+If @var{key-regexp} is:
+
+@table @asis
+@item @samp{\@var{digit}}
+then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
+grouping in @var{record-regexp} is the sort key.
+
+@item @samp{\&}
+then the whole record is the sort key.
+
+@item a regular expression
+then @code{sort-regexp-fields} searches for a match for the regular
+expression within the record.  If such a match is found, it is the sort
+key.  If there is no match for @var{key-regexp} within a record then
+that record is ignored, which means its position in the buffer is not
+changed.  (The other records may move around it.)
+@end table
+
+For example, if you plan to sort all the lines in the region by the
+first word on each line starting with the letter @samp{f}, you should
+set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
+@samp{\<f\w*\>}.  The resulting expression looks like this:
+
+@example
+@group
+(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
+                    (region-beginning)
+                    (region-end))
+@end group
+@end example
+
+If you call @code{sort-regexp-fields} interactively, it prompts for
+@var{record-regexp} and @var{key-regexp} in the minibuffer.
+@end deffn
+
+@deffn Command sort-lines reverse start end
+This command alphabetically sorts lines in the region between
+@var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
+is in reverse order.
+@end deffn
+
+@deffn Command sort-paragraphs reverse start end
+This command alphabetically sorts paragraphs in the region between
+@var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
+is in reverse order.
+@end deffn
+
+@deffn Command sort-pages reverse start end
+This command alphabetically sorts pages in the region between
+@var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
+is in reverse order.
+@end deffn
+
+@deffn Command sort-fields field start end
+This command sorts lines in the region between @var{start} and
+@var{end}, comparing them alphabetically by the @var{field}th field
+of each line.  Fields are separated by whitespace and numbered starting
+from 1.  If @var{field} is negative, sorting is by the
+@w{@minus{}@var{field}th} field from the end of the line.  This command
+is useful for sorting tables.
+@end deffn
+
+@deffn Command sort-numeric-fields field start end
+This command sorts lines in the region between @var{start} and
+@var{end}, comparing them numerically by the @var{field}th field of
+each line.  Fields are separated by whitespace and numbered starting
+from 1.  The specified field must contain a number in each line of the
+region.  Numbers starting with 0 are treated as octal, and numbers
+starting with @samp{0x} are treated as hexadecimal.
+
+If @var{field} is negative, sorting is by the
+@w{@minus{}@var{field}th} field from the end of the line.  This
+command is useful for sorting tables.
+@end deffn
+
+@defopt sort-numeric-base
+This variable specifies the default radix for
+@code{sort-numeric-fields} to parse numbers.
+@end defopt
+
+@deffn Command sort-columns reverse &optional beg end
+This command sorts the lines in the region between @var{beg} and
+@var{end}, comparing them alphabetically by a certain range of
+columns.  The column positions of @var{beg} and @var{end} bound the
+range of columns to sort on.
+
+If @var{reverse} is non-@code{nil}, the sort is in reverse order.
+
+One unusual thing about this command is that the entire line
+containing position @var{beg}, and the entire line containing position
+@var{end}, are included in the region sorted.
+
+Note that @code{sort-columns} rejects text that contains tabs, because
+tabs could be split across the specified columns.  Use @kbd{M-x
+untabify} to convert tabs to spaces before sorting.
+
+When possible, this command actually works by calling the @code{sort}
+utility program.
+@end deffn
+
+@node Columns
+@comment  node-name,  next,  previous,  up
+@section Counting Columns
+@cindex columns
+@cindex counting columns
+@cindex horizontal position
+
+  The column functions convert between a character position (counting
+characters from the beginning of the buffer) and a column position
+(counting screen characters from the beginning of a line).
+
+  These functions count each character according to the number of
+columns it occupies on the screen.  This means control characters count
+as occupying 2 or 4 columns, depending upon the value of
+@code{ctl-arrow}, and tabs count as occupying a number of columns that
+depends on the value of @code{tab-width} and on the column where the tab
+begins.  @xref{Usual Display}.
+
+  Column number computations ignore the width of the window and the
+amount of horizontal scrolling.  Consequently, a column value can be
+arbitrarily high.  The first (or leftmost) column is numbered 0.  They
+also ignore overlays and text properties, aside from invisibility.
+
+@defun current-column
+This function returns the horizontal position of point, measured in
+columns, counting from 0 at the left margin.  The column position is the
+sum of the widths of all the displayed representations of the characters
+between the start of the current line and point.
+
+For an example of using @code{current-column}, see the description of
+@code{count-lines} in @ref{Text Lines}.
+@end defun
+
+@defun move-to-column column &optional force
+This function moves point to @var{column} in the current line.  The
+calculation of @var{column} takes into account the widths of the
+displayed representations of the characters between the start of the
+line and point.
+
+If column @var{column} is beyond the end of the line, point moves to the
+end of the line.  If @var{column} is negative, point moves to the
+beginning of the line.
+
+If it is impossible to move to column @var{column} because that is in
+the middle of a multicolumn character such as a tab, point moves to the
+end of that character.  However, if @var{force} is non-@code{nil}, and
+@var{column} is in the middle of a tab, then @code{move-to-column}
+converts the tab into spaces so that it can move precisely to column
+@var{column}.  Other multicolumn characters can cause anomalies despite
+@var{force}, since there is no way to split them.
+
+The argument @var{force} also has an effect if the line isn't long
+enough to reach column @var{column}; if it is @code{t}, that means to
+add whitespace at the end of the line to reach that column.
+
+If @var{column} is not an integer, an error is signaled.
+
+The return value is the column number actually moved to.
+@end defun
+
+@node Indentation
+@section Indentation
+@cindex indentation
+
+  The indentation functions are used to examine, move to, and change
+whitespace that is at the beginning of a line.  Some of the functions
+can also change whitespace elsewhere on a line.  Columns and indentation
+count from zero at the left margin.
+
+@menu
+* Primitive Indent::      Functions used to count and insert indentation.
+* Mode-Specific Indent::  Customize indentation for different modes.
+* Region Indent::         Indent all the lines in a region.
+* Relative Indent::       Indent the current line based on previous lines.
+* Indent Tabs::           Adjustable, typewriter-like tab stops.
+* Motion by Indent::      Move to first non-blank character.
+@end menu
+
+@node Primitive Indent
+@subsection Indentation Primitives
+
+  This section describes the primitive functions used to count and
+insert indentation.  The functions in the following sections use these
+primitives.  @xref{Width}, for related functions.
+
+@defun current-indentation
+@comment !!Type Primitive Function
+@comment !!SourceFile indent.c
+This function returns the indentation of the current line, which is
+the horizontal position of the first nonblank character.  If the
+contents are entirely blank, then this is the horizontal position of the
+end of the line.
+@end defun
+
+@deffn Command indent-to column &optional minimum
+@comment !!Type Primitive Function
+@comment !!SourceFile indent.c
+This function indents from point with tabs and spaces until @var{column}
+is reached.  If @var{minimum} is specified and non-@code{nil}, then at
+least that many spaces are inserted even if this requires going beyond
+@var{column}.  Otherwise the function does nothing if point is already
+beyond @var{column}.  The value is the column at which the inserted
+indentation ends.
+
+The inserted whitespace characters inherit text properties from the
+surrounding text (usually, from the preceding text only).  @xref{Sticky
+Properties}.
+@end deffn
+
+@defopt indent-tabs-mode
+@comment !!SourceFile indent.c
+If this variable is non-@code{nil}, indentation functions can insert
+tabs as well as spaces.  Otherwise, they insert only spaces.  Setting
+this variable automatically makes it buffer-local in the current buffer.
+@end defopt
+
+@node Mode-Specific Indent
+@subsection Indentation Controlled by Major Mode
+
+  An important function of each major mode is to customize the @key{TAB}
+key to indent properly for the language being edited.  This section
+describes the mechanism of the @key{TAB} key and how to control it.
+The functions in this section return unpredictable values.
+
+@defvar indent-line-function
+This variable's value is the function to be used by @key{TAB} (and
+various commands) to indent the current line.  The command
+@code{indent-according-to-mode} does no more than call this function.
+
+In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
+mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
+The default value is @code{indent-relative}.
+@end defvar
+
+@deffn Command indent-according-to-mode
+This command calls the function in @code{indent-line-function} to
+indent the current line in a way appropriate for the current major mode.
+@end deffn
+
+@deffn Command indent-for-tab-command
+This command calls the function in @code{indent-line-function} to indent
+the current line; however, if that function is
+@code{indent-to-left-margin}, @code{insert-tab} is called instead.  (That
+is a trivial command that inserts a tab character.)
+@end deffn
+
+@deffn Command newline-and-indent
+@comment !!SourceFile simple.el
+This function inserts a newline, then indents the new line (the one
+following the newline just inserted) according to the major mode.
+
+It does indentation by calling the current @code{indent-line-function}.
+In programming language modes, this is the same thing @key{TAB} does,
+but in some text modes, where @key{TAB} inserts a tab,
+@code{newline-and-indent} indents to the column specified by
+@code{left-margin}.
+@end deffn
+
+@deffn Command reindent-then-newline-and-indent
+@comment !!SourceFile simple.el
+This command reindents the current line, inserts a newline at point,
+and then indents the new line (the one following the newline just
+inserted).
+
+This command does indentation on both lines according to the current
+major mode, by calling the current value of @code{indent-line-function}.
+In programming language modes, this is the same thing @key{TAB} does,
+but in some text modes, where @key{TAB} inserts a tab,
+@code{reindent-then-newline-and-indent} indents to the column specified
+by @code{left-margin}.
+@end deffn
+
+@node Region Indent
+@subsection Indenting an Entire Region
+
+  This section describes commands that indent all the lines in the
+region.  They return unpredictable values.
+
+@deffn Command indent-region start end to-column
+This command indents each nonblank line starting between @var{start}
+(inclusive) and @var{end} (exclusive).  If @var{to-column} is
+@code{nil}, @code{indent-region} indents each nonblank line by calling
+the current mode's indentation function, the value of
+@code{indent-line-function}.
+
+If @var{to-column} is non-@code{nil}, it should be an integer
+specifying the number of columns of indentation; then this function
+gives each line exactly that much indentation, by either adding or
+deleting whitespace.
+
+If there is a fill prefix, @code{indent-region} indents each line
+by making it start with the fill prefix.
+@end deffn
+
+@defvar indent-region-function
+The value of this variable is a function that can be used by
+@code{indent-region} as a short cut.  It should take two arguments, the
+start and end of the region.  You should design the function so
+that it will produce the same results as indenting the lines of the
+region one by one, but presumably faster.
+
+If the value is @code{nil}, there is no short cut, and
+@code{indent-region} actually works line by line.
+
+A short-cut function is useful in modes such as C mode and Lisp mode,
+where the @code{indent-line-function} must scan from the beginning of
+the function definition: applying it to each line would be quadratic in
+time.  The short cut can update the scan information as it moves through
+the lines indenting them; this takes linear time.  In a mode where
+indenting a line individually is fast, there is no need for a short cut.
+
+@code{indent-region} with a non-@code{nil} argument @var{to-column} has
+a different meaning and does not use this variable.
+@end defvar
+
+@deffn Command indent-rigidly start end count
+@comment !!SourceFile indent.el
+This command indents all lines starting between @var{start}
+(inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
+This ``preserves the shape'' of the affected region, moving it as a
+rigid unit.  Consequently, this command is useful not only for indenting
+regions of unindented text, but also for indenting regions of formatted
+code.
+
+For example, if @var{count} is 3, this command adds 3 columns of
+indentation to each of the lines beginning in the region specified.
+
+In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
+@code{indent-rigidly} to indent the text copied from the message being
+replied to.
+@end deffn
+
+@defun indent-code-rigidly start end columns &optional nochange-regexp
+This is like @code{indent-rigidly}, except that it doesn't alter lines
+that start within strings or comments.
+
+In addition, it doesn't alter a line if @var{nochange-regexp} matches at
+the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
+@end defun
+
+@node Relative Indent
+@subsection Indentation Relative to Previous Lines
+
+  This section describes two commands that indent the current line
+based on the contents of previous lines.
+
+@deffn Command indent-relative &optional unindented-ok
+This command inserts whitespace at point, extending to the same
+column as the next @dfn{indent point} of the previous nonblank line.  An
+indent point is a non-whitespace character following whitespace.  The
+next indent point is the first one at a column greater than the current
+column of point.  For example, if point is underneath and to the left of
+the first non-blank character of a line of text, it moves to that column
+by inserting whitespace.
+
+If the previous nonblank line has no next indent point (i.e., none at a
+great enough column position), @code{indent-relative} either does
+nothing (if @var{unindented-ok} is non-@code{nil}) or calls
+@code{tab-to-tab-stop}.  Thus, if point is underneath and to the right
+of the last column of a short line of text, this command ordinarily
+moves point to the next tab stop by inserting whitespace.
+
+The return value of @code{indent-relative} is unpredictable.
+
+In the following example, point is at the beginning of the second
+line:
+
+@example
+@group
+            This line is indented twelve spaces.
+@point{}The quick brown fox jumped.
+@end group
+@end example
+
+@noindent
+Evaluation of the expression @code{(indent-relative nil)} produces the
+following:
+
+@example
+@group
+            This line is indented twelve spaces.
+            @point{}The quick brown fox jumped.
+@end group
+@end example
+
+  In this next example, point is between the @samp{m} and @samp{p} of
+@samp{jumped}:
+
+@example
+@group
+            This line is indented twelve spaces.
+The quick brown fox jum@point{}ped.
+@end group
+@end example
+
+@noindent
+Evaluation of the expression @code{(indent-relative nil)} produces the
+following:
+
+@example
+@group
+            This line is indented twelve spaces.
+The quick brown fox jum  @point{}ped.
+@end group
+@end example
+@end deffn
+
+@deffn Command indent-relative-maybe
+@comment !!SourceFile indent.el
+This command indents the current line like the previous nonblank line,
+by calling @code{indent-relative} with @code{t} as the
+@var{unindented-ok} argument.  The return value is unpredictable.
+
+If the previous nonblank line has no indent points beyond the current
+column, this command does nothing.
+@end deffn
+
+@node Indent Tabs
+@comment  node-name,  next,  previous,  up
+@subsection Adjustable ``Tab Stops''
+@cindex tabs stops for indentation
+
+  This section explains the mechanism for user-specified ``tab stops''
+and the mechanisms that use and set them.  The name ``tab stops'' is
+used because the feature is similar to that of the tab stops on a
+typewriter.  The feature works by inserting an appropriate number of
+spaces and tab characters to reach the next tab stop column; it does not
+affect the display of tab characters in the buffer (@pxref{Usual
+Display}).  Note that the @key{TAB} character as input uses this tab
+stop feature only in a few major modes, such as Text mode.
+@xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
+
+@deffn Command tab-to-tab-stop
+This command inserts spaces or tabs before point, up to the next tab
+stop column defined by @code{tab-stop-list}.  It searches the list for
+an element greater than the current column number, and uses that element
+as the column to indent to.  It does nothing if no such element is
+found.
+@end deffn
+
+@defopt tab-stop-list
+This variable is the list of tab stop columns used by
+@code{tab-to-tab-stops}.  The elements should be integers in increasing
+order.  The tab stop columns need not be evenly spaced.
+
+Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
+interactively.
+@end defopt
+
+@node Motion by Indent
+@subsection Indentation-Based Motion Commands
+
+  These commands, primarily for interactive use, act based on the
+indentation in the text.
+
+@deffn Command back-to-indentation
+@comment !!SourceFile simple.el
+This command moves point to the first non-whitespace character in the
+current line (which is the line in which point is located).  It returns
+@code{nil}.
+@end deffn
+
+@deffn Command backward-to-indentation &optional arg
+@comment !!SourceFile simple.el
+This command moves point backward @var{arg} lines and then to the
+first nonblank character on that line.  It returns @code{nil}.
+If @var{arg} is omitted or @code{nil}, it defaults to 1.
+@end deffn
+
+@deffn Command forward-to-indentation &optional arg
+@comment !!SourceFile simple.el
+This command moves point forward @var{arg} lines and then to the first
+nonblank character on that line.  It returns @code{nil}.
+If @var{arg} is omitted or @code{nil}, it defaults to 1.
+@end deffn
+
+@node Case Changes
+@comment  node-name,  next,  previous,  up
+@section Case Changes
+@cindex case conversion in buffers
+
+  The case change commands described here work on text in the current
+buffer.  @xref{Case Conversion}, for case conversion functions that work
+on strings and characters.  @xref{Case Tables}, for how to customize
+which characters are upper or lower case and how to convert them.
+
+@deffn Command capitalize-region start end
+This function capitalizes all words in the region defined by
+@var{start} and @var{end}.  To capitalize means to convert each word's
+first character to upper case and convert the rest of each word to lower
+case.  The function returns @code{nil}.
+
+If one end of the region is in the middle of a word, the part of the
+word within the region is treated as an entire word.
+
+When @code{capitalize-region} is called interactively, @var{start} and
+@var{end} are point and the mark, with the smallest first.
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the contents of the 5th foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(capitalize-region 1 44)
+@result{} nil
+
+---------- Buffer: foo ----------
+This Is The Contents Of The 5th Foo.
+---------- Buffer: foo ----------
+@end group
+@end example
+@end deffn
+
+@deffn Command downcase-region start end
+This function converts all of the letters in the region defined by
+@var{start} and @var{end} to lower case.  The function returns
+@code{nil}.
+
+When @code{downcase-region} is called interactively, @var{start} and
+@var{end} are point and the mark, with the smallest first.
+@end deffn
+
+@deffn Command upcase-region start end
+This function converts all of the letters in the region defined by
+@var{start} and @var{end} to upper case.  The function returns
+@code{nil}.
+
+When @code{upcase-region} is called interactively, @var{start} and
+@var{end} are point and the mark, with the smallest first.
+@end deffn
+
+@deffn Command capitalize-word count
+This function capitalizes @var{count} words after point, moving point
+over as it does.  To capitalize means to convert each word's first
+character to upper case and convert the rest of each word to lower case.
+If @var{count} is negative, the function capitalizes the
+@minus{}@var{count} previous words but does not move point.  The value
+is @code{nil}.
+
+If point is in the middle of a word, the part of the word before point
+is ignored when moving forward.  The rest is treated as an entire word.
+
+When @code{capitalize-word} is called interactively, @var{count} is
+set to the numeric prefix argument.
+@end deffn
+
+@deffn Command downcase-word count
+This function converts the @var{count} words after point to all lower
+case, moving point over as it does.  If @var{count} is negative, it
+converts the @minus{}@var{count} previous words but does not move point.
+The value is @code{nil}.
+
+When @code{downcase-word} is called interactively, @var{count} is set
+to the numeric prefix argument.
+@end deffn
+
+@deffn Command upcase-word count
+This function converts the @var{count} words after point to all upper
+case, moving point over as it does.  If @var{count} is negative, it
+converts the @minus{}@var{count} previous words but does not move point.
+The value is @code{nil}.
+
+When @code{upcase-word} is called interactively, @var{count} is set to
+the numeric prefix argument.
+@end deffn
+
+@node Text Properties
+@section Text Properties
+@cindex text properties
+@cindex attributes of text
+@cindex properties of text
+
+  Each character position in a buffer or a string can have a @dfn{text
+property list}, much like the property list of a symbol (@pxref{Property
+Lists}).  The properties belong to a particular character at a
+particular place, such as, the letter @samp{T} at the beginning of this
+sentence or the first @samp{o} in @samp{foo}---if the same character
+occurs in two different places, the two occurrences in general have
+different properties.
+
+  Each property has a name and a value.  Both of these can be any Lisp
+object, but the name is normally a symbol.  Typically each property
+name symbol is used for a particular purpose; for instance, the text
+property @code{face} specifies the faces for displaying the character
+(@pxref{Special Properties}).  The usual way to access the property
+list is to specify a name and ask what value corresponds to it.
+
+  If a character has a @code{category} property, we call it the
+@dfn{property category} of the character.  It should be a symbol.  The
+properties of the symbol serve as defaults for the properties of the
+character.
+
+  Copying text between strings and buffers preserves the properties
+along with the characters; this includes such diverse functions as
+@code{substring}, @code{insert}, and @code{buffer-substring}.
+
+@menu
+* Examining Properties::   Looking at the properties of one character.
+* Changing Properties::	   Setting the properties of a range of text.
+* Property Search::	   Searching for where a property changes value.
+* Special Properties::	   Particular properties with special meanings.
+* Format Properties::      Properties for representing formatting of text.
+* Sticky Properties::      How inserted text gets properties from
+                             neighboring text.
+* Lazy Properties::        Computing text properties in a lazy fashion
+                             only when text is examined.
+* Clickable Text::         Using text properties to make regions of text
+                             do something when you click on them.
+* Links and Mouse-1::      How to make @key{Mouse-1} follow a link.
+* Fields::                 The @code{field} property defines
+                             fields within the buffer.
+* Not Intervals::	   Why text properties do not use
+			     Lisp-visible text intervals.
+@end menu
+
+@node Examining Properties
+@subsection Examining Text Properties
+
+  The simplest way to examine text properties is to ask for the value of
+a particular property of a particular character.  For that, use
+@code{get-text-property}.  Use @code{text-properties-at} to get the
+entire property list of a character.  @xref{Property Search}, for
+functions to examine the properties of a number of characters at once.
+
+  These functions handle both strings and buffers.  Keep in mind that
+positions in a string start from 0, whereas positions in a buffer start
+from 1.
+
+@defun get-text-property pos prop &optional object
+This function returns the value of the @var{prop} property of the
+character after position @var{pos} in @var{object} (a buffer or
+string).  The argument @var{object} is optional and defaults to the
+current buffer.
+
+If there is no @var{prop} property strictly speaking, but the character
+has a property category that is a symbol, then @code{get-text-property} returns
+the @var{prop} property of that symbol.
+@end defun
+
+@defun get-char-property position prop &optional object
+This function is like @code{get-text-property}, except that it checks
+overlays first and then text properties.  @xref{Overlays}.
+
+The argument @var{object} may be a string, a buffer, or a window.  If it
+is a window, then the buffer displayed in that window is used for text
+properties and overlays, but only the overlays active for that window
+are considered.  If @var{object} is a buffer, then all overlays in that
+buffer are considered, as well as text properties.  If @var{object} is a
+string, only text properties are considered, since strings never have
+overlays.
+@end defun
+
+@defun get-char-property-and-overlay position prop &optional object
+This is like @code{get-char-property}, but gives extra information
+about the overlay that the property value comes from.
+
+Its value is a cons cell whose @sc{car} is the property value, the
+same value @code{get-char-property} would return with the same
+arguments.  Its @sc{cdr} is the overlay in which the property was
+found, or @code{nil}, if it was found as a text property or not found
+at all.
+
+If @var{position} is at the end of @var{object}, both the @sc{car} and
+the @sc{cdr} of the value are @code{nil}.
+@end defun
+
+@defvar char-property-alias-alist
+This variable holds an alist which maps property names to a list of
+alternative property names.  If a character does not specify a direct
+value for a property, the alternative property names are consulted in
+order; the first non-@code{nil} value is used.  This variable takes
+precedence over @code{default-text-properties}, and @code{category}
+properties take precedence over this variable.
+@end defvar
+
+@defun text-properties-at position &optional object
+This function returns the entire property list of the character at
+@var{position} in the string or buffer @var{object}.  If @var{object} is
+@code{nil}, it defaults to the current buffer.
+@end defun
+
+@defvar default-text-properties
+This variable holds a property list giving default values for text
+properties.  Whenever a character does not specify a value for a
+property, neither directly, through a category symbol, or through
+@code{char-property-alias-alist}, the value stored in this list is
+used instead.  Here is an example:
+
+@example
+(setq default-text-properties '(foo 69)
+      char-property-alias-alist nil)
+;; @r{Make sure character 1 has no properties of its own.}
+(set-text-properties 1 2 nil)
+;; @r{What we get, when we ask, is the default value.}
+(get-text-property 1 'foo)
+     @result{} 69
+@end example
+@end defvar
+
+@node Changing Properties
+@subsection Changing Text Properties
+
+  The primitives for changing properties apply to a specified range of
+text in a buffer or string.  The function @code{set-text-properties}
+(see end of section) sets the entire property list of the text in that
+range; more often, it is useful to add, change, or delete just certain
+properties specified by name.
+
+  Since text properties are considered part of the contents of the
+buffer (or string), and can affect how a buffer looks on the screen,
+any change in buffer text properties marks the buffer as modified.
+Buffer text property changes are undoable also (@pxref{Undo}).
+Positions in a string start from 0, whereas positions in a buffer
+start from 1.
+
+@defun put-text-property start end prop value &optional object
+This function sets the @var{prop} property to @var{value} for the text
+between @var{start} and @var{end} in the string or buffer @var{object}.
+If @var{object} is @code{nil}, it defaults to the current buffer.
+@end defun
+
+@defun add-text-properties start end props &optional object
+This function adds or overrides text properties for the text between
+@var{start} and @var{end} in the string or buffer @var{object}.  If
+@var{object} is @code{nil}, it defaults to the current buffer.
+
+The argument @var{props} specifies which properties to add.  It should
+have the form of a property list (@pxref{Property Lists}): a list whose
+elements include the property names followed alternately by the
+corresponding values.
+
+The return value is @code{t} if the function actually changed some
+property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
+its values agree with those in the text).
+
+For example, here is how to set the @code{comment} and @code{face}
+properties of a range of text:
+
+@example
+(add-text-properties @var{start} @var{end}
+                     '(comment t face highlight))
+@end example
+@end defun
+
+@defun remove-text-properties start end props &optional object
+This function deletes specified text properties from the text between
+@var{start} and @var{end} in the string or buffer @var{object}.  If
+@var{object} is @code{nil}, it defaults to the current buffer.
+
+The argument @var{props} specifies which properties to delete.  It
+should have the form of a property list (@pxref{Property Lists}): a list
+whose elements are property names alternating with corresponding values.
+But only the names matter---the values that accompany them are ignored.
+For example, here's how to remove the @code{face} property.
+
+@example
+(remove-text-properties @var{start} @var{end} '(face nil))
+@end example
+
+The return value is @code{t} if the function actually changed some
+property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
+if no character in the specified text had any of those properties).
+
+To remove all text properties from certain text, use
+@code{set-text-properties} and specify @code{nil} for the new property
+list.
+@end defun
+
+@defun remove-list-of-text-properties start end list-of-properties &optional object
+Like @code{remove-text-properties} except that
+@var{list-of-properties} is a list of property names only, not an
+alternating list of property names and values.
+@end defun
+
+@defun set-text-properties start end props &optional object
+This function completely replaces the text property list for the text
+between @var{start} and @var{end} in the string or buffer @var{object}.
+If @var{object} is @code{nil}, it defaults to the current buffer.
+
+The argument @var{props} is the new property list.  It should be a list
+whose elements are property names alternating with corresponding values.
+
+After @code{set-text-properties} returns, all the characters in the
+specified range have identical properties.
+
+If @var{props} is @code{nil}, the effect is to get rid of all properties
+from the specified range of text.  Here's an example:
+
+@example
+(set-text-properties @var{start} @var{end} nil)
+@end example
+
+Do not rely on the return value of this function.
+@end defun
+
+  The easiest way to make a string with text properties
+is with @code{propertize}:
+
+@defun propertize string &rest properties
+This function returns a copy of @var{string} which has the text
+properties @var{properties}.  These properties apply to all the
+characters in the string that is returned.  Here is an example that
+constructs a string with a @code{face} property and a @code{mouse-face}
+property:
+
+@smallexample
+(propertize "foo" 'face 'italic
+            'mouse-face 'bold-italic)
+     @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
+@end smallexample
+
+To put different properties on various parts of a string, you can
+construct each part with @code{propertize} and then combine them with
+@code{concat}:
+
+@smallexample
+(concat
+ (propertize "foo" 'face 'italic
+             'mouse-face 'bold-italic)
+ " and "
+ (propertize "bar" 'face 'italic
+             'mouse-face 'bold-italic))
+     @result{} #("foo and bar"
+                 0 3 (face italic mouse-face bold-italic)
+                 3 8 nil
+                 8 11 (face italic mouse-face bold-italic))
+@end smallexample
+@end defun
+
+  See also the function @code{buffer-substring-no-properties}
+(@pxref{Buffer Contents}) which copies text from the buffer
+but does not copy its properties.
+
+@node Property Search
+@subsection Text Property Search Functions
+
+  In typical use of text properties, most of the time several or many
+consecutive characters have the same value for a property.  Rather than
+writing your programs to examine characters one by one, it is much
+faster to process chunks of text that have the same property value.
+
+  Here are functions you can use to do this.  They use @code{eq} for
+comparing property values.  In all cases, @var{object} defaults to the
+current buffer.
+
+  For high performance, it's very important to use the @var{limit}
+argument to these functions, especially the ones that search for a
+single property---otherwise, they may spend a long time scanning to the
+end of the buffer, if the property you are interested in does not change.
+
+  These functions do not move point; instead, they return a position (or
+@code{nil}).  Remember that a position is always between two characters;
+the position returned by these functions is between two characters with
+different properties.
+
+@defun next-property-change pos &optional object limit
+The function scans the text forward from position @var{pos} in the
+string or buffer @var{object} till it finds a change in some text
+property, then returns the position of the change.  In other words, it
+returns the position of the first character beyond @var{pos} whose
+properties are not identical to those of the character just after
+@var{pos}.
+
+If @var{limit} is non-@code{nil}, then the scan ends at position
+@var{limit}.  If there is no property change before that point,
+@code{next-property-change} returns @var{limit}.
+
+The value is @code{nil} if the properties remain unchanged all the way
+to the end of @var{object} and @var{limit} is @code{nil}.  If the value
+is non-@code{nil}, it is a position greater than or equal to @var{pos}.
+The value equals @var{pos} only when @var{limit} equals @var{pos}.
+
+Here is an example of how to scan the buffer by chunks of text within
+which all properties are constant:
+
+@smallexample
+(while (not (eobp))
+  (let ((plist (text-properties-at (point)))
+        (next-change
+         (or (next-property-change (point) (current-buffer))
+             (point-max))))
+    @r{Process text from point to @var{next-change}@dots{}}
+    (goto-char next-change)))
+@end smallexample
+@end defun
+
+@defun previous-property-change pos &optional object limit
+This is like @code{next-property-change}, but scans back from @var{pos}
+instead of forward.  If the value is non-@code{nil}, it is a position
+less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
+equals @var{pos}.
+@end defun
+
+@defun next-single-property-change pos prop &optional object limit
+The function scans text for a change in the @var{prop} property, then
+returns the position of the change.  The scan goes forward from
+position @var{pos} in the string or buffer @var{object}.  In other
+words, this function returns the position of the first character
+beyond @var{pos} whose @var{prop} property differs from that of the
+character just after @var{pos}.
+
+If @var{limit} is non-@code{nil}, then the scan ends at position
+@var{limit}.  If there is no property change before that point,
+@code{next-single-property-change} returns @var{limit}.
+
+The value is @code{nil} if the property remains unchanged all the way to
+the end of @var{object} and @var{limit} is @code{nil}.  If the value is
+non-@code{nil}, it is a position greater than or equal to @var{pos}; it
+equals @var{pos} only if @var{limit} equals @var{pos}.
+@end defun
+
+@defun previous-single-property-change pos prop &optional object limit
+This is like @code{next-single-property-change}, but scans back from
+@var{pos} instead of forward.  If the value is non-@code{nil}, it is a
+position less than or equal to @var{pos}; it equals @var{pos} only if
+@var{limit} equals @var{pos}.
+@end defun
+
+@defun next-char-property-change pos &optional limit
+This is like @code{next-property-change} except that it considers
+overlay properties as well as text properties, and if no change is
+found before the end of the buffer, it returns the maximum buffer
+position rather than @code{nil} (in this sense, it resembles the
+corresponding overlay function @code{next-overlay-change}, rather than
+@code{next-property-change}).  There is no @var{object} operand
+because this function operates only on the current buffer.  It returns
+the next address at which either kind of property changes.
+@end defun
+
+@defun previous-char-property-change pos &optional limit
+This is like @code{next-char-property-change}, but scans back from
+@var{pos} instead of forward, and returns the minimum buffer
+position if no change is found.
+@end defun
+
+@defun next-single-char-property-change pos prop &optional object limit
+This is like @code{next-single-property-change} except that it
+considers overlay properties as well as text properties, and if no
+change is found before the end of the @var{object}, it returns the
+maximum valid position in @var{object} rather than @code{nil}.  Unlike
+@code{next-char-property-change}, this function @emph{does} have an
+@var{object} operand; if @var{object} is not a buffer, only
+text-properties are considered.
+@end defun
+
+@defun previous-single-char-property-change pos prop &optional object limit
+This is like @code{next-single-char-property-change}, but scans back
+from @var{pos} instead of forward, and returns the minimum valid
+position in @var{object} if no change is found.
+@end defun
+
+@defun text-property-any start end prop value &optional object
+This function returns non-@code{nil} if at least one character between
+@var{start} and @var{end} has a property @var{prop} whose value is
+@var{value}.  More precisely, it returns the position of the first such
+character.  Otherwise, it returns @code{nil}.
+
+The optional fifth argument, @var{object}, specifies the string or
+buffer to scan.  Positions are relative to @var{object}.  The default
+for @var{object} is the current buffer.
+@end defun
+
+@defun text-property-not-all start end prop value &optional object
+This function returns non-@code{nil} if at least one character between
+@var{start} and @var{end} does not have a property @var{prop} with value
+@var{value}.  More precisely, it returns the position of the first such
+character.  Otherwise, it returns @code{nil}.
+
+The optional fifth argument, @var{object}, specifies the string or
+buffer to scan.  Positions are relative to @var{object}.  The default
+for @var{object} is the current buffer.
+@end defun
+
+@node Special Properties
+@subsection Properties with Special Meanings
+
+  Here is a table of text property names that have special built-in
+meanings.  The following sections list a few additional special property
+names that control filling and property inheritance.  All other names
+have no standard meaning, and you can use them as you like.
+
+  Note: the properties @code{composition}, @code{display},
+@code{invisible} and @code{intangible} can also cause point to move to
+an acceptable place, after each Emacs command.  @xref{Adjusting
+Point}.
+
+@table @code
+@cindex property category of text character
+@kindex category @r{(text property)}
+@item category
+If a character has a @code{category} property, we call it the
+@dfn{property category} of the character.  It should be a symbol.  The
+properties of this symbol serve as defaults for the properties of the
+character.
+
+@item face
+@cindex face codes of text
+@kindex face @r{(text property)}
+You can use the property @code{face} to control the font and color of
+text.  @xref{Faces}, for more information.
+
+In the simplest case, the value is a face name.  It can also be a list;
+then each element can be any of these possibilities;
+
+@itemize @bullet
+@item
+A face name (a symbol or string).
+
+@item
+A property list of face attributes.  This has the
+form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
+face attribute name and @var{value} is a meaningful value for that
+attribute.  With this feature, you do not need to create a face each
+time you want to specify a particular attribute for certain text.
+@xref{Face Attributes}.
+
+@item
+A cons cell with the form @code{(foreground-color . @var{color-name})} or
+@code{(background-color . @var{color-name})}.  These elements specify
+just the foreground color or just the background color.  @xref{Color
+Names}, for the supported forms of @var{color-name}.
+
+A cons cell of @code{(foreground-color . @var{color-name})} is equivalent to
+specifying @code{(:foreground @var{color-name})}; likewise for the
+background.
+@end itemize
+
+You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
+update @code{face} properties based on the contents of the text.
+
+@item font-lock-face
+@kindex font-lock-face @r{(text property)}
+The @code{font-lock-face} property is the same in all respects as the
+@code{face} property, but its state of activation is controlled by
+@code{font-lock-mode}.  This can be advantageous for special buffers
+which are not intended to be user-editable, or for static areas of
+text which are always fontified in the same way.
+@xref{Precalculated Fontification}.
+
+Strictly speaking, @code{font-lock-face} is not a built-in text
+property; rather, it is implemented in Font Lock mode using
+@code{char-property-alias-alist}.  @xref{Examining Properties}.
+
+This property is new in Emacs 22.1.
+
+@item mouse-face
+@kindex mouse-face @r{(text property)}
+The property @code{mouse-face} is used instead of @code{face} when the
+mouse is on or near the character.  For this purpose, ``near'' means
+that all text between the character and where the mouse is have the same
+@code{mouse-face} property value.
+
+@item fontified
+@kindex fontified @r{(text property)}
+This property says whether the text is ready for display.  If
+@code{nil}, Emacs's redisplay routine calls the functions in
+@code{fontification-functions} (@pxref{Auto Faces}) to prepare this
+part of the buffer before it is displayed.  It is used internally by
+the ``just in time'' font locking code.
+
+@item display
+This property activates various features that change the
+way text is displayed.  For example, it can make text appear taller
+or shorter, higher or lower, wider or narrow, or replaced with an image.
+@xref{Display Property}.
+
+@item help-echo
+@kindex help-echo @r{(text property)}
+@cindex tooltip
+@anchor{Text help-echo}
+If text has a string as its @code{help-echo} property, then when you
+move the mouse onto that text, Emacs displays that string in the echo
+area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
+Manual}).
+
+If the value of the @code{help-echo} property is a function, that
+function is called with three arguments, @var{window}, @var{object} and
+@var{pos} and should return a help string or @code{nil} for
+none.  The first argument, @var{window} is the window in which
+the help was found.  The second, @var{object}, is the buffer, overlay or
+string which had the @code{help-echo} property.  The @var{pos}
+argument is as follows:
+
+@itemize @bullet{}
+@item
+If @var{object} is a buffer, @var{pos} is the position in the buffer.
+@item
+If @var{object} is an overlay, that overlay has a @code{help-echo}
+property, and @var{pos} is the position in the overlay's buffer.
+@item
+If @var{object} is a string (an overlay string or a string displayed
+with the @code{display} property), @var{pos} is the position in that
+string.
+@end itemize
+
+If the value of the @code{help-echo} property is neither a function nor
+a string, it is evaluated to obtain a help string.
+
+You can alter the way help text is displayed by setting the variable
+@code{show-help-function} (@pxref{Help display}).
+
+This feature is used in the mode line and for other active text.
+
+@item keymap
+@cindex keymap of character
+@kindex keymap @r{(text property)}
+The @code{keymap} property specifies an additional keymap for
+commands.  When this keymap applies, it is used for key lookup before
+the minor mode keymaps and before the buffer's local map.
+@xref{Active Keymaps}.  If the property value is a symbol, the
+symbol's function definition is used as the keymap.
+
+The property's value for the character before point applies if it is
+non-@code{nil} and rear-sticky, and the property's value for the
+character after point applies if it is non-@code{nil} and
+front-sticky.  (For mouse clicks, the position of the click is used
+instead of the position of point.)
+
+@item local-map
+@kindex local-map @r{(text property)}
+This property works like @code{keymap} except that it specifies a
+keymap to use @emph{instead of} the buffer's local map.  For most
+purposes (perhaps all purposes), it is better to use the @code{keymap}
+property.
+
+@item syntax-table
+The @code{syntax-table} property overrides what the syntax table says
+about this particular character.  @xref{Syntax Properties}.
+
+@item read-only
+@cindex read-only character
+@kindex read-only @r{(text property)}
+If a character has the property @code{read-only}, then modifying that
+character is not allowed.  Any command that would do so gets an error,
+@code{text-read-only}.  If the property value is a string, that string
+is used as the error message.
+
+Insertion next to a read-only character is an error if inserting
+ordinary text there would inherit the @code{read-only} property due to
+stickiness.  Thus, you can control permission to insert next to
+read-only text by controlling the stickiness.  @xref{Sticky Properties}.
+
+Since changing properties counts as modifying the buffer, it is not
+possible to remove a @code{read-only} property unless you know the
+special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
+and then remove the property.  @xref{Read Only Buffers}.
+
+@item invisible
+@kindex invisible @r{(text property)}
+A non-@code{nil} @code{invisible} property can make a character invisible
+on the screen.  @xref{Invisible Text}, for details.
+
+@item intangible
+@kindex intangible @r{(text property)}
+If a group of consecutive characters have equal and non-@code{nil}
+@code{intangible} properties, then you cannot place point between them.
+If you try to move point forward into the group, point actually moves to
+the end of the group.  If you try to move point backward into the group,
+point actually moves to the start of the group.
+
+If consecutive characters have unequal non-@code{nil}
+@code{intangible} properties, they belong to separate groups; each
+group is separately treated as described above.
+
+When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
+the @code{intangible} property is ignored.
+
+@item field
+@kindex field @r{(text property)}
+Consecutive characters with the same @code{field} property constitute a
+@dfn{field}.  Some motion functions including @code{forward-word} and
+@code{beginning-of-line} stop moving at a field boundary.
+@xref{Fields}.
+
+@item cursor
+@kindex cursor @r{(text property)}
+Normally, the cursor is displayed at the end of any overlay and text
+property strings present at the current window position.  You can
+place the cursor on any desired character of these strings by giving
+that character a non-@code{nil} @var{cursor} text property.
+
+@item pointer
+@kindex pointer @r{(text property)}
+This specifies a specific pointer shape when the mouse pointer is over
+this text or image.  @xref{Pointer Shape}, for possible pointer
+shapes.
+
+@item line-spacing
+@kindex line-spacing @r{(text property)}
+A newline can have a @code{line-spacing} text or overlay property that
+controls the height of the display line ending with that newline.  The
+property value overrides the default frame line spacing and the buffer
+local @code{line-spacing} variable.  @xref{Line Height}.
+
+@item line-height
+@kindex line-height @r{(text property)}
+A newline can have a @code{line-height} text or overlay property that
+controls the total height of the display line ending in that newline.
+@xref{Line Height}.
+
+@item modification-hooks
+@cindex change hooks for a character
+@cindex hooks for changing a character
+@kindex modification-hooks @r{(text property)}
+If a character has the property @code{modification-hooks}, then its
+value should be a list of functions; modifying that character calls all
+of those functions.  Each function receives two arguments: the beginning
+and end of the part of the buffer being modified.  Note that if a
+particular modification hook function appears on several characters
+being modified by a single primitive, you can't predict how many times
+the function will be called.
+
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
+Overlays also support the @code{modification-hooks} property, but the
+details are somewhat different (@pxref{Overlay Properties}).
+
+@item insert-in-front-hooks
+@itemx insert-behind-hooks
+@kindex insert-in-front-hooks @r{(text property)}
+@kindex insert-behind-hooks @r{(text property)}
+The operation of inserting text in a buffer also calls the functions
+listed in the @code{insert-in-front-hooks} property of the following
+character and in the @code{insert-behind-hooks} property of the
+preceding character.  These functions receive two arguments, the
+beginning and end of the inserted text.  The functions are called
+@emph{after} the actual insertion takes place.
+
+See also @ref{Change Hooks}, for other hooks that are called
+when you change text in a buffer.
+
+@item point-entered
+@itemx point-left
+@cindex hooks for motion of point
+@kindex point-entered @r{(text property)}
+@kindex point-left @r{(text property)}
+The special properties @code{point-entered} and @code{point-left}
+record hook functions that report motion of point.  Each time point
+moves, Emacs compares these two property values:
+
+@itemize @bullet
+@item
+the @code{point-left} property of the character after the old location,
+and
+@item
+the @code{point-entered} property of the character after the new
+location.
+@end itemize
+
+@noindent
+If these two values differ, each of them is called (if not @code{nil})
+with two arguments: the old value of point, and the new one.
+
+The same comparison is made for the characters before the old and new
+locations.  The result may be to execute two @code{point-left} functions
+(which may be the same function) and/or two @code{point-entered}
+functions (which may be the same function).  In any case, all the
+@code{point-left} functions are called first, followed by all the
+@code{point-entered} functions.
+
+It is possible with @code{char-after} to examine characters at various
+buffer positions without moving point to those positions.  Only an
+actual change in the value of point runs these hook functions.
+
+@defvar inhibit-point-motion-hooks
+When this variable is non-@code{nil}, @code{point-left} and
+@code{point-entered} hooks are not run, and the @code{intangible}
+property has no effect.  Do not set this variable globally; bind it with
+@code{let}.
+@end defvar
+
+@defvar show-help-function
+@anchor{Help display} If this variable is non-@code{nil}, it specifies a
+function called to display help strings.  These may be @code{help-echo}
+properties, menu help strings (@pxref{Simple Menu Items},
+@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
+Bar}).  The specified function is called with one argument, the help
+string to display.  Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
+Manual}) provides an example.
+@end defvar
+
+@item composition
+@kindex composition @r{(text property)}
+This text property is used to display a sequence of characters as a
+single glyph composed from components.  But the value of the property
+itself is completely internal to Emacs and should not be manipulated
+directly by, for instance, @code{put-text-property}.
+
+@end table
+
+@node Format Properties
+@subsection Formatted Text Properties
+
+  These text properties affect the behavior of the fill commands.  They
+are used for representing formatted text.  @xref{Filling}, and
+@ref{Margins}.
+
+@table @code
+@item hard
+If a newline character has this property, it is a ``hard'' newline.
+The fill commands do not alter hard newlines and do not move words
+across them.  However, this property takes effect only if the
+@code{use-hard-newlines} minor mode is enabled.  @xref{Hard and Soft
+Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
+
+@item right-margin
+This property specifies an extra right margin for filling this part of the
+text.
+
+@item left-margin
+This property specifies an extra left margin for filling this part of the
+text.
+
+@item justification
+This property specifies the style of justification for filling this part
+of the text.
+@end table
+
+@node Sticky Properties
+@subsection Stickiness of Text Properties
+@cindex sticky text properties
+@cindex inheritance of text properties
+
+  Self-inserting characters normally take on the same properties as the
+preceding character.  This is called @dfn{inheritance} of properties.
+
+  In a Lisp program, you can do insertion with inheritance or without,
+depending on your choice of insertion primitive.  The ordinary text
+insertion functions such as @code{insert} do not inherit any properties.
+They insert text with precisely the properties of the string being
+inserted, and no others.  This is correct for programs that copy text
+from one context to another---for example, into or out of the kill ring.
+To insert with inheritance, use the special primitives described in this
+section.  Self-inserting characters inherit properties because they work
+using these primitives.
+
+  When you do insertion with inheritance, @emph{which} properties are
+inherited, and from where, depends on which properties are @dfn{sticky}.
+Insertion after a character inherits those of its properties that are
+@dfn{rear-sticky}.  Insertion before a character inherits those of its
+properties that are @dfn{front-sticky}.  When both sides offer different
+sticky values for the same property, the previous character's value
+takes precedence.
+
+  By default, a text property is rear-sticky but not front-sticky; thus,
+the default is to inherit all the properties of the preceding character,
+and nothing from the following character.
+
+  You can control the stickiness of various text properties with two
+specific text properties, @code{front-sticky} and @code{rear-nonsticky},
+and with the variable @code{text-property-default-nonsticky}.  You can
+use the variable to specify a different default for a given property.
+You can use those two text properties to make any specific properties
+sticky or nonsticky in any particular part of the text.
+
+  If a character's @code{front-sticky} property is @code{t}, then all
+its properties are front-sticky.  If the @code{front-sticky} property is
+a list, then the sticky properties of the character are those whose
+names are in the list.  For example, if a character has a
+@code{front-sticky} property whose value is @code{(face read-only)},
+then insertion before the character can inherit its @code{face} property
+and its @code{read-only} property, but no others.
+
+  The @code{rear-nonsticky} property works the opposite way.  Most
+properties are rear-sticky by default, so the @code{rear-nonsticky}
+property says which properties are @emph{not} rear-sticky.  If a
+character's @code{rear-nonsticky} property is @code{t}, then none of its
+properties are rear-sticky.  If the @code{rear-nonsticky} property is a
+list, properties are rear-sticky @emph{unless} their names are in the
+list.
+
+@defvar text-property-default-nonsticky
+This variable holds an alist which defines the default rear-stickiness
+of various text properties.  Each element has the form
+@code{(@var{property} . @var{nonstickiness})}, and it defines the
+stickiness of a particular text property, @var{property}.
+
+If @var{nonstickiness} is non-@code{nil}, this means that the property
+@var{property} is rear-nonsticky by default.  Since all properties are
+front-nonsticky by default, this makes @var{property} nonsticky in both
+directions by default.
+
+The text properties @code{front-sticky} and @code{rear-nonsticky}, when
+used, take precedence over the default @var{nonstickiness} specified in
+@code{text-property-default-nonsticky}.
+@end defvar
+
+  Here are the functions that insert text with inheritance of properties:
+
+@defun insert-and-inherit &rest strings
+Insert the strings @var{strings}, just like the function @code{insert},
+but inherit any sticky properties from the adjoining text.
+@end defun
+
+@defun insert-before-markers-and-inherit &rest strings
+Insert the strings @var{strings}, just like the function
+@code{insert-before-markers}, but inherit any sticky properties from the
+adjoining text.
+@end defun
+
+  @xref{Insertion}, for the ordinary insertion functions which do not
+inherit.
+
+@node Lazy Properties
+@subsection Lazy Computation of Text Properties
+
+  Instead of computing text properties for all the text in the buffer,
+you can arrange to compute the text properties for parts of the text
+when and if something depends on them.
+
+  The primitive that extracts text from the buffer along with its
+properties is @code{buffer-substring}.  Before examining the properties,
+this function runs the abnormal hook @code{buffer-access-fontify-functions}.
+
+@defvar buffer-access-fontify-functions
+This variable holds a list of functions for computing text properties.
+Before @code{buffer-substring} copies the text and text properties for a
+portion of the buffer, it calls all the functions in this list.  Each of
+the functions receives two arguments that specify the range of the
+buffer being accessed.  (The buffer itself is always the current
+buffer.)
+@end defvar
+
+  The function @code{buffer-substring-no-properties} does not call these
+functions, since it ignores text properties anyway.
+
+  In order to prevent the hook functions from being called more than
+once for the same part of the buffer, you can use the variable
+@code{buffer-access-fontified-property}.
+
+@defvar buffer-access-fontified-property
+If this variable's value is non-@code{nil}, it is a symbol which is used
+as a text property name.  A non-@code{nil} value for that text property
+means, ``the other text properties for this character have already been
+computed.''
+
+If all the characters in the range specified for @code{buffer-substring}
+have a non-@code{nil} value for this property, @code{buffer-substring}
+does not call the @code{buffer-access-fontify-functions} functions.  It
+assumes these characters already have the right text properties, and
+just copies the properties they already have.
+
+The normal way to use this feature is that the
+@code{buffer-access-fontify-functions} functions add this property, as
+well as others, to the characters they operate on.  That way, they avoid
+being called over and over for the same text.
+@end defvar
+
+@node Clickable Text
+@subsection Defining Clickable Text
+@cindex clickable text
+
+  @dfn{Clickable text} is text that can be clicked, with either the
+the mouse or via keyboard commands, to produce some result.  Many
+major modes use clickable text to implement features such as
+hyper-links.  The @code{button} package provides an easy way to insert
+and manipulate clickable text.  @xref{Buttons}.
+
+  In this section, we will explain how to manually set up clickable
+text in a buffer using text properties.  This involves two things: (1)
+indicating clickability when the mouse moves over the text, and (2)
+making @kbd{RET} or a mouse click on that text do something.
+
+  Indicating clickability usually involves highlighting the text, and
+often involves displaying helpful information about the action, such
+as which mouse button to press, or a short summary of the action.
+This can be done with the @code{mouse-face} and @code{help-echo}
+text properties.  @xref{Special Properties}.
+Here is an example of how Dired does it:
+
+@smallexample
+(condition-case nil
+    (if (dired-move-to-filename)
+        (add-text-properties
+         (point)
+         (save-excursion
+           (dired-move-to-end-of-filename)
+           (point))
+         '(mouse-face highlight
+           help-echo "mouse-2: visit this file in other window")))
+  (error nil))
+@end smallexample
+
+@noindent
+The first two arguments to @code{add-text-properties} specify the
+beginning and end of the text.
+
+  The usual way to make the mouse do something when you click it
+on this text is to define @code{mouse-2} in the major mode's
+keymap.  The job of checking whether the click was on clickable text
+is done by the command definition.  Here is how Dired does it:
+
+@smallexample
+(defun dired-mouse-find-file-other-window (event)
+  "In Dired, visit the file or directory name you click on."
+  (interactive "e")
+  (let (window pos file)
+    (save-excursion
+      (setq window (posn-window (event-end event))
+            pos (posn-point (event-end event)))
+      (if (not (windowp window))
+          (error "No file chosen"))
+      (set-buffer (window-buffer window))
+      (goto-char pos)
+      (setq file (dired-get-file-for-visit)))
+    (if (file-directory-p file)
+        (or (and (cdr dired-subdir-alist)
+                 (dired-goto-subdir file))
+            (progn
+              (select-window window)
+              (dired-other-window file)))
+      (select-window window)
+      (find-file-other-window (file-name-sans-versions file t)))))
+@end smallexample
+
+@noindent
+The reason for the @code{save-excursion} construct is to avoid
+changing the current buffer.  In this case,
+Dired uses the functions @code{posn-window} and @code{posn-point}
+to determine which buffer the click happened in and where, and
+in that buffer, @code{dired-get-file-for-visit} to determine which
+file to visit.
+
+  Instead of defining a mouse command for the major mode, you can define
+a key binding for the clickable text itself, using the @code{keymap}
+text property:
+
+@example
+(let ((map (make-sparse-keymap)))
+  (define-key map [mouse-2] 'operate-this-button)
+  (put-text-property (point)
+                     (save-excursion
+                       (dired-move-to-end-of-filename)
+                       (point))
+                     'keymap map))
+@end example
+
+@noindent
+This method makes it possible to define different commands for various
+clickable pieces of text.  Also, the major mode definition (or the
+global definition) remains available for the rest of the text in the
+buffer.
+
+@node Links and Mouse-1
+@subsection Links and Mouse-1
+@cindex follow links
+@cindex mouse-1
+
+  The normal Emacs command for activating text in read-only buffers is
+@key{Mouse-2}, which includes following textual links.  However, most
+graphical applications use @key{Mouse-1} for following links.  For
+compatibility, @key{Mouse-1} follows links in Emacs too, when you
+click on a link quickly without moving the mouse.  The user can
+customize this behavior through the variable
+@code{mouse-1-click-follows-link}.
+
+  To define text as a link at the Lisp level, you should bind the
+@code{mouse-2} event to a command to follow the link.  Then, to indicate that
+@key{Mouse-1} should also follow the link, you should specify a
+@code{follow-link} condition either as a text property or as a key
+binding:
+
+@table @asis
+@item @code{follow-link} property
+If the clickable text has a non-@code{nil} @code{follow-link} text or overlay
+property, that specifies the condition.
+
+@item @code{follow-link} event
+If there is a binding for the @code{follow-link} event, either on the
+clickable text or in the local keymap, the binding is the condition.
+@end table
+
+  Regardless of how you set the @code{follow-link} condition, its
+value is used as follows to determine whether the given position is
+inside a link, and (if so) to compute an @dfn{action code} saying how
+@key{Mouse-1} should handle the link.
+
+@table @asis
+@item @code{mouse-face}
+If the condition is @code{mouse-face}, a position is inside a link if
+there is a non-@code{nil} @code{mouse-face} property at that position.
+The action code is always @code{t}.
+
+For example, here is how Info mode handles @key{Mouse-1}:
+
+@smallexample
+(define-key Info-mode-map [follow-link] 'mouse-face)
+@end smallexample
+
+@item a function
+If the condition is a valid function, @var{func}, then a position
+@var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates
+to non-@code{nil}.  The value returned by @var{func} serves as the
+action code.
+
+For example, here is how pcvs enables @key{Mouse-1} to follow links on
+file names only:
+
+@smallexample
+(define-key map [follow-link]
+  (lambda (pos)
+    (eq (get-char-property pos 'face) 'cvs-filename-face)))
+@end smallexample
+
+@item anything else
+If the condition value is anything else, then the position is inside a
+link and the condition itself is the action code.  Clearly you should
+only specify this kind of condition on the text that constitutes a
+link.
+@end table
+
+@noindent
+The action code tells @key{Mouse-1} how to follow the link:
+
+@table @asis
+@item a string or vector
+If the action code is a string or vector, the @key{Mouse-1} event is
+translated into the first element of the string or vector; i.e., the
+action of the @key{Mouse-1} click is the local or global binding of
+that character or symbol.  Thus, if the action code is @code{"foo"},
+@key{Mouse-1} translates into @kbd{f}.  If it is @code{[foo]},
+@key{Mouse-1} translates into @key{foo}.
+
+@item anything else
+For any other non-@code{nil} action code, the @code{mouse-1} event is
+translated into a @code{mouse-2} event at the same position.
+@end table
+
+  To define @key{Mouse-1} to activate a button defined with
+@code{define-button-type}, give the button a @code{follow-link}
+property with a value as specified above to determine how to follow
+the link.  For example, here is how Help mode handles @key{Mouse-1}:
+
+@smallexample
+(define-button-type 'help-xref
+  'follow-link t
+  'action #'help-button-action)
+@end smallexample
+
+  To define @key{Mouse-1} on a widget defined with
+@code{define-widget}, give the widget a @code{:follow-link} property
+with a value as specified above to determine how to follow the link.
+
+For example, here is how the @code{link} widget specifies that
+a @key{Mouse-1} click shall be translated to @key{RET}:
+
+@smallexample
+(define-widget 'link 'item
+  "An embedded link."
+  :button-prefix 'widget-link-prefix
+  :button-suffix 'widget-link-suffix
+  :follow-link "\C-m"
+  :help-echo "Follow the link."
+  :format "%[%t%]")
+@end smallexample
+
+@defun mouse-on-link-p pos
+This function returns non-@code{nil} if position @var{pos} in the
+current buffer is on a link.  @var{pos} can also be a mouse event
+location, as returned by @code{event-start} (@pxref{Accessing Events}).
+@end defun
+
+@node Fields
+@subsection Defining and Using Fields
+@cindex fields
+
+  A field is a range of consecutive characters in the buffer that are
+identified by having the same value (comparing with @code{eq}) of the
+@code{field} property (either a text-property or an overlay property).
+This section describes special functions that are available for
+operating on fields.
+
+  You specify a field with a buffer position, @var{pos}.  We think of
+each field as containing a range of buffer positions, so the position
+you specify stands for the field containing that position.
+
+  When the characters before and after @var{pos} are part of the same
+field, there is no doubt which field contains @var{pos}: the one those
+characters both belong to.  When @var{pos} is at a boundary between
+fields, which field it belongs to depends on the stickiness of the
+@code{field} properties of the two surrounding characters (@pxref{Sticky
+Properties}).  The field whose property would be inherited by text
+inserted at @var{pos} is the field that contains @var{pos}.
+
+  There is an anomalous case where newly inserted text at @var{pos}
+would not inherit the @code{field} property from either side.  This
+happens if the previous character's @code{field} property is not
+rear-sticky, and the following character's @code{field} property is not
+front-sticky.  In this case, @var{pos} belongs to neither the preceding
+field nor the following field; the field functions treat it as belonging
+to an empty field whose beginning and end are both at @var{pos}.
+
+  In all of these functions, if @var{pos} is omitted or @code{nil}, the
+value of point is used by default.  If narrowing is in effect, then
+@var{pos} should fall within the accessible portion.  @xref{Narrowing}.
+
+@defun field-beginning &optional pos escape-from-edge limit
+This function returns the beginning of the field specified by @var{pos}.
+
+If @var{pos} is at the beginning of its field, and
+@var{escape-from-edge} is non-@code{nil}, then the return value is
+always the beginning of the preceding field that @emph{ends} at @var{pos},
+regardless of the stickiness of the @code{field} properties around
+@var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the
+beginning of the field is before @var{limit}, then @var{limit} will be
+returned instead.
+@end defun
+
+@defun field-end &optional pos escape-from-edge limit
+This function returns the end of the field specified by @var{pos}.
+
+If @var{pos} is at the end of its field, and @var{escape-from-edge} is
+non-@code{nil}, then the return value is always the end of the following
+field that @emph{begins} at @var{pos}, regardless of the stickiness of
+the @code{field} properties around @var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the end
+of the field is after @var{limit}, then @var{limit} will be returned
+instead.
+@end defun
+
+@defun field-string &optional pos
+This function returns the contents of the field specified by @var{pos},
+as a string.
+@end defun
+
+@defun field-string-no-properties &optional pos
+This function returns the contents of the field specified by @var{pos},
+as a string, discarding text properties.
+@end defun
+
+@defun delete-field &optional pos
+This function deletes the text of the field specified by @var{pos}.
+@end defun
+
+@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
+This function ``constrains'' @var{new-pos} to the field that
+@var{old-pos} belongs to---in other words, it returns the position
+closest to @var{new-pos} that is in the same field as @var{old-pos}.
+
+If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
+the value of point instead, and moves point to the resulting position
+as well as returning it.
+
+If @var{old-pos} is at the boundary of two fields, then the acceptable
+final positions depend on the argument @var{escape-from-edge}.  If
+@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
+the field whose @code{field} property equals what new characters
+inserted at @var{old-pos} would inherit.  (This depends on the
+stickiness of the @code{field} property for the characters before and
+after @var{old-pos}.)  If @var{escape-from-edge} is non-@code{nil},
+@var{new-pos} can be anywhere in the two adjacent fields.
+Additionally, if two fields are separated by another field with the
+special value @code{boundary}, then any point within this special
+field is also considered to be ``on the boundary.''
+
+Commands like @kbd{C-a} with no argumemt, that normally move backward
+to a specific kind of location and stay there once there, probably
+should specify @code{nil} for @var{escape-from-edge}.  Other motion
+commands that check fields should probably pass @code{t}.
+
+If the optional argument @var{only-in-line} is non-@code{nil}, and
+constraining @var{new-pos} in the usual way would move it to a different
+line, @var{new-pos} is returned unconstrained.  This used in commands
+that move by line, such as @code{next-line} and
+@code{beginning-of-line}, so that they respect field boundaries only in
+the case where they can still move to the right line.
+
+If the optional argument @var{inhibit-capture-property} is
+non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
+name, then any field boundaries are ignored.
+
+You can cause @code{constrain-to-field} to ignore all field boundaries
+(and so never constrain anything) by binding the variable
+@code{inhibit-field-text-motion} to a non-@code{nil} value.
+@end defun
+
+@node Not Intervals
+@subsection Why Text Properties are not Intervals
+@cindex intervals
+
+  Some editors that support adding attributes to text in the buffer do
+so by letting the user specify ``intervals'' within the text, and adding
+the properties to the intervals.  Those editors permit the user or the
+programmer to determine where individual intervals start and end.  We
+deliberately provided a different sort of interface in Emacs Lisp to
+avoid certain paradoxical behavior associated with text modification.
+
+  If the actual subdivision into intervals is meaningful, that means you
+can distinguish between a buffer that is just one interval with a
+certain property, and a buffer containing the same text subdivided into
+two intervals, both of which have that property.
+
+  Suppose you take the buffer with just one interval and kill part of
+the text.  The text remaining in the buffer is one interval, and the
+copy in the kill ring (and the undo list) becomes a separate interval.
+Then if you yank back the killed text, you get two intervals with the
+same properties.  Thus, editing does not preserve the distinction
+between one interval and two.
+
+  Suppose we ``fix'' this problem by coalescing the two intervals when
+the text is inserted.  That works fine if the buffer originally was a
+single interval.  But suppose instead that we have two adjacent
+intervals with the same properties, and we kill the text of one interval
+and yank it back.  The same interval-coalescence feature that rescues
+the other case causes trouble in this one: after yanking, we have just
+one interval.  One again, editing does not preserve the distinction
+between one interval and two.
+
+  Insertion of text at the border between intervals also raises
+questions that have no satisfactory answer.
+
+  However, it is easy to arrange for editing to behave consistently for
+questions of the form, ``What are the properties of this character?''
+So we have decided these are the only questions that make sense; we have
+not implemented asking questions about where intervals start or end.
+
+  In practice, you can usually use the text property search functions in
+place of explicit interval boundaries.  You can think of them as finding
+the boundaries of intervals, assuming that intervals are always
+coalesced whenever possible.  @xref{Property Search}.
+
+  Emacs also provides explicit intervals as a presentation feature; see
+@ref{Overlays}.
+
+@node Substitution
+@section Substituting for a Character Code
+
+  The following functions replace characters within a specified region
+based on their character codes.
+
+@defun subst-char-in-region start end old-char new-char &optional noundo
+@cindex replace characters
+This function replaces all occurrences of the character @var{old-char}
+with the character @var{new-char} in the region of the current buffer
+defined by @var{start} and @var{end}.
+
+@cindex undo avoidance
+If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
+not record the change for undo and does not mark the buffer as modified.
+This was useful for controlling the old selective display feature
+(@pxref{Selective Display}).
+
+@code{subst-char-in-region} does not move point and returns
+@code{nil}.
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the contents of the buffer before.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(subst-char-in-region 1 20 ?i ?X)
+     @result{} nil
+
+---------- Buffer: foo ----------
+ThXs Xs the contents of the buffer before.
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defun
+
+@defun translate-region start end table
+This function applies a translation table to the characters in the
+buffer between positions @var{start} and @var{end}.
+
+The translation table @var{table} is a string or a char-table;
+@code{(aref @var{table} @var{ochar})} gives the translated character
+corresponding to @var{ochar}.  If @var{table} is a string, any
+characters with codes larger than the length of @var{table} are not
+altered by the translation.
+
+The return value of @code{translate-region} is the number of
+characters that were actually changed by the translation.  This does
+not count characters that were mapped into themselves in the
+translation table.
+@end defun
+
+@node Registers
+@section Registers
+@cindex registers
+
+  A register is a sort of variable used in Emacs editing that can hold a
+variety of different kinds of values.  Each register is named by a
+single character.  All @acronym{ASCII} characters and their meta variants
+(but with the exception of @kbd{C-g}) can be used to name registers.
+Thus, there are 255 possible registers.  A register is designated in
+Emacs Lisp by the character that is its name.
+
+@defvar register-alist
+This variable is an alist of elements of the form @code{(@var{name} .
+@var{contents})}.  Normally, there is one element for each Emacs
+register that has been used.
+
+The object @var{name} is a character (an integer) identifying the
+register.
+@end defvar
+
+  The @var{contents} of a register can have several possible types:
+
+@table @asis
+@item a number
+A number stands for itself.  If @code{insert-register} finds a number
+in the register, it converts the number to decimal.
+
+@item a marker
+A marker represents a buffer position to jump to.
+
+@item a string
+A string is text saved in the register.
+
+@item a rectangle
+A rectangle is represented by a list of strings.
+
+@item @code{(@var{window-configuration} @var{position})}
+This represents a window configuration to restore in one frame, and a
+position to jump to in the current buffer.
+
+@item @code{(@var{frame-configuration} @var{position})}
+This represents a frame configuration to restore, and a position
+to jump to in the current buffer.
+
+@item (file @var{filename})
+This represents a file to visit; jumping to this value visits file
+@var{filename}.
+
+@item (file-query @var{filename} @var{position})
+This represents a file to visit and a position in it; jumping to this
+value visits file @var{filename} and goes to buffer position
+@var{position}.  Restoring this type of position asks the user for
+confirmation first.
+@end table
+
+  The functions in this section return unpredictable values unless
+otherwise stated.
+
+@defun get-register reg
+This function returns the contents of the register
+@var{reg}, or @code{nil} if it has no contents.
+@end defun
+
+@defun set-register reg value
+This function sets the contents of register @var{reg} to @var{value}.
+A register can be set to any value, but the other register functions
+expect only certain data types.  The return value is @var{value}.
+@end defun
+
+@deffn Command view-register reg
+This command displays what is contained in register @var{reg}.
+@end deffn
+
+@ignore
+@deffn Command point-to-register reg
+This command stores both the current location of point and the current
+buffer in register @var{reg} as a marker.
+@end deffn
+
+@deffn Command jump-to-register reg
+@deffnx Command register-to-point reg
+@comment !!SourceFile register.el
+This command restores the status recorded in register @var{reg}.
+
+If @var{reg} contains a marker, it moves point to the position stored in
+the marker.  Since both the buffer and the location within the buffer
+are stored by the @code{point-to-register} function, this command can
+switch you to another buffer.
+
+If @var{reg} contains a window configuration or a frame configuration.
+@code{jump-to-register} restores that configuration.
+@end deffn
+@end ignore
+
+@deffn Command insert-register reg &optional beforep
+This command inserts contents of register @var{reg} into the current
+buffer.
+
+Normally, this command puts point before the inserted text, and the
+mark after it.  However, if the optional second argument @var{beforep}
+is non-@code{nil}, it puts the mark before and point after.
+You can pass a non-@code{nil} second argument @var{beforep} to this
+function interactively by supplying any prefix argument.
+
+If the register contains a rectangle, then the rectangle is inserted
+with its upper left corner at point.  This means that text is inserted
+in the current line and underneath it on successive lines.
+
+If the register contains something other than saved text (a string) or
+a rectangle (a list), currently useless things happen.  This may be
+changed in the future.
+@end deffn
+
+@ignore
+@deffn Command copy-to-register reg start end &optional delete-flag
+This command copies the region from @var{start} to @var{end} into
+register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it deletes
+the region from the buffer after copying it into the register.
+@end deffn
+
+@deffn Command prepend-to-register reg start end &optional delete-flag
+This command prepends the region from @var{start} to @var{end} into
+register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it deletes
+the region from the buffer after copying it to the register.
+@end deffn
+
+@deffn Command append-to-register reg start end &optional delete-flag
+This command appends the region from @var{start} to @var{end} to the
+text already in register @var{reg}.  If @var{delete-flag} is
+non-@code{nil}, it deletes the region from the buffer after copying it
+to the register.
+@end deffn
+
+@deffn Command copy-rectangle-to-register reg start end &optional delete-flag
+This command copies a rectangular region from @var{start} to @var{end}
+into register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it
+deletes the region from the buffer after copying it to the register.
+@end deffn
+
+@deffn Command window-configuration-to-register reg
+This function stores the window configuration of the selected frame in
+register @var{reg}.
+@end deffn
+
+@deffn Command frame-configuration-to-register reg
+This function stores the current frame configuration in register
+@var{reg}.
+@end deffn
+@end ignore
+
+@node Transposition
+@section Transposition of Text
+
+  This subroutine is used by the transposition commands.
+
+@defun transpose-regions start1 end1 start2 end2 &optional leave-markers
+This function exchanges two nonoverlapping portions of the buffer.
+Arguments @var{start1} and @var{end1} specify the bounds of one portion
+and arguments @var{start2} and @var{end2} specify the bounds of the
+other portion.
+
+Normally, @code{transpose-regions} relocates markers with the transposed
+text; a marker previously positioned within one of the two transposed
+portions moves along with that portion, thus remaining between the same
+two characters in their new position.  However, if @var{leave-markers}
+is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
+all markers unrelocated.
+@end defun
+
+@node Base 64
+@section Base 64 Encoding
+@cindex base 64 encoding
+
+  Base 64 code is used in email to encode a sequence of 8-bit bytes as
+a longer sequence of @acronym{ASCII} graphic characters.  It is defined in
+Internet RFC@footnote{
+An RFC, an acronym for @dfn{Request for Comments}, is a numbered
+Internet informational document describing a standard.  RFCs are
+usually written by technical experts acting on their own initiative,
+and are traditionally written in a pragmatic, experience-driven
+manner.
+}2045.  This section describes the functions for
+converting to and from this code.
+
+@defun base64-encode-region beg end &optional no-line-break
+This function converts the region from @var{beg} to @var{end} into base
+64 code.  It returns the length of the encoded text.  An error is
+signaled if a character in the region is multibyte, i.e.@: in a
+multibyte buffer the region must contain only characters from the
+charsets @code{ascii}, @code{eight-bit-control} and
+@code{eight-bit-graphic}.
+
+Normally, this function inserts newline characters into the encoded
+text, to avoid overlong lines.  However, if the optional argument
+@var{no-line-break} is non-@code{nil}, these newlines are not added, so
+the output is just one long line.
+@end defun
+
+@defun base64-encode-string string &optional no-line-break
+This function converts the string @var{string} into base 64 code.  It
+returns a string containing the encoded text.  As for
+@code{base64-encode-region}, an error is signaled if a character in the
+string is multibyte.
+
+Normally, this function inserts newline characters into the encoded
+text, to avoid overlong lines.  However, if the optional argument
+@var{no-line-break} is non-@code{nil}, these newlines are not added, so
+the result string is just one long line.
+@end defun
+
+@defun base64-decode-region beg end
+This function converts the region from @var{beg} to @var{end} from base
+64 code into the corresponding decoded text.  It returns the length of
+the decoded text.
+
+The decoding functions ignore newline characters in the encoded text.
+@end defun
+
+@defun base64-decode-string string
+This function converts the string @var{string} from base 64 code into
+the corresponding decoded text.  It returns a unibyte string containing the
+decoded text.
+
+The decoding functions ignore newline characters in the encoded text.
+@end defun
+
+@node MD5 Checksum
+@section MD5 Checksum
+@cindex MD5 checksum
+@cindex message digest computation
+
+  MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
+``fingerprints'' of a document or program.  They are used to verify
+that you have an exact and unaltered copy of the data.  The algorithm
+to calculate the MD5 message digest is defined in Internet
+RFC@footnote{
+For an explanation of what is an RFC, see the footnote in @ref{Base
+64}.
+}1321.  This section describes the Emacs facilities for computing
+message digests.
+
+@defun md5 object &optional start end coding-system noerror
+This function returns the MD5 message digest of @var{object}, which
+should be a buffer or a string.
+
+The two optional arguments @var{start} and @var{end} are character
+positions specifying the portion of @var{object} to compute the
+message digest for.  If they are @code{nil} or omitted, the digest is
+computed for the whole of @var{object}.
+
+The function @code{md5} does not compute the message digest directly
+from the internal Emacs representation of the text (@pxref{Text
+Representations}).  Instead, it encodes the text using a coding
+system, and computes the message digest from the encoded text.  The
+optional fourth argument @var{coding-system} specifies which coding
+system to use for encoding the text.  It should be the same coding
+system that you used to read the text, or that you used or will use
+when saving or sending the text.  @xref{Coding Systems}, for more
+information about coding systems.
+
+If @var{coding-system} is @code{nil} or omitted, the default depends
+on @var{object}.  If @var{object} is a buffer, the default for
+@var{coding-system} is whatever coding system would be chosen by
+default for writing this text into a file.  If @var{object} is a
+string, the user's most preferred coding system (@pxref{Recognize
+Coding, prefer-coding-system, the description of
+@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
+
+Normally, @code{md5} signals an error if the text can't be encoded
+using the specified or chosen coding system.  However, if
+@var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
+coding instead.
+@end defun
+
+@node Atomic Changes
+@section Atomic Change Groups
+@cindex atomic changes
+
+  In data base terminology, an @dfn{atomic} change is an indivisible
+change---it can succeed entirely or it can fail entirely, but it
+cannot partly succeed.  A Lisp program can make a series of changes to
+one or several buffers as an @dfn{atomic change group}, meaning that
+either the entire series of changes will be installed in their buffers
+or, in case of an error, none of them will be.
+
+  To do this for one buffer, the one already current, simply write a
+call to @code{atomic-change-group} around the code that makes the
+changes, like this:
+
+@example
+(atomic-change-group
+  (insert foo)
+  (delete-region x y))
+@end example
+
+@noindent
+If an error (or other nonlocal exit) occurs inside the body of
+@code{atomic-change-group}, it unmakes all the changes in that buffer
+that were during the execution of the body.  This kind of change group
+has no effect on any other buffers---any such changes remain.
+
+  If you need something more sophisticated, such as to make changes in
+various buffers constitute one atomic group, you must directly call
+lower-level functions that @code{atomic-change-group} uses.
+
+@defun prepare-change-group &optional buffer
+This function sets up a change group for buffer @var{buffer}, which
+defaults to the current buffer.  It returns a ``handle'' that
+represents the change group.  You must use this handle to activate the
+change group and subsequently to finish it.
+@end defun
+
+  To use the change group, you must @dfn{activate} it.  You must do
+this before making any changes in the text of @var{buffer}.
+
+@defun activate-change-group handle
+This function activates the change group that @var{handle} designates.
+@end defun
+
+  After you activate the change group, any changes you make in that
+buffer become part of it.  Once you have made all the desired changes
+in the buffer, you must @dfn{finish} the change group.  There are two
+ways to do this: you can either accept (and finalize) all the changes,
+or cancel them all.
+
+@defun accept-change-group handle
+This function accepts all the changes in the change group specified by
+@var{handle}, making them final.
+@end defun
+
+@defun cancel-change-group handle
+This function cancels and undoes all the changes in the change group
+specified by @var{handle}.
+@end defun
+
+  Your code should use @code{unwind-protect} to make sure the group is
+always finished.  The call to @code{activate-change-group} should be
+inside the @code{unwind-protect}, in case the user types @kbd{C-g}
+just after it runs.  (This is one reason why
+@code{prepare-change-group} and @code{activate-change-group} are
+separate functions, because normally you would call
+@code{prepare-change-group} before the start of that
+@code{unwind-protect}.)  Once you finish the group, don't use the
+handle again---in particular, don't try to finish the same group
+twice.
+
+  To make a multibuffer change group, call @code{prepare-change-group}
+once for each buffer you want to cover, then use @code{nconc} to
+combine the returned values, like this:
+
+@example
+(nconc (prepare-change-group buffer-1)
+       (prepare-change-group buffer-2))
+@end example
+
+You can then activate the multibuffer change group with a single call
+to @code{activate-change-group}, and finish it with a single call to
+@code{accept-change-group} or @code{cancel-change-group}.
+
+  Nested use of several change groups for the same buffer works as you
+would expect.  Non-nested use of change groups for the same buffer
+will get Emacs confused, so don't let it happen; the first change
+group you start for any given buffer should be the last one finished.
+
+@node Change Hooks
+@section Change Hooks
+@cindex change hooks
+@cindex hooks for text changes
+
+  These hook variables let you arrange to take notice of all changes in
+all buffers (or in a particular buffer, if you make them buffer-local).
+See also @ref{Special Properties}, for how to detect changes to specific
+parts of the text.
+
+  The functions you use in these hooks should save and restore the match
+data if they do anything that uses regular expressions; otherwise, they
+will interfere in bizarre ways with the editing operations that call
+them.
+
+@defvar before-change-functions
+This variable holds a list of functions to call before any buffer
+modification.  Each function gets two arguments, the beginning and end
+of the region that is about to change, represented as integers.  The
+buffer that is about to change is always the current buffer.
+@end defvar
+
+@defvar after-change-functions
+This variable holds a list of functions to call after any buffer
+modification.  Each function receives three arguments: the beginning and
+end of the region just changed, and the length of the text that existed
+before the change.  All three arguments are integers.  The buffer that's
+about to change is always the current buffer.
+
+The length of the old text is the difference between the buffer positions
+before and after that text as it was before the change.  As for the
+changed text, its length is simply the difference between the first two
+arguments.
+@end defvar
+
+  Output of messages into the @samp{*Messages*} buffer does not
+call these functions.
+
+@defmac combine-after-change-calls body@dots{}
+The macro executes @var{body} normally, but arranges to call the
+after-change functions just once for a series of several changes---if
+that seems safe.
+
+If a program makes several text changes in the same area of the buffer,
+using the macro @code{combine-after-change-calls} around that part of
+the program can make it run considerably faster when after-change hooks
+are in use.  When the after-change hooks are ultimately called, the
+arguments specify a portion of the buffer including all of the changes
+made within the @code{combine-after-change-calls} body.
+
+@strong{Warning:} You must not alter the values of
+@code{after-change-functions} within
+the body of a @code{combine-after-change-calls} form.
+
+@strong{Warning:} if the changes you combine occur in widely scattered
+parts of the buffer, this will still work, but it is not advisable,
+because it may lead to inefficient behavior for some change hook
+functions.
+@end defmac
+
+@defvar first-change-hook
+This variable is a normal hook that is run whenever a buffer is changed
+that was previously in the unmodified state.
+@end defvar
+
+@defvar inhibit-modification-hooks
+If this variable is non-@code{nil}, all of the change hooks are
+disabled; none of them run.  This affects all the hook variables
+described above in this section, as well as the hooks attached to
+certain special text properties (@pxref{Special Properties}) and overlay
+properties (@pxref{Overlay Properties}).
+
+Also, this variable is bound to non-@code{nil} while running those
+same hook variables, so that by default modifying the buffer from
+a modification hook does not cause other modification hooks to be run.
+If you do want modification hooks to be run in a particular piece of
+code that is itself run from a modification hook, then rebind locally
+@code{inhibit-modification-hooks} to @code{nil}.
+@end defvar
+
+@ignore
+   arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
+@end ignore
diff --git a/doc/lispref/tindex.pl b/doc/lispref/tindex.pl
new file mode 100755
index 00000000000..89bbe5f5f6f
--- /dev/null
+++ b/doc/lispref/tindex.pl
@@ -0,0 +1,127 @@
+#! /usr/bin/perl
+
+# Copyright (C) 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.
+
+require 5;
+use Getopt::Long;
+
+my $USAGE = <<ENDUSAGE;
+Remove \@tindex lines from files that were already present in previous
+versions.
+
+Usage: $0 [--old=EXT] FILE...
+       $0 --help
+       $0 --version
+
+  --help	display this help and exit
+  --version	print version and exit
+  --old=DIR	find old files in DIR
+
+The script performs two passes.  In the first pass, Texinfo files from
+DIR are scanned for \@tindex lines, and identifiers in them are
+recorded.  In a second pass, Texinfo files in the current directory
+are scanned, and \@tindex lines for identifiers that were recorded in
+the first pass are removed.  Old file contents are saved in files
+with extension ".orig".  A list of modified files and removed \@tindex
+identifiers is printed to stdout at the end.
+ENDUSAGE
+
+sub fatal {
+    print STDERR "$0: ", @_, ".\n";
+    exit 1;
+}
+
+my $help = 0;
+my $version = 0;
+my $old;
+
+my $rc = GetOptions ('help' => \$help, 'version' => \$version,
+                     'old=s' => \$old);
+if ($version) {
+    print "0.1\n";
+    exit 0;
+} elsif (!$rc || !$old || @ARGV) {
+    print $USAGE;
+    exit 1;
+} elsif ($help) {
+    print $USAGE;
+    exit 0;
+}
+
+# Fill the hash %tindex with associations VAR -> COUNT where
+# the keys VAR are identifiers mentioned in @tindex lines in the older
+# files to process and COUNT is the number of times they are seen in
+# the files.
+
+my %tindex;
+my %removed;
+my @old_files = glob "$old/*.texi";
+my @new_files = glob "*.texi";
+fatal ("No Texinfo files found in `$old'") unless @old_files;
+fatal ("No Texinfo files found in current directory") unless @new_files;
+
+print "Scanning old files for \@tindex lines\n";
+foreach $file (@old_files) {
+    open (IN, "<$file") or fatal "Cannot open $file: $!";
+    while (<IN>) {
+	++$tindex{$1} if /^\s*\@tindex\s+(\S+)/;
+    }
+    close IN;
+}
+
+# Process current files and remove those @tindex lines which we
+# know were already present in the files scanned above.
+
+print "Removing old \@tindex lines\n";
+foreach $file (@new_files) {
+    my $modified = 0;
+    my $contents = "";
+
+    open (IN, "< $file") or fatal "Cannot open $file.orig for reading: $!";
+    while (<IN>) {
+	if (/^\s*\@tindex\s+(\S+)/ && $tindex{$1}) {
+	    ++$removed{$1};
+	    $modified = 1;
+	} else {
+	    $contents = $contents . $_;
+	}
+    }
+
+    close IN;
+
+    if ($modified) {
+	print "  $file\n";
+	system ("cp $file $file.orig") == 0 or fatal "Cannot backup $file: $!";
+	open (OUT, ">$file") or fatal "Cannot open $file for writing: $!";
+	print OUT $contents;
+	close OUT;
+    }
+}
+
+# Print a list of identifiers removed.
+
+print "Removed \@tindex commands for:\n";
+my $key;
+foreach $key (keys %removed) {
+    print "  $key\n";
+}
+
+# arch-tag: f8460df6-6bef-4c98-8555-e2c63a88b0fa
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
new file mode 100644
index 00000000000..f3070f4659b
--- /dev/null
+++ b/doc/lispref/tips.texi
@@ -0,0 +1,1130 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/tips
+@node Tips, GNU Emacs Internals, GPL, Top
+@appendix Tips and Conventions
+@cindex tips for writing Lisp
+@cindex standards of coding style
+@cindex coding standards
+
+  This chapter describes no additional features of Emacs Lisp.  Instead
+it gives advice on making effective use of the features described in the
+previous chapters, and describes conventions Emacs Lisp programmers
+should follow.
+
+  You can automatically check some of the conventions described below by
+running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
+It cannot check all of the conventions, and not all the warnings it
+gives necessarily correspond to problems, but it is worth examining them
+all.
+
+@menu
+* Coding Conventions::        Conventions for clean and robust programs.
+* Key Binding Conventions::   Which keys should be bound by which programs.
+* Programming Tips::          Making Emacs code fit smoothly in Emacs.
+* Compilation Tips::          Making compiled code run fast.
+* Warning Tips::              Turning off compiler warnings.
+* Documentation Tips::        Writing readable documentation strings.
+* Comment Tips::	      Conventions for writing comments.
+* Library Headers::           Standard headers for library packages.
+@end menu
+
+@node Coding Conventions
+@section Emacs Lisp Coding Conventions
+
+@cindex coding conventions in Emacs Lisp
+  Here are conventions that you should follow when writing Emacs Lisp
+code intended for widespread use:
+
+@itemize @bullet
+@item
+Simply loading the package should not change Emacs's editing behavior.
+Include a command or commands to enable and disable the feature,
+or to invoke it.
+
+This convention is mandatory for any file that includes custom
+definitions.  If fixing such a file to follow this convention requires
+an incompatible change, go ahead and make the incompatible change;
+don't postpone it.
+
+@item
+Since all global variables share the same name space, and all
+functions share another name space, you should choose a short word to
+distinguish your program from other Lisp programs@footnote{The
+benefits of a Common Lisp-style package system are considered not to
+outweigh the costs.}.  Then take care to begin the names of all global
+variables, constants, and functions in your program with the chosen
+prefix.  This helps avoid name conflicts.
+
+Occasionally, for a command name intended for users to use, it is more
+convenient if some words come before the package's name prefix.  And
+constructs that define functions, variables, etc., work better if they
+start with @samp{defun} or @samp{defvar}, so put the name prefix later
+on in the name.
+
+This recommendation applies even to names for traditional Lisp
+primitives that are not primitives in Emacs Lisp---such as
+@code{copy-list}.  Believe it or not, there is more than one plausible
+way to define @code{copy-list}.  Play it safe; append your name prefix
+to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
+instead.
+
+If you write a function that you think ought to be added to Emacs under
+a certain name, such as @code{twiddle-files}, don't call it by that name
+in your program.  Call it @code{mylib-twiddle-files} in your program,
+and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
+it to Emacs.  If and when we do, we can change the name easily enough.
+
+If one prefix is insufficient, your package can use two or three
+alternative common prefixes, so long as they make sense.
+
+Separate the prefix from the rest of the symbol name with a hyphen,
+@samp{-}.  This will be consistent with Emacs itself and with most Emacs
+Lisp programs.
+
+@item
+Put a call to @code{provide} at the end of each separate Lisp file.
+
+@item
+If a file requires certain other Lisp programs to be loaded
+beforehand, then the comments at the beginning of the file should say
+so.  Also, use @code{require} to make sure they are loaded.
+
+@item
+If one file @var{foo} uses a macro defined in another file @var{bar},
+@var{foo} should contain this expression before the first use of the
+macro:
+
+@example
+(eval-when-compile (require '@var{bar}))
+@end example
+
+@noindent
+(And the library @var{bar} should contain @code{(provide '@var{bar})},
+to make the @code{require} work.)  This will cause @var{bar} to be
+loaded when you byte-compile @var{foo}.  Otherwise, you risk compiling
+@var{foo} without the necessary macro loaded, and that would produce
+compiled code that won't work right.  @xref{Compiling Macros}.
+
+Using @code{eval-when-compile} avoids loading @var{bar} when
+the compiled version of @var{foo} is @emph{used}.
+
+@item
+Please don't require the @code{cl} package of Common Lisp extensions at
+run time.  Use of this package is optional, and it is not part of the
+standard Emacs namespace.  If your package loads @code{cl} at run time,
+that could cause name clashes for users who don't use that package.
+
+However, there is no problem with using the @code{cl} package at
+compile time, with @code{(eval-when-compile (require 'cl))}.  That's
+sufficient for using the macros in the @code{cl} package, because the
+compiler expands them before generating the byte-code.
+
+@item
+When defining a major mode, please follow the major mode
+conventions.  @xref{Major Mode Conventions}.
+
+@item
+When defining a minor mode, please follow the minor mode
+conventions.  @xref{Minor Mode Conventions}.
+
+@item
+If the purpose of a function is to tell you whether a certain condition
+is true or false, give the function a name that ends in @samp{p}.  If
+the name is one word, add just @samp{p}; if the name is multiple words,
+add @samp{-p}.  Examples are @code{framep} and @code{frame-live-p}.
+
+@item
+If a user option variable records a true-or-false condition, give it a
+name that ends in @samp{-flag}.
+
+@item
+If the purpose of a variable is to store a single function, give it a
+name that ends in @samp{-function}.  If the purpose of a variable is
+to store a list of functions (i.e., the variable is a hook), please
+follow the naming conventions for hooks.  @xref{Hooks}.
+
+@item
+@cindex unloading packages, preparing for
+If loading the file adds functions to hooks, define a function
+@code{@var{feature}-unload-hook}, where @var{feature} is the name of
+the feature the package provides, and make it undo any such changes.
+Using @code{unload-feature} to unload the file will run this function.
+@xref{Unloading}.
+
+@item
+It is a bad idea to define aliases for the Emacs primitives.  Normally
+you should use the standard names instead.  The case where an alias
+may be useful is where it facilitates backwards compatibility or
+portability.
+
+@item
+If a package needs to define an alias or a new function for
+compatibility with some other version of Emacs, name it with the package
+prefix, not with the raw name with which it occurs in the other version.
+Here is an example from Gnus, which provides many examples of such
+compatibility issues.
+
+@example
+(defalias 'gnus-point-at-bol
+  (if (fboundp 'point-at-bol)
+      'point-at-bol
+    'line-beginning-position))
+@end example
+
+@item
+Redefining (or advising) an Emacs primitive is a bad idea.  It may do
+the right thing for a particular program, but there is no telling what
+other programs might break as a result.  In any case, it is a problem
+for debugging, because the advised function doesn't do what its source
+code says it does.  If the programmer investigating the problem is
+unaware that there is advice on the function, the experience can be
+very frustrating.
+
+We hope to remove all the places in Emacs that advise primitives.
+In the mean time, please don't add any more.
+
+@item
+It is likewise a bad idea for one Lisp package to advise a function
+in another Lisp package.
+
+@item
+Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
+Loading}) in libraries and packages.  This feature is meant for
+personal customizations; using it in a Lisp program is unclean,
+because it modifies the behavior of another Lisp file in a way that's
+not visible in that file.  This is an obstacle for debugging, much
+like advising a function in the other package.
+
+@item
+If a file does replace any of the functions or library programs of
+standard Emacs, prominent comments at the beginning of the file should
+say which functions are replaced, and how the behavior of the
+replacements differs from that of the originals.
+
+@item
+Constructs that define a function or variable should be macros,
+not functions, and their names should start with @samp{def}.
+
+@item
+A macro that defines a function or variable should have a name that
+starts with @samp{define-}.  The macro should receive the name to be
+defined as the first argument.  That will help various tools find the
+definition automatically.  Avoid constructing the names in the macro
+itself, since that would confuse these tools.
+
+@item
+Please keep the names of your Emacs Lisp source files to 13 characters
+or less.  This way, if the files are compiled, the compiled files' names
+will be 14 characters or less, which is short enough to fit on all kinds
+of Unix systems.
+
+@item
+In some other systems there is a convention of choosing variable names
+that begin and end with @samp{*}.  We don't use that convention in Emacs
+Lisp, so please don't use it in your programs.  (Emacs uses such names
+only for special-purpose buffers.)  The users will find Emacs more
+coherent if all libraries use the same conventions.
+
+@item
+If your program contains non-ASCII characters in string or character
+constants, you should make sure Emacs always decodes these characters
+the same way, regardless of the user's settings.  There are two ways
+to do that:
+
+@itemize -
+@item
+Use coding system @code{emacs-mule}, and specify that for
+@code{coding} in the @samp{-*-} line or the local variables list.
+
+@example
+;; XXX.el  -*- coding: emacs-mule; -*-
+@end example
+
+@item
+Use one of the coding systems based on ISO 2022 (such as
+iso-8859-@var{n} and iso-2022-7bit), and specify it with @samp{!} at
+the end for @code{coding}.  (The @samp{!} turns off any possible
+character translation.)
+
+@example
+;; XXX.el -*- coding: iso-latin-2!; -*-
+@end example
+@end itemize
+
+@item
+Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
+default indentation parameters.
+
+@item
+Don't make a habit of putting close-parentheses on lines by themselves;
+Lisp programmers find this disconcerting.  Once in a while, when there
+is a sequence of many consecutive close-parentheses, it may make sense
+to split the sequence in one or two significant places.
+
+@item
+Please put a copyright notice and copying permission notice on the
+file if you distribute copies.  Use a notice like this one:
+
+@smallexample
+;; Copyright (C) @var{year} @var{name}
+
+;; 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
+
+If you have signed papers to assign the copyright to the Foundation,
+then use @samp{Free Software Foundation, Inc.} as @var{name}.
+Otherwise, use your name.  See also @xref{Library Headers}.
+@end itemize
+
+@node Key Binding Conventions
+@section Key Binding Conventions
+@cindex key binding, conventions for
+
+@itemize @bullet
+@item
+@cindex mouse-2
+@cindex references, following
+Special major modes used for read-only text should usually redefine
+@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
+Modes such as Dired, Info, Compilation, and Occur redefine it in this
+way.
+
+In addition, they should mark the text as a kind of ``link'' so that
+@kbd{mouse-1} will follow it also.  @xref{Links and Mouse-1}.
+
+@item
+@cindex reserved keys
+@cindex keys, reserved
+Please do not define @kbd{C-c @var{letter}} as a key in Lisp programs.
+Sequences consisting of @kbd{C-c} and a letter (either upper or lower
+case) are reserved for users; they are the @strong{only} sequences
+reserved for users, so do not block them.
+
+Changing all the Emacs major modes to respect this convention was a
+lot of work; abandoning this convention would make that work go to
+waste, and inconvenience users.  Please comply with it.
+
+@item
+Function keys @key{F5} through @key{F9} without modifier keys are
+also reserved for users to define.
+
+@item
+Applications should not bind mouse events based on button 1 with the
+shift key held down.  These events include @kbd{S-mouse-1},
+@kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on.  They are reserved for
+users.
+
+@item
+Sequences consisting of @kbd{C-c} followed by a control character or a
+digit are reserved for major modes.
+
+@item
+Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
+@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
+
+@item
+Sequences consisting of @kbd{C-c} followed by any other punctuation
+character are allocated for minor modes.  Using them in a major mode is
+not absolutely prohibited, but if you do that, the major mode binding
+may be shadowed from time to time by minor modes.
+
+@item
+Do not bind @kbd{C-h} following any prefix character (including
+@kbd{C-c}).  If you don't bind @kbd{C-h}, it is automatically available
+as a help character for listing the subcommands of the prefix character.
+
+@item
+Do not bind a key sequence ending in @key{ESC} except following
+another @key{ESC}.  (That is, it is OK to bind a sequence ending in
+@kbd{@key{ESC} @key{ESC}}.)
+
+The reason for this rule is that a non-prefix binding for @key{ESC} in
+any context prevents recognition of escape sequences as function keys in
+that context.
+
+@item
+Anything which acts like a temporary mode or state which the user can
+enter and leave should define @kbd{@key{ESC} @key{ESC}} or
+@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
+
+For a state which accepts ordinary Emacs commands, or more generally any
+kind of state in which @key{ESC} followed by a function key or arrow key
+is potentially meaningful, then you must not define @kbd{@key{ESC}
+@key{ESC}}, since that would preclude recognizing an escape sequence
+after @key{ESC}.  In these states, you should define @kbd{@key{ESC}
+@key{ESC} @key{ESC}} as the way to escape.  Otherwise, define
+@kbd{@key{ESC} @key{ESC}} instead.
+@end itemize
+
+@node Programming Tips
+@section Emacs Programming Tips
+@cindex programming conventions
+
+  Following these conventions will make your program fit better
+into Emacs when it runs.
+
+@itemize @bullet
+@item
+Don't use @code{next-line} or @code{previous-line} in programs; nearly
+always, @code{forward-line} is more convenient as well as more
+predictable and robust.  @xref{Text Lines}.
+
+@item
+Don't call functions that set the mark, unless setting the mark is one
+of the intended features of your program.  The mark is a user-level
+feature, so it is incorrect to change the mark except to supply a value
+for the user's benefit.  @xref{The Mark}.
+
+In particular, don't use any of these functions:
+
+@itemize @bullet
+@item
+@code{beginning-of-buffer}, @code{end-of-buffer}
+@item
+@code{replace-string}, @code{replace-regexp}
+@item
+@code{insert-file}, @code{insert-buffer}
+@end itemize
+
+If you just want to move point, or replace a certain string, or insert
+a file or buffer's contents, without any of the other features
+intended for interactive users, you can replace these functions with
+one or two lines of simple Lisp code.
+
+@item
+Use lists rather than vectors, except when there is a particular reason
+to use a vector.  Lisp has more facilities for manipulating lists than
+for vectors, and working with lists is usually more convenient.
+
+Vectors are advantageous for tables that are substantial in size and are
+accessed in random order (not searched front to back), provided there is
+no need to insert or delete elements (only lists allow that).
+
+@item
+The recommended way to show a message in the echo area is with
+the @code{message} function, not @code{princ}.  @xref{The Echo Area}.
+
+@item
+When you encounter an error condition, call the function @code{error}
+(or @code{signal}).  The function @code{error} does not return.
+@xref{Signaling Errors}.
+
+Do not use @code{message}, @code{throw}, @code{sleep-for},
+or @code{beep} to report errors.
+
+@item
+An error message should start with a capital letter but should not end
+with a period.
+
+@item
+A question asked in the minibuffer with @code{y-or-n-p} or
+@code{yes-or-no-p} should start with a capital letter and end with
+@samp{? }.
+
+@item
+When you mention a default value in a minibuffer prompt,
+put it and the word @samp{default} inside parentheses.
+It should look like this:
+
+@example
+Enter the answer (default 42):
+@end example
+
+@item
+In @code{interactive}, if you use a Lisp expression to produce a list
+of arguments, don't try to provide the ``correct'' default values for
+region or position arguments.  Instead, provide @code{nil} for those
+arguments if they were not specified, and have the function body
+compute the default value when the argument is @code{nil}.  For
+instance, write this:
+
+@example
+(defun foo (pos)
+  (interactive
+   (list (if @var{specified} @var{specified-pos})))
+  (unless pos (setq pos @var{default-pos}))
+  ...)
+@end example
+
+@noindent
+rather than this:
+
+@example
+(defun foo (pos)
+  (interactive
+   (list (if @var{specified} @var{specified-pos}
+             @var{default-pos})))
+  ...)
+@end example
+
+@noindent
+This is so that repetition of the command will recompute
+these defaults based on the current circumstances.
+
+You do not need to take such precautions when you use interactive
+specs @samp{d}, @samp{m} and @samp{r}, because they make special
+arrangements to recompute the argument values on repetition of the
+command.
+
+@item
+Many commands that take a long time to execute display a message that
+says something like @samp{Operating...} when they start, and change it to
+@samp{Operating...done} when they finish.  Please keep the style of
+these messages uniform: @emph{no} space around the ellipsis, and
+@emph{no} period after @samp{done}.
+
+@item
+Try to avoid using recursive edits.  Instead, do what the Rmail @kbd{e}
+command does: use a new local keymap that contains one command defined
+to switch back to the old local keymap.  Or do what the
+@code{edit-options} command does: switch to another buffer and let the
+user switch back at will.  @xref{Recursive Editing}.
+@end itemize
+
+@node Compilation Tips
+@section Tips for Making Compiled Code Fast
+@cindex execution speed
+@cindex speedups
+
+  Here are ways of improving the execution speed of byte-compiled
+Lisp programs.
+
+@itemize @bullet
+@item
+@cindex profiling
+@cindex timing programs
+@cindex @file{elp.el}
+Profile your program with the @file{elp} library.  See the file
+@file{elp.el} for instructions.
+
+@item
+@cindex @file{benchmark.el}
+@cindex benchmarking
+Check the speed of individual Emacs Lisp forms using the
+@file{benchmark} library.  See the functions @code{benchmark-run} and
+@code{benchmark-run-compiled} in @file{benchmark.el}.
+
+@item
+Use iteration rather than recursion whenever possible.
+Function calls are slow in Emacs Lisp even when a compiled function
+is calling another compiled function.
+
+@item
+Using the primitive list-searching functions @code{memq}, @code{member},
+@code{assq}, or @code{assoc} is even faster than explicit iteration.  It
+can be worth rearranging a data structure so that one of these primitive
+search functions can be used.
+
+@item
+Certain built-in functions are handled specially in byte-compiled code,
+avoiding the need for an ordinary function call.  It is a good idea to
+use these functions rather than alternatives.  To see whether a function
+is handled specially by the compiler, examine its @code{byte-compile}
+property.  If the property is non-@code{nil}, then the function is
+handled specially.
+
+For example, the following input will show you that @code{aref} is
+compiled specially (@pxref{Array Functions}):
+
+@example
+@group
+(get 'aref 'byte-compile)
+     @result{} byte-compile-two-args
+@end group
+@end example
+
+@item
+If calling a small function accounts for a substantial part of your
+program's running time, make the function inline.  This eliminates
+the function call overhead.  Since making a function inline reduces
+the flexibility of changing the program, don't do it unless it gives
+a noticeable speedup in something slow enough that users care about
+the speed.  @xref{Inline Functions}.
+@end itemize
+
+@node Warning Tips
+@section Tips for Avoiding Compiler Warnings
+@cindex byte compiler warnings, how to avoid
+
+@itemize @bullet
+@item
+Try to avoid compiler warnings about undefined free variables, by adding
+dummy @code{defvar} definitions for these variables, like this:
+
+@example
+(defvar foo)
+@end example
+
+Such a definition has no effect except to tell the compiler
+not to warn about uses of the variable @code{foo} in this file.
+
+@item
+If you use many functions and variables from a certain file, you can
+add a @code{require} for that package to avoid compilation warnings
+for them.  For instance,
+
+@example
+(eval-when-compile
+  (require 'foo))
+@end example
+
+@item
+If you bind a variable in one function, and use it or set it in
+another function, the compiler warns about the latter function unless
+the variable has a definition.  But adding a definition would be
+unclean if the variable has a short name, since Lisp packages should
+not define short variable names.  The right thing to do is to rename
+this variable to start with the name prefix used for the other
+functions and variables in your package.
+
+@item
+The last resort for avoiding a warning, when you want to do something
+that usually is a mistake but it's not a mistake in this one case,
+is to put a call to @code{with-no-warnings} around it.
+@end itemize
+
+@node Documentation Tips
+@section Tips for Documentation Strings
+@cindex documentation strings, conventions and tips
+
+@findex checkdoc-minor-mode
+  Here are some tips and conventions for the writing of documentation
+strings.  You can check many of these conventions by running the command
+@kbd{M-x checkdoc-minor-mode}.
+
+@itemize @bullet
+@item
+Every command, function, or variable intended for users to know about
+should have a documentation string.
+
+@item
+An internal variable or subroutine of a Lisp program might as well have
+a documentation string.  In earlier Emacs versions, you could save space
+by using a comment instead of a documentation string, but that is no
+longer the case---documentation strings now take up very little space in
+a running Emacs.
+
+@item
+Format the documentation string so that it fits in an Emacs window on an
+80-column screen.  It is a good idea for most lines to be no wider than
+60 characters.  The first line should not be wider than 67 characters
+or it will look bad in the output of @code{apropos}.
+
+You can fill the text if that looks good.  However, rather than blindly
+filling the entire documentation string, you can often make it much more
+readable by choosing certain line breaks with care.  Use blank lines
+between topics if the documentation string is long.
+
+@item
+The first line of the documentation string should consist of one or two
+complete sentences that stand on their own as a summary.  @kbd{M-x
+apropos} displays just the first line, and if that line's contents don't
+stand on their own, the result looks bad.  In particular, start the
+first line with a capital letter and end with a period.
+
+For a function, the first line should briefly answer the question,
+``What does this function do?''  For a variable, the first line should
+briefly answer the question, ``What does this value mean?''
+
+Don't limit the documentation string to one line; use as many lines as
+you need to explain the details of how to use the function or
+variable.  Please use complete sentences for the rest of the text too.
+
+@item
+When the user tries to use a disabled command, Emacs displays just the
+first paragraph of its documentation string---everything through the
+first blank line.  If you wish, you can choose which information to
+include before the first blank line so as to make this display useful.
+
+@item
+The first line should mention all the important arguments of the
+function, and should mention them in the order that they are written
+in a function call.  If the function has many arguments, then it is
+not feasible to mention them all in the first line; in that case, the
+first line should mention the first few arguments, including the most
+important arguments.
+
+@item
+When a function's documentation string mentions the value of an argument
+of the function, use the argument name in capital letters as if it were
+a name for that value.  Thus, the documentation string of the function
+@code{eval} refers to its second argument as @samp{FORM}, because the
+actual argument name is @code{form}:
+
+@example
+Evaluate FORM and return its value.
+@end example
+
+Also write metasyntactic variables in capital letters, such as when you
+show the decomposition of a list or vector into subunits, some of which
+may vary.  @samp{KEY} and @samp{VALUE} in the following example
+illustrate this practice:
+
+@example
+The argument TABLE should be an alist whose elements
+have the form (KEY . VALUE).  Here, KEY is ...
+@end example
+
+@item
+Never change the case of a Lisp symbol when you mention it in a doc
+string.  If the symbol's name is @code{foo}, write ``foo,'' not
+``Foo'' (which is a different symbol).
+
+This might appear to contradict the policy of writing function
+argument values, but there is no real contradiction; the argument
+@emph{value} is not the same thing as the @emph{symbol} which the
+function uses to hold the value.
+
+If this puts a lower-case letter at the beginning of a sentence
+and that annoys you, rewrite the sentence so that the symbol
+is not at the start of it.
+
+@item
+Do not start or end a documentation string with whitespace.
+
+@item
+@strong{Do not} indent subsequent lines of a documentation string so
+that the text is lined up in the source code with the text of the first
+line.  This looks nice in the source code, but looks bizarre when users
+view the documentation.  Remember that the indentation before the
+starting double-quote is not part of the string!
+
+@anchor{Docstring hyperlinks}
+@item
+@iftex
+When a documentation string refers to a Lisp symbol, write it as it
+would be printed (which usually means in lower case), with single-quotes
+around it.  For example: @samp{`lambda'}.  There are two exceptions:
+write @code{t} and @code{nil} without single-quotes.
+@end iftex
+@ifnottex
+When a documentation string refers to a Lisp symbol, write it as it
+would be printed (which usually means in lower case), with single-quotes
+around it.  For example: @samp{lambda}.  There are two exceptions: write
+t and nil without single-quotes.  (In this manual, we use a different
+convention, with single-quotes for all symbols.)
+@end ifnottex
+
+@cindex hyperlinks in documentation strings
+Help mode automatically creates a hyperlink when a documentation string
+uses a symbol name inside single quotes, if the symbol has either a
+function or a variable definition.  You do not need to do anything
+special to make use of this feature.  However, when a symbol has both a
+function definition and a variable definition, and you want to refer to
+just one of them, you can specify which one by writing one of the words
+@samp{variable}, @samp{option}, @samp{function}, or @samp{command},
+immediately before the symbol name.  (Case makes no difference in
+recognizing these indicator words.)  For example, if you write
+
+@example
+This function sets the variable `buffer-file-name'.
+@end example
+
+@noindent
+then the hyperlink will refer only to the variable documentation of
+@code{buffer-file-name}, and not to its function documentation.
+
+If a symbol has a function definition and/or a variable definition, but
+those are irrelevant to the use of the symbol that you are documenting,
+you can write the words @samp{symbol} or @samp{program} before the
+symbol name to prevent making any hyperlink.  For example,
+
+@example
+If the argument KIND-OF-RESULT is the symbol `list',
+this function returns a list of all the objects
+that satisfy the criterion.
+@end example
+
+@noindent
+does not make a hyperlink to the documentation, irrelevant here, of the
+function @code{list}.
+
+Normally, no hyperlink is made for a variable without variable
+documentation.  You can force a hyperlink for such variables by
+preceding them with one of the words @samp{variable} or
+@samp{option}.
+
+Hyperlinks for faces are only made if the face name is preceded or
+followed by the word @samp{face}.  In that case, only the face
+documentation will be shown, even if the symbol is also defined as a
+variable or as a function.
+
+To make a hyperlink to Info documentation, write the name of the Info
+node (or anchor) in single quotes, preceded by @samp{info node},
+@samp{Info node}, @samp{info anchor} or @samp{Info anchor}.  The Info
+file name defaults to @samp{emacs}.  For example,
+
+@smallexample
+See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
+@end smallexample
+
+Finally, to create a hyperlink to URLs, write the URL in single
+quotes, preceded by @samp{URL}. For example,
+
+@smallexample
+The home page for the GNU project has more information (see URL
+`http://www.gnu.org/').
+@end smallexample
+
+@item
+Don't write key sequences directly in documentation strings.  Instead,
+use the @samp{\\[@dots{}]} construct to stand for them.  For example,
+instead of writing @samp{C-f}, write the construct
+@samp{\\[forward-char]}.  When Emacs displays the documentation string,
+it substitutes whatever key is currently bound to @code{forward-char}.
+(This is normally @samp{C-f}, but it may be some other character if the
+user has moved key bindings.)  @xref{Keys in Documentation}.
+
+@item
+In documentation strings for a major mode, you will want to refer to the
+key bindings of that mode's local map, rather than global ones.
+Therefore, use the construct @samp{\\<@dots{}>} once in the
+documentation string to specify which key map to use.  Do this before
+the first use of @samp{\\[@dots{}]}.  The text inside the
+@samp{\\<@dots{}>} should be the name of the variable containing the
+local keymap for the major mode.
+
+It is not practical to use @samp{\\[@dots{}]} very many times, because
+display of the documentation string will become slow.  So use this to
+describe the most important commands in your major mode, and then use
+@samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
+
+@item
+For consistency, phrase the verb in the first sentence of a function's
+documentation string as an imperative---for instance, use ``Return the
+cons of A and B.'' in preference to ``Returns the cons of A and B@.''
+Usually it looks good to do likewise for the rest of the first
+paragraph.  Subsequent paragraphs usually look better if each sentence
+is indicative and has a proper subject.
+
+@item
+The documentation string for a function that is a yes-or-no predicate
+should start with words such as ``Return t if,'' to indicate
+explicitly what constitutes ``truth.''  The word ``return'' avoids
+starting the sentence with lower-case ``t,'' which could be somewhat
+distracting.
+
+@item
+If a line in a documentation string begins with an open-parenthesis,
+write a backslash before the open-parenthesis, like this:
+
+@example
+The argument FOO can be either a number
+\(a buffer position) or a string (a file name).
+@end example
+
+This prevents the open-parenthesis from being treated as the start of a
+defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
+
+@item
+Write documentation strings in the active voice, not the passive, and in
+the present tense, not the future.  For instance, use ``Return a list
+containing A and B.'' instead of ``A list containing A and B will be
+returned.''
+
+@item
+Avoid using the word ``cause'' (or its equivalents) unnecessarily.
+Instead of, ``Cause Emacs to display text in boldface,'' write just
+``Display text in boldface.''
+
+@item
+Avoid using ``iff'' (a mathematics term meaning ``if and only if''),
+since many people are unfamiliar with it and mistake it for a typo.  In
+most cases, the meaning is clear with just ``if''.  Otherwise, try to
+find an alternate phrasing that conveys the meaning.
+
+@item
+When a command is meaningful only in a certain mode or situation,
+do mention that in the documentation string.  For example,
+the documentation of @code{dired-find-file} is:
+
+@example
+In Dired, visit the file or directory named on this line.
+@end example
+
+@item
+When you define a variable that users ought to set interactively, you
+normally should use @code{defcustom}.  However, if for some reason you
+use @code{defvar} instead, start the doc string with a @samp{*}.
+@xref{Defining Variables}.
+
+@item
+The documentation string for a variable that is a yes-or-no flag should
+start with words such as ``Non-nil means,'' to make it clear that
+all non-@code{nil} values are equivalent and indicate explicitly what
+@code{nil} and non-@code{nil} mean.
+@end itemize
+
+@node Comment Tips
+@section Tips on Writing Comments
+@cindex comments, Lisp convention for
+
+  We recommend these conventions for where to put comments and how to
+indent them:
+
+@table @samp
+@item ;
+Comments that start with a single semicolon, @samp{;}, should all be
+aligned to the same column on the right of the source code.  Such
+comments usually explain how the code on the same line does its job.  In
+Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
+command automatically inserts such a @samp{;} in the right place, or
+aligns such a comment if it is already present.
+
+This and following examples are taken from the Emacs sources.
+
+@smallexample
+@group
+(setq base-version-list                 ; there was a base
+      (assoc (substring fn 0 start-vn)  ; version to which
+             file-version-assoc-list))  ; this looks like
+                                        ; a subversion
+@end group
+@end smallexample
+
+@item ;;
+Comments that start with two semicolons, @samp{;;}, should be aligned to
+the same level of indentation as the code.  Such comments usually
+describe the purpose of the following lines or the state of the program
+at that point.  For example:
+
+@smallexample
+@group
+(prog1 (setq auto-fill-function
+             @dots{}
+             @dots{}
+  ;; update mode line
+  (force-mode-line-update)))
+@end group
+@end smallexample
+
+We also normally use two semicolons for comments outside functions.
+
+@smallexample
+@group
+;; This Lisp code is run in Emacs
+;; when it is to operate as a server
+;; for other processes.
+@end group
+@end smallexample
+
+Every function that has no documentation string (presumably one that is
+used only internally within the package it belongs to), should instead
+have a two-semicolon comment right before the function, explaining what
+the function does and how to call it properly.  Explain precisely what
+each argument means and how the function interprets its possible values.
+
+@item ;;;
+Comments that start with three semicolons, @samp{;;;}, should start at
+the left margin.  These are used, occasionally, for comments within
+functions that should start at the margin.  We also use them sometimes
+for comments that are between functions---whether to use two or three
+semicolons depends on whether the comment should be considered a
+``heading'' by Outline minor mode.  By default, comments starting with
+at least three semicolons (followed by a single space and a
+non-whitespace character) are considered headings, comments starting
+with two or less are not.
+
+Another use for triple-semicolon comments is for commenting out lines
+within a function.  We use three semicolons for this precisely so that
+they remain at the left margin.  By default, Outline minor mode does
+not consider a comment to be a heading (even if it starts with at
+least three semicolons) if the semicolons are followed by at least two
+spaces.  Thus, if you add an introductory comment to the commented out
+code, make sure to indent it by at least two spaces after the three
+semicolons.
+
+@smallexample
+(defun foo (a)
+;;;  This is no longer necessary.
+;;;  (force-mode-line-update)
+  (message "Finished with %s" a))
+@end smallexample
+
+When commenting out entire functions, use two semicolons.
+
+@item ;;;;
+Comments that start with four semicolons, @samp{;;;;}, should be aligned
+to the left margin and are used for headings of major sections of a
+program.  For example:
+
+@smallexample
+;;;; The kill ring
+@end smallexample
+@end table
+
+@noindent
+The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
+(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
+automatically indent comments according to these conventions,
+depending on the number of semicolons.  @xref{Comments,,
+Manipulating Comments, emacs, The GNU Emacs Manual}.
+
+@node Library Headers
+@section Conventional Headers for Emacs Libraries
+@cindex header comments
+@cindex library header comments
+
+  Emacs has conventions for using special comments in Lisp libraries
+to divide them into sections and give information such as who wrote
+them.  This section explains these conventions.
+
+  We'll start with an example, a package that is included in the Emacs
+distribution.
+
+  Parts of this example reflect its status as part of Emacs; for
+example, the copyright notice lists the Free Software Foundation as the
+copyright holder, and the copying permission says the file is part of
+Emacs.  When you write a package and post it, the copyright holder would
+be you (unless your employer claims to own it instead), and you should
+get the suggested copying permission from the end of the GNU General
+Public License itself.  Don't say your file is part of Emacs
+if we haven't installed it in Emacs yet!
+
+  With that warning out of the way, on to the example:
+
+@smallexample
+@group
+;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
+
+;; Copyright (C) 1992 Free Software Foundation, Inc.
+@end group
+
+;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
+;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
+;; Created: 14 Jul 1992
+;; Version: 1.2
+@group
+;; Keywords: docs
+
+;; This file is part of GNU Emacs.
+@dots{}
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+@end group
+@end smallexample
+
+  The very first line should have this format:
+
+@example
+;;; @var{filename} --- @var{description}
+@end example
+
+@noindent
+The description should be complete in one line.  If the file
+needs a @samp{-*-} specification, put it after @var{description}.
+
+  After the copyright notice come several @dfn{header comment} lines,
+each beginning with @samp{;; @var{header-name}:}.  Here is a table of
+the conventional possibilities for @var{header-name}:
+
+@table @samp
+@item Author
+This line states the name and net address of at least the principal
+author of the library.
+
+If there are multiple authors, you can list them on continuation lines
+led by @code{;;} and a tab character, like this:
+
+@smallexample
+@group
+;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
+;;      Dave Sill <de5@@ornl.gov>
+;;      Dave Brennan <brennan@@hal.com>
+;;      Eric Raymond <esr@@snark.thyrsus.com>
+@end group
+@end smallexample
+
+@item Maintainer
+This line should contain a single name/address as in the Author line, or
+an address only, or the string @samp{FSF}.  If there is no maintainer
+line, the person(s) in the Author field are presumed to be the
+maintainers.  The example above is mildly bogus because the maintainer
+line is redundant.
+
+The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
+possible a Lisp function to ``send mail to the maintainer'' without
+having to mine the name out by hand.
+
+Be sure to surround the network address with @samp{<@dots{}>} if
+you include the person's full name as well as the network address.
+
+@item Created
+This optional line gives the original creation date of the
+file.  For historical interest only.
+
+@item Version
+If you wish to record version numbers for the individual Lisp program, put
+them in this line.
+
+@item Adapted-By
+In this header line, place the name of the person who adapted the
+library for installation (to make it fit the style conventions, for
+example).
+
+@item Keywords
+This line lists keywords for the @code{finder-by-keyword} help command.
+Please use that command to see a list of the meaningful keywords.
+
+This field is important; it's how people will find your package when
+they're looking for things by topic area.  To separate the keywords, you
+can use spaces, commas, or both.
+@end table
+
+  Just about every Lisp library ought to have the @samp{Author} and
+@samp{Keywords} header comment lines.  Use the others if they are
+appropriate.  You can also put in header lines with other header
+names---they have no standard meanings, so they can't do any harm.
+
+  We use additional stylized comments to subdivide the contents of the
+library file.  These should be separated by blank lines from anything
+else.  Here is a table of them:
+
+@table @samp
+@item ;;; Commentary:
+This begins introductory comments that explain how the library works.
+It should come right after the copying permissions, terminated by a
+@samp{Change Log}, @samp{History} or @samp{Code} comment line.  This
+text is used by the Finder package, so it should make sense in that
+context.
+
+@item ;;; Documentation:
+This was used in some files in place of @samp{;;; Commentary:},
+but it is deprecated.
+
+@item ;;; Change Log:
+This begins change log information stored in the library file (if you
+store the change history there).  For Lisp files distributed with Emacs,
+the change history is kept in the file @file{ChangeLog} and not in the
+source file at all; these files generally do not have a @samp{;;; Change
+Log:} line.  @samp{History} is an alternative to @samp{Change Log}.
+
+@item ;;; Code:
+This begins the actual code of the program.
+
+@item ;;; @var{filename} ends here
+This is the @dfn{footer line}; it appears at the very end of the file.
+Its purpose is to enable people to detect truncated versions of the file
+from the lack of a footer line.
+@end table
+
+@ignore
+   arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e
+@end ignore
diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt
new file mode 100644
index 00000000000..6e40920cf66
--- /dev/null
+++ b/doc/lispref/two-volume-cross-refs.txt
@@ -0,0 +1,322 @@
+Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
+  Free Software Foundation, Inc.
+  See end for copying conditions.
+
+Two Volume Cross References
+===========================
+
+12 June 2007 (karl)
+
+For lispref 2.9 (for Emacs 22, June 2007), I created a very ugly
+Makefile, in the file two-volume.make, to encapsulate all the steps
+below, without manual intervention.  In theory, simply running "make -f
+two-volume.make" should create a vol1.pdf and vol2.pdf with all the
+niceties worked out.
+
+One issue not explicitly discussed below is getting page numbers right.
+It's not enough to go through the whole process.  You have to go through
+the whole process twice -- otherwise, some index entries and/or toc
+entries will be off by one.  See two-volume.make for a few more comments.
+
+For future editions, it should suffice to update the usual things in
+vol[12].texi (as well as elisp.texi).  That was my hope, anyway.
+
+
+18 March 1992 (bob)
+
+This enables you to create manuals in *two* volumes, with tables of
+contents, cross references, and indices in each volume referring to
+*both* volumes.
+
+The procedure is tedious.  However, the resulting two volumes are
+conveniently organized.  Each has an index of the whole two volumes.
+Each volume starts with page 1.  (I don't like multi-volume works
+where each volume starts with a higher page number since I find it
+harder to go to the right place in the volume.)
+
+References to the same volume are just the page number; references to
+the other volume are a volumne number (in Roman numerals) preceding
+the page number.
+
+For example, in Volume I:
+
+    list length ......... 90
+    list motion ......II:117
+
+and in Volume II:
+
+    list length ....... I:90
+    list motion .........117
+
+All other references and the table of contents work the same way.  I
+find this *very* helpful.
+
+
+In brief: you run tex on a .texi file with
+
+  a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file
+  b. redone .aux file
+  c. redone .fns file
+
+
+Here are the steps in detail:
+
+% tex vol1.texi
+% texindex vol1.??
+% tex vol1.texi
+
+% tex vol2.texi
+% texindex vol2.??
+% tex vol2.texi
+
+### Create .aux files with volume numbers for other volume.
+
+% cp vol1.aux elisp1-aux
+% cp vol2.aux elisp2-aux
+
+% cp vol1.aux elisp1-aux-vol-added
+% cp vol2.aux elisp2-aux-vol-added
+
+on elisp1-aux-vol-number-added
+(volume-aux-markup 1)           see defun for volume-aux-markup below.
+to create             elisp1-aux-vol-added
+
+on elisp2-aux-vol-number-added
+(volume-aux-markup 2)
+to create             elisp2-aux-vol-added
+
+insert elisp2-aux-vol-added into vol1.aux  (append)
+insert elisp1-aux-vol-added into vol2.aux  (prepend)
+
+(so you dont have to do it again)
+% cp vol1.aux elisp1-aux-ready
+% cp vol2.aux elisp2-aux-ready
+
+
+### Create .fn files with volume numbers for other volume.
+
+% cp vol1.fn elisp1-fn
+% cp vol2.fn elisp2-fn
+
+% cp vol1.fn elisp1-fn-vol-number-added
+% cp vol2.fn elisp2-fn-vol-number-added
+
+on elisp1-fn-vol-number-added
+(volume-index-markup "I")
+to create             elisp1-fn-vol-number-added
+
+on elisp2-fn-vol-number-added
+(volume-index-markup "II")
+to create             elisp2-fn-vol-number-added
+
+insert elisp2-fn-vol-number-added into vol1.fn: do following `cat'
+insert elisp1-fn-vol-number-added into vol2.fn: do following `cat'
+
+% cat elisp2-fn-vol-number-added >> vol1.fn
+% cat elisp1-fn-vol-number-added >> vol2.fn
+
+Be sure to handle special case entries by hand.
+Be sure that .fn file has no blank lines.
+
+% texindex vol1.fn
+% texindex vol2.fn
+
+(so you dont have to do it again)
+% cp vol1.fns elisp1-fns-2vol-ready
+% cp vol2.fns elisp2-fns-2vol-ready
+
+### Create merged .toc file with volume number headings.
+
+append vol2.toc to vol1.toc  with following `cat'
+
+% cat vol1.toc vol2.toc > elisp-toc-2vol.toc
+
+and edit in Volume titles
+
+\unnumbchapentry {Volume 1}{}
+\unnumbchapentry {}{}
+
+\unnumbchapentry {Index}{295}
+\unnumbchapentry {}{}
+\unnumbchapentry {Volume 2}{}
+\unnumbchapentry {}{}
+
+If you want to put in volume numbers for TOC, then do this:
+Create volume specific .toc files with volume numbers in them.
+
+% cp elisp-toc-2vol.toc elisp1-toc.toc
+% cp elisp-toc-2vol.toc elisp2-toc.toc
+
+Use keyboard macro to put I: in first half of elisp1-toc.toc and
+II: in first half of elisp2-toc.toc
+
+Copy the tocs to something you can remember more easily
+
+% cp elisp2-toc.toc elisp1-toc-ready.toc
+% cp elisp1-toc.toc elisp2-toc-ready.toc
+
+Then, edit vol1.texi to input elisp1-toc-ready.toc
+and vol2.texi to input elisp2-toc-ready.toc
+
+
+### Now format the two volumes:
+
+% cp elisp1-aux-2vol-ready vol1.aux
+% cp elisp2-aux-2vol-ready vol2.aux
+
+% tex vol1.texi
+% tex vol2.texi
+
+
+
+For every additional run:
+
+### recopy aux files so the correct ones are read:
+% cp elisp1-aux-2vol-ready vol1.aux
+% cp elisp2-aux-2vol-ready vol2.aux
+
+Do not run texindex.  Then proper sorted index will stay.
+ else do: % cp elisp2-fns-2vol-ready vol2.fns
+
+Do not change the .texi files; they will call the elisp-toc-2vol.toc file.
+
+% tex vol1.texi
+% tex vol2.texi
+
+================================================================
+
+
+(defun volume-aux-markup (arg)
+  "Append `vol. NUMBER' to page number.
+Apply to aux file that you save.
+Then insert marked file into other volume's .aux file."
+  (interactive "sType volume number, 1 or 2: " )
+  (goto-char (point-min))
+  (while (search-forward "-pg" nil t)
+    (end-of-line 1)
+    (delete-backward-char 1 nil)
+    (insert ", vol.'tie" arg "}")))
+
+(defun volume-index-markup (arg)
+  "Prepend  `NUMBER:' to page number.  Use Roman Numeral.
+Apply only to unsorted index file,
+Then insert marked file into other volume's unsorted index file.
+Then run texindex on that file and save."
+  (interactive
+   "sType volume number,  roman number I or II: " )
+  (goto-char (point-min))
+  (while (search-forward "\\entry" nil t)
+    (search-forward "}{" (save-excursion (end-of-line) (point)) nil)
+    (insert arg ":")))
+
+
+================================================================
+
+
+The steps:
+
+1. Run TeX, texindex and TeX on file1.
+2. Run TeX, texindex and TeX on file2.
+
+3. Copy both .aux files into specially named files
+
+4. In the case of the elisp ref manual,
+
+   copy the *unsorted* function index files into specially named files
+   (no other index used in elisp ref manual)
+
+
+5. For aux files:
+
+   Run a function on the specially named .aux files to label each
+   entry according to volume.  Save these files.
+
+   i.e., convert
+   'xrdef {Special-pg}{7}  to 'xrdef {Special-pg}{7, vol.'tie1}
+
+5a.Insert each specially named .aux file into the regular .aux file of
+   the other volume.
+
+6. For index files:
+
+   Run a function on the specially named unsorted index files to label
+   each entry according to volume.  Save these files.
+
+6b.Insert each specially named marked unsorted index file into the
+   regular unsorted file of the other volume.  Run texindex on this
+
+7. Insert the other volumes .toc file into the .toc, edit, and rename to
+   elisp-toc-2vol.toc
+
+7a. insert special @contents and @summarycontents defs into .texi files.
+
+8. Run TeX on each .texi file.
+
+================
+
+
+
+Here is the discursive commentary:
+
+I've been running some small test files, called test1.texi and
+test2.texi.  As far as I can see, if we run tex on the two test files,
+tex creates a .aux for each that includes the names of all the nodes
+in that file.  The node names are used for cross references.
+
+If you insert the .aux file for the second test file, test2.aux, into
+the .aux file for the first test file, test1.aux, then when you next
+run TeX on the first test file, test1.texi, the second volume cross
+references are inserted.
+
+You can edit the text of the cross reference in test2.aux to include
+the volume number.
+
+For example, you can take the following two lines from test1.texi and
+insert them into test2.texi:
+
+    'xrdef {Special-pg}{7}
+    'xrdef {Special-snt}{Section'tie1.6}
+
+You can re-edit this to show that the page is in volume 1:
+
+    'xrdef {Special-pg}{7, vol.'tie1}
+    'xrdef {Special-snt}{Section'tie1.6}
+
+(The  'tie  is a TeX special command to keep the number tied on one
+line to the previous word.  I don't know if it works after a period in
+the "vol." but figure it is worth trying.  {The  ' is the @  of  .aux files.}
+Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the
+definition for 'tie is the following:
+
+    \def\tie{\penalty 10000\ }     % Save plain tex definition of ~.
+
+)
+
+After running tex on the test2.texi file with the augmented test2.aux
+file, you can see the following in the resulting DVI file:
+
+    See Section 1.6 [Special], page 7, vol. 1
+
+Note that TeX rewrites the .aux file each time TeX is run, so after
+running Tex using an .aux file augmented with the .aux file from the
+other volume, the new .aux file will *lack* the other volumes cross
+references.  Save your augmented .aux file in some other name for
+another run!
+
+
+COPYING CONDITIONS
+
+This 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 3, or (at your option)
+any later version.
+
+This 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 file; see the file COPYING.  If not, write to
+the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+Boston, MA 02110-1301, USA.
diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make
new file mode 100644
index 00000000000..b2550576825
--- /dev/null
+++ b/doc/lispref/two-volume.make
@@ -0,0 +1,227 @@
+# Copyright 2007 Free Software Foundation, Inc.
+# See end for copying conditions.
+
+# although it would be nice to use tex rather than pdftex to avoid
+# colors, spurious warnings about names being referenced but not
+# existing, etc., dvips | ps2pdf doesn't preserve the page size.
+# Instead of creating a special dvips config file, put up with the warnings.
+tex = pdftex -interaction=nonstopmode
+
+all: vol1.pdf vol2.pdf
+
+# vol1.texi and vol2.texi specially define \tocreadfilename so we can
+# use our premade .toc's.
+# 
+vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready
+	@echo -e "\f Final TeX run for volume 1..."
+	cp elisp1med-toc-ready elisp1-toc-ready.toc
+	cp elisp1med-fns-ready vol1.fns
+	cp elisp1med-aux-ready vol1.aux
+	$(tex) vol1.texi
+#
+vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready
+	@echo "Final TeX run for volume 2..."
+	cp elisp2med-toc-ready elisp2-toc-ready.toc
+	cp elisp2med-fns-ready vol2.fns
+	cp elisp2med-aux-ready vol2.aux
+	$(tex) vol2.texi
+
+#  intermediate toc files.
+# 
+# vol1 toc: volume 1, page break, volume 2 (with II: prepended).
+elisp1med-toc-ready: elisp1med-init elisp2med-init
+	echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
+	cat elisp1med-toc >>$@
+	echo '@page' >>$@
+	echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
+	sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@	
+#
+# vol2 toc: volume 1 (with I: prepended), page break, volume 2.
+elisp2med-toc-ready: elisp1med-init elisp2med-init
+	echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
+	sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@	
+	echo '@page' >>$@
+	echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
+	cat elisp2med-toc >>$@
+
+
+#  intermediate aux files.
+# 
+# append vol2's fixed aux to normal vol1.  
+elisp1med-aux-ready: elisp2med-aux-vol-added
+	cat elisp1med-aux $< >$@
+#
+# prepend vol1's fixed aux to vol2.
+elisp2med-aux-ready: elisp1med-aux-vol-added
+	cat $< elisp2med-aux >$@
+
+# on -pg entries, append volume number after page number.
+elisp1med-aux-vol-added: elisp1med-init
+	sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1med-aux >$@
+#
+elisp2med-aux-vol-added: elisp2med-init
+	sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@
+	
+
+
+#  intermediate index (fns) file.
+# 
+elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added
+	cat elisp2med-fn-vol-added >>vol1.fn
+	texindex vol1.fn
+	cp vol1.fns $@
+#
+elisp2med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added
+	cat elisp1med-fn-vol-added >>vol2.fn
+	texindex vol2.fn
+	cp vol2.fns $@
+
+# Insert volume number (I: or II:) into index file.
+elisp1med-fn-vol-added: elisp1med-init
+	cp vol1.fn elisp1med-fn
+	sed 's/}{/}{I:/' elisp1med-fn >$@
+#
+elisp2med-fn-vol-added: elisp2med-init
+	cp vol2.fn elisp2med-fn
+	sed 's/}{/}{II:/' elisp2med-fn >$@
+
+# -----------------------------------------------------------------------------
+# everything above is essentially a duplicate of everything below. sorry.
+# -----------------------------------------------------------------------------
+
+#  intermediate TeX runs.
+# 
+# this generates what would be the final versions -- except the page
+# numbers aren't right.  The process of adding the I: and II: changes
+# the page breaks, so a few index entries, at least are wrong.  (In
+# 2007, x-meta-keysym in vol.II ended up on page 374 when the index had
+# it on page 375 from the initial run.)
+# 
+# So, we start all over again, from these fns/aux/toc files.
+# 
+elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready texinfo.tex
+	@echo -e "\f Intermediate TeX run for volume 1..."
+	cp elisp1init-toc-ready elisp1-toc-ready.toc
+	cp elisp1-fns-ready vol1.fns
+	cp elisp1-aux-ready vol1.aux
+	$(tex) vol1.texi
+	texindex vol1.??
+	mv vol1.aux elisp1med-aux
+	mv vol1.toc elisp1med-toc
+#
+elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready texinfo.tex
+	@echo "Final TeX run for volume 2..."
+	cp elisp2init-toc-ready elisp2-toc-ready.toc
+	cp elisp2-fns-ready vol2.fns
+	cp elisp2-aux-ready vol2.aux
+	$(tex) vol2.texi
+	texindex vol2.??
+	mv vol2.aux elisp2med-aux
+	mv vol2.toc elisp2med-toc
+
+
+#  initial toc files.
+# 
+# vol1 toc: volume 1, page break, volume 2 (with II: prepended).
+elisp1init-toc-ready: elisp1-init elisp2-init
+	echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
+	cat elisp1-toc >>$@
+	echo '@page' >>$@
+	echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
+	sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@	
+#
+# vol2 toc: volume 1 (with I: prepended), page break, volume 2.
+elisp2init-toc-ready: elisp1-init elisp2-init
+	echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
+	sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@	
+	echo '@page' >>$@
+	echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
+	cat elisp2-toc >>$@
+
+
+#  initial aux files.
+# 
+# append vol2's fixed aux to normal vol1.  The initial runs saved
+# elisp1-aux and elisp2-aux.
+elisp1-aux-ready: elisp2-aux-vol-added
+	cat elisp1-aux $< >$@
+#
+# prepend vol1's fixed aux to vol2.
+elisp2-aux-ready: elisp1-aux-vol-added
+	cat $< elisp2-aux >$@
+
+# on -pg entries, append volume number after page number.
+elisp1-aux-vol-added: elisp1-init
+	sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1-aux >$@
+#
+elisp2-aux-vol-added: elisp2-init
+	sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@
+	
+
+#  initial index (fns) file.
+# 
+# Append other volume's index entries to this one's.
+# Index entries in this volume will then take precedence.
+elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added
+	cat elisp2-fn-vol-added >>vol1.fn
+	texindex vol1.fn
+	cp vol1.fns $@
+#
+elisp2-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added
+	cat elisp1-fn-vol-added >>vol2.fn
+	texindex vol2.fn
+	cp vol2.fns $@
+
+# Insert volume number (I: or II:) into index file.
+elisp1-fn-vol-added: elisp1-init
+	cp vol1.fn elisp1-fn
+	sed 's/}{/}{I:/' elisp1-fn >$@
+#
+elisp2-fn-vol-added: elisp2-init
+	cp vol2.fn elisp2-fn
+	sed 's/}{/}{II:/' elisp2-fn >$@
+
+
+#  initial TeX runs.
+# 
+# We use the .fn, .aux, and .toc files created here in subsequent
+# processing.  The page numbers generated here will not be correct yet,
+# but we run texindex and TeX a second time just to get them closer.
+# Otherwise it might take even longer for them to converge.
+# 
+elisp1-init: vol1.texi
+	@echo -e "\f Initial TeX run for volume 1..."
+	rm -f vol1.aux vol1.toc
+	$(tex) $<
+	texindex vol1.??
+	mv vol1.aux elisp1-aux
+	mv vol1.toc elisp1-toc
+	touch $@
+#
+elisp2-init: vol2.texi
+	@echo "Initial TeX run for volume 2..."
+	rm -f vol2.aux vol2.toc
+	$(tex) $<
+	texindex vol2.??
+	mv vol2.aux elisp2-aux
+	mv vol2.toc elisp2-toc
+	touch $@
+
+# COPYING CONDITIONS
+# 
+# This 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 3, or (at your option)
+# any later version.
+# 
+# This 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 file; 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: 5c258a2e-d4a9-4d0e-b279-fb3a6faa27eb
diff --git a/doc/lispref/two.el b/doc/lispref/two.el
new file mode 100644
index 00000000000..baade844463
--- /dev/null
+++ b/doc/lispref/two.el
@@ -0,0 +1,80 @@
+;; Auxiliary functions for preparing a two volume manual.
+
+;; Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
+;;   Free Software Foundation, Inc.
+
+;; --rjc 30mar92
+
+;; This 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 3, or (at your option)
+;; any later version.
+
+;; This 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 file; see the file COPYING.  If not, write to
+;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+
+(defun volume-aux-markup (arg)
+  "Append `vol. NUMBER' to page number.
+Apply to aux file that you save.
+Then insert marked file into other volume's .aux file."
+  (interactive "sType volume number, 1 or 2: " )
+  (goto-char (point-min))
+  (while (search-forward "-pg" nil t)
+    (end-of-line 1)
+    (delete-backward-char 1 nil)
+    (insert ", vol.'tie" arg "}")))
+
+(defun volume-index-markup (arg)
+  "Prepend  `NUMBER:' to page number.  Use Roman Numeral.
+Apply only to unsorted index file,
+Then insert marked file into other volume's unsorted index file.
+Then run texindex on that file and save."
+  (interactive
+   "sType volume number,  roman number I or II: " )
+  (goto-char (point-min))
+  (while (search-forward "\\entry" nil t)
+    (search-forward "}{" (save-excursion (end-of-line) (point)) nil)
+    (insert arg ":")))
+
+(defun volume-numbers-toc-markup (arg)
+  (interactive
+   "sType volume number,  roman number I or II: " )
+  (goto-char (point-min))
+  (while (search-forward "chapentry" nil t)
+    (end-of-line)
+    (search-backward "{" nil t)
+    (forward-char 1)
+    (insert arg ":")))
+
+(defun volume-header-toc-markup ()
+  "Insert Volume I and Volume II text into .toc file.
+NOTE: this auxilary function is file specific.
+This is for the *Elisp Ref Manual*"
+  (interactive)
+  (goto-char (point-min))
+  (insert "\\unnumbchapentry {Volume 1}{}\n\\unnumbchapentry {}{}\n")
+  (search-forward "\\unnumbchapentry {Index}")
+  (forward-line 1)
+  (insert
+   "\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {Volume 2}{}\n\\unnumbchapentry {}{}\n"))
+
+
+;;; In batch mode, you cannot call functions with args; hence this kludge:
+
+(defun volume-aux-markup-1 () (volume-aux-markup "1"))
+(defun volume-aux-markup-2 () (volume-aux-markup "2"))
+
+(defun volume-index-markup-I () (volume-index-markup "I"))
+(defun volume-index-markup-II () (volume-index-markup "II"))
+
+(defun volume-numbers-toc-markup-I () (volume-numbers-toc-markup "I"))
+(defun volume-numbers-toc-markup-II () (volume-numbers-toc-markup "II"))
+
+;;; arch-tag: 848955fe-e9cf-45e7-a2f1-570ef156d6a5
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
new file mode 100644
index 00000000000..9d9dc8260bb
--- /dev/null
+++ b/doc/lispref/variables.texi
@@ -0,0 +1,1908 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000,
+@c   2001, 2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/variables
+@node Variables, Functions, Control Structures, Top
+@chapter Variables
+@cindex variable
+
+  A @dfn{variable} is a name used in a program to stand for a value.
+Nearly all programming languages have variables of some sort.  In the
+text of a Lisp program, variables are written using the syntax for
+symbols.
+
+  In Lisp, unlike most programming languages, programs are represented
+primarily as Lisp objects and only secondarily as text.  The Lisp
+objects used for variables are symbols: the symbol name is the variable
+name, and the variable's value is stored in the value cell of the
+symbol.  The use of a symbol as a variable is independent of its use as
+a function name.  @xref{Symbol Components}.
+
+  The Lisp objects that constitute a Lisp program determine the textual
+form of the program---it is simply the read syntax for those Lisp
+objects.  This is why, for example, a variable in a textual Lisp program
+is written using the read syntax for the symbol that represents the
+variable.
+
+@menu
+* Global Variables::      Variable values that exist permanently, everywhere.
+* Constant Variables::    Certain "variables" have values that never change.
+* Local Variables::       Variable values that exist only temporarily.
+* Void Variables::        Symbols that lack values.
+* Defining Variables::    A definition says a symbol is used as a variable.
+* Tips for Defining::     Things you should think about when you
+                            define a variable.
+* Accessing Variables::   Examining values of variables whose names
+                            are known only at run time.
+* Setting Variables::     Storing new values in variables.
+* Variable Scoping::      How Lisp chooses among local and global values.
+* Buffer-Local Variables::  Variable values in effect only in one buffer.
+* Frame-Local Variables::   Variable values in effect only in one frame.
+* Future Local Variables::  New kinds of local values we might add some day.
+* File Local Variables::  Handling local variable lists in files.
+* Variable Aliases::      Variables that are aliases for other variables.
+* Variables with Restricted Values::  Non-constant variables whose value can
+                                        @emph{not} be an arbitrary Lisp object.
+@end menu
+
+@node Global Variables
+@section Global Variables
+@cindex global variable
+
+  The simplest way to use a variable is @dfn{globally}.  This means that
+the variable has just one value at a time, and this value is in effect
+(at least for the moment) throughout the Lisp system.  The value remains
+in effect until you specify a new one.  When a new value replaces the
+old one, no trace of the old value remains in the variable.
+
+  You specify a value for a symbol with @code{setq}.  For example,
+
+@example
+(setq x '(a b))
+@end example
+
+@noindent
+gives the variable @code{x} the value @code{(a b)}.  Note that
+@code{setq} does not evaluate its first argument, the name of the
+variable, but it does evaluate the second argument, the new value.
+
+  Once the variable has a value, you can refer to it by using the symbol
+by itself as an expression.  Thus,
+
+@example
+@group
+x @result{} (a b)
+@end group
+@end example
+
+@noindent
+assuming the @code{setq} form shown above has already been executed.
+
+  If you do set the same variable again, the new value replaces the old
+one:
+
+@example
+@group
+x
+     @result{} (a b)
+@end group
+@group
+(setq x 4)
+     @result{} 4
+@end group
+@group
+x
+     @result{} 4
+@end group
+@end example
+
+@node Constant Variables
+@section Variables that Never Change
+@kindex setting-constant
+@cindex keyword symbol
+@cindex variable with constant value
+@cindex constant variables
+@cindex symbol that evaluates to itself
+@cindex symbol with constant value
+
+  In Emacs Lisp, certain symbols normally evaluate to themselves.  These
+include @code{nil} and @code{t}, as well as any symbol whose name starts
+with @samp{:} (these are called @dfn{keywords}).  These symbols cannot
+be rebound, nor can their values be changed.  Any attempt to set or bind
+@code{nil} or @code{t} signals a @code{setting-constant} error.  The
+same is true for a keyword (a symbol whose name starts with @samp{:}),
+if it is interned in the standard obarray, except that setting such a
+symbol to itself is not an error.
+
+@example
+@group
+nil @equiv{} 'nil
+     @result{} nil
+@end group
+@group
+(setq nil 500)
+@error{} Attempt to set constant symbol: nil
+@end group
+@end example
+
+@defun keywordp object
+function returns @code{t} if @var{object} is a symbol whose name
+starts with @samp{:}, interned in the standard obarray, and returns
+@code{nil} otherwise.
+@end defun
+
+@node Local Variables
+@section Local Variables
+@cindex binding local variables
+@cindex local variables
+@cindex local binding
+@cindex global binding
+
+  Global variables have values that last until explicitly superseded
+with new values.  Sometimes it is useful to create variable values that
+exist temporarily---only until a certain part of the program finishes.
+These values are called @dfn{local}, and the variables so used are
+called @dfn{local variables}.
+
+  For example, when a function is called, its argument variables receive
+new local values that last until the function exits.  The @code{let}
+special form explicitly establishes new local values for specified
+variables; these last until exit from the @code{let} form.
+
+@cindex shadowing of variables
+  Establishing a local value saves away the previous value (or lack of
+one) of the variable.  When the life span of the local value is over,
+the previous value is restored.  In the mean time, we say that the
+previous value is @dfn{shadowed} and @dfn{not visible}.  Both global and
+local values may be shadowed (@pxref{Scope}).
+
+  If you set a variable (such as with @code{setq}) while it is local,
+this replaces the local value; it does not alter the global value, or
+previous local values, that are shadowed.  To model this behavior, we
+speak of a @dfn{local binding} of the variable as well as a local value.
+
+  The local binding is a conceptual place that holds a local value.
+Entry to a function, or a special form such as @code{let}, creates the
+local binding; exit from the function or from the @code{let} removes the
+local binding.  As long as the local binding lasts, the variable's value
+is stored within it.  Use of @code{setq} or @code{set} while there is a
+local binding stores a different value into the local binding; it does
+not create a new binding.
+
+  We also speak of the @dfn{global binding}, which is where
+(conceptually) the global value is kept.
+
+@cindex current binding
+  A variable can have more than one local binding at a time (for
+example, if there are nested @code{let} forms that bind it).  In such a
+case, the most recently created local binding that still exists is the
+@dfn{current binding} of the variable.  (This rule is called
+@dfn{dynamic scoping}; see @ref{Variable Scoping}.)  If there are no
+local bindings, the variable's global binding is its current binding.
+We sometimes call the current binding the @dfn{most-local existing
+binding}, for emphasis.  Ordinary evaluation of a symbol always returns
+the value of its current binding.
+
+  The special forms @code{let} and @code{let*} exist to create
+local bindings.
+
+@defspec let (bindings@dots{}) forms@dots{}
+This special form binds variables according to @var{bindings} and then
+evaluates all of the @var{forms} in textual order.  The @code{let}-form
+returns the value of the last form in @var{forms}.
+
+Each of the @var{bindings} is either @w{(i) a} symbol, in which case
+that symbol is bound to @code{nil}; or @w{(ii) a} list of the form
+@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is
+bound to the result of evaluating @var{value-form}.  If @var{value-form}
+is omitted, @code{nil} is used.
+
+All of the @var{value-form}s in @var{bindings} are evaluated in the
+order they appear and @emph{before} binding any of the symbols to them.
+Here is an example of this: @code{z} is bound to the old value of
+@code{y}, which is 2, not the new value of @code{y}, which is 1.
+
+@example
+@group
+(setq y 2)
+     @result{} 2
+@end group
+@group
+(let ((y 1)
+      (z y))
+  (list y z))
+     @result{} (1 2)
+@end group
+@end example
+@end defspec
+
+@defspec let* (bindings@dots{}) forms@dots{}
+This special form is like @code{let}, but it binds each variable right
+after computing its local value, before computing the local value for
+the next variable.  Therefore, an expression in @var{bindings} can
+reasonably refer to the preceding symbols bound in this @code{let*}
+form.  Compare the following example with the example above for
+@code{let}.
+
+@example
+@group
+(setq y 2)
+     @result{} 2
+@end group
+@group
+(let* ((y 1)
+       (z y))    ; @r{Use the just-established value of @code{y}.}
+  (list y z))
+     @result{} (1 1)
+@end group
+@end example
+@end defspec
+
+  Here is a complete list of the other facilities that create local
+bindings:
+
+@itemize @bullet
+@item
+Function calls (@pxref{Functions}).
+
+@item
+Macro calls (@pxref{Macros}).
+
+@item
+@code{condition-case} (@pxref{Errors}).
+@end itemize
+
+  Variables can also have buffer-local bindings (@pxref{Buffer-Local
+Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a
+few variables have terminal-local bindings (@pxref{Multiple Displays}).
+These kinds of bindings work somewhat like ordinary local bindings, but
+they are localized depending on ``where'' you are in Emacs, rather than
+localized in time.
+
+@defvar max-specpdl-size
+@anchor{Definition of max-specpdl-size}
+@cindex variable limit error
+@cindex evaluation error
+@cindex infinite recursion
+This variable defines the limit on the total number of local variable
+bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,,
+Cleaning Up from Nonlocal Exits}) that are allowed before signaling an
+error (with data @code{"Variable binding depth exceeds
+max-specpdl-size"}).
+
+This limit, with the associated error when it is exceeded, is one way
+that Lisp avoids infinite recursion on an ill-defined function.
+@code{max-lisp-eval-depth} provides another limit on depth of nesting.
+@xref{Definition of max-lisp-eval-depth,, Eval}.
+
+The default value is 1000.  Entry to the Lisp debugger increases the
+value, if there is little room left, to make sure the debugger itself
+has room to execute.
+@end defvar
+
+@node Void Variables
+@section When a Variable is ``Void''
+@kindex void-variable
+@cindex void variable
+
+  If you have never given a symbol any value as a global variable, we
+say that that symbol's global value is @dfn{void}.  In other words, the
+symbol's value cell does not have any Lisp object in it.  If you try to
+evaluate the symbol, you get a @code{void-variable} error rather than
+a value.
+
+  Note that a value of @code{nil} is not the same as void.  The symbol
+@code{nil} is a Lisp object and can be the value of a variable just as any
+other object can be; but it is @emph{a value}.  A void variable does not
+have any value.
+
+  After you have given a variable a value, you can make it void once more
+using @code{makunbound}.
+
+@defun makunbound symbol
+This function makes the current variable binding of @var{symbol} void.
+Subsequent attempts to use this symbol's value as a variable will signal
+the error @code{void-variable}, unless and until you set it again.
+
+@code{makunbound} returns @var{symbol}.
+
+@example
+@group
+(makunbound 'x)      ; @r{Make the global value of @code{x} void.}
+     @result{} x
+@end group
+@group
+x
+@error{} Symbol's value as variable is void: x
+@end group
+@end example
+
+If @var{symbol} is locally bound, @code{makunbound} affects the most
+local existing binding.  This is the only way a symbol can have a void
+local binding, since all the constructs that create local bindings
+create them with values.  In this case, the voidness lasts at most as
+long as the binding does; when the binding is removed due to exit from
+the construct that made it, the previous local or global binding is
+reexposed as usual, and the variable is no longer void unless the newly
+reexposed binding was void all along.
+
+@smallexample
+@group
+(setq x 1)               ; @r{Put a value in the global binding.}
+     @result{} 1
+(let ((x 2))             ; @r{Locally bind it.}
+  (makunbound 'x)        ; @r{Void the local binding.}
+  x)
+@error{} Symbol's value as variable is void: x
+@end group
+@group
+x                        ; @r{The global binding is unchanged.}
+     @result{} 1
+
+(let ((x 2))             ; @r{Locally bind it.}
+  (let ((x 3))           ; @r{And again.}
+    (makunbound 'x)      ; @r{Void the innermost-local binding.}
+    x))                  ; @r{And refer: it's void.}
+@error{} Symbol's value as variable is void: x
+@end group
+
+@group
+(let ((x 2))
+  (let ((x 3))
+    (makunbound 'x))     ; @r{Void inner binding, then remove it.}
+  x)                     ; @r{Now outer @code{let} binding is visible.}
+     @result{} 2
+@end group
+@end smallexample
+@end defun
+
+  A variable that has been made void with @code{makunbound} is
+indistinguishable from one that has never received a value and has
+always been void.
+
+  You can use the function @code{boundp} to test whether a variable is
+currently void.
+
+@defun boundp variable
+@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void;
+more precisely, if its current binding is not void.  It returns
+@code{nil} otherwise.
+
+@smallexample
+@group
+(boundp 'abracadabra)          ; @r{Starts out void.}
+     @result{} nil
+@end group
+@group
+(let ((abracadabra 5))         ; @r{Locally bind it.}
+  (boundp 'abracadabra))
+     @result{} t
+@end group
+@group
+(boundp 'abracadabra)          ; @r{Still globally void.}
+     @result{} nil
+@end group
+@group
+(setq abracadabra 5)           ; @r{Make it globally nonvoid.}
+     @result{} 5
+@end group
+@group
+(boundp 'abracadabra)
+     @result{} t
+@end group
+@end smallexample
+@end defun
+
+@node Defining Variables
+@section Defining Global Variables
+@cindex variable definition
+
+  You may announce your intention to use a symbol as a global variable
+with a @dfn{variable definition}: a special form, either @code{defconst}
+or @code{defvar}.
+
+  In Emacs Lisp, definitions serve three purposes.  First, they inform
+people who read the code that certain symbols are @emph{intended} to be
+used a certain way (as variables).  Second, they inform the Lisp system
+of these things, supplying a value and documentation.  Third, they
+provide information to utilities such as @code{etags} and
+@code{make-docfile}, which create data bases of the functions and
+variables in a program.
+
+  The difference between @code{defconst} and @code{defvar} is primarily
+a matter of intent, serving to inform human readers of whether the value
+should ever change.  Emacs Lisp does not restrict the ways in which a
+variable can be used based on @code{defconst} or @code{defvar}
+declarations.  However, it does make a difference for initialization:
+@code{defconst} unconditionally initializes the variable, while
+@code{defvar} initializes it only if it is void.
+
+@ignore
+  One would expect user option variables to be defined with
+@code{defconst}, since programs do not change them.  Unfortunately, this
+has bad results if the definition is in a library that is not preloaded:
+@code{defconst} would override any prior value when the library is
+loaded.  Users would like to be able to set user options in their init
+files, and override the default values given in the definitions.  For
+this reason, user options must be defined with @code{defvar}.
+@end ignore
+
+@defspec defvar symbol [value [doc-string]]
+This special form defines @var{symbol} as a variable and can also
+initialize and document it.  The definition informs a person reading
+your code that @var{symbol} is used as a variable that might be set or
+changed.  Note that @var{symbol} is not evaluated; the symbol to be
+defined must appear explicitly in the @code{defvar}.
+
+If @var{symbol} is void and @var{value} is specified, @code{defvar}
+evaluates it and sets @var{symbol} to the result.  But if @var{symbol}
+already has a value (i.e., it is not void), @var{value} is not even
+evaluated, and @var{symbol}'s value remains unchanged.  If @var{value}
+is omitted, the value of @var{symbol} is not changed in any case.
+
+If @var{symbol} has a buffer-local binding in the current buffer,
+@code{defvar} operates on the default value, which is buffer-independent,
+not the current (buffer-local) binding.  It sets the default value if
+the default value is void.  @xref{Buffer-Local Variables}.
+
+When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
+Emacs Lisp mode (@code{eval-defun}), a special feature of
+@code{eval-defun} arranges to set the variable unconditionally, without
+testing whether its value is void.
+
+If the @var{doc-string} argument appears, it specifies the documentation
+for the variable.  (This opportunity to specify documentation is one of
+the main benefits of defining the variable.)  The documentation is
+stored in the symbol's @code{variable-documentation} property.  The
+Emacs help functions (@pxref{Documentation}) look for this property.
+
+If the variable is a user option that users would want to set
+interactively, you should use @samp{*} as the first character of
+@var{doc-string}.  This lets users set the variable conveniently using
+the @code{set-variable} command.  Note that you should nearly always
+use @code{defcustom} instead of @code{defvar} to define these
+variables, so that users can use @kbd{M-x customize} and related
+commands to set them.  @xref{Customization}.
+
+Here are some examples.  This form defines @code{foo} but does not
+initialize it:
+
+@example
+@group
+(defvar foo)
+     @result{} foo
+@end group
+@end example
+
+This example initializes the value of @code{bar} to @code{23}, and gives
+it a documentation string:
+
+@example
+@group
+(defvar bar 23
+  "The normal weight of a bar.")
+     @result{} bar
+@end group
+@end example
+
+The following form changes the documentation string for @code{bar},
+making it a user option, but does not change the value, since @code{bar}
+already has a value.  (The addition @code{(1+ nil)} would get an error
+if it were evaluated, but since it is not evaluated, there is no error.)
+
+@example
+@group
+(defvar bar (1+ nil)
+  "*The normal weight of a bar.")
+     @result{} bar
+@end group
+@group
+bar
+     @result{} 23
+@end group
+@end example
+
+Here is an equivalent expression for the @code{defvar} special form:
+
+@example
+@group
+(defvar @var{symbol} @var{value} @var{doc-string})
+@equiv{}
+(progn
+  (if (not (boundp '@var{symbol}))
+      (setq @var{symbol} @var{value}))
+  (if '@var{doc-string}
+    (put '@var{symbol} 'variable-documentation '@var{doc-string}))
+  '@var{symbol})
+@end group
+@end example
+
+The @code{defvar} form returns @var{symbol}, but it is normally used
+at top level in a file where its value does not matter.
+@end defspec
+
+@defspec defconst symbol value [doc-string]
+This special form defines @var{symbol} as a value and initializes it.
+It informs a person reading your code that @var{symbol} has a standard
+global value, established here, that should not be changed by the user
+or by other programs.  Note that @var{symbol} is not evaluated; the
+symbol to be defined must appear explicitly in the @code{defconst}.
+
+@code{defconst} always evaluates @var{value}, and sets the value of
+@var{symbol} to the result.  If @var{symbol} does have a buffer-local
+binding in the current buffer, @code{defconst} sets the default value,
+not the buffer-local value.  (But you should not be making
+buffer-local bindings for a symbol that is defined with
+@code{defconst}.)
+
+Here, @code{pi} is a constant that presumably ought not to be changed
+by anyone (attempts by the Indiana State Legislature notwithstanding).
+As the second form illustrates, however, this is only advisory.
+
+@example
+@group
+(defconst pi 3.1415 "Pi to five places.")
+     @result{} pi
+@end group
+@group
+(setq pi 3)
+     @result{} pi
+@end group
+@group
+pi
+     @result{} 3
+@end group
+@end example
+@end defspec
+
+@defun user-variable-p variable
+@cindex user option
+This function returns @code{t} if @var{variable} is a user option---a
+variable intended to be set by the user for customization---and
+@code{nil} otherwise.  (Variables other than user options exist for the
+internal purposes of Lisp programs, and users need not know about them.)
+
+User option variables are distinguished from other variables either
+though being declared using @code{defcustom}@footnote{They may also be
+declared equivalently in @file{cus-start.el}.} or by the first character
+of their @code{variable-documentation} property.  If the property exists
+and is a string, and its first character is @samp{*}, then the variable
+is a user option.  Aliases of user options are also user options.
+@end defun
+
+@kindex variable-interactive
+  If a user option variable has a @code{variable-interactive} property,
+the @code{set-variable} command uses that value to control reading the
+new value for the variable.  The property's value is used as if it were
+specified in @code{interactive} (@pxref{Using Interactive}).  However,
+this feature is largely obsoleted by @code{defcustom}
+(@pxref{Customization}).
+
+  @strong{Warning:} If the @code{defconst} and @code{defvar} special
+forms are used while the variable has a local binding (made with
+@code{let}, or a function argument), they set the local-binding's
+value; the top-level binding is not changed.  This is not what you
+usually want.  To prevent it, use these special forms at top level in
+a file, where normally no local binding is in effect, and make sure to
+load the file before making a local binding for the variable.
+
+@node Tips for Defining
+@section Tips for Defining Variables Robustly
+
+  When you define a variable whose value is a function, or a list of
+functions, use a name that ends in @samp{-function} or
+@samp{-functions}, respectively.
+
+  There are several other variable name conventions;
+here is a complete list:
+
+@table @samp
+@item @dots{}-hook
+The variable is a normal hook (@pxref{Hooks}).
+
+@item @dots{}-function
+The value is a function.
+
+@item @dots{}-functions
+The value is a list of functions.
+
+@item @dots{}-form
+The value is a form (an expression).
+
+@item @dots{}-forms
+The value is a list of forms (expressions).
+
+@item @dots{}-predicate
+The value is a predicate---a function of one argument that returns
+non-@code{nil} for ``good'' arguments and @code{nil} for ``bad''
+arguments.
+
+@item @dots{}-flag
+The value is significant only as to whether it is @code{nil} or not.
+
+@item @dots{}-program
+The value is a program name.
+
+@item @dots{}-command
+The value is a whole shell command.
+
+@item @dots{}-switches
+The value specifies options for a command.
+@end table
+
+  When you define a variable, always consider whether you should mark
+it as ``risky''; see @ref{File Local Variables}.
+
+  When defining and initializing a variable that holds a complicated
+value (such as a keymap with bindings in it), it's best to put the
+entire computation of the value into the @code{defvar}, like this:
+
+@example
+(defvar my-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map "\C-c\C-a" 'my-command)
+    @dots{}
+    map)
+  @var{docstring})
+@end example
+
+@noindent
+This method has several benefits.  First, if the user quits while
+loading the file, the variable is either still uninitialized or
+initialized properly, never in-between.  If it is still uninitialized,
+reloading the file will initialize it properly.  Second, reloading the
+file once the variable is initialized will not alter it; that is
+important if the user has run hooks to alter part of the contents (such
+as, to rebind keys).  Third, evaluating the @code{defvar} form with
+@kbd{C-M-x} @emph{will} reinitialize the map completely.
+
+  Putting so much code in the @code{defvar} form has one disadvantage:
+it puts the documentation string far away from the line which names the
+variable.  Here's a safe way to avoid that:
+
+@example
+(defvar my-mode-map nil
+  @var{docstring})
+(unless my-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map "\C-c\C-a" 'my-command)
+    @dots{}
+    (setq my-mode-map map)))
+@end example
+
+@noindent
+This has all the same advantages as putting the initialization inside
+the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
+each form, if you do want to reinitialize the variable.
+
+  But be careful not to write the code like this:
+
+@example
+(defvar my-mode-map nil
+  @var{docstring})
+(unless my-mode-map
+  (setq my-mode-map (make-sparse-keymap))
+  (define-key my-mode-map "\C-c\C-a" 'my-command)
+  @dots{})
+@end example
+
+@noindent
+This code sets the variable, then alters it, but it does so in more than
+one step.  If the user quits just after the @code{setq}, that leaves the
+variable neither correctly initialized nor void nor @code{nil}.  Once
+that happens, reloading the file will not initialize the variable; it
+will remain incomplete.
+
+@node Accessing Variables
+@section Accessing Variable Values
+
+  The usual way to reference a variable is to write the symbol which
+names it (@pxref{Symbol Forms}).  This requires you to specify the
+variable name when you write the program.  Usually that is exactly what
+you want to do.  Occasionally you need to choose at run time which
+variable to reference; then you can use @code{symbol-value}.
+
+@defun symbol-value symbol
+This function returns the value of @var{symbol}.  This is the value in
+the innermost local binding of the symbol, or its global value if it
+has no local bindings.
+
+@example
+@group
+(setq abracadabra 5)
+     @result{} 5
+@end group
+@group
+(setq foo 9)
+     @result{} 9
+@end group
+
+@group
+;; @r{Here the symbol @code{abracadabra}}
+;;   @r{is the symbol whose value is examined.}
+(let ((abracadabra 'foo))
+  (symbol-value 'abracadabra))
+     @result{} foo
+@end group
+
+@group
+;; @r{Here, the value of @code{abracadabra},}
+;;   @r{which is @code{foo},}
+;;   @r{is the symbol whose value is examined.}
+(let ((abracadabra 'foo))
+  (symbol-value abracadabra))
+     @result{} 9
+@end group
+
+@group
+(symbol-value 'abracadabra)
+     @result{} 5
+@end group
+@end example
+
+A @code{void-variable} error is signaled if the current binding of
+@var{symbol} is void.
+@end defun
+
+@node Setting Variables
+@section How to Alter a Variable Value
+
+  The usual way to change the value of a variable is with the special
+form @code{setq}.  When you need to compute the choice of variable at
+run time, use the function @code{set}.
+
+@defspec setq [symbol form]@dots{}
+This special form is the most common method of changing a variable's
+value.  Each @var{symbol} is given a new value, which is the result of
+evaluating the corresponding @var{form}.  The most-local existing
+binding of the symbol is changed.
+
+@code{setq} does not evaluate @var{symbol}; it sets the symbol that you
+write.  We say that this argument is @dfn{automatically quoted}.  The
+@samp{q} in @code{setq} stands for ``quoted.''
+
+The value of the @code{setq} form is the value of the last @var{form}.
+
+@example
+@group
+(setq x (1+ 2))
+     @result{} 3
+@end group
+x                   ; @r{@code{x} now has a global value.}
+     @result{} 3
+@group
+(let ((x 5))
+  (setq x 6)        ; @r{The local binding of @code{x} is set.}
+  x)
+     @result{} 6
+@end group
+x                   ; @r{The global value is unchanged.}
+     @result{} 3
+@end example
+
+Note that the first @var{form} is evaluated, then the first
+@var{symbol} is set, then the second @var{form} is evaluated, then the
+second @var{symbol} is set, and so on:
+
+@example
+@group
+(setq x 10          ; @r{Notice that @code{x} is set before}
+      y (1+ x))     ;   @r{the value of @code{y} is computed.}
+     @result{} 11
+@end group
+@end example
+@end defspec
+
+@defun set symbol value
+This function sets @var{symbol}'s value to @var{value}, then returns
+@var{value}.  Since @code{set} is a function, the expression written for
+@var{symbol} is evaluated to obtain the symbol to set.
+
+The most-local existing binding of the variable is the binding that is
+set; shadowed bindings are not affected.
+
+@example
+@group
+(set one 1)
+@error{} Symbol's value as variable is void: one
+@end group
+@group
+(set 'one 1)
+     @result{} 1
+@end group
+@group
+(set 'two 'one)
+     @result{} one
+@end group
+@group
+(set two 2)         ; @r{@code{two} evaluates to symbol @code{one}.}
+     @result{} 2
+@end group
+@group
+one                 ; @r{So it is @code{one} that was set.}
+     @result{} 2
+(let ((one 1))      ; @r{This binding of @code{one} is set,}
+  (set 'one 3)      ;   @r{not the global value.}
+  one)
+     @result{} 3
+@end group
+@group
+one
+     @result{} 2
+@end group
+@end example
+
+If @var{symbol} is not actually a symbol, a @code{wrong-type-argument}
+error is signaled.
+
+@example
+(set '(x y) 'z)
+@error{} Wrong type argument: symbolp, (x y)
+@end example
+
+Logically speaking, @code{set} is a more fundamental primitive than
+@code{setq}.  Any use of @code{setq} can be trivially rewritten to use
+@code{set}; @code{setq} could even be defined as a macro, given the
+availability of @code{set}.  However, @code{set} itself is rarely used;
+beginners hardly need to know about it.  It is useful only for choosing
+at run time which variable to set.  For example, the command
+@code{set-variable}, which reads a variable name from the user and then
+sets the variable, needs to use @code{set}.
+
+@cindex CL note---@code{set} local
+@quotation
+@b{Common Lisp note:} In Common Lisp, @code{set} always changes the
+symbol's ``special'' or dynamic value, ignoring any lexical bindings.
+In Emacs Lisp, all variables and all bindings are dynamic, so @code{set}
+always affects the most local existing binding.
+@end quotation
+@end defun
+
+@node Variable Scoping
+@section Scoping Rules for Variable Bindings
+
+  A given symbol @code{foo} can have several local variable bindings,
+established at different places in the Lisp program, as well as a global
+binding.  The most recently established binding takes precedence over
+the others.
+
+@cindex scope
+@cindex extent
+@cindex dynamic scoping
+@cindex lexical scoping
+  Local bindings in Emacs Lisp have @dfn{indefinite scope} and
+@dfn{dynamic extent}.  @dfn{Scope} refers to @emph{where} textually in
+the source code the binding can be accessed.  ``Indefinite scope'' means
+that any part of the program can potentially access the variable
+binding.  @dfn{Extent} refers to @emph{when}, as the program is
+executing, the binding exists.  ``Dynamic extent'' means that the binding
+lasts as long as the activation of the construct that established it.
+
+  The combination of dynamic extent and indefinite scope is called
+@dfn{dynamic scoping}.  By contrast, most programming languages use
+@dfn{lexical scoping}, in which references to a local variable must be
+located textually within the function or block that binds the variable.
+
+@cindex CL note---special variables
+@quotation
+@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are
+dynamically scoped, like all variables in Emacs Lisp.
+@end quotation
+
+@menu
+* Scope::          Scope means where in the program a value is visible.
+                     Comparison with other languages.
+* Extent::         Extent means how long in time a value exists.
+* Impl of Scope::  Two ways to implement dynamic scoping.
+* Using Scoping::  How to use dynamic scoping carefully and avoid problems.
+@end menu
+
+@node Scope
+@subsection Scope
+
+  Emacs Lisp uses @dfn{indefinite scope} for local variable bindings.
+This means that any function anywhere in the program text might access a
+given binding of a variable.  Consider the following function
+definitions:
+
+@example
+@group
+(defun binder (x)   ; @r{@code{x} is bound in @code{binder}.}
+   (foo 5))         ; @r{@code{foo} is some other function.}
+@end group
+
+@group
+(defun user ()      ; @r{@code{x} is used ``free'' in @code{user}.}
+  (list x))
+@end group
+@end example
+
+  In a lexically scoped language, the binding of @code{x} in
+@code{binder} would never be accessible in @code{user}, because
+@code{user} is not textually contained within the function
+@code{binder}.  However, in dynamically-scoped Emacs Lisp, @code{user}
+may or may not refer to the binding of @code{x} established in
+@code{binder}, depending on the circumstances:
+
+@itemize @bullet
+@item
+If we call @code{user} directly without calling @code{binder} at all,
+then whatever binding of @code{x} is found, it cannot come from
+@code{binder}.
+
+@item
+If we define @code{foo} as follows and then call @code{binder}, then the
+binding made in @code{binder} will be seen in @code{user}:
+
+@example
+@group
+(defun foo (lose)
+  (user))
+@end group
+@end example
+
+@item
+However, if we define @code{foo} as follows and then call @code{binder},
+then the binding made in @code{binder} @emph{will not} be seen in
+@code{user}:
+
+@example
+(defun foo (x)
+  (user))
+@end example
+
+@noindent
+Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
+(The binding in @code{foo} is said to @dfn{shadow} the one made in
+@code{binder}.)  Therefore, @code{user} will access the @code{x} bound
+by @code{foo} instead of the one bound by @code{binder}.
+@end itemize
+
+Emacs Lisp uses dynamic scoping because simple implementations of
+lexical scoping are slow.  In addition, every Lisp system needs to offer
+dynamic scoping at least as an option; if lexical scoping is the norm,
+there must be a way to specify dynamic scoping instead for a particular
+variable.  It might not be a bad thing for Emacs to offer both, but
+implementing it with dynamic scoping only was much easier.
+
+@node Extent
+@subsection Extent
+
+  @dfn{Extent} refers to the time during program execution that a
+variable name is valid.  In Emacs Lisp, a variable is valid only while
+the form that bound it is executing.  This is called @dfn{dynamic
+extent}.  ``Local'' or ``automatic'' variables in most languages,
+including C and Pascal, have dynamic extent.
+
+  One alternative to dynamic extent is @dfn{indefinite extent}.  This
+means that a variable binding can live on past the exit from the form
+that made the binding.  Common Lisp and Scheme, for example, support
+this, but Emacs Lisp does not.
+
+  To illustrate this, the function below, @code{make-add}, returns a
+function that purports to add @var{n} to its own argument @var{m}.  This
+would work in Common Lisp, but it does not do the job in Emacs Lisp,
+because after the call to @code{make-add} exits, the variable @code{n}
+is no longer bound to the actual argument 2.
+
+@example
+(defun make-add (n)
+    (function (lambda (m) (+ n m))))  ; @r{Return a function.}
+     @result{} make-add
+(fset 'add2 (make-add 2))  ; @r{Define function @code{add2}}
+                           ;   @r{with @code{(make-add 2)}.}
+     @result{} (lambda (m) (+ n m))
+(add2 4)                   ; @r{Try to add 2 to 4.}
+@error{} Symbol's value as variable is void: n
+@end example
+
+@cindex closures not available
+  Some Lisp dialects have ``closures,'' objects that are like functions
+but record additional variable bindings.  Emacs Lisp does not have
+closures.
+
+@node Impl of Scope
+@subsection Implementation of Dynamic Scoping
+@cindex deep binding
+
+  A simple sample implementation (which is not how Emacs Lisp actually
+works) may help you understand dynamic binding.  This technique is
+called @dfn{deep binding} and was used in early Lisp systems.
+
+  Suppose there is a stack of bindings, which are variable-value pairs.
+At entry to a function or to a @code{let} form, we can push bindings
+onto the stack for the arguments or local variables created there.  We
+can pop those bindings from the stack at exit from the binding
+construct.
+
+  We can find the value of a variable by searching the stack from top to
+bottom for a binding for that variable; the value from that binding is
+the value of the variable.  To set the variable, we search for the
+current binding, then store the new value into that binding.
+
+  As you can see, a function's bindings remain in effect as long as it
+continues execution, even during its calls to other functions.  That is
+why we say the extent of the binding is dynamic.  And any other function
+can refer to the bindings, if it uses the same variables while the
+bindings are in effect.  That is why we say the scope is indefinite.
+
+@cindex shallow binding
+  The actual implementation of variable scoping in GNU Emacs Lisp uses a
+technique called @dfn{shallow binding}.  Each variable has a standard
+place in which its current value is always found---the value cell of the
+symbol.
+
+  In shallow binding, setting the variable works by storing a value in
+the value cell.  Creating a new binding works by pushing the old value
+(belonging to a previous binding) onto a stack, and storing the new
+local value in the value cell.  Eliminating a binding works by popping
+the old value off the stack, into the value cell.
+
+  We use shallow binding because it has the same results as deep
+binding, but runs faster, since there is never a need to search for a
+binding.
+
+@node Using Scoping
+@subsection Proper Use of Dynamic Scoping
+
+  Binding a variable in one function and using it in another is a
+powerful technique, but if used without restraint, it can make programs
+hard to understand.  There are two clean ways to use this technique:
+
+@itemize @bullet
+@item
+Use or bind the variable only in a few related functions, written close
+together in one file.  Such a variable is used for communication within
+one program.
+
+You should write comments to inform other programmers that they can see
+all uses of the variable before them, and to advise them not to add uses
+elsewhere.
+
+@item
+Give the variable a well-defined, documented meaning, and make all
+appropriate functions refer to it (but not bind it or set it) wherever
+that meaning is relevant.  For example, the variable
+@code{case-fold-search} is defined as ``non-@code{nil} means ignore case
+when searching''; various search and replace functions refer to it
+directly or through their subroutines, but do not bind or set it.
+
+Then you can bind the variable in other programs, knowing reliably what
+the effect will be.
+@end itemize
+
+  In either case, you should define the variable with @code{defvar}.
+This helps other people understand your program by telling them to look
+for inter-function usage.  It also avoids a warning from the byte
+compiler.  Choose the variable's name to avoid name conflicts---don't
+use short names like @code{x}.
+
+@node Buffer-Local Variables
+@section Buffer-Local Variables
+@cindex variable, buffer-local
+@cindex buffer-local variables
+
+  Global and local variable bindings are found in most programming
+languages in one form or another.  Emacs, however, also supports additional,
+unusual kinds of variable binding: @dfn{buffer-local} bindings, which
+apply only in one buffer, and @dfn{frame-local} bindings, which apply only in
+one frame.  Having different values for a variable in different buffers
+and/or frames is an important customization method.
+
+  This section describes buffer-local bindings; for frame-local
+bindings, see the following section, @ref{Frame-Local Variables}.  (A few
+variables have bindings that are local to each terminal; see
+@ref{Multiple Displays}.)
+
+@menu
+* Intro to Buffer-Local::      Introduction and concepts.
+* Creating Buffer-Local::      Creating and destroying buffer-local bindings.
+* Default Value::              The default value is seen in buffers
+                                 that don't have their own buffer-local values.
+@end menu
+
+@node Intro to Buffer-Local
+@subsection Introduction to Buffer-Local Variables
+
+  A buffer-local variable has a buffer-local binding associated with a
+particular buffer.  The binding is in effect when that buffer is
+current; otherwise, it is not in effect.  If you set the variable while
+a buffer-local binding is in effect, the new value goes in that binding,
+so its other bindings are unchanged.  This means that the change is
+visible only in the buffer where you made it.
+
+  The variable's ordinary binding, which is not associated with any
+specific buffer, is called the @dfn{default binding}.  In most cases,
+this is the global binding.
+
+  A variable can have buffer-local bindings in some buffers but not in
+other buffers.  The default binding is shared by all the buffers that
+don't have their own bindings for the variable.  (This includes all
+newly-created buffers.)  If you set the variable in a buffer that does
+not have a buffer-local binding for it, this sets the default binding
+(assuming there are no frame-local bindings to complicate the matter),
+so the new value is visible in all the buffers that see the default
+binding.
+
+  The most common use of buffer-local bindings is for major modes to change
+variables that control the behavior of commands.  For example, C mode and
+Lisp mode both set the variable @code{paragraph-start} to specify that only
+blank lines separate paragraphs.  They do this by making the variable
+buffer-local in the buffer that is being put into C mode or Lisp mode, and
+then setting it to the new value for that mode.  @xref{Major Modes}.
+
+  The usual way to make a buffer-local binding is with
+@code{make-local-variable}, which is what major mode commands typically
+use.  This affects just the current buffer; all other buffers (including
+those yet to be created) will continue to share the default value unless
+they are explicitly given their own buffer-local bindings.
+
+@cindex automatically buffer-local
+  A more powerful operation is to mark the variable as
+@dfn{automatically buffer-local} by calling
+@code{make-variable-buffer-local}.  You can think of this as making the
+variable local in all buffers, even those yet to be created.  More
+precisely, the effect is that setting the variable automatically makes
+the variable local to the current buffer if it is not already so.  All
+buffers start out by sharing the default value of the variable as usual,
+but setting the variable creates a buffer-local binding for the current
+buffer.  The new value is stored in the buffer-local binding, leaving
+the default binding untouched.  This means that the default value cannot
+be changed with @code{setq} in any buffer; the only way to change it is
+with @code{setq-default}.
+
+  @strong{Warning:} When a variable has buffer-local or frame-local
+bindings in one or more buffers, @code{let} rebinds the binding that's
+currently in effect.  For instance, if the current buffer has a
+buffer-local value, @code{let} temporarily rebinds that.  If no
+buffer-local or frame-local bindings are in effect, @code{let} rebinds
+the default value.  If inside the @code{let} you then change to a
+different current buffer in which a different binding is in effect,
+you won't see the @code{let} binding any more.  And if you exit the
+@code{let} while still in the other buffer, you won't see the
+unbinding occur (though it will occur properly).  Here is an example
+to illustrate:
+
+@example
+@group
+(setq foo 'g)
+(set-buffer "a")
+(make-local-variable 'foo)
+@end group
+(setq foo 'a)
+(let ((foo 'temp))
+  ;; foo @result{} 'temp  ; @r{let binding in buffer @samp{a}}
+  (set-buffer "b")
+  ;; foo @result{} 'g     ; @r{the global value since foo is not local in @samp{b}}
+  @var{body}@dots{})
+@group
+foo @result{} 'g        ; @r{exiting restored the local value in buffer @samp{a},}
+                 ; @r{but we don't see that in buffer @samp{b}}
+@end group
+@group
+(set-buffer "a") ; @r{verify the local value was restored}
+foo @result{} 'a
+@end group
+@end example
+
+  Note that references to @code{foo} in @var{body} access the
+buffer-local binding of buffer @samp{b}.
+
+  When a file specifies local variable values, these become buffer-local
+values when you visit the file.  @xref{File Variables,,, emacs, The
+GNU Emacs Manual}.
+
+@node Creating Buffer-Local
+@subsection Creating and Deleting Buffer-Local Bindings
+
+@deffn Command make-local-variable variable
+This function creates a buffer-local binding in the current buffer for
+@var{variable} (a symbol).  Other buffers are not affected.  The value
+returned is @var{variable}.
+
+@c Emacs 19 feature
+The buffer-local value of @var{variable} starts out as the same value
+@var{variable} previously had.  If @var{variable} was void, it remains
+void.
+
+@example
+@group
+;; @r{In buffer @samp{b1}:}
+(setq foo 5)                ; @r{Affects all buffers.}
+     @result{} 5
+@end group
+@group
+(make-local-variable 'foo)  ; @r{Now it is local in @samp{b1}.}
+     @result{} foo
+@end group
+@group
+foo                         ; @r{That did not change}
+     @result{} 5                   ;   @r{the value.}
+@end group
+@group
+(setq foo 6)                ; @r{Change the value}
+     @result{} 6                   ;   @r{in @samp{b1}.}
+@end group
+@group
+foo
+     @result{} 6
+@end group
+
+@group
+;; @r{In buffer @samp{b2}, the value hasn't changed.}
+(save-excursion
+  (set-buffer "b2")
+  foo)
+     @result{} 5
+@end group
+@end example
+
+Making a variable buffer-local within a @code{let}-binding for that
+variable does not work reliably, unless the buffer in which you do this
+is not current either on entry to or exit from the @code{let}.  This is
+because @code{let} does not distinguish between different kinds of
+bindings; it knows only which variable the binding was made for.
+
+If the variable is terminal-local, this function signals an error.  Such
+variables cannot have buffer-local bindings as well.  @xref{Multiple
+Displays}.
+
+@strong{Warning:} do not use @code{make-local-variable} for a hook
+variable.  The hook variables are automatically made buffer-local as
+needed if you use the @var{local} argument to @code{add-hook} or
+@code{remove-hook}.
+@end deffn
+
+@deffn Command make-variable-buffer-local variable
+This function marks @var{variable} (a symbol) automatically
+buffer-local, so that any subsequent attempt to set it will make it
+local to the current buffer at the time.
+
+A peculiar wrinkle of this feature is that binding the variable (with
+@code{let} or other binding constructs) does not create a buffer-local
+binding for it.  Only setting the variable (with @code{set} or
+@code{setq}), while the variable does not have a @code{let}-style
+binding that was made in the current buffer, does so.
+
+If @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}.  If @var{variable}
+already has a default value, that value remains unchanged.
+Subsequently calling @code{makunbound} on @var{variable} will result
+in a void buffer-local value and leave the default value unaffected.
+
+The value returned is @var{variable}.
+
+@strong{Warning:} Don't assume that you should use
+@code{make-variable-buffer-local} for user-option variables, simply
+because users @emph{might} want to customize them differently in
+different buffers.  Users can make any variable local, when they wish
+to.  It is better to leave the choice to them.
+
+The time to use @code{make-variable-buffer-local} is when it is crucial
+that no two buffers ever share the same binding.  For example, when a
+variable is used for internal purposes in a Lisp program which depends
+on having separate values in separate buffers, then using
+@code{make-variable-buffer-local} can be the best solution.
+@end deffn
+
+@defun local-variable-p variable &optional buffer
+This returns @code{t} if @var{variable} is buffer-local in buffer
+@var{buffer} (which defaults to the current buffer); otherwise,
+@code{nil}.
+@end defun
+
+@defun local-variable-if-set-p variable &optional buffer
+This returns @code{t} if @var{variable} will become buffer-local in
+buffer @var{buffer} (which defaults to the current buffer) if it is
+set there.
+@end defun
+
+@defun buffer-local-value variable buffer
+This function returns the buffer-local binding of @var{variable} (a
+symbol) in buffer @var{buffer}.  If @var{variable} does not have a
+buffer-local binding in buffer @var{buffer}, it returns the default
+value (@pxref{Default Value}) of @var{variable} instead.
+@end defun
+
+@defun buffer-local-variables &optional buffer
+This function returns a list describing the buffer-local variables in
+buffer @var{buffer}.  (If @var{buffer} is omitted, the current buffer is
+used.)  It returns an association list (@pxref{Association Lists}) in
+which each element contains one buffer-local variable and its value.
+However, when a variable's buffer-local binding in @var{buffer} is void,
+then the variable appears directly in the resulting list.
+
+@example
+@group
+(make-local-variable 'foobar)
+(makunbound 'foobar)
+(make-local-variable 'bind-me)
+(setq bind-me 69)
+@end group
+(setq lcl (buffer-local-variables))
+    ;; @r{First, built-in variables local in all buffers:}
+@result{} ((mark-active . nil)
+    (buffer-undo-list . nil)
+    (mode-name . "Fundamental")
+    @dots{}
+@group
+    ;; @r{Next, non-built-in buffer-local variables.}
+    ;; @r{This one is buffer-local and void:}
+    foobar
+    ;; @r{This one is buffer-local and nonvoid:}
+    (bind-me . 69))
+@end group
+@end example
+
+Note that storing new values into the @sc{cdr}s of cons cells in this
+list does @emph{not} change the buffer-local values of the variables.
+@end defun
+
+@deffn Command kill-local-variable variable
+This function deletes the buffer-local binding (if any) for
+@var{variable} (a symbol) in the current buffer.  As a result, the
+default binding of @var{variable} becomes visible in this buffer.  This
+typically results in a change in the value of @var{variable}, since the
+default value is usually different from the buffer-local value just
+eliminated.
+
+If you kill the buffer-local binding of a variable that automatically
+becomes buffer-local when set, this makes the default value visible in
+the current buffer.  However, if you set the variable again, that will
+once again create a buffer-local binding for it.
+
+@code{kill-local-variable} returns @var{variable}.
+
+This function is a command because it is sometimes useful to kill one
+buffer-local variable interactively, just as it is useful to create
+buffer-local variables interactively.
+@end deffn
+
+@defun kill-all-local-variables
+This function eliminates all the buffer-local variable bindings of the
+current buffer except for variables marked as ``permanent.''  As a
+result, the buffer will see the default values of most variables.
+
+This function also resets certain other information pertaining to the
+buffer: it sets the local keymap to @code{nil}, the syntax table to the
+value of @code{(standard-syntax-table)}, the case table to
+@code{(standard-case-table)}, and the abbrev table to the value of
+@code{fundamental-mode-abbrev-table}.
+
+The very first thing this function does is run the normal hook
+@code{change-major-mode-hook} (see below).
+
+Every major mode command begins by calling this function, which has the
+effect of switching to Fundamental mode and erasing most of the effects
+of the previous major mode.  To ensure that this does its job, the
+variables that major modes set should not be marked permanent.
+
+@code{kill-all-local-variables} returns @code{nil}.
+@end defun
+
+@defvar change-major-mode-hook
+The function @code{kill-all-local-variables} runs this normal hook
+before it does anything else.  This gives major modes a way to arrange
+for something special to be done if the user switches to a different
+major mode.  It is also useful for buffer-specific minor modes
+that should be forgotten if the user changes the major mode.
+
+For best results, make this variable buffer-local, so that it will
+disappear after doing its job and will not interfere with the
+subsequent major mode.  @xref{Hooks}.
+@end defvar
+
+@c Emacs 19 feature
+@cindex permanent local variable
+A buffer-local variable is @dfn{permanent} if the variable name (a
+symbol) has a @code{permanent-local} property that is non-@code{nil}.
+Permanent locals are appropriate for data pertaining to where the file
+came from or how to save it, rather than with how to edit the contents.
+
+@node Default Value
+@subsection The Default Value of a Buffer-Local Variable
+@cindex default value
+
+  The global value of a variable with buffer-local bindings is also
+called the @dfn{default} value, because it is the value that is in
+effect whenever neither the current buffer nor the selected frame has
+its own binding for the variable.
+
+  The functions @code{default-value} and @code{setq-default} access and
+change a variable's default value regardless of whether the current
+buffer has a buffer-local binding.  For example, you could use
+@code{setq-default} to change the default setting of
+@code{paragraph-start} for most buffers; and this would work even when
+you are in a C or Lisp mode buffer that has a buffer-local value for
+this variable.
+
+@c Emacs 19 feature
+  The special forms @code{defvar} and @code{defconst} also set the
+default value (if they set the variable at all), rather than any
+buffer-local or frame-local value.
+
+@defun default-value symbol
+This function returns @var{symbol}'s default value.  This is the value
+that is seen in buffers and frames that do not have their own values for
+this variable.  If @var{symbol} is not buffer-local, this is equivalent
+to @code{symbol-value} (@pxref{Accessing Variables}).
+@end defun
+
+@c Emacs 19 feature
+@defun default-boundp symbol
+The function @code{default-boundp} tells you whether @var{symbol}'s
+default value is nonvoid.  If @code{(default-boundp 'foo)} returns
+@code{nil}, then @code{(default-value 'foo)} would get an error.
+
+@code{default-boundp} is to @code{default-value} as @code{boundp} is to
+@code{symbol-value}.
+@end defun
+
+@defspec setq-default [symbol form]@dots{}
+This special form gives each @var{symbol} a new default value, which is
+the result of evaluating the corresponding @var{form}.  It does not
+evaluate @var{symbol}, but does evaluate @var{form}.  The value of the
+@code{setq-default} form is the value of the last @var{form}.
+
+If a @var{symbol} is not buffer-local for the current buffer, and is not
+marked automatically buffer-local, @code{setq-default} has the same
+effect as @code{setq}.  If @var{symbol} is buffer-local for the current
+buffer, then this changes the value that other buffers will see (as long
+as they don't have a buffer-local value), but not the value that the
+current buffer sees.
+
+@example
+@group
+;; @r{In buffer @samp{foo}:}
+(make-local-variable 'buffer-local)
+     @result{} buffer-local
+@end group
+@group
+(setq buffer-local 'value-in-foo)
+     @result{} value-in-foo
+@end group
+@group
+(setq-default buffer-local 'new-default)
+     @result{} new-default
+@end group
+@group
+buffer-local
+     @result{} value-in-foo
+@end group
+@group
+(default-value 'buffer-local)
+     @result{} new-default
+@end group
+
+@group
+;; @r{In (the new) buffer @samp{bar}:}
+buffer-local
+     @result{} new-default
+@end group
+@group
+(default-value 'buffer-local)
+     @result{} new-default
+@end group
+@group
+(setq buffer-local 'another-default)
+     @result{} another-default
+@end group
+@group
+(default-value 'buffer-local)
+     @result{} another-default
+@end group
+
+@group
+;; @r{Back in buffer @samp{foo}:}
+buffer-local
+     @result{} value-in-foo
+(default-value 'buffer-local)
+     @result{} another-default
+@end group
+@end example
+@end defspec
+
+@defun set-default symbol value
+This function is like @code{setq-default}, except that @var{symbol} is
+an ordinary evaluated argument.
+
+@example
+@group
+(set-default (car '(a b c)) 23)
+     @result{} 23
+@end group
+@group
+(default-value 'a)
+     @result{} 23
+@end group
+@end example
+@end defun
+
+@node Frame-Local Variables
+@section Frame-Local Variables
+@cindex frame-local variables
+
+  Just as variables can have buffer-local bindings, they can also have
+frame-local bindings.  These bindings belong to one frame, and are in
+effect when that frame is selected.  Frame-local bindings are actually
+frame parameters: you create a frame-local binding in a specific frame
+by calling @code{modify-frame-parameters} and specifying the variable
+name as the parameter name.
+
+  To enable frame-local bindings for a certain variable, call the function
+@code{make-variable-frame-local}.
+
+@deffn Command make-variable-frame-local variable
+Enable the use of frame-local bindings for @var{variable}.  This does
+not in itself create any frame-local bindings for the variable; however,
+if some frame already has a value for @var{variable} as a frame
+parameter, that value automatically becomes a frame-local binding.
+
+If @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}.  If @var{variable}
+already has a default value, that value remains unchanged.
+
+If the variable is terminal-local, this function signals an error,
+because such variables cannot have frame-local bindings as well.
+@xref{Multiple Displays}.  A few variables that are implemented
+specially in Emacs can be buffer-local, but can never be frame-local.
+
+This command returns @var{variable}.
+@end deffn
+
+  Buffer-local bindings take precedence over frame-local bindings.  Thus,
+consider a variable @code{foo}: if the current buffer has a buffer-local
+binding for @code{foo}, that binding is active; otherwise, if the
+selected frame has a frame-local binding for @code{foo}, that binding is
+active; otherwise, the default binding of @code{foo} is active.
+
+  Here is an example.  First we prepare a few bindings for @code{foo}:
+
+@example
+(setq f1 (selected-frame))
+(make-variable-frame-local 'foo)
+
+;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
+(set-buffer (get-buffer-create "b1"))
+(make-local-variable 'foo)
+(setq foo '(b 1))
+
+;; @r{Make a frame-local binding for @code{foo} in a new frame.}
+;; @r{Store that frame in @code{f2}.}
+(setq f2 (make-frame))
+(modify-frame-parameters f2 '((foo . (f 2))))
+@end example
+
+  Now we examine @code{foo} in various contexts.  Whenever the
+buffer @samp{b1} is current, its buffer-local binding is in effect,
+regardless of the selected frame:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer-create "b1"))
+foo
+     @result{} (b 1)
+
+(select-frame f2)
+(set-buffer (get-buffer-create "b1"))
+foo
+     @result{} (b 1)
+@end example
+
+@noindent
+Otherwise, the frame gets a chance to provide the binding; when frame
+@code{f2} is selected, its frame-local binding is in effect:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+foo
+     @result{} (f 2)
+@end example
+
+@noindent
+When neither the current buffer nor the selected frame provides
+a binding, the default binding is used:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer "*scratch*"))
+foo
+     @result{} nil
+@end example
+
+@noindent
+When the active binding of a variable is a frame-local binding, setting
+the variable changes that binding.  You can observe the result with
+@code{frame-parameters}:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+(setq foo 'nobody)
+(assq 'foo (frame-parameters f2))
+     @result{} (foo . nobody)
+@end example
+
+@node Future Local Variables
+@section Possible Future Local Variables
+
+  We have considered the idea of bindings that are local to a category
+of frames---for example, all color frames, or all frames with dark
+backgrounds.  We have not implemented them because it is not clear that
+this feature is really useful.  You can get more or less the same
+results by adding a function to @code{after-make-frame-functions}, set up to
+define a particular frame parameter according to the appropriate
+conditions for each frame.
+
+  It would also be possible to implement window-local bindings.  We
+don't know of many situations where they would be useful, and it seems
+that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
+bindings offer a way to handle these situations more robustly.
+
+  If sufficient application is found for either of these two kinds of
+local bindings, we will provide it in a subsequent Emacs version.
+
+@node File Local Variables
+@section File Local Variables
+@cindex file local variables
+
+  A file can specify local variable values; Emacs uses these to create
+buffer-local bindings for those variables in the buffer visiting that
+file.  @xref{File variables, , Local Variables in Files, emacs, The
+GNU Emacs Manual}, for basic information about file local variables.
+This section describes the functions and variables that affect
+processing of file local variables.
+
+@defopt enable-local-variables
+This variable controls whether to process file local variables.
+The possible values are:
+
+@table @asis
+@item @code{t} (the default)
+Set the safe variables, and query (once) about any unsafe variables.
+@item @code{:safe}
+Set only the safe variables and do not query.
+@item @code{:all}
+Set all the variables and do not query.
+@item @code{nil}
+Don't set any variables.
+@item anything else
+Query (once) about all the variables.
+@end table
+@end defopt
+
+@defun hack-local-variables &optional mode-only
+This function parses, and binds or evaluates as appropriate, any local
+variables specified by the contents of the current buffer.  The variable
+@code{enable-local-variables} has its effect here.  However, this
+function does not look for the @samp{mode:} local variable in the
+@w{@samp{-*-}} line.  @code{set-auto-mode} does that, also taking
+@code{enable-local-variables} into account (@pxref{Auto Major Mode}).
+
+If the optional argument @var{mode-only} is non-@code{nil}, then all
+this function does is return @code{t} if the @w{@samp{-*-}} line or
+the local variables list specifies a mode and @code{nil} otherwise.
+It does not set the mode nor any other file local variable.
+@end defun
+
+  If a file local variable could specify a function that would
+be called later, or an expression that would be executed later, simply
+visiting a file could take over your Emacs.  Emacs takes several
+measures to prevent this.
+
+@cindex safe local variable
+  You can specify safe values for a variable with a
+@code{safe-local-variable} property.  The property has to be
+a function of one argument; any value is safe if the function
+returns non-@code{nil} given that value.  Many commonly encountered
+file variables standardly have @code{safe-local-variable} properties,
+including @code{fill-column}, @code{fill-prefix}, and
+@code{indent-tabs-mode}.  For boolean-valued variables that are safe,
+use @code{booleanp} as the property value.  Lambda expressions should
+be quoted so that @code{describe-variable} can display the predicate.
+
+@defopt safe-local-variable-values
+This variable provides another way to mark some variable values as
+safe.  It is a list of cons cells @code{(@var{var} . @var{val})},
+where @var{var} is a variable name and @var{val} is a value which is
+safe for that variable.
+
+When Emacs asks the user whether or not to obey a set of file local
+variable specifications, the user can choose to mark them as safe.
+Doing so adds those variable/value pairs to
+@code{safe-local-variable-values}, and saves it to the user's custom
+file.
+@end defopt
+
+@defun safe-local-variable-p sym val
+This function returns non-@code{nil} if it is safe to give @var{sym}
+the value @var{val}, based on the above criteria.
+@end defun
+
+@c @cindex risky local variable   Duplicates risky-local-variable
+  Some variables are considered @dfn{risky}.  A variable whose name
+ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function},
+@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
+@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist},
+@samp{-program}, or @samp{-predicate} is considered risky.  The
+variables @samp{font-lock-keywords}, @samp{font-lock-keywords}
+followed by a digit, and @samp{font-lock-syntactic-keywords} are also
+considered risky.  Finally, any variable whose name has a
+non-@code{nil} @code{risky-local-variable} property is considered
+risky.
+
+@defun risky-local-variable-p sym
+This function returns non-@code{nil} if @var{sym} is a risky variable,
+based on the above criteria.
+@end defun
+
+  If a variable is risky, it will not be entered automatically into
+@code{safe-local-variable-values} as described above.  Therefore,
+Emacs will always query before setting a risky variable, unless the
+user explicitly allows the setting by customizing
+@code{safe-local-variable-values} directly.
+
+@defvar ignored-local-variables
+This variable holds a list of variables that should not be given local
+values by files.  Any value specified for one of these variables is
+completely ignored.
+@end defvar
+
+  The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
+normally asks for confirmation before handling it.
+
+@defopt enable-local-eval
+This variable controls processing of @samp{Eval:} in @samp{-*-} lines
+or local variables
+lists in files being visited.  A value of @code{t} means process them
+unconditionally; @code{nil} means ignore them; anything else means ask
+the user what to do for each file.  The default value is @code{maybe}.
+@end defopt
+
+@defopt safe-local-eval-forms
+This variable holds a list of expressions that are safe to
+evaluate when found in the @samp{Eval:} ``variable'' in a file
+local variables list.
+@end defopt
+
+  If the expression is a function call and the function has a
+@code{safe-local-eval-function} property, the property value
+determines whether the expression is safe to evaluate.  The property
+value can be a predicate to call to test the expression, a list of
+such predicates (it's safe if any predicate succeeds), or @code{t}
+(always safe provided the arguments are constant).
+
+  Text properties are also potential loopholes, since their values
+could include functions to call.  So Emacs discards all text
+properties from string values specified for file local variables.
+
+@node Variable Aliases
+@section Variable Aliases
+@cindex variable aliases
+
+  It is sometimes useful to make two variables synonyms, so that both
+variables always have the same value, and changing either one also
+changes the other.  Whenever you change the name of a
+variable---either because you realize its old name was not well
+chosen, or because its meaning has partly changed---it can be useful
+to keep the old name as an @emph{alias} of the new one for
+compatibility.  You can do this with @code{defvaralias}.
+
+@defun defvaralias new-alias base-variable &optional docstring
+This function defines the symbol @var{new-alias} as a variable alias
+for symbol @var{base-variable}. This means that retrieving the value
+of @var{new-alias} returns the value of @var{base-variable}, and
+changing the value of @var{new-alias} changes the value of
+@var{base-variable}.  The two aliased variable names always share the
+same value and the same bindings.
+
+If the @var{docstring} argument is non-@code{nil}, it specifies the
+documentation for @var{new-alias}; otherwise, the alias gets the same
+documentation as @var{base-variable} has, if any, unless
+@var{base-variable} is itself an alias, in which case @var{new-alias} gets
+the documentation of the variable at the end of the chain of aliases.
+
+This function returns @var{base-variable}.
+@end defun
+
+  Variable aliases are convenient for replacing an old name for a
+variable with a new name.  @code{make-obsolete-variable} declares that
+the old name is obsolete and therefore that it may be removed at some
+stage in the future.
+
+@defun make-obsolete-variable obsolete-name current-name &optional when
+This function makes the byte-compiler warn that the variable
+@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol, it is
+the variable's new name; then the warning message says to use
+@var{current-name} instead of @var{obsolete-name}.  If @var{current-name}
+is a string, this is the message and there is no replacement variable.
+
+If provided, @var{when} should be a string indicating when the
+variable was first made obsolete---for example, a date or a release
+number.
+@end defun
+
+  You can make two variables synonyms and declare one obsolete at the
+same time using the macro @code{define-obsolete-variable-alias}.
+
+@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring
+This macro marks the variable @var{obsolete-name} as obsolete and also
+makes it an alias for the variable @var{current-name}.  It is
+equivalent to the following:
+
+@example
+(defvaralias @var{obsolete-name} @var{current-name} @var{docstring})
+(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when})
+@end example
+@end defmac
+
+@defun indirect-variable variable
+This function returns the variable at the end of the chain of aliases
+of @var{variable}.  If @var{variable} is not a symbol, or if @var{variable} is
+not defined as an alias, the function returns @var{variable}.
+
+This function signals a @code{cyclic-variable-indirection} error if
+there is a loop in the chain of symbols.
+@end defun
+
+@example
+(defvaralias 'foo 'bar)
+(indirect-variable 'foo)
+     @result{} bar
+(indirect-variable 'bar)
+     @result{} bar
+(setq bar 2)
+bar
+     @result{} 2
+@group
+foo
+     @result{} 2
+@end group
+(setq foo 0)
+bar
+     @result{} 0
+foo
+     @result{} 0
+@end example
+
+@node Variables with Restricted Values
+@section Variables with Restricted Values
+
+  Ordinary Lisp variables can be assigned any value that is a valid
+Lisp object.  However, certain Lisp variables are not defined in Lisp,
+but in C.  Most of these variables are defined in the C code using
+@code{DEFVAR_LISP}.  Like variables defined in Lisp, these can take on
+any value.  However, some variables are defined using
+@code{DEFVAR_INT} or @code{DEFVAR_BOOL}.  @xref{Defining Lisp
+variables in C,, Writing Emacs Primitives}, in particular the
+description of functions of the type @code{syms_of_@var{filename}},
+for a brief discussion of the C implementation.
+
+  Variables of type @code{DEFVAR_BOOL} can only take on the values
+@code{nil} or @code{t}.  Attempting to assign them any other value
+will set them to @code{t}:
+
+@example
+(let ((display-hourglass 5))
+  display-hourglass)
+     @result{} t
+@end example
+
+@defvar byte-boolean-vars
+This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
+@end defvar
+
+  Variables of type @code{DEFVAR_INT} can only take on integer values.
+Attempting to assign them any other value will result in an error:
+
+@example
+(setq window-min-height 5.0)
+@error{} Wrong type argument: integerp, 5.0
+@end example
+
+@ignore
+   arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e
+@end ignore
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
new file mode 100644
index 00000000000..d41b2f076df
--- /dev/null
+++ b/doc/lispref/vol1.texi
@@ -0,0 +1,1507 @@
+\input texinfo  @c -*-texinfo-*-
+@c This file is used for printing the GNU Emacs Lisp Reference Manual
+@c in two volumes.  It is a modified version of elisp.texi.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c %**start of header
+@setfilename elisp
+@settitle GNU Emacs Lisp Reference Manual: Volume 1
+@c %**end of header
+
+@c See two-volume-cross-refs.txt.
+@tex
+\message{Formatting for two volume edition...Volume 1...}
+%
+% Read special toc file, set up in two-volume.make.
+\gdef\tocreadfilename{elisp1-toc-ready.toc}
+%
+% Don't make outlines, they're not needed and \readdatafile can't pay
+% attention to the special definition above.
+\global\let\pdfmakeoutlines=\relax
+%
+% Start volume 1 chapter numbering at 1; this must be listed as chapno0.
+\global\chapno=0
+@end tex
+
+@c Version of the manual and of Emacs.
+@c Please remember to update the edition number in README as well.
+@set VERSION  2.9
+@set EMACSVER 22
+
+@dircategory Emacs
+@direntry
+* Elisp: (elisp).       The Emacs Lisp Reference Manual.
+@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.
+@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
+\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
+
+@c Combine indices.
+@synindex cp fn
+@syncodeindex vr fn
+@syncodeindex ky fn
+@syncodeindex pg fn
+@c We use the "type index" to index new functions and variables.
+@c @syncodeindex tp fn
+
+@copying
+This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@*
+corresponding to Emacs version @value{EMACSVER}.
+
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 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 ``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
+
+@titlepage
+@title GNU Emacs Lisp Reference Manual
+@subtitle Volume 1
+@subtitle For Emacs Version @value{EMACSVER}
+@subtitle Revision @value{VERSION}, June 2007
+
+@author by Bil Lewis, Dan LaLiberte, Richard Stallman
+@author and the GNU Manual Group
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+
+@sp 2
+
+Published by the Free Software Foundation @*
+51 Franklin St, Fifth Floor @*
+Boston, MA 02110-1301 @*
+USA @*
+ISBN 1-882114-74-4
+
+@sp 2
+Cover art by Etienne Suvasa.
+@end titlepage
+
+
+@c Print the tables of contents
+@summarycontents
+@contents
+
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Emacs Lisp
+
+This Info file contains edition @value{VERSION} of the GNU Emacs Lisp
+Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
+@end ifnottex
+
+@menu
+* Introduction::            Introduction and conventions used.
+
+* Lisp Data Types::         Data types of objects in Emacs Lisp.
+* Numbers::                 Numbers and arithmetic functions.
+* Strings and Characters::  Strings, and functions that work on them.
+* Lists::                   Lists, cons cells, and related functions.
+* Sequences Arrays Vectors::  Lists, strings and vectors are called sequences.
+                                Certain functions act on any kind of sequence.
+                                The description of vectors is here as well.
+* Hash Tables::             Very fast lookup-tables.
+* Symbols::                 Symbols represent names, uniquely.
+
+* Evaluation::              How Lisp expressions are evaluated.
+* Control Structures::      Conditionals, loops, nonlocal exits.
+* Variables::               Using symbols in programs to stand for values.
+* Functions::               A function is a Lisp program
+                              that can be invoked from other functions.
+* Macros::                  Macros are a way to extend the Lisp language.
+* Customization::           Writing customization declarations.
+
+* Loading::                 Reading files of Lisp code into Lisp.
+* Byte Compilation::        Compilation makes programs run faster.
+* Advising Functions::      Adding to the definition of a function.
+* Debugging::               Tools and tips for debugging Lisp programs.
+
+* Read and Print::          Converting Lisp objects to text and back.
+* Minibuffers::             Using the minibuffer to read input.
+* Command Loop::            How the editor command loop works,
+                              and how you can call its subroutines.
+* Keymaps::                 Defining the bindings from keys to commands.
+* Modes::                   Defining major and minor modes.
+* Documentation::           Writing and using documentation strings.
+
+* Files::                   Accessing files.
+* Backups and Auto-Saving:: Controlling how backups and auto-save
+                              files are made.
+* Buffers::                 Creating and using buffer objects.
+* Windows::                 Manipulating windows and displaying buffers.
+* Frames::		    Making multiple system-level windows.
+* Positions::               Buffer positions and motion functions.
+* Markers::                 Markers represent positions and update
+                              automatically when the text is changed.
+
+* Text::                    Examining and changing text in buffers.
+* Non-ASCII Characters::    Non-ASCII text in buffers and strings.
+* Searching and Matching::  Searching buffers for strings or regexps.
+* Syntax Tables::           The syntax table controls word and list parsing.
+* Abbrevs::                 How Abbrev mode works, and its data structures.
+
+* Processes::               Running and communicating with subprocesses.
+* Display::	            Features for controlling the screen display.
+* System Interface::        Getting the user id, system type, environment
+                              variables, and other such things.
+
+Appendices
+
+* Antinews::                Info for users downgrading to Emacs 21.
+* GNU Free Documentation License:: The license for this documentation
+* GPL::                     Conditions for copying and changing GNU Emacs.
+* Tips::                    Advice and coding conventions for Emacs Lisp.
+* GNU Emacs Internals::     Building and dumping Emacs;
+                              internal data structures.
+* Standard Errors::         List of all error symbols.
+* Standard Buffer-Local Variables::
+                            List of variables buffer-local in all buffers.
+* Standard Keymaps::        List of standard keymaps.
+* Standard Hooks::          List of standard hook variables.
+
+* Index::                   Index including concepts, functions, variables,
+                              and other terms.
+
+@ignore
+* New Symbols::             New functions and variables in Emacs @value{EMACSVER}.
+@end ignore
+
+@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 other nodes that are inferiors of those already listed,
+mentioned here so you can get to them in one step:
+
+Introduction
+
+* Caveats::                 Flaws and a request for help.
+* Lisp History::            Emacs Lisp is descended from Maclisp.
+* Conventions::             How the manual is formatted.
+* Version Info::            Which Emacs version is running?
+* Acknowledgements::        The authors, editors, and sponsors of this manual.
+
+Conventions
+
+* Some Terms::              Explanation of terms we use in this manual.
+* nil and t::               How the symbols @code{nil} and @code{t} are used.
+* Evaluation Notation::     The format we use for examples of evaluation.
+* Printing Notation::       The format we use for examples that print output.
+* Error Messages::          The format we use for examples of errors.
+* Buffer Text Notation::    The format we use for buffer contents in examples.
+* Format of Descriptions::  Notation for describing functions, variables, etc.
+
+Format of Descriptions
+
+* A Sample Function Description::  A description of an imaginary
+                                     function, @code{foo}.
+* A Sample Variable Description::  A description of an imaginary
+                                     variable, @code{electric-future-map}.
+
+Lisp Data Types
+
+* Printed Representation::  How Lisp objects are represented as text.
+* Comments::                Comments and their formatting conventions.
+* Programming Types::       Types found in all Lisp systems.
+* Editing Types::           Types specific to Emacs.
+* Circular Objects::            Read syntax for circular structure.
+* Type Predicates::         Tests related to types.
+* Equality Predicates::     Tests of equality between any two objects.
+
+Programming Types
+
+* Integer Type::        Numbers without fractional parts.
+* Floating Point Type:: Numbers with fractional parts and with a large range.
+* Character Type::      The representation of letters, numbers and
+                          control characters.
+* Symbol Type::         A multi-use object that refers to a function,
+                        variable, property list, or itself.
+* Sequence Type::       Both lists and arrays are classified as sequences.
+* Cons Cell Type::      Cons cells, and lists (which are made from cons cells).
+* Array Type::          Arrays include strings and vectors.
+* String Type::         An (efficient) array of characters.
+* Vector Type::         One-dimensional arrays.
+* Char-Table Type::     One-dimensional sparse arrays indexed by characters.
+* Bool-Vector Type::    One-dimensional arrays of @code{t} or @code{nil}.
+* Hash Table Type::     Super-fast lookup tables.
+* Function Type::       A piece of executable code you can call from elsewhere.
+* Macro Type::          A method of expanding an expression into another
+                          expression, more fundamental but less pretty.
+* Primitive Function Type::     A function written in C, callable from Lisp.
+* Byte-Code Type::      A function written in Lisp, then compiled.
+* Autoload Type::       A type used for automatically loading seldom-used
+                          functions.
+
+Character Type
+
+* Basic Char Syntax::       Syntax for regular characters.
+* General Escape Syntax::   How to specify characters by their codes.
+* Ctl-Char Syntax::         Syntax for control characters.
+* Meta-Char Syntax::        Syntax for meta-characters.
+* Other Char Bits::         Syntax for hyper-, super-, and alt-characters.
+
+Cons Cell and List Types
+
+* Box Diagrams::            Drawing pictures of lists.
+* Dotted Pair Notation::    An alternative syntax for lists.
+* Association List Type::   A specially constructed list.
+
+String Type
+
+* Syntax for Strings::      How to specify Lisp strings.
+* Non-ASCII in Strings::    International characters in strings.
+* Nonprinting Characters::  Literal unprintable characters in strings.
+* Text Props and Strings::  Strings with text properties.
+
+Editing Types
+
+* Buffer Type::             The basic object of editing.
+* Marker Type::             A position in a buffer.
+* Window Type::             What makes buffers visible.
+* Frame Type::		    Windows subdivide frames.
+* Window Configuration Type::  Recording the way a frame is subdivided.
+* Frame Configuration Type::   Recording the status of all frames.
+* Process Type::            A process running on the underlying OS.
+* Stream Type::             Receive or send characters.
+* Keymap Type::             What function a keystroke invokes.
+* Overlay Type::            How an overlay is represented.
+
+Numbers
+
+* Integer Basics::          Representation and range of integers.
+* Float Basics::	    Representation and range of floating point.
+* Predicates on Numbers::   Testing for numbers.
+* Comparison of Numbers::   Equality and inequality predicates.
+* Numeric Conversions::	    Converting float to integer and vice versa.
+* Arithmetic Operations::   How to add, subtract, multiply and divide.
+* Rounding Operations::     Explicitly rounding floating point numbers.
+* Bitwise Operations::      Logical and, or, not, shifting.
+* Math Functions::          Trig, exponential and logarithmic functions.
+* Random Numbers::          Obtaining random integers, predictable or not.
+
+Strings and Characters
+
+* String Basics::           Basic properties of strings and characters.
+* Predicates for Strings::  Testing whether an object is a string or char.
+* Creating Strings::        Functions to allocate new strings.
+* Modifying Strings::         Altering the contents of an existing string.
+* Text Comparison::         Comparing characters or strings.
+* String Conversion::       Converting characters to strings and vice versa.
+* Formatting Strings::      @code{format}: Emacs's analogue of @code{printf}.
+* Case Conversion::         Case conversion functions.
+* Case Tables::		    Customizing case conversion.
+
+Lists
+
+* Cons Cells::              How lists are made out of cons cells.
+* List-related Predicates:: Is this object a list?  Comparing two lists.
+* List Elements::           Extracting the pieces of a list.
+* Building Lists::          Creating list structure.
+* List Variables::          Modifying lists stored in variables.
+* Modifying Lists::         Storing new pieces into an existing list.
+* Sets And Lists::          A list can represent a finite mathematical set.
+* Association Lists::       A list can represent a finite relation or mapping.
+* Rings::                   Managing a fixed-size ring of objects.
+
+Modifying Existing List Structure
+
+* Setcar::                  Replacing an element in a list.
+* Setcdr::                  Replacing part of the list backbone.
+                              This can be used to remove or add elements.
+* Rearrangement::           Reordering the elements in a list; combining lists.
+
+Sequences, Arrays, and Vectors
+
+* Sequence Functions::      Functions that accept any kind of sequence.
+* Arrays::                  Characteristics of arrays in Emacs Lisp.
+* Array Functions::         Functions specifically for arrays.
+* Vectors::                 Special characteristics of Emacs Lisp vectors.
+* Vector Functions::        Functions specifically for vectors.
+* Char-Tables::             How to work with char-tables.
+* Bool-Vectors::            How to work with bool-vectors.
+
+Hash Tables
+
+* Creating Hash::           Functions to create hash tables.
+* Hash Access::             Reading and writing the hash table contents.
+* Defining Hash::           Defining new comparison methods
+* Other Hash::              Miscellaneous.
+
+Symbols
+
+* Symbol Components::       Symbols have names, values, function definitions
+                              and property lists.
+* Definitions::             A definition says how a symbol will be used.
+* Creating Symbols::        How symbols are kept unique.
+* Property Lists::          Each symbol has a property list
+                              for recording miscellaneous information.
+
+Property Lists
+
+* Plists and Alists::       Comparison of the advantages of property
+                              lists and association lists.
+* Symbol Plists::           Functions to access symbols' property lists.
+* Other Plists::            Accessing property lists stored elsewhere.
+
+Evaluation
+
+* Intro Eval::              Evaluation in the scheme of things.
+* Forms::                   How various sorts of objects are evaluated.
+* Quoting::                 Avoiding evaluation (to put constants in
+                              the program).
+* Eval::                    How to invoke the Lisp interpreter explicitly.
+
+Kinds of Forms
+
+* Self-Evaluating Forms::   Forms that evaluate to themselves.
+* Symbol Forms::            Symbols evaluate as variables.
+* Classifying Lists::       How to distinguish various sorts of list forms.
+* Function Indirection::    When a symbol appears as the car of a list,
+			      we find the real function via the symbol.
+* Function Forms::          Forms that call functions.
+* Macro Forms::             Forms that call macros.
+* Special Forms::           "Special forms" are idiosyncratic primitives,
+                              most of them extremely important.
+* Autoloading::             Functions set up to load files
+                              containing their real definitions.
+
+Control Structures
+
+* Sequencing::              Evaluation in textual order.
+* Conditionals::            @code{if}, @code{cond}, @code{when}, @code{unless}.
+* Combining Conditions::    @code{and}, @code{or}, @code{not}.
+* Iteration::               @code{while} loops.
+* Nonlocal Exits::          Jumping out of a sequence.
+
+Nonlocal Exits
+
+* Catch and Throw::         Nonlocal exits for the program's own purposes.
+* Examples of Catch::       Showing how such nonlocal exits can be written.
+* Errors::                  How errors are signaled and handled.
+* Cleanups::                Arranging to run a cleanup form if an
+                              error happens.
+
+Errors
+
+* Signaling Errors::        How to report an error.
+* Processing of Errors::    What Emacs does when you report an error.
+* Handling Errors::         How you can trap errors and continue execution.
+* Error Symbols::           How errors are classified for trapping them.
+* Standard Errors::         List of all error symbols.
+
+Variables
+
+* Global Variables::        Variable values that exist permanently, everywhere.
+* Constant Variables::      Certain "variables" have values that never change.
+* Local Variables::         Variable values that exist only temporarily.
+* Void Variables::          Symbols that lack values.
+* Defining Variables::      A definition says a symbol is used as a variable.
+* Tips for Defining::       Things you should think about when you
+                              define a variable.
+* Accessing Variables::     Examining values of variables whose names
+                              are known only at run time.
+* Setting Variables::       Storing new values in variables.
+* Variable Scoping::        How Lisp chooses among local and global values.
+* Buffer-Local Variables::  Variable values in effect only in one buffer.
+* Frame-Local Variables::   Variable values in effect only in one frame.
+* Future Local Variables::  New kinds of local values we might add some day.
+* File Local Variables::    Handling local variable lists in files.
+* Variable Aliases::        Variables that are aliases for other variables.
+* Variables with Restricted Values::  Non-constant variables whose value can
+                                        @emph{not} be an arbitrary Lisp object.
+* Standard Buffer-Local Variables::
+                            List of variables buffer-local in all buffers.
+
+Scoping Rules for Variable Bindings
+
+* Scope::                   Scope means where in the program a value
+                              is visible.  Comparison with other languages.
+* Extent::                  Extent means how long in time a value exists.
+* Impl of Scope::           Two ways to implement dynamic scoping.
+* Using Scoping::           How to use dynamic scoping carefully and
+                              avoid problems.
+
+Buffer-Local Variables
+
+* Intro to Buffer-Local::   Introduction and concepts.
+* Creating Buffer-Local::   Creating and destroying buffer-local bindings.
+* Default Value::           The default value is seen in buffers
+                              that don't have their own buffer-local values.
+
+Functions
+
+* What Is a Function::      Lisp functions vs primitives; terminology.
+* Lambda Expressions::      How functions are expressed as Lisp objects.
+* Function Names::          A symbol can serve as the name of a function.
+* Defining Functions::      Lisp expressions for defining functions.
+* Calling Functions::       How to use an existing function.
+* Mapping Functions::       Applying a function to each element of a list, etc.
+* Anonymous Functions::     Lambda-expressions are functions with no names.
+* Function Cells::          Accessing or setting the function definition
+                              of a symbol.
+* Obsolete Functions::      Declaring functions obsolete.
+* Inline Functions::	    Defining functions that the compiler will open code.
+* Function Safety::         Determining whether a function is safe to call.
+* Related Topics::          Cross-references to specific Lisp primitives
+                              that have a special bearing on how
+                              functions work.
+
+Lambda Expressions
+
+* Lambda Components::       The parts of a lambda expression.
+* Simple Lambda::           A simple example.
+* Argument List::           Details and special features of argument lists.
+* Function Documentation::  How to put documentation in a function.
+
+Macros
+
+* Simple Macro::            A basic example.
+* Expansion::               How, when and why macros are expanded.
+* Compiling Macros::        How macros are expanded by the compiler.
+* Defining Macros::         How to write a macro definition.
+* Backquote::               Easier construction of list structure.
+* Problems with Macros::    Don't evaluate the macro arguments too many times.
+                              Don't hide the user's variables.
+* Indenting Macros::        Specifying how to indent macro calls.
+
+Common Problems Using Macros
+
+* Wrong Time::             Do the work in the expansion, not in the macro.
+* Argument Evaluation::    The expansion should evaluate each macro arg once.
+* Surprising Local Vars::  Local variable bindings in the expansion
+                              require special care.
+* Eval During Expansion::  Don't evaluate them; put them in the expansion.
+* Repeated Expansion::     Avoid depending on how many times expansion is done.
+
+Writing Customization Definitions
+
+* Common Keywords::         Common keyword arguments for all kinds of
+                              customization declarations.
+* Group Definitions::       Writing customization group definitions.
+* Variable Definitions::    Declaring user options.
+* Customization Types::     Specifying the type of a user option.
+
+Customization Types
+
+* Simple Types::            Simple customization types: sexp, integer, number,
+                              string, file, directory, alist.
+* Composite Types::         Build new types from other types or data.
+* Splicing into Lists::     Splice elements into list with @code{:inline}.
+* Type Keywords::           Keyword-argument pairs in a customization type.
+* Defining New Types::      Give your type a name.
+
+Loading
+
+* How Programs Do Loading:: The @code{load} function and others.
+* Load Suffixes::           Details about the suffixes that @code{load} tries.
+* Library Search::          Finding a library to load.
+* Loading Non-ASCII::       Non-@acronym{ASCII} characters in Emacs Lisp files.
+* Autoload::                Setting up a function to autoload.
+* Repeated Loading::        Precautions about loading a file twice.
+* Named Features::          Loading a library if it isn't already loaded.
+* Where Defined::           Finding which file defined a certain symbol.
+* Unloading::		    How to "unload" a library that was loaded.
+* Hooks for Loading::	    Providing code to be run when
+			      particular libraries are loaded.
+
+Byte Compilation
+
+* Speed of Byte-Code::      An example of speedup from byte compilation.
+* Compilation Functions::   Byte compilation functions.
+* Docs and Compilation::    Dynamic loading of documentation strings.
+* Dynamic Loading::         Dynamic loading of individual functions.
+* Eval During Compile::     Code to be evaluated when you compile.
+* Compiler Errors::         Handling compiler error messages.
+* Byte-Code Objects::	    The data type used for byte-compiled functions.
+* Disassembly::             Disassembling byte-code; how to read byte-code.
+
+Advising Emacs Lisp Functions
+
+* Simple Advice::           A simple example to explain the basics of advice.
+* Defining Advice::         Detailed description of @code{defadvice}.
+* Around-Advice::           Wrapping advice around a function's definition.
+* Computed Advice::         ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice::    Advice doesn't do anything until you activate it.
+* Enabling Advice::         You can enable or disable each piece of advice.
+* Preactivation::           Preactivation is a way of speeding up the
+                              loading of compiled advice.
+* Argument Access in Advice:: How advice can access the function's arguments.
+* Advising Primitives::     Accessing arguments when advising a primitive.
+* Combined Definition::     How advice is implemented.
+
+Debugging Lisp Programs
+
+* Debugger::                How the Emacs Lisp debugger is implemented.
+* Edebug::                  A source-level Emacs Lisp debugger.
+* Syntax Errors::           How to find syntax errors.
+* Test Coverage::           Ensuring you have tested all branches in your code.
+* Compilation Errors::      How to find errors that show up in
+                              byte compilation.
+
+The Lisp Debugger
+
+* Error Debugging::         Entering the debugger when an error happens.
+* Infinite Loops::	    Stopping and debugging a program that doesn't exit.
+* Function Debugging::      Entering it when a certain function is called.
+* Explicit Debug::          Entering it at a certain point in the program.
+* Using Debugger::          What the debugger does; what you see while in it.
+* Debugger Commands::       Commands used while in the debugger.
+* Invoking the Debugger::   How to call the function @code{debug}.
+* Internals of Debugger::   Subroutines of the debugger, and global variables.
+
+Edebug
+
+* Using Edebug::	    Introduction to use of Edebug.
+* Instrumenting::	    You must instrument your code
+			      in order to debug it with Edebug.
+* Edebug Execution Modes::  Execution modes, stopping more or less often.
+* Jumping::		    Commands to jump to a specified place.
+* Edebug Misc::		    Miscellaneous commands.
+* Breaks::		    Setting breakpoints to make the program stop.
+* Trapping Errors::	    Trapping errors with Edebug.
+* Edebug Views::	    Views inside and outside of Edebug.
+* Edebug Eval::		    Evaluating expressions within Edebug.
+* Eval List::		    Expressions whose values are displayed
+			      each time you enter Edebug.
+* Printing in Edebug::	    Customization of printing.
+* Trace Buffer::	    How to produce trace output in a buffer.
+* Coverage Testing::	    How to test evaluation coverage.
+* The Outside Context::	    Data that Edebug saves and restores.
+* Edebug and Macros::       Specifying how to handle macro calls.
+* Edebug Options::	    Option variables for customizing Edebug.
+
+Debugging Invalid Lisp Syntax
+
+* Excess Open::             How to find a spurious open paren or missing close.
+* Excess Close::            How to find a spurious close paren or missing open.
+
+Reading and Printing Lisp Objects
+
+* Streams Intro::           Overview of streams, reading and printing.
+* Input Streams::           Various data types that can be used as
+                              input streams.
+* Input Functions::         Functions to read Lisp objects from text.
+* Output Streams::          Various data types that can be used as
+                              output streams.
+* Output Functions::        Functions to print Lisp objects as text.
+* Output Variables::        Variables that control what the printing
+                              functions do.
+
+Minibuffers
+
+* Intro to Minibuffers::    Basic information about minibuffers.
+* Text from Minibuffer::    How to read a straight text string.
+* Object from Minibuffer::  How to read a Lisp object or expression.
+* Minibuffer History::	    Recording previous minibuffer inputs
+			      so the user can reuse them.
+* Initial Input::           Specifying initial contents for the minibuffer.
+* Completion::              How to invoke and customize completion.
+* Yes-or-No Queries::       Asking a question with a simple answer.
+* Multiple Queries::	    Asking a series of similar questions.
+* Reading a Password::	    Reading a password from the terminal.
+* Minibuffer Commands::     Commands used as key bindings in minibuffers.
+* Minibuffer Contents::     How such commands access the minibuffer text.
+* Minibuffer Windows::      Operating on the special minibuffer windows.
+* Recursive Mini::          Whether recursive entry to minibuffer is allowed.
+* Minibuffer Misc::         Various customization hooks and variables.
+
+Completion
+
+* Basic Completion::        Low-level functions for completing strings.
+                              (These are too low level to use the minibuffer.)
+* Minibuffer Completion::   Invoking the minibuffer with completion.
+* Completion Commands::     Minibuffer commands that do completion.
+* High-Level Completion::   Convenient special cases of completion
+                              (reading buffer name, file name, etc.)
+* Reading File Names::      Using completion to read file names.
+* Programmed Completion::   Finding the completions for a given file name.
+
+Command Loop
+
+* Command Overview::    How the command loop reads commands.
+* Defining Commands::   Specifying how a function should read arguments.
+* Interactive Call::    Calling a command, so that it will read arguments.
+* Command Loop Info::   Variables set by the command loop for you to examine.
+* Adjusting Point::     Adjustment of point after a command.
+* Input Events::	What input looks like when you read it.
+* Reading Input::       How to read input events from the keyboard or mouse.
+* Special Events::      Events processed immediately and individually.
+* Waiting::             Waiting for user input or elapsed time.
+* Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
+* Prefix Command Arguments::    How the commands to set prefix args work.
+* Recursive Editing::   Entering a recursive edit,
+                          and why you usually shouldn't.
+* Disabling Commands::  How the command loop handles disabled commands.
+* Command History::     How the command history is set up, and how accessed.
+* Keyboard Macros::     How keyboard macros are implemented.
+
+Defining Commands
+
+* Using Interactive::       General rules for @code{interactive}.
+* Interactive Codes::       The standard letter-codes for reading arguments
+                              in various ways.
+* Interactive Examples::    Examples of how to read interactive arguments.
+
+Input Events
+
+* Keyboard Events::         Ordinary characters--keys with symbols on them.
+* Function Keys::           Function keys--keys with names, not symbols.
+* Mouse Events::            Overview of mouse events.
+* Click Events::            Pushing and releasing a mouse button.
+* Drag Events::             Moving the mouse before releasing the button.
+* Button-Down Events::      A button was pushed and not yet released.
+* Repeat Events::           Double and triple click (or drag, or down).
+* Motion Events::           Just moving the mouse, not pushing a button.
+* Focus Events::            Moving the mouse between frames.
+* Misc Events::             Other events the system can generate.
+* Event Examples::          Examples of the lists for mouse events.
+* Classifying Events::      Finding the modifier keys in an event symbol.
+* Accessing Events::        Functions to extract info from events.
+* Strings of Events::       Special considerations for putting
+                              keyboard character events in a string.
+
+Reading Input
+
+* Key Sequence Input::      How to read one key sequence.
+* Reading One Event::       How to read just one event.
+* Event Mod::               How Emacs modifies events as they are read.
+* Invoking the Input Method::   How reading an event uses the input method.
+* Quoted Character Input::  Asking the user to specify a character.
+* Event Input Misc::        How to reread or throw away input events.
+
+Keymaps
+
+* Key Sequences::           Key sequences as Lisp objects.
+* Keymap Basics::           Basic concepts of keymaps.
+* Format of Keymaps::       What a keymap looks like as a Lisp object.
+* Creating Keymaps::        Functions to create and copy keymaps.
+* Inheritance and Keymaps:: How one keymap can inherit the bindings
+                              of another keymap.
+* Prefix Keys::             Defining a key with a keymap as its definition.
+* Active Keymaps::          How Emacs searches the active keymaps
+                              for a key binding.
+* Searching Keymaps::       A pseudo-Lisp summary of searching active maps.
+* Controlling Active Maps:: Each buffer has a local keymap
+                               to override the standard (global) bindings.
+                               A minor mode can also override them.
+* Key Lookup::              How extracting elements from keymaps works.
+* Functions for Key Lookup::    How to request key lookup.
+* Changing Key Bindings::   Redefining a key in a keymap.
+* Remapping Commands::      A keymap can translate one command to another.
+* Translation Keymaps::     Keymaps for translating sequences of events.
+* Key Binding Commands::    Interactive interfaces for redefining keys.
+* Scanning Keymaps::        Looking through all keymaps, for printing help.
+* Menu Keymaps::            A keymap can define a menu for X
+                              or for use from the terminal.
+* Standard Keymaps::        List of standard keymaps.
+
+Major and Minor Modes
+
+* Hooks::                   How to use hooks; how to write code that
+                              provides hooks.
+* Major Modes::             Defining major modes.
+* Minor Modes::             Defining minor modes.
+* Mode Line Format::        Customizing the text that appears in the mode line.
+* Imenu::                   How a mode can provide a menu
+                              of definitions in the buffer.
+* Font Lock Mode::          How modes can highlight text according to syntax.
+* Desktop Save Mode::       How modes can have buffer state saved between
+                              Emacs sessions.
+
+Menu Keymaps
+
+* Defining Menus::          How to make a keymap that defines a menu.
+* Mouse Menus::             How users actuate the menu with the mouse.
+* Keyboard Menus::          How users actuate the menu with the keyboard.
+* Menu Example::            Making a simple menu.
+* Menu Bar::                How to customize the menu bar.
+* Tool Bar::                A tool bar is a row of images.
+* Modifying Menus::         How to add new items to a menu.
+
+Defining Menus
+
+* Simple Menu Items::       A simple kind of menu key binding,
+                              limited in capabilities.
+* Extended Menu Items::     More powerful menu item definitions
+                              let you specify keywords to enable
+                              various features.
+* Menu Separators::         Drawing a horizontal line through a menu.
+* Alias Menu Items::        Using command aliases in menu items.
+
+Major and Minor Modes
+
+* Hooks::              How to use hooks; how to write code that provides hooks.
+* Major Modes::        Defining major modes.
+* Minor Modes::        Defining minor modes.
+* Mode Line Format::   Customizing the text that appears in the mode line.
+* Imenu::              How a mode can provide a menu
+                         of definitions in the buffer.
+* Font Lock Mode::     How modes can highlight text according to syntax.
+* Desktop Save Mode::  How modes can have buffer state saved between
+                         Emacs sessions.
+
+Major Modes
+
+* Major Mode Basics::
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* Example Major Modes::     Text mode and Lisp modes.
+* Auto Major Mode::         How Emacs chooses the major mode automatically.
+* Mode Help::               Finding out how to use a mode.
+* Derived Modes::           Defining a new major mode based on another major
+                              mode.
+* Generic Modes::           Defining a simple major mode that supports
+                              comment syntax and Font Lock mode.
+* Mode Hooks::              Hooks run at the end of major mode functions.
+
+Minor Modes
+
+* Minor Mode Conventions::  Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+* Defining Minor Modes::    A convenient facility for defining minor modes.
+
+Mode Line Format
+
+* Mode Line Basics::
+* Mode Line Data::          The data structure that controls the mode line.
+* Mode Line Variables::     Variables used in that data structure.
+* %-Constructs::            Putting information into a mode line.
+* Properties in Mode::      Using text properties in the mode line.
+* Header Lines::            Like a mode line, but at the top.
+* Emulating Mode Line::     Formatting text as the mode line would.
+
+Font Lock Mode
+
+* Font Lock Basics::        Overview of customizing Font Lock.
+* Search-based Fontification::  Fontification based on regexps.
+* Customizing Keywords::    Customizing search-based fontification.
+* Other Font Lock Variables::   Additional customization facilities.
+* Levels of Font Lock::     Each mode can define alternative levels
+                              so that the user can select more or less.
+* Precalculated Fontification:: How Lisp programs that produce the buffer
+                                  contents can also specify how to fontify it.
+* Faces for Font Lock::     Special faces specifically for Font Lock.
+* Syntactic Font Lock::     Fontification based on syntax tables.
+* Setting Syntax Properties::   Defining character syntax based on context
+                                  using the Font Lock mechanism.
+* Multiline Font Lock::     How to coerce Font Lock into properly
+                              highlighting multiline constructs.
+
+Multiline Font Lock Constructs
+
+* Font Lock Multiline::     Marking multiline chunks with a text property
+* Region to Fontify::       Controlling which region gets refontified
+                              after a buffer change.
+
+Documentation
+
+* Documentation Basics::    Good style for doc strings.
+                              Where to put them.  How Emacs stores them.
+* Accessing Documentation:: How Lisp programs can access doc strings.
+* Keys in Documentation::   Substituting current key bindings.
+* Describing Characters::   Making printable descriptions of
+                              non-printing characters and key sequences.
+* Help Functions::          Subroutines used by Emacs help facilities.
+
+Files
+
+* Visiting Files::          Reading files into Emacs buffers for editing.
+* Saving Buffers::          Writing changed buffers back into files.
+* Reading from Files::      Reading files into other buffers.
+* Writing to Files::        Writing new files from parts of buffers.
+* File Locks::              Locking and unlocking files, to prevent
+                              simultaneous editing by two people.
+* Information about Files:: Testing existence, accessibility, size of files.
+* Changing Files::          Renaming files, changing protection, etc.
+* File Names::              Decomposing and expanding file names.
+* Contents of Directories:: Getting a list of the files in a directory.
+* Create/Delete Dirs::	    Creating and Deleting Directories.
+* Magic File Names::	    Defining "magic" special handling
+			      for certain file names.
+* Format Conversion::       Conversion to and from various file formats.
+
+Visiting Files
+
+* Visiting Functions::      The usual interface functions for visiting.
+* Subroutines of Visiting:: Lower-level subroutines that they use.
+
+Information about Files
+
+* Testing Accessibility::   Is a given file readable?  Writable?
+* Kinds of Files::          Is it a directory?  A symbolic link?
+* Truenames::		    Eliminating symbolic links from a file name.
+* File Attributes::         How large is it?  Any other names?  Etc.
+* Locating Files::          How to find a file in standard places.
+
+File Names
+
+* File Name Components::    The directory part of a file name, and the rest.
+* Relative File Names::     Some file names are relative to a
+                              current directory.
+* Directory Names::         A directory's name as a directory
+                              is different from its name as a file.
+* File Name Expansion::     Converting relative file names to absolute ones.
+* Unique File Names::       Generating names for temporary files.
+* File Name Completion::    Finding the completions for a given file name.
+* Standard File Names::     If your package uses a fixed file name,
+                              how to handle various operating systems simply.
+
+Backups and Auto-Saving
+
+* Backup Files::            How backup files are made; how their names
+                              are chosen.
+* Auto-Saving::             How auto-save files are made; how their
+                              names are chosen.
+* Reverting::               @code{revert-buffer}, and how to customize
+                              what it does.
+
+Backup Files
+
+* Making Backups::          How Emacs makes backup files, and when.
+* Rename or Copy::          Two alternatives: renaming the old file
+                              or copying it.
+* Numbered Backups::        Keeping multiple backups for each source file.
+* Backup Names::            How backup file names are computed; customization.
+
+Buffers
+
+* Buffer Basics::           What is a buffer?
+* Current Buffer::          Designating a buffer as current
+                              so primitives will access its contents.
+* Buffer Names::            Accessing and changing buffer names.
+* Buffer File Name::        The buffer file name indicates which file
+                              is visited.
+* Buffer Modification::     A buffer is @dfn{modified} if it needs to be saved.
+* Modification Time::       Determining whether the visited file was changed
+                              ``behind Emacs's back''.
+* Read Only Buffers::       Modifying text is not allowed in a
+                              read-only buffer.
+* The Buffer List::         How to look at all the existing buffers.
+* Creating Buffers::        Functions that create buffers.
+* Killing Buffers::         Buffers exist until explicitly killed.
+* Indirect Buffers::        An indirect buffer shares text with some
+                              other buffer.
+* Buffer Gap::              The gap in the buffer.
+
+Windows
+
+* Basic Windows::           Basic information on using windows.
+* Splitting Windows::       Splitting one window into two windows.
+* Deleting Windows::        Deleting a window gives its space to other windows.
+* Selecting Windows::       The selected window is the one that you edit in.
+* Cyclic Window Ordering::  Moving around the existing windows.
+* Buffers and Windows::     Each window displays the contents of a buffer.
+* Displaying Buffers::      Higher-level functions for displaying a buffer
+                              and choosing a window for it.
+* Choosing Window::	    How to choose a window for displaying a buffer.
+* Window Point::            Each window has its own location of point.
+* Window Start::            The display-start position controls which text
+                              is on-screen in the window.
+* Textual Scrolling::       Moving text up and down through the window.
+* Vertical Scrolling::      Moving the contents up and down on the window.
+* Horizontal Scrolling::    Moving the contents sideways on the window.
+* Size of Window::          Accessing the size of a window.
+* Resizing Windows::        Changing the size of a window.
+* Coordinates and Windows:: Converting coordinates to windows.
+* Window Tree::             The layout and sizes of all windows in a frame.
+* Window Configurations::   Saving and restoring the state of the screen.
+* Window Hooks::            Hooks for scrolling, window size changes,
+                              redisplay going past a certain point,
+                              or window configuration changes.
+
+Frames
+
+* Creating Frames::	    Creating additional frames.
+* Multiple Displays::       Creating frames on other displays.
+* Frame Parameters::	    Controlling frame size, position, font, etc.
+* Frame Titles::            Automatic updating of frame titles.
+* Deleting Frames::	    Frames last until explicitly deleted.
+* Finding All Frames::	    How to examine all existing frames.
+* Frames and Windows::	    A frame contains windows;
+			      display of text always works through windows.
+* Minibuffers and Frames::  How a frame finds the minibuffer to use.
+* Input Focus::		    Specifying the selected frame.
+* Visibility of Frames::    Frames may be visible or invisible, or icons.
+* Raising and Lowering::    Raising a frame makes it hide other windows;
+			      lowering it puts it underneath the others.
+* Frame Configurations::    Saving the state of all frames.
+* Mouse Tracking::	    Getting events that say when the mouse moves.
+* Mouse Position::	    Asking where the mouse is, or moving it.
+* Pop-Up Menus::	    Displaying a menu for the user to select from.
+* Dialog Boxes::            Displaying a box to ask yes or no.
+* Pointer Shape::           Specifying the shape of the mouse pointer.
+* Window System Selections::Transferring text to and from other windows.
+* Drag and Drop::               Internals of Drag-and-Drop implementation.
+* Color Names::	            Getting the definitions of color names.
+* Text Terminal Colors::    Defining colors for text-only terminals.
+* Resources::		    Getting resource values from the server.
+* Display Feature Testing:: Determining the features of a terminal.
+
+Frame Parameters
+
+* Parameter Access::        How to change a frame's parameters.
+* Initial Parameters::	    Specifying frame parameters when you make a frame.
+* Window Frame Parameters:: List of frame parameters for window systems.
+* Size and Position::       Changing the size and position of a frame.
+* Geometry::                Parsing geometry specifications.
+
+Window Frame Parameters
+
+* Basic Parameters::        Parameters that are fundamental.
+* Position Parameters::     The position of the frame on the screen.
+* Size Parameters::         Frame's size.
+* Layout Parameters::       Size of parts of the frame, and
+                              enabling or disabling some parts.
+* Buffer Parameters::       Which buffers have been or should be shown.
+* Management Parameters::   Communicating with the window manager.
+* Cursor Parameters::       Controlling the cursor appearance.
+* Color Parameters::        Colors of various parts of the frame.
+
+Positions
+
+* Point::                   The special position where editing takes place.
+* Motion::                  Changing point.
+* Excursions::              Temporary motion and buffer changes.
+* Narrowing::               Restricting editing to a portion of the buffer.
+
+Motion
+
+* Character Motion::        Moving in terms of characters.
+* Word Motion::             Moving in terms of words.
+* Buffer End Motion::       Moving to the beginning or end of the buffer.
+* Text Lines::              Moving in terms of lines of text.
+* Screen Lines::            Moving in terms of lines as displayed.
+* List Motion::             Moving by parsing lists and sexps.
+* Skipping Characters::     Skipping characters belonging to a certain set.
+
+Markers
+
+* Overview of Markers::     The components of a marker, and how it relocates.
+* Predicates on Markers::   Testing whether an object is a marker.
+* Creating Markers::        Making empty markers or markers at certain places.
+* Information from Markers::Finding the marker's buffer or character
+                              position.
+* Marker Insertion Types::  Two ways a marker can relocate when you
+                              insert where it points.
+* Moving Markers::          Moving the marker to a new buffer or position.
+* The Mark::                How "the mark" is implemented with a marker.
+* The Region::              How to access "the region".
+
+Text
+
+* Near Point::              Examining text in the vicinity of point.
+* Buffer Contents::         Examining text in a general fashion.
+* Comparing Text::          Comparing substrings of buffers.
+* Insertion::               Adding new text to a buffer.
+* Commands for Insertion::  User-level commands to insert text.
+* Deletion::                Removing text from a buffer.
+* User-Level Deletion::     User-level commands to delete text.
+* The Kill Ring::           Where removed text sometimes is saved for
+                              later use.
+* Undo::                    Undoing changes to the text of a buffer.
+* Maintaining Undo::        How to enable and disable undo information.
+			      How to control how much information is kept.
+* Filling::                 Functions for explicit filling.
+* Margins::                 How to specify margins for filling commands.
+* Adaptive Fill::           Adaptive Fill mode chooses a fill prefix
+                              from context.
+* Auto Filling::            How auto-fill mode is implemented to break lines.
+* Sorting::                 Functions for sorting parts of the buffer.
+* Columns::                 Computing horizontal positions, and using them.
+* Indentation::             Functions to insert or adjust indentation.
+* Case Changes::            Case conversion of parts of the buffer.
+* Text Properties::         Assigning Lisp property lists to text characters.
+* Substitution::            Replacing a given character wherever it appears.
+* Transposition::           Swapping two portions of a buffer.
+* Registers::               How registers are implemented.  Accessing
+                              the text or position stored in a register.
+* Base 64::                 Conversion to or from base 64 encoding.
+* MD5 Checksum::            Compute the MD5 "message digest"/"checksum".
+* Atomic Changes::          Installing several buffer changes "atomically".
+* Change Hooks::            Supplying functions to be run when text is changed.
+
+The Kill Ring
+
+* Kill Ring Concepts::      What text looks like in the kill ring.
+* Kill Functions::          Functions that kill text.
+* Yanking::                 How yanking is done.
+* Yank Commands::           Commands that access the kill ring.
+* Low-Level Kill Ring::	    Functions and variables for kill ring access.
+* Internals of Kill Ring::  Variables that hold kill-ring data.
+
+Indentation
+
+* Primitive Indent::        Functions used to count and insert indentation.
+* Mode-Specific Indent::    Customize indentation for different modes.
+* Region Indent::           Indent all the lines in a region.
+* Relative Indent::         Indent the current line based on previous lines.
+* Indent Tabs::             Adjustable, typewriter-like tab stops.
+* Motion by Indent::        Move to first non-blank character.
+
+Text Properties
+
+* Examining Properties::    Looking at the properties of one character.
+* Changing Properties::	    Setting the properties of a range of text.
+* Property Search::	    Searching for where a property changes value.
+* Special Properties::	    Particular properties with special meanings.
+* Format Properties::       Properties for representing formatting of text.
+* Sticky Properties::       How inserted text gets properties from
+                              neighboring text.
+* Saving Properties::       Saving text properties in files, and reading
+                              them back.
+* Lazy Properties::         Computing text properties in a lazy fashion
+                              only when text is examined.
+* Clickable Text::          Using text properties to make regions of text
+                              do something when you click on them.
+* Links and Mouse-1::       How to make @key{Mouse-1} follow a link.
+* Fields::                  The @code{field} property defines
+                              fields within the buffer.
+* Not Intervals::	    Why text properties do not use
+			      Lisp-visible text intervals.
+
+Non-ASCII Characters
+
+* Text Representations::    Unibyte and multibyte representations
+* Converting Representations::  Converting unibyte to multibyte and vice versa.
+* Selecting a Representation::  Treating a byte sequence as unibyte or multi.
+* Character Codes::         How unibyte and multibyte relate to
+                                codes of individual characters.
+* Character Sets::          The space of possible character codes
+                                is divided into various character sets.
+* Chars and Bytes::         More information about multibyte encodings.
+* Splitting Characters::    Converting a character to its byte sequence.
+* Scanning Charsets::       Which character sets are used in a buffer?
+* Translation of Characters::   Translation tables are used for conversion.
+* Coding Systems::          Coding systems are conversions for saving files.
+* Input Methods::           Input methods allow users to enter various
+                                non-ASCII characters without special keyboards.
+* Locales::                 Interacting with the POSIX locale.
+
+Coding Systems
+
+* Coding System Basics::    Basic concepts.
+* Encoding and I/O::        How file I/O functions handle coding systems.
+* Lisp and Coding Systems:: Functions to operate on coding system names.
+* User-Chosen Coding Systems::  Asking the user to choose a coding system.
+* Default Coding Systems::  Controlling the default choices.
+* Specifying Coding Systems::   Requesting a particular coding system
+                                    for a single file operation.
+* Explicit Encoding::       Encoding or decoding text without doing I/O.
+* Terminal I/O Encoding::   Use of encoding for terminal I/O.
+* MS-DOS File Types::       How DOS "text" and "binary" files
+                                relate to coding systems.
+
+Searching and Matching
+
+* String Search::           Search for an exact match.
+* Searching and Case::      Case-independent or case-significant searching.
+* Regular Expressions::     Describing classes of strings.
+* Regexp Search::           Searching for a match for a regexp.
+* POSIX Regexps::           Searching POSIX-style for the longest match.
+* Match Data::              Finding out which part of the text matched,
+                              after a string or regexp search.
+* Search and Replace::	    Commands that loop, searching and replacing.
+* Standard Regexps::        Useful regexps for finding sentences, pages,...
+
+Regular Expressions
+
+* Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Example::          Illustrates regular expression syntax.
+* Regexp Functions::        Functions for operating on regular expressions.
+
+Syntax of Regular Expressions
+
+* Regexp Special::          Special characters in regular expressions.
+* Char Classes::            Character classes used in regular expressions.
+* Regexp Backslash::        Backslash-sequences in regular expressions.
+
+The Match Data
+
+* Replacing Match::	    Replacing a substring that was matched.
+* Simple Match Data::       Accessing single items of match data,
+			      such as where a particular subexpression started.
+* Entire Match Data::       Accessing the entire match data at once, as a list.
+* Saving Match Data::       Saving and restoring the match data.
+
+Syntax Tables
+
+* Syntax Basics::           Basic concepts of syntax tables.
+* Syntax Descriptors::      How characters are classified.
+* Syntax Table Functions::  How to create, examine and alter syntax tables.
+* Syntax Properties::       Overriding syntax with text properties.
+* Motion and Syntax::	    Moving over characters with certain syntaxes.
+* Parsing Expressions::     Parsing balanced expressions
+                              using the syntax table.
+* Standard Syntax Tables::  Syntax tables used by various major modes.
+* Syntax Table Internals::  How syntax table information is stored.
+* Categories::              Another way of classifying character syntax.
+
+Syntax Descriptors
+
+* Syntax Class Table::      Table of syntax classes.
+* Syntax Flags::            Additional flags each character can have.
+
+Parsing Expressions
+
+* Motion via Parsing::      Motion functions that work by parsing.
+* Position Parse::          Determining the syntactic state of a position.
+* Parser State::            How Emacs represents a syntactic state.
+* Low-Level Parsing::       Parsing across a specified region.
+* Control Parsing::         Parameters that affect parsing.
+
+Abbrevs And Abbrev Expansion
+
+* Abbrev Mode::             Setting up Emacs for abbreviation.
+* Abbrev Tables::           Creating and working with abbrev tables.
+* Defining Abbrevs::        Specifying abbreviations and their expansions.
+* Abbrev Files::            Saving abbrevs in files.
+* Abbrev Expansion::        Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables::  Abbrev tables used by various major modes.
+
+Processes
+
+* Subprocess Creation::     Functions that start subprocesses.
+* Shell Arguments::         Quoting an argument to pass it to a shell.
+* Synchronous Processes::   Details of using synchronous subprocesses.
+* Asynchronous Processes::  Starting up an asynchronous subprocess.
+* Deleting Processes::      Eliminating an asynchronous subprocess.
+* Process Information::     Accessing run-status and other attributes.
+* Input to Processes::      Sending input to an asynchronous subprocess.
+* Signals to Processes::    Stopping, continuing or interrupting
+                              an asynchronous subprocess.
+* Output from Processes::   Collecting output from an asynchronous subprocess.
+* Sentinels::               Sentinels run when process run-status changes.
+* Query Before Exit::       Whether to query if exiting will kill a process.
+* Transaction Queues::      Transaction-based communication with subprocesses.
+* Network::                 Opening network connections.
+* Network Servers::         Network servers let Emacs accept net connections.
+* Datagrams::               UDP network connections.
+* Low-Level Network::       Lower-level but more general function
+                              to create connections and servers.
+* Misc Network::            Additional relevant functions for network connections.
+* Byte Packing::            Using bindat to pack and unpack binary data.
+
+Receiving Output from Processes
+
+* Process Buffers::         If no filter, output is put in a buffer.
+* Filter Functions::        Filter functions accept output from the process.
+* Decoding Output::         Filters can get unibyte or multibyte strings.
+* Accepting Output::        How to wait until process output arrives.
+
+Low-Level Network Access
+
+* Proc: Network Processes.  Using @code{make-network-process}.
+* Options: Network Options.  Further control over network connections.
+* Features: Network Feature Testing.
+                            Determining which network features work on
+                              the machine you are using.
+
+Packing and Unpacking Byte Arrays
+
+* Bindat Spec::             Describing data layout.
+* Bindat Functions::        Doing the unpacking and packing.
+* Bindat Examples::         Samples of what bindat.el can do for you!
+
+Emacs Display
+
+* Refresh Screen::          Clearing the screen and redrawing everything on it.
+* Forcing Redisplay::       Forcing redisplay.
+* Truncation::              Folding or wrapping long text lines.
+* The Echo Area::           Displaying messages at the bottom of the screen.
+* Warnings::                Displaying warning messages for the user.
+* Invisible Text::          Hiding part of the buffer text.
+* Selective Display::       Hiding part of the buffer text (the old way).
+* Temporary Displays::      Displays that go away automatically.
+* Overlays::		    Use overlays to highlight parts of the buffer.
+* Width::                   How wide a character or string is on the screen.
+* Line Height::             Controlling the height of lines.
+* Faces::		    A face defines a graphics style
+                              for text characters: font, colors, etc.
+* Fringes::                 Controlling window fringes.
+* Scroll Bars::             Controlling vertical scroll bars.
+* Display Property::        Enabling special display features.
+* Images::                  Displaying images in Emacs buffers.
+* Buttons::                 Adding clickable buttons to Emacs buffers.
+* Abstract Display::        Emacs' Widget for Object Collections.
+* Blinking::                How Emacs shows the matching open parenthesis.
+* Usual Display::	    The usual conventions for displaying nonprinting chars.
+* Display Tables::	    How to specify other conventions.
+* Beeping::                 Audible signal to the user.
+* Window Systems::          Which window system is being used.
+
+The Echo Area
+
+* Displaying Messages::     Explicitly displaying text in the echo area.
+* Progress::                Informing user about progress of a long operation.
+* Logging Messages::        Echo area messages are logged for the user.
+* Echo Area Customization:: Controlling the echo area.
+
+Reporting Warnings
+
+* Warning Basics::          Warnings concepts and functions to report them.
+* Warning Variables::       Variables programs bind to customize their warnings.
+* Warning Options::         Variables users set to control display of warnings.
+
+Overlays
+
+* Managing Overlays::       Creating and moving overlays.
+* Overlay Properties::      How to read and set properties.
+			    What properties do to the screen display.
+* Finding Overlays::        Searching for overlays.
+
+Faces
+
+* Defining Faces::          How to define a face with @code{defface}.
+* Face Attributes::         What is in a face?
+* Attribute Functions::     Functions to examine and set face attributes.
+* Displaying Faces::        How Emacs combines the faces specified for
+                              a character.
+* Font Selection::          Finding the best available font for a face.
+* Face Functions::          How to define and examine faces.
+* Auto Faces::              Hook for automatic face assignment.
+* Font Lookup::             Looking up the names of available fonts
+                              and information about them.
+* Fontsets::                A fontset is a collection of fonts
+                              that handle a range of character sets.
+
+Fringes
+
+* Fringe Size/Pos::         Specifying where to put the window fringes.
+* Fringe Indicators::       Displaying indicator icons in the window fringes.
+* Fringe Cursors::          Displaying cursors in the right fringe.
+* Fringe Bitmaps::          Specifying bitmaps for fringe indicators.
+* Customizing Bitmaps::     Specifying your own bitmaps to use in the fringes.
+* Overlay Arrow::           Display of an arrow to indicate position.
+
+The @code{display} Property
+
+* Specified Space::         Displaying one space with a specified width.
+* Pixel Specification::     Specifying space width or height in pixels.
+* Other Display Specs::     Displaying an image; magnifying text; moving it
+                              up or down on the page; adjusting the width
+                              of spaces within text.
+* Display Margins::         Displaying text or images to the side of
+                              the main text.
+
+Images
+
+* Image Descriptors::       How to specify an image for use in @code{:display}.
+* XBM Images::              Special features for XBM format.
+* XPM Images::              Special features for XPM format.
+* GIF Images::              Special features for GIF format.
+* PostScript Images::       Special features for PostScript format.
+* Other Image Types::       Various other formats are supported.
+* Defining Images::         Convenient ways to define an image for later use.
+* Showing Images::          Convenient ways to display an image once
+                              it is defined.
+* Image Cache::             Internal mechanisms of image display.
+
+Buttons
+
+* Button Properties::       Button properties with special meanings.
+* Button Types::            Defining common properties for classes of buttons.
+* Making Buttons::          Adding buttons to Emacs buffers.
+* Manipulating Buttons::    Getting and setting properties of buttons.
+* Button Buffer Commands::  Buffer-wide commands and bindings for buttons.
+
+Abstract Display
+
+* Abstract Display Functions::  Functions in the Ewoc package.
+* Abstract Display Example::    Example of using Ewoc.
+
+Display Tables
+
+* Display Table Format::    What a display table consists of.
+* Active Display Table::    How Emacs selects a display table to use.
+* Glyphs::                  How to define a glyph, and what glyphs mean.
+
+Operating System Interface
+
+* Starting Up::             Customizing Emacs start-up processing.
+* Getting Out::             How exiting works (permanent or temporary).
+* System Environment::      Distinguish the name and kind of system.
+* User Identification::     Finding the name and user id of the user.
+* Time of Day::		    Getting the current time.
+* Time Conversion::         Converting a time from numeric form to a string, or
+                              to calendrical data (or vice versa).
+* Time Parsing::            Converting a time from numeric form to text
+                              and vice versa.
+* Processor Run Time::      Getting the run time used by Emacs.
+* Time Calculations::       Adding, subtracting, comparing times, etc.
+* Timers::		    Setting a timer to call a function at a certain time.
+* Idle Timers::             Setting a timer to call a function when Emacs has
+                              been idle for a certain length of time.
+* Terminal Input::          Accessing and recording terminal input.
+* Terminal Output::         Controlling and recording terminal output.
+* Sound Output::            Playing sounds on the computer's speaker.
+* X11 Keysyms::             Operating on key symbols for X Windows
+* Batch Mode::              Running Emacs without terminal interaction.
+* Session Management::      Saving and restoring state with X Session Management.
+
+Starting Up Emacs
+
+* Startup Summary::         Sequence of actions Emacs performs at start-up.
+* Init File::               Details on reading the init file (@file{.emacs}).
+* Terminal-Specific::       How the terminal-specific Lisp file is read.
+* Command-Line Arguments::  How command-line arguments are processed,
+                              and how you can customize them.
+
+Getting Out of Emacs
+
+* Killing Emacs::           Exiting Emacs irreversibly.
+* Suspending Emacs::        Exiting Emacs reversibly.
+
+Terminal Input
+
+* Input Modes::		    Options for how input is processed.
+* Recording Input::	    Saving histories of recent or all input events.
+
+Tips and Conventions
+
+* Coding Conventions::      Conventions for clean and robust programs.
+* Key Binding Conventions:: Which keys should be bound by which programs.
+* Programming Tips::        Making Emacs code fit smoothly in Emacs.
+* Compilation Tips::        Making compiled code run fast.
+* Warning Tips::            Turning off compiler warnings.
+* Documentation Tips::      Writing readable documentation strings.
+* Comment Tips::	    Conventions for writing comments.
+* Library Headers::         Standard headers for library packages.
+
+GNU Emacs Internals
+
+* Building Emacs::          How the dumped Emacs is made.
+* Pure Storage::            A kludge to make preloaded Lisp functions sharable.
+* Garbage Collection::      Reclaiming space for Lisp objects no longer used.
+* Memory Usage::            Info about total size of Lisp objects made so far.
+* Writing Emacs Primitives::  Writing C code for Emacs.
+* Object Internals::        Data formats of buffers, windows, processes.
+
+Object Internals
+
+* Buffer Internals::        Components of a buffer structure.
+* Window Internals::        Components of a window structure.
+* Process Internals::       Components of a process structure.
+@end detailmenu
+@end menu
+
+@include intro.texi
+@include objects.texi
+@include numbers.texi
+@include strings.texi
+
+@include lists.texi
+@include sequences.texi
+@include hash.texi
+@include symbols.texi
+@include eval.texi
+
+@include control.texi
+@include variables.texi
+@include functions.texi
+@include macros.texi
+
+@include customize.texi
+@include loading.texi
+@include compile.texi
+@include advice.texi
+
+@include debugging.texi
+@include streams.texi
+@include minibuf.texi
+@include commands.texi
+
+@include keymaps.texi
+@include modes.texi
+@include help.texi
+@include files.texi
+
+@include backups.texi
+
+@c ================ Beginning of Volume 2 ================
+@c include buffers.texi
+@c include windows.texi
+@c include frames.texi
+
+@c include positions.texi
+@c include markers.texi
+@c include text.texi
+@c include nonascii.texi
+
+@c include searching.texi
+@c include syntax.texi
+@c include abbrevs.texi
+@c include processes.texi
+
+@c include display.texi
+@c include os.texi
+
+@c MOVE to Emacs Manual:  include misc-modes.texi
+
+@c appendices
+
+@c  REMOVE this:  include non-hacker.texi
+
+@c include anti.texi
+@c include doclicense.texi
+@c include gpl.texi
+@c include tips.texi
+@c include internals.texi
+@c include errors.texi
+@c include locals.texi
+@c include maps.texi
+@c include hooks.texi
+
+@include index.texi
+
+@ignore
+@node New Symbols, , Index, Top
+@unnumbered New Symbols Since the Previous Edition
+
+@printindex tp
+@end ignore
+
+@bye
+
+
+These words prevent "local variables" above from confusing Emacs.
+
+@ignore
+   arch-tag: 9594760d-8801-4d1b-aeb9-f3b3166b5be2
+@end ignore
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
new file mode 100644
index 00000000000..515973c6281
--- /dev/null
+++ b/doc/lispref/vol2.texi
@@ -0,0 +1,1506 @@
+\input texinfo  @c -*-texinfo-*-
+@c This file is used for printing the GNU Emacs Lisp Reference Manual
+@c in two volumes.  It is a modified version of elisp.texi.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c %**start of header
+@setfilename elisp
+@settitle GNU Emacs Lisp Reference Manual: Volume 2
+@c %**end of header
+
+@c See two-volume-cross-refs.txt.
+@tex
+\message{Formatting for two volume edition...Volume 2...}
+%
+% Read special toc file, set up in two-volume.make.
+\gdef\tocreadfilename{elisp2-toc-ready.toc}
+%
+% Don't make outlines, they're not needed and \readdatafile can't pay
+% attention to the special definition above.
+\global\let\pdfmakeoutlines=\relax
+%
+% Start volume 2 chapter numbering at 27; this must be listed as chapno26
+\global\chapno=26
+@end tex
+
+@c Version of the manual and of Emacs.
+@c Please remember to update the edition number in README as well.
+@set VERSION  2.9
+@set EMACSVER 22
+
+@dircategory Emacs
+@direntry
+* Elisp: (elisp).       The Emacs Lisp Reference Manual.
+@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.
+@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
+\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
+
+@c Combine indices.
+@synindex cp fn
+@syncodeindex vr fn
+@syncodeindex ky fn
+@syncodeindex pg fn
+@c We use the "type index" to index new functions and variables.
+@c @syncodeindex tp fn
+
+@copying
+This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@*
+corresponding to Emacs version @value{EMACSVER}.
+
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 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 ``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
+
+@titlepage
+@title GNU Emacs Lisp Reference Manual
+@subtitle Volume 2
+@subtitle For Emacs Version @value{EMACSVER}
+@subtitle Revision @value{VERSION}, June 2007
+
+@author by Bil Lewis, Dan LaLiberte, Richard Stallman
+@author and the GNU Manual Group
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+
+@sp 2
+Published by the Free Software Foundation @*
+51 Franklin St, Fifth Floor @*
+Boston, MA 02110-1301 @*
+USA @*
+ISBN 1-882114-74-4
+
+@sp 2
+Cover art by Etienne Suvasa.
+@end titlepage
+
+
+@c Print the tables of contents
+@summarycontents
+@contents
+
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Emacs Lisp
+
+This Info file contains edition @value{VERSION} of the GNU Emacs Lisp
+Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
+@end ifnottex
+
+@menu
+* Introduction::            Introduction and conventions used.
+
+* Lisp Data Types::         Data types of objects in Emacs Lisp.
+* Numbers::                 Numbers and arithmetic functions.
+* Strings and Characters::  Strings, and functions that work on them.
+* Lists::                   Lists, cons cells, and related functions.
+* Sequences Arrays Vectors::  Lists, strings and vectors are called sequences.
+                                Certain functions act on any kind of sequence.
+                                The description of vectors is here as well.
+* Hash Tables::             Very fast lookup-tables.
+* Symbols::                 Symbols represent names, uniquely.
+
+* Evaluation::              How Lisp expressions are evaluated.
+* Control Structures::      Conditionals, loops, nonlocal exits.
+* Variables::               Using symbols in programs to stand for values.
+* Functions::               A function is a Lisp program
+                              that can be invoked from other functions.
+* Macros::                  Macros are a way to extend the Lisp language.
+* Customization::           Writing customization declarations.
+
+* Loading::                 Reading files of Lisp code into Lisp.
+* Byte Compilation::        Compilation makes programs run faster.
+* Advising Functions::      Adding to the definition of a function.
+* Debugging::               Tools and tips for debugging Lisp programs.
+
+* Read and Print::          Converting Lisp objects to text and back.
+* Minibuffers::             Using the minibuffer to read input.
+* Command Loop::            How the editor command loop works,
+                              and how you can call its subroutines.
+* Keymaps::                 Defining the bindings from keys to commands.
+* Modes::                   Defining major and minor modes.
+* Documentation::           Writing and using documentation strings.
+
+* Files::                   Accessing files.
+* Backups and Auto-Saving:: Controlling how backups and auto-save
+                              files are made.
+* Buffers::                 Creating and using buffer objects.
+* Windows::                 Manipulating windows and displaying buffers.
+* Frames::		    Making multiple system-level windows.
+* Positions::               Buffer positions and motion functions.
+* Markers::                 Markers represent positions and update
+                              automatically when the text is changed.
+
+* Text::                    Examining and changing text in buffers.
+* Non-ASCII Characters::    Non-ASCII text in buffers and strings.
+* Searching and Matching::  Searching buffers for strings or regexps.
+* Syntax Tables::           The syntax table controls word and list parsing.
+* Abbrevs::                 How Abbrev mode works, and its data structures.
+
+* Processes::               Running and communicating with subprocesses.
+* Display::	            Features for controlling the screen display.
+* System Interface::        Getting the user id, system type, environment
+                              variables, and other such things.
+
+Appendices
+
+* Antinews::                Info for users downgrading to Emacs 21.
+* GNU Free Documentation License:: The license for this documentation
+* GPL::                     Conditions for copying and changing GNU Emacs.
+* Tips::                    Advice and coding conventions for Emacs Lisp.
+* GNU Emacs Internals::     Building and dumping Emacs;
+                              internal data structures.
+* Standard Errors::         List of all error symbols.
+* Standard Buffer-Local Variables::
+                            List of variables buffer-local in all buffers.
+* Standard Keymaps::        List of standard keymaps.
+* Standard Hooks::          List of standard hook variables.
+
+* Index::                   Index including concepts, functions, variables,
+                              and other terms.
+
+@ignore
+* New Symbols::             New functions and variables in Emacs @value{EMACSVER}.
+@end ignore
+
+@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 other nodes that are inferiors of those already listed,
+mentioned here so you can get to them in one step:
+
+Introduction
+
+* Caveats::                 Flaws and a request for help.
+* Lisp History::            Emacs Lisp is descended from Maclisp.
+* Conventions::             How the manual is formatted.
+* Version Info::            Which Emacs version is running?
+* Acknowledgements::        The authors, editors, and sponsors of this manual.
+
+Conventions
+
+* Some Terms::              Explanation of terms we use in this manual.
+* nil and t::               How the symbols @code{nil} and @code{t} are used.
+* Evaluation Notation::     The format we use for examples of evaluation.
+* Printing Notation::       The format we use for examples that print output.
+* Error Messages::          The format we use for examples of errors.
+* Buffer Text Notation::    The format we use for buffer contents in examples.
+* Format of Descriptions::  Notation for describing functions, variables, etc.
+
+Format of Descriptions
+
+* A Sample Function Description::  A description of an imaginary
+                                     function, @code{foo}.
+* A Sample Variable Description::  A description of an imaginary
+                                     variable, @code{electric-future-map}.
+
+Lisp Data Types
+
+* Printed Representation::  How Lisp objects are represented as text.
+* Comments::                Comments and their formatting conventions.
+* Programming Types::       Types found in all Lisp systems.
+* Editing Types::           Types specific to Emacs.
+* Circular Objects::            Read syntax for circular structure.
+* Type Predicates::         Tests related to types.
+* Equality Predicates::     Tests of equality between any two objects.
+
+Programming Types
+
+* Integer Type::        Numbers without fractional parts.
+* Floating Point Type:: Numbers with fractional parts and with a large range.
+* Character Type::      The representation of letters, numbers and
+                          control characters.
+* Symbol Type::         A multi-use object that refers to a function,
+                        variable, property list, or itself.
+* Sequence Type::       Both lists and arrays are classified as sequences.
+* Cons Cell Type::      Cons cells, and lists (which are made from cons cells).
+* Array Type::          Arrays include strings and vectors.
+* String Type::         An (efficient) array of characters.
+* Vector Type::         One-dimensional arrays.
+* Char-Table Type::     One-dimensional sparse arrays indexed by characters.
+* Bool-Vector Type::    One-dimensional arrays of @code{t} or @code{nil}.
+* Hash Table Type::     Super-fast lookup tables.
+* Function Type::       A piece of executable code you can call from elsewhere.
+* Macro Type::          A method of expanding an expression into another
+                          expression, more fundamental but less pretty.
+* Primitive Function Type::     A function written in C, callable from Lisp.
+* Byte-Code Type::      A function written in Lisp, then compiled.
+* Autoload Type::       A type used for automatically loading seldom-used
+                          functions.
+
+Character Type
+
+* Basic Char Syntax::       Syntax for regular characters.
+* General Escape Syntax::   How to specify characters by their codes.
+* Ctl-Char Syntax::         Syntax for control characters.
+* Meta-Char Syntax::        Syntax for meta-characters.
+* Other Char Bits::         Syntax for hyper-, super-, and alt-characters.
+
+Cons Cell and List Types
+
+* Box Diagrams::            Drawing pictures of lists.
+* Dotted Pair Notation::    An alternative syntax for lists.
+* Association List Type::   A specially constructed list.
+
+String Type
+
+* Syntax for Strings::      How to specify Lisp strings.
+* Non-ASCII in Strings::    International characters in strings.
+* Nonprinting Characters::  Literal unprintable characters in strings.
+* Text Props and Strings::  Strings with text properties.
+
+Editing Types
+
+* Buffer Type::             The basic object of editing.
+* Marker Type::             A position in a buffer.
+* Window Type::             What makes buffers visible.
+* Frame Type::		    Windows subdivide frames.
+* Window Configuration Type::  Recording the way a frame is subdivided.
+* Frame Configuration Type::   Recording the status of all frames.
+* Process Type::            A process running on the underlying OS.
+* Stream Type::             Receive or send characters.
+* Keymap Type::             What function a keystroke invokes.
+* Overlay Type::            How an overlay is represented.
+
+Numbers
+
+* Integer Basics::          Representation and range of integers.
+* Float Basics::	    Representation and range of floating point.
+* Predicates on Numbers::   Testing for numbers.
+* Comparison of Numbers::   Equality and inequality predicates.
+* Numeric Conversions::	    Converting float to integer and vice versa.
+* Arithmetic Operations::   How to add, subtract, multiply and divide.
+* Rounding Operations::     Explicitly rounding floating point numbers.
+* Bitwise Operations::      Logical and, or, not, shifting.
+* Math Functions::          Trig, exponential and logarithmic functions.
+* Random Numbers::          Obtaining random integers, predictable or not.
+
+Strings and Characters
+
+* String Basics::           Basic properties of strings and characters.
+* Predicates for Strings::  Testing whether an object is a string or char.
+* Creating Strings::        Functions to allocate new strings.
+* Modifying Strings::         Altering the contents of an existing string.
+* Text Comparison::         Comparing characters or strings.
+* String Conversion::       Converting characters to strings and vice versa.
+* Formatting Strings::      @code{format}: Emacs's analogue of @code{printf}.
+* Case Conversion::         Case conversion functions.
+* Case Tables::		    Customizing case conversion.
+
+Lists
+
+* Cons Cells::              How lists are made out of cons cells.
+* List-related Predicates:: Is this object a list?  Comparing two lists.
+* List Elements::           Extracting the pieces of a list.
+* Building Lists::          Creating list structure.
+* List Variables::          Modifying lists stored in variables.
+* Modifying Lists::         Storing new pieces into an existing list.
+* Sets And Lists::          A list can represent a finite mathematical set.
+* Association Lists::       A list can represent a finite relation or mapping.
+* Rings::                   Managing a fixed-size ring of objects.
+
+Modifying Existing List Structure
+
+* Setcar::                  Replacing an element in a list.
+* Setcdr::                  Replacing part of the list backbone.
+                              This can be used to remove or add elements.
+* Rearrangement::           Reordering the elements in a list; combining lists.
+
+Sequences, Arrays, and Vectors
+
+* Sequence Functions::      Functions that accept any kind of sequence.
+* Arrays::                  Characteristics of arrays in Emacs Lisp.
+* Array Functions::         Functions specifically for arrays.
+* Vectors::                 Special characteristics of Emacs Lisp vectors.
+* Vector Functions::        Functions specifically for vectors.
+* Char-Tables::             How to work with char-tables.
+* Bool-Vectors::            How to work with bool-vectors.
+
+Hash Tables
+
+* Creating Hash::           Functions to create hash tables.
+* Hash Access::             Reading and writing the hash table contents.
+* Defining Hash::           Defining new comparison methods
+* Other Hash::              Miscellaneous.
+
+Symbols
+
+* Symbol Components::       Symbols have names, values, function definitions
+                              and property lists.
+* Definitions::             A definition says how a symbol will be used.
+* Creating Symbols::        How symbols are kept unique.
+* Property Lists::          Each symbol has a property list
+                              for recording miscellaneous information.
+
+Property Lists
+
+* Plists and Alists::       Comparison of the advantages of property
+                              lists and association lists.
+* Symbol Plists::           Functions to access symbols' property lists.
+* Other Plists::            Accessing property lists stored elsewhere.
+
+Evaluation
+
+* Intro Eval::              Evaluation in the scheme of things.
+* Forms::                   How various sorts of objects are evaluated.
+* Quoting::                 Avoiding evaluation (to put constants in
+                              the program).
+* Eval::                    How to invoke the Lisp interpreter explicitly.
+
+Kinds of Forms
+
+* Self-Evaluating Forms::   Forms that evaluate to themselves.
+* Symbol Forms::            Symbols evaluate as variables.
+* Classifying Lists::       How to distinguish various sorts of list forms.
+* Function Indirection::    When a symbol appears as the car of a list,
+			      we find the real function via the symbol.
+* Function Forms::          Forms that call functions.
+* Macro Forms::             Forms that call macros.
+* Special Forms::           "Special forms" are idiosyncratic primitives,
+                              most of them extremely important.
+* Autoloading::             Functions set up to load files
+                              containing their real definitions.
+
+Control Structures
+
+* Sequencing::              Evaluation in textual order.
+* Conditionals::            @code{if}, @code{cond}, @code{when}, @code{unless}.
+* Combining Conditions::    @code{and}, @code{or}, @code{not}.
+* Iteration::               @code{while} loops.
+* Nonlocal Exits::          Jumping out of a sequence.
+
+Nonlocal Exits
+
+* Catch and Throw::         Nonlocal exits for the program's own purposes.
+* Examples of Catch::       Showing how such nonlocal exits can be written.
+* Errors::                  How errors are signaled and handled.
+* Cleanups::                Arranging to run a cleanup form if an
+                              error happens.
+
+Errors
+
+* Signaling Errors::        How to report an error.
+* Processing of Errors::    What Emacs does when you report an error.
+* Handling Errors::         How you can trap errors and continue execution.
+* Error Symbols::           How errors are classified for trapping them.
+* Standard Errors::         List of all error symbols.
+
+Variables
+
+* Global Variables::        Variable values that exist permanently, everywhere.
+* Constant Variables::      Certain "variables" have values that never change.
+* Local Variables::         Variable values that exist only temporarily.
+* Void Variables::          Symbols that lack values.
+* Defining Variables::      A definition says a symbol is used as a variable.
+* Tips for Defining::       Things you should think about when you
+                              define a variable.
+* Accessing Variables::     Examining values of variables whose names
+                              are known only at run time.
+* Setting Variables::       Storing new values in variables.
+* Variable Scoping::        How Lisp chooses among local and global values.
+* Buffer-Local Variables::  Variable values in effect only in one buffer.
+* Frame-Local Variables::   Variable values in effect only in one frame.
+* Future Local Variables::  New kinds of local values we might add some day.
+* File Local Variables::    Handling local variable lists in files.
+* Variable Aliases::        Variables that are aliases for other variables.
+* Variables with Restricted Values::  Non-constant variables whose value can
+                                        @emph{not} be an arbitrary Lisp object.
+* Standard Buffer-Local Variables::
+                            List of variables buffer-local in all buffers.
+
+Scoping Rules for Variable Bindings
+
+* Scope::                   Scope means where in the program a value
+                              is visible.  Comparison with other languages.
+* Extent::                  Extent means how long in time a value exists.
+* Impl of Scope::           Two ways to implement dynamic scoping.
+* Using Scoping::           How to use dynamic scoping carefully and
+                              avoid problems.
+
+Buffer-Local Variables
+
+* Intro to Buffer-Local::   Introduction and concepts.
+* Creating Buffer-Local::   Creating and destroying buffer-local bindings.
+* Default Value::           The default value is seen in buffers
+                              that don't have their own buffer-local values.
+
+Functions
+
+* What Is a Function::      Lisp functions vs primitives; terminology.
+* Lambda Expressions::      How functions are expressed as Lisp objects.
+* Function Names::          A symbol can serve as the name of a function.
+* Defining Functions::      Lisp expressions for defining functions.
+* Calling Functions::       How to use an existing function.
+* Mapping Functions::       Applying a function to each element of a list, etc.
+* Anonymous Functions::     Lambda-expressions are functions with no names.
+* Function Cells::          Accessing or setting the function definition
+                              of a symbol.
+* Obsolete Functions::      Declaring functions obsolete.
+* Inline Functions::	    Defining functions that the compiler will open code.
+* Function Safety::         Determining whether a function is safe to call.
+* Related Topics::          Cross-references to specific Lisp primitives
+                              that have a special bearing on how
+                              functions work.
+
+Lambda Expressions
+
+* Lambda Components::       The parts of a lambda expression.
+* Simple Lambda::           A simple example.
+* Argument List::           Details and special features of argument lists.
+* Function Documentation::  How to put documentation in a function.
+
+Macros
+
+* Simple Macro::            A basic example.
+* Expansion::               How, when and why macros are expanded.
+* Compiling Macros::        How macros are expanded by the compiler.
+* Defining Macros::         How to write a macro definition.
+* Backquote::               Easier construction of list structure.
+* Problems with Macros::    Don't evaluate the macro arguments too many times.
+                              Don't hide the user's variables.
+* Indenting Macros::        Specifying how to indent macro calls.
+
+Common Problems Using Macros
+
+* Wrong Time::             Do the work in the expansion, not in the macro.
+* Argument Evaluation::    The expansion should evaluate each macro arg once.
+* Surprising Local Vars::  Local variable bindings in the expansion
+                              require special care.
+* Eval During Expansion::  Don't evaluate them; put them in the expansion.
+* Repeated Expansion::     Avoid depending on how many times expansion is done.
+
+Writing Customization Definitions
+
+* Common Keywords::         Common keyword arguments for all kinds of
+                              customization declarations.
+* Group Definitions::       Writing customization group definitions.
+* Variable Definitions::    Declaring user options.
+* Customization Types::     Specifying the type of a user option.
+
+Customization Types
+
+* Simple Types::            Simple customization types: sexp, integer, number,
+                              string, file, directory, alist.
+* Composite Types::         Build new types from other types or data.
+* Splicing into Lists::     Splice elements into list with @code{:inline}.
+* Type Keywords::           Keyword-argument pairs in a customization type.
+* Defining New Types::      Give your type a name.
+
+Loading
+
+* How Programs Do Loading:: The @code{load} function and others.
+* Load Suffixes::           Details about the suffixes that @code{load} tries.
+* Library Search::          Finding a library to load.
+* Loading Non-ASCII::       Non-@acronym{ASCII} characters in Emacs Lisp files.
+* Autoload::                Setting up a function to autoload.
+* Repeated Loading::        Precautions about loading a file twice.
+* Named Features::          Loading a library if it isn't already loaded.
+* Where Defined::           Finding which file defined a certain symbol.
+* Unloading::		    How to "unload" a library that was loaded.
+* Hooks for Loading::	    Providing code to be run when
+			      particular libraries are loaded.
+
+Byte Compilation
+
+* Speed of Byte-Code::      An example of speedup from byte compilation.
+* Compilation Functions::   Byte compilation functions.
+* Docs and Compilation::    Dynamic loading of documentation strings.
+* Dynamic Loading::         Dynamic loading of individual functions.
+* Eval During Compile::     Code to be evaluated when you compile.
+* Compiler Errors::         Handling compiler error messages.
+* Byte-Code Objects::	    The data type used for byte-compiled functions.
+* Disassembly::             Disassembling byte-code; how to read byte-code.
+
+Advising Emacs Lisp Functions
+
+* Simple Advice::           A simple example to explain the basics of advice.
+* Defining Advice::         Detailed description of @code{defadvice}.
+* Around-Advice::           Wrapping advice around a function's definition.
+* Computed Advice::         ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice::    Advice doesn't do anything until you activate it.
+* Enabling Advice::         You can enable or disable each piece of advice.
+* Preactivation::           Preactivation is a way of speeding up the
+                              loading of compiled advice.
+* Argument Access in Advice:: How advice can access the function's arguments.
+* Advising Primitives::     Accessing arguments when advising a primitive.
+* Combined Definition::     How advice is implemented.
+
+Debugging Lisp Programs
+
+* Debugger::                How the Emacs Lisp debugger is implemented.
+* Edebug::                  A source-level Emacs Lisp debugger.
+* Syntax Errors::           How to find syntax errors.
+* Test Coverage::           Ensuring you have tested all branches in your code.
+* Compilation Errors::      How to find errors that show up in
+                              byte compilation.
+
+The Lisp Debugger
+
+* Error Debugging::         Entering the debugger when an error happens.
+* Infinite Loops::	    Stopping and debugging a program that doesn't exit.
+* Function Debugging::      Entering it when a certain function is called.
+* Explicit Debug::          Entering it at a certain point in the program.
+* Using Debugger::          What the debugger does; what you see while in it.
+* Debugger Commands::       Commands used while in the debugger.
+* Invoking the Debugger::   How to call the function @code{debug}.
+* Internals of Debugger::   Subroutines of the debugger, and global variables.
+
+Edebug
+
+* Using Edebug::	    Introduction to use of Edebug.
+* Instrumenting::	    You must instrument your code
+			      in order to debug it with Edebug.
+* Edebug Execution Modes::  Execution modes, stopping more or less often.
+* Jumping::		    Commands to jump to a specified place.
+* Edebug Misc::		    Miscellaneous commands.
+* Breaks::		    Setting breakpoints to make the program stop.
+* Trapping Errors::	    Trapping errors with Edebug.
+* Edebug Views::	    Views inside and outside of Edebug.
+* Edebug Eval::		    Evaluating expressions within Edebug.
+* Eval List::		    Expressions whose values are displayed
+			      each time you enter Edebug.
+* Printing in Edebug::	    Customization of printing.
+* Trace Buffer::	    How to produce trace output in a buffer.
+* Coverage Testing::	    How to test evaluation coverage.
+* The Outside Context::	    Data that Edebug saves and restores.
+* Edebug and Macros::       Specifying how to handle macro calls.
+* Edebug Options::	    Option variables for customizing Edebug.
+
+Debugging Invalid Lisp Syntax
+
+* Excess Open::             How to find a spurious open paren or missing close.
+* Excess Close::            How to find a spurious close paren or missing open.
+
+Reading and Printing Lisp Objects
+
+* Streams Intro::           Overview of streams, reading and printing.
+* Input Streams::           Various data types that can be used as
+                              input streams.
+* Input Functions::         Functions to read Lisp objects from text.
+* Output Streams::          Various data types that can be used as
+                              output streams.
+* Output Functions::        Functions to print Lisp objects as text.
+* Output Variables::        Variables that control what the printing
+                              functions do.
+
+Minibuffers
+
+* Intro to Minibuffers::    Basic information about minibuffers.
+* Text from Minibuffer::    How to read a straight text string.
+* Object from Minibuffer::  How to read a Lisp object or expression.
+* Minibuffer History::	    Recording previous minibuffer inputs
+			      so the user can reuse them.
+* Initial Input::           Specifying initial contents for the minibuffer.
+* Completion::              How to invoke and customize completion.
+* Yes-or-No Queries::       Asking a question with a simple answer.
+* Multiple Queries::	    Asking a series of similar questions.
+* Reading a Password::	    Reading a password from the terminal.
+* Minibuffer Commands::     Commands used as key bindings in minibuffers.
+* Minibuffer Contents::     How such commands access the minibuffer text.
+* Minibuffer Windows::      Operating on the special minibuffer windows.
+* Recursive Mini::          Whether recursive entry to minibuffer is allowed.
+* Minibuffer Misc::         Various customization hooks and variables.
+
+Completion
+
+* Basic Completion::        Low-level functions for completing strings.
+                              (These are too low level to use the minibuffer.)
+* Minibuffer Completion::   Invoking the minibuffer with completion.
+* Completion Commands::     Minibuffer commands that do completion.
+* High-Level Completion::   Convenient special cases of completion
+                              (reading buffer name, file name, etc.)
+* Reading File Names::      Using completion to read file names.
+* Programmed Completion::   Finding the completions for a given file name.
+
+Command Loop
+
+* Command Overview::    How the command loop reads commands.
+* Defining Commands::   Specifying how a function should read arguments.
+* Interactive Call::    Calling a command, so that it will read arguments.
+* Command Loop Info::   Variables set by the command loop for you to examine.
+* Adjusting Point::     Adjustment of point after a command.
+* Input Events::	What input looks like when you read it.
+* Reading Input::       How to read input events from the keyboard or mouse.
+* Special Events::      Events processed immediately and individually.
+* Waiting::             Waiting for user input or elapsed time.
+* Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
+* Prefix Command Arguments::    How the commands to set prefix args work.
+* Recursive Editing::   Entering a recursive edit,
+                          and why you usually shouldn't.
+* Disabling Commands::  How the command loop handles disabled commands.
+* Command History::     How the command history is set up, and how accessed.
+* Keyboard Macros::     How keyboard macros are implemented.
+
+Defining Commands
+
+* Using Interactive::       General rules for @code{interactive}.
+* Interactive Codes::       The standard letter-codes for reading arguments
+                              in various ways.
+* Interactive Examples::    Examples of how to read interactive arguments.
+
+Input Events
+
+* Keyboard Events::         Ordinary characters--keys with symbols on them.
+* Function Keys::           Function keys--keys with names, not symbols.
+* Mouse Events::            Overview of mouse events.
+* Click Events::            Pushing and releasing a mouse button.
+* Drag Events::             Moving the mouse before releasing the button.
+* Button-Down Events::      A button was pushed and not yet released.
+* Repeat Events::           Double and triple click (or drag, or down).
+* Motion Events::           Just moving the mouse, not pushing a button.
+* Focus Events::            Moving the mouse between frames.
+* Misc Events::             Other events the system can generate.
+* Event Examples::          Examples of the lists for mouse events.
+* Classifying Events::      Finding the modifier keys in an event symbol.
+* Accessing Events::        Functions to extract info from events.
+* Strings of Events::       Special considerations for putting
+                              keyboard character events in a string.
+
+Reading Input
+
+* Key Sequence Input::      How to read one key sequence.
+* Reading One Event::       How to read just one event.
+* Event Mod::               How Emacs modifies events as they are read.
+* Invoking the Input Method::   How reading an event uses the input method.
+* Quoted Character Input::  Asking the user to specify a character.
+* Event Input Misc::        How to reread or throw away input events.
+
+Keymaps
+
+* Key Sequences::           Key sequences as Lisp objects.
+* Keymap Basics::           Basic concepts of keymaps.
+* Format of Keymaps::       What a keymap looks like as a Lisp object.
+* Creating Keymaps::        Functions to create and copy keymaps.
+* Inheritance and Keymaps:: How one keymap can inherit the bindings
+                              of another keymap.
+* Prefix Keys::             Defining a key with a keymap as its definition.
+* Active Keymaps::          How Emacs searches the active keymaps
+                              for a key binding.
+* Searching Keymaps::       A pseudo-Lisp summary of searching active maps.
+* Controlling Active Maps:: Each buffer has a local keymap
+                               to override the standard (global) bindings.
+                               A minor mode can also override them.
+* Key Lookup::              How extracting elements from keymaps works.
+* Functions for Key Lookup::    How to request key lookup.
+* Changing Key Bindings::   Redefining a key in a keymap.
+* Remapping Commands::      A keymap can translate one command to another.
+* Translation Keymaps::     Keymaps for translating sequences of events.
+* Key Binding Commands::    Interactive interfaces for redefining keys.
+* Scanning Keymaps::        Looking through all keymaps, for printing help.
+* Menu Keymaps::            A keymap can define a menu for X
+                              or for use from the terminal.
+* Standard Keymaps::        List of standard keymaps.
+
+Major and Minor Modes
+
+* Hooks::                   How to use hooks; how to write code that
+                              provides hooks.
+* Major Modes::             Defining major modes.
+* Minor Modes::             Defining minor modes.
+* Mode Line Format::        Customizing the text that appears in the mode line.
+* Imenu::                   How a mode can provide a menu
+                              of definitions in the buffer.
+* Font Lock Mode::          How modes can highlight text according to syntax.
+* Desktop Save Mode::       How modes can have buffer state saved between
+                              Emacs sessions.
+
+Menu Keymaps
+
+* Defining Menus::          How to make a keymap that defines a menu.
+* Mouse Menus::             How users actuate the menu with the mouse.
+* Keyboard Menus::          How users actuate the menu with the keyboard.
+* Menu Example::            Making a simple menu.
+* Menu Bar::                How to customize the menu bar.
+* Tool Bar::                A tool bar is a row of images.
+* Modifying Menus::         How to add new items to a menu.
+
+Defining Menus
+
+* Simple Menu Items::       A simple kind of menu key binding,
+                              limited in capabilities.
+* Extended Menu Items::     More powerful menu item definitions
+                              let you specify keywords to enable
+                              various features.
+* Menu Separators::         Drawing a horizontal line through a menu.
+* Alias Menu Items::        Using command aliases in menu items.
+
+Major and Minor Modes
+
+* Hooks::              How to use hooks; how to write code that provides hooks.
+* Major Modes::        Defining major modes.
+* Minor Modes::        Defining minor modes.
+* Mode Line Format::   Customizing the text that appears in the mode line.
+* Imenu::              How a mode can provide a menu
+                         of definitions in the buffer.
+* Font Lock Mode::     How modes can highlight text according to syntax.
+* Desktop Save Mode::  How modes can have buffer state saved between
+                         Emacs sessions.
+
+Major Modes
+
+* Major Mode Basics::
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* Example Major Modes::     Text mode and Lisp modes.
+* Auto Major Mode::         How Emacs chooses the major mode automatically.
+* Mode Help::               Finding out how to use a mode.
+* Derived Modes::           Defining a new major mode based on another major
+                              mode.
+* Generic Modes::           Defining a simple major mode that supports
+                              comment syntax and Font Lock mode.
+* Mode Hooks::              Hooks run at the end of major mode functions.
+
+Minor Modes
+
+* Minor Mode Conventions::  Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+* Defining Minor Modes::    A convenient facility for defining minor modes.
+
+Mode Line Format
+
+* Mode Line Basics::
+* Mode Line Data::          The data structure that controls the mode line.
+* Mode Line Variables::     Variables used in that data structure.
+* %-Constructs::            Putting information into a mode line.
+* Properties in Mode::      Using text properties in the mode line.
+* Header Lines::            Like a mode line, but at the top.
+* Emulating Mode Line::     Formatting text as the mode line would.
+
+Font Lock Mode
+
+* Font Lock Basics::        Overview of customizing Font Lock.
+* Search-based Fontification::  Fontification based on regexps.
+* Customizing Keywords::    Customizing search-based fontification.
+* Other Font Lock Variables::   Additional customization facilities.
+* Levels of Font Lock::     Each mode can define alternative levels
+                              so that the user can select more or less.
+* Precalculated Fontification:: How Lisp programs that produce the buffer
+                                  contents can also specify how to fontify it.
+* Faces for Font Lock::     Special faces specifically for Font Lock.
+* Syntactic Font Lock::     Fontification based on syntax tables.
+* Setting Syntax Properties::   Defining character syntax based on context
+                                  using the Font Lock mechanism.
+* Multiline Font Lock::     How to coerce Font Lock into properly
+                              highlighting multiline constructs.
+
+Multiline Font Lock Constructs
+
+* Font Lock Multiline::     Marking multiline chunks with a text property
+* Region to Fontify::       Controlling which region gets refontified
+                              after a buffer change.
+
+Documentation
+
+* Documentation Basics::    Good style for doc strings.
+                              Where to put them.  How Emacs stores them.
+* Accessing Documentation:: How Lisp programs can access doc strings.
+* Keys in Documentation::   Substituting current key bindings.
+* Describing Characters::   Making printable descriptions of
+                              non-printing characters and key sequences.
+* Help Functions::          Subroutines used by Emacs help facilities.
+
+Files
+
+* Visiting Files::          Reading files into Emacs buffers for editing.
+* Saving Buffers::          Writing changed buffers back into files.
+* Reading from Files::      Reading files into other buffers.
+* Writing to Files::        Writing new files from parts of buffers.
+* File Locks::              Locking and unlocking files, to prevent
+                              simultaneous editing by two people.
+* Information about Files:: Testing existence, accessibility, size of files.
+* Changing Files::          Renaming files, changing protection, etc.
+* File Names::              Decomposing and expanding file names.
+* Contents of Directories:: Getting a list of the files in a directory.
+* Create/Delete Dirs::	    Creating and Deleting Directories.
+* Magic File Names::	    Defining "magic" special handling
+			      for certain file names.
+* Format Conversion::       Conversion to and from various file formats.
+
+Visiting Files
+
+* Visiting Functions::      The usual interface functions for visiting.
+* Subroutines of Visiting:: Lower-level subroutines that they use.
+
+Information about Files
+
+* Testing Accessibility::   Is a given file readable?  Writable?
+* Kinds of Files::          Is it a directory?  A symbolic link?
+* Truenames::		    Eliminating symbolic links from a file name.
+* File Attributes::         How large is it?  Any other names?  Etc.
+* Locating Files::          How to find a file in standard places.
+
+File Names
+
+* File Name Components::    The directory part of a file name, and the rest.
+* Relative File Names::     Some file names are relative to a
+                              current directory.
+* Directory Names::         A directory's name as a directory
+                              is different from its name as a file.
+* File Name Expansion::     Converting relative file names to absolute ones.
+* Unique File Names::       Generating names for temporary files.
+* File Name Completion::    Finding the completions for a given file name.
+* Standard File Names::     If your package uses a fixed file name,
+                              how to handle various operating systems simply.
+
+Backups and Auto-Saving
+
+* Backup Files::            How backup files are made; how their names
+                              are chosen.
+* Auto-Saving::             How auto-save files are made; how their
+                              names are chosen.
+* Reverting::               @code{revert-buffer}, and how to customize
+                              what it does.
+
+Backup Files
+
+* Making Backups::          How Emacs makes backup files, and when.
+* Rename or Copy::          Two alternatives: renaming the old file
+                              or copying it.
+* Numbered Backups::        Keeping multiple backups for each source file.
+* Backup Names::            How backup file names are computed; customization.
+
+Buffers
+
+* Buffer Basics::           What is a buffer?
+* Current Buffer::          Designating a buffer as current
+                              so primitives will access its contents.
+* Buffer Names::            Accessing and changing buffer names.
+* Buffer File Name::        The buffer file name indicates which file
+                              is visited.
+* Buffer Modification::     A buffer is @dfn{modified} if it needs to be saved.
+* Modification Time::       Determining whether the visited file was changed
+                              ``behind Emacs's back''.
+* Read Only Buffers::       Modifying text is not allowed in a
+                              read-only buffer.
+* The Buffer List::         How to look at all the existing buffers.
+* Creating Buffers::        Functions that create buffers.
+* Killing Buffers::         Buffers exist until explicitly killed.
+* Indirect Buffers::        An indirect buffer shares text with some
+                              other buffer.
+* Buffer Gap::              The gap in the buffer.
+
+Windows
+
+* Basic Windows::           Basic information on using windows.
+* Splitting Windows::       Splitting one window into two windows.
+* Deleting Windows::        Deleting a window gives its space to other windows.
+* Selecting Windows::       The selected window is the one that you edit in.
+* Cyclic Window Ordering::  Moving around the existing windows.
+* Buffers and Windows::     Each window displays the contents of a buffer.
+* Displaying Buffers::      Higher-level functions for displaying a buffer
+                              and choosing a window for it.
+* Choosing Window::	    How to choose a window for displaying a buffer.
+* Window Point::            Each window has its own location of point.
+* Window Start::            The display-start position controls which text
+                              is on-screen in the window.
+* Textual Scrolling::       Moving text up and down through the window.
+* Vertical Scrolling::      Moving the contents up and down on the window.
+* Horizontal Scrolling::    Moving the contents sideways on the window.
+* Size of Window::          Accessing the size of a window.
+* Resizing Windows::        Changing the size of a window.
+* Coordinates and Windows:: Converting coordinates to windows.
+* Window Tree::             The layout and sizes of all windows in a frame.
+* Window Configurations::   Saving and restoring the state of the screen.
+* Window Hooks::            Hooks for scrolling, window size changes,
+                              redisplay going past a certain point,
+                              or window configuration changes.
+
+Frames
+
+* Creating Frames::	    Creating additional frames.
+* Multiple Displays::       Creating frames on other displays.
+* Frame Parameters::	    Controlling frame size, position, font, etc.
+* Frame Titles::            Automatic updating of frame titles.
+* Deleting Frames::	    Frames last until explicitly deleted.
+* Finding All Frames::	    How to examine all existing frames.
+* Frames and Windows::	    A frame contains windows;
+			      display of text always works through windows.
+* Minibuffers and Frames::  How a frame finds the minibuffer to use.
+* Input Focus::		    Specifying the selected frame.
+* Visibility of Frames::    Frames may be visible or invisible, or icons.
+* Raising and Lowering::    Raising a frame makes it hide other windows;
+			      lowering it puts it underneath the others.
+* Frame Configurations::    Saving the state of all frames.
+* Mouse Tracking::	    Getting events that say when the mouse moves.
+* Mouse Position::	    Asking where the mouse is, or moving it.
+* Pop-Up Menus::	    Displaying a menu for the user to select from.
+* Dialog Boxes::            Displaying a box to ask yes or no.
+* Pointer Shape::           Specifying the shape of the mouse pointer.
+* Window System Selections::Transferring text to and from other windows.
+* Drag and Drop::               Internals of Drag-and-Drop implementation.
+* Color Names::	            Getting the definitions of color names.
+* Text Terminal Colors::    Defining colors for text-only terminals.
+* Resources::		    Getting resource values from the server.
+* Display Feature Testing:: Determining the features of a terminal.
+
+Frame Parameters
+
+* Parameter Access::        How to change a frame's parameters.
+* Initial Parameters::	    Specifying frame parameters when you make a frame.
+* Window Frame Parameters:: List of frame parameters for window systems.
+* Size and Position::       Changing the size and position of a frame.
+* Geometry::                Parsing geometry specifications.
+
+Window Frame Parameters
+
+* Basic Parameters::        Parameters that are fundamental.
+* Position Parameters::     The position of the frame on the screen.
+* Size Parameters::         Frame's size.
+* Layout Parameters::       Size of parts of the frame, and
+                              enabling or disabling some parts.
+* Buffer Parameters::       Which buffers have been or should be shown.
+* Management Parameters::   Communicating with the window manager.
+* Cursor Parameters::       Controlling the cursor appearance.
+* Color Parameters::        Colors of various parts of the frame.
+
+Positions
+
+* Point::                   The special position where editing takes place.
+* Motion::                  Changing point.
+* Excursions::              Temporary motion and buffer changes.
+* Narrowing::               Restricting editing to a portion of the buffer.
+
+Motion
+
+* Character Motion::        Moving in terms of characters.
+* Word Motion::             Moving in terms of words.
+* Buffer End Motion::       Moving to the beginning or end of the buffer.
+* Text Lines::              Moving in terms of lines of text.
+* Screen Lines::            Moving in terms of lines as displayed.
+* List Motion::             Moving by parsing lists and sexps.
+* Skipping Characters::     Skipping characters belonging to a certain set.
+
+Markers
+
+* Overview of Markers::     The components of a marker, and how it relocates.
+* Predicates on Markers::   Testing whether an object is a marker.
+* Creating Markers::        Making empty markers or markers at certain places.
+* Information from Markers::Finding the marker's buffer or character
+                              position.
+* Marker Insertion Types::  Two ways a marker can relocate when you
+                              insert where it points.
+* Moving Markers::          Moving the marker to a new buffer or position.
+* The Mark::                How "the mark" is implemented with a marker.
+* The Region::              How to access "the region".
+
+Text
+
+* Near Point::              Examining text in the vicinity of point.
+* Buffer Contents::         Examining text in a general fashion.
+* Comparing Text::          Comparing substrings of buffers.
+* Insertion::               Adding new text to a buffer.
+* Commands for Insertion::  User-level commands to insert text.
+* Deletion::                Removing text from a buffer.
+* User-Level Deletion::     User-level commands to delete text.
+* The Kill Ring::           Where removed text sometimes is saved for
+                              later use.
+* Undo::                    Undoing changes to the text of a buffer.
+* Maintaining Undo::        How to enable and disable undo information.
+			      How to control how much information is kept.
+* Filling::                 Functions for explicit filling.
+* Margins::                 How to specify margins for filling commands.
+* Adaptive Fill::           Adaptive Fill mode chooses a fill prefix
+                              from context.
+* Auto Filling::            How auto-fill mode is implemented to break lines.
+* Sorting::                 Functions for sorting parts of the buffer.
+* Columns::                 Computing horizontal positions, and using them.
+* Indentation::             Functions to insert or adjust indentation.
+* Case Changes::            Case conversion of parts of the buffer.
+* Text Properties::         Assigning Lisp property lists to text characters.
+* Substitution::            Replacing a given character wherever it appears.
+* Transposition::           Swapping two portions of a buffer.
+* Registers::               How registers are implemented.  Accessing
+                              the text or position stored in a register.
+* Base 64::                 Conversion to or from base 64 encoding.
+* MD5 Checksum::            Compute the MD5 "message digest"/"checksum".
+* Atomic Changes::          Installing several buffer changes "atomically".
+* Change Hooks::            Supplying functions to be run when text is changed.
+
+The Kill Ring
+
+* Kill Ring Concepts::      What text looks like in the kill ring.
+* Kill Functions::          Functions that kill text.
+* Yanking::                 How yanking is done.
+* Yank Commands::           Commands that access the kill ring.
+* Low-Level Kill Ring::	    Functions and variables for kill ring access.
+* Internals of Kill Ring::  Variables that hold kill-ring data.
+
+Indentation
+
+* Primitive Indent::        Functions used to count and insert indentation.
+* Mode-Specific Indent::    Customize indentation for different modes.
+* Region Indent::           Indent all the lines in a region.
+* Relative Indent::         Indent the current line based on previous lines.
+* Indent Tabs::             Adjustable, typewriter-like tab stops.
+* Motion by Indent::        Move to first non-blank character.
+
+Text Properties
+
+* Examining Properties::    Looking at the properties of one character.
+* Changing Properties::	    Setting the properties of a range of text.
+* Property Search::	    Searching for where a property changes value.
+* Special Properties::	    Particular properties with special meanings.
+* Format Properties::       Properties for representing formatting of text.
+* Sticky Properties::       How inserted text gets properties from
+                              neighboring text.
+* Saving Properties::       Saving text properties in files, and reading
+                              them back.
+* Lazy Properties::         Computing text properties in a lazy fashion
+                              only when text is examined.
+* Clickable Text::          Using text properties to make regions of text
+                              do something when you click on them.
+* Links and Mouse-1::       How to make @key{Mouse-1} follow a link.
+* Fields::                  The @code{field} property defines
+                              fields within the buffer.
+* Not Intervals::	    Why text properties do not use
+			      Lisp-visible text intervals.
+
+Non-ASCII Characters
+
+* Text Representations::    Unibyte and multibyte representations
+* Converting Representations::  Converting unibyte to multibyte and vice versa.
+* Selecting a Representation::  Treating a byte sequence as unibyte or multi.
+* Character Codes::         How unibyte and multibyte relate to
+                                codes of individual characters.
+* Character Sets::          The space of possible character codes
+                                is divided into various character sets.
+* Chars and Bytes::         More information about multibyte encodings.
+* Splitting Characters::    Converting a character to its byte sequence.
+* Scanning Charsets::       Which character sets are used in a buffer?
+* Translation of Characters::   Translation tables are used for conversion.
+* Coding Systems::          Coding systems are conversions for saving files.
+* Input Methods::           Input methods allow users to enter various
+                                non-ASCII characters without special keyboards.
+* Locales::                 Interacting with the POSIX locale.
+
+Coding Systems
+
+* Coding System Basics::    Basic concepts.
+* Encoding and I/O::        How file I/O functions handle coding systems.
+* Lisp and Coding Systems:: Functions to operate on coding system names.
+* User-Chosen Coding Systems::  Asking the user to choose a coding system.
+* Default Coding Systems::  Controlling the default choices.
+* Specifying Coding Systems::   Requesting a particular coding system
+                                    for a single file operation.
+* Explicit Encoding::       Encoding or decoding text without doing I/O.
+* Terminal I/O Encoding::   Use of encoding for terminal I/O.
+* MS-DOS File Types::       How DOS "text" and "binary" files
+                                relate to coding systems.
+
+Searching and Matching
+
+* String Search::           Search for an exact match.
+* Searching and Case::      Case-independent or case-significant searching.
+* Regular Expressions::     Describing classes of strings.
+* Regexp Search::           Searching for a match for a regexp.
+* POSIX Regexps::           Searching POSIX-style for the longest match.
+* Match Data::              Finding out which part of the text matched,
+                              after a string or regexp search.
+* Search and Replace::	    Commands that loop, searching and replacing.
+* Standard Regexps::        Useful regexps for finding sentences, pages,...
+
+Regular Expressions
+
+* Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Example::          Illustrates regular expression syntax.
+* Regexp Functions::        Functions for operating on regular expressions.
+
+Syntax of Regular Expressions
+
+* Regexp Special::          Special characters in regular expressions.
+* Char Classes::            Character classes used in regular expressions.
+* Regexp Backslash::        Backslash-sequences in regular expressions.
+
+The Match Data
+
+* Replacing Match::	    Replacing a substring that was matched.
+* Simple Match Data::       Accessing single items of match data,
+			      such as where a particular subexpression started.
+* Entire Match Data::       Accessing the entire match data at once, as a list.
+* Saving Match Data::       Saving and restoring the match data.
+
+Syntax Tables
+
+* Syntax Basics::           Basic concepts of syntax tables.
+* Syntax Descriptors::      How characters are classified.
+* Syntax Table Functions::  How to create, examine and alter syntax tables.
+* Syntax Properties::       Overriding syntax with text properties.
+* Motion and Syntax::	    Moving over characters with certain syntaxes.
+* Parsing Expressions::     Parsing balanced expressions
+                              using the syntax table.
+* Standard Syntax Tables::  Syntax tables used by various major modes.
+* Syntax Table Internals::  How syntax table information is stored.
+* Categories::              Another way of classifying character syntax.
+
+Syntax Descriptors
+
+* Syntax Class Table::      Table of syntax classes.
+* Syntax Flags::            Additional flags each character can have.
+
+Parsing Expressions
+
+* Motion via Parsing::      Motion functions that work by parsing.
+* Position Parse::          Determining the syntactic state of a position.
+* Parser State::            How Emacs represents a syntactic state.
+* Low-Level Parsing::       Parsing across a specified region.
+* Control Parsing::         Parameters that affect parsing.
+
+Abbrevs And Abbrev Expansion
+
+* Abbrev Mode::             Setting up Emacs for abbreviation.
+* Abbrev Tables::           Creating and working with abbrev tables.
+* Defining Abbrevs::        Specifying abbreviations and their expansions.
+* Abbrev Files::            Saving abbrevs in files.
+* Abbrev Expansion::        Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables::  Abbrev tables used by various major modes.
+
+Processes
+
+* Subprocess Creation::     Functions that start subprocesses.
+* Shell Arguments::         Quoting an argument to pass it to a shell.
+* Synchronous Processes::   Details of using synchronous subprocesses.
+* Asynchronous Processes::  Starting up an asynchronous subprocess.
+* Deleting Processes::      Eliminating an asynchronous subprocess.
+* Process Information::     Accessing run-status and other attributes.
+* Input to Processes::      Sending input to an asynchronous subprocess.
+* Signals to Processes::    Stopping, continuing or interrupting
+                              an asynchronous subprocess.
+* Output from Processes::   Collecting output from an asynchronous subprocess.
+* Sentinels::               Sentinels run when process run-status changes.
+* Query Before Exit::       Whether to query if exiting will kill a process.
+* Transaction Queues::      Transaction-based communication with subprocesses.
+* Network::                 Opening network connections.
+* Network Servers::         Network servers let Emacs accept net connections.
+* Datagrams::               UDP network connections.
+* Low-Level Network::       Lower-level but more general function
+                              to create connections and servers.
+* Misc Network::            Additional relevant functions for network connections.
+* Byte Packing::            Using bindat to pack and unpack binary data.
+
+Receiving Output from Processes
+
+* Process Buffers::         If no filter, output is put in a buffer.
+* Filter Functions::        Filter functions accept output from the process.
+* Decoding Output::         Filters can get unibyte or multibyte strings.
+* Accepting Output::        How to wait until process output arrives.
+
+Low-Level Network Access
+
+* Proc: Network Processes.  Using @code{make-network-process}.
+* Options: Network Options.  Further control over network connections.
+* Features: Network Feature Testing.
+                            Determining which network features work on
+                              the machine you are using.
+
+Packing and Unpacking Byte Arrays
+
+* Bindat Spec::             Describing data layout.
+* Bindat Functions::        Doing the unpacking and packing.
+* Bindat Examples::         Samples of what bindat.el can do for you!
+
+Emacs Display
+
+* Refresh Screen::          Clearing the screen and redrawing everything on it.
+* Forcing Redisplay::       Forcing redisplay.
+* Truncation::              Folding or wrapping long text lines.
+* The Echo Area::           Displaying messages at the bottom of the screen.
+* Warnings::                Displaying warning messages for the user.
+* Invisible Text::          Hiding part of the buffer text.
+* Selective Display::       Hiding part of the buffer text (the old way).
+* Temporary Displays::      Displays that go away automatically.
+* Overlays::		    Use overlays to highlight parts of the buffer.
+* Width::                   How wide a character or string is on the screen.
+* Line Height::             Controlling the height of lines.
+* Faces::		    A face defines a graphics style
+                              for text characters: font, colors, etc.
+* Fringes::                 Controlling window fringes.
+* Scroll Bars::             Controlling vertical scroll bars.
+* Display Property::        Enabling special display features.
+* Images::                  Displaying images in Emacs buffers.
+* Buttons::                 Adding clickable buttons to Emacs buffers.
+* Abstract Display::        Emacs' Widget for Object Collections.
+* Blinking::                How Emacs shows the matching open parenthesis.
+* Usual Display::	    The usual conventions for displaying nonprinting chars.
+* Display Tables::	    How to specify other conventions.
+* Beeping::                 Audible signal to the user.
+* Window Systems::          Which window system is being used.
+
+The Echo Area
+
+* Displaying Messages::     Explicitly displaying text in the echo area.
+* Progress::                Informing user about progress of a long operation.
+* Logging Messages::        Echo area messages are logged for the user.
+* Echo Area Customization:: Controlling the echo area.
+
+Reporting Warnings
+
+* Warning Basics::          Warnings concepts and functions to report them.
+* Warning Variables::       Variables programs bind to customize their warnings.
+* Warning Options::         Variables users set to control display of warnings.
+
+Overlays
+
+* Managing Overlays::       Creating and moving overlays.
+* Overlay Properties::      How to read and set properties.
+			    What properties do to the screen display.
+* Finding Overlays::        Searching for overlays.
+
+Faces
+
+* Defining Faces::          How to define a face with @code{defface}.
+* Face Attributes::         What is in a face?
+* Attribute Functions::     Functions to examine and set face attributes.
+* Displaying Faces::        How Emacs combines the faces specified for
+                              a character.
+* Font Selection::          Finding the best available font for a face.
+* Face Functions::          How to define and examine faces.
+* Auto Faces::              Hook for automatic face assignment.
+* Font Lookup::             Looking up the names of available fonts
+                              and information about them.
+* Fontsets::                A fontset is a collection of fonts
+                              that handle a range of character sets.
+
+Fringes
+
+* Fringe Size/Pos::         Specifying where to put the window fringes.
+* Fringe Indicators::       Displaying indicator icons in the window fringes.
+* Fringe Cursors::          Displaying cursors in the right fringe.
+* Fringe Bitmaps::          Specifying bitmaps for fringe indicators.
+* Customizing Bitmaps::     Specifying your own bitmaps to use in the fringes.
+* Overlay Arrow::           Display of an arrow to indicate position.
+
+The @code{display} Property
+
+* Specified Space::         Displaying one space with a specified width.
+* Pixel Specification::     Specifying space width or height in pixels.
+* Other Display Specs::     Displaying an image; magnifying text; moving it
+                              up or down on the page; adjusting the width
+                              of spaces within text.
+* Display Margins::         Displaying text or images to the side of
+                              the main text.
+
+Images
+
+* Image Descriptors::       How to specify an image for use in @code{:display}.
+* XBM Images::              Special features for XBM format.
+* XPM Images::              Special features for XPM format.
+* GIF Images::              Special features for GIF format.
+* PostScript Images::       Special features for PostScript format.
+* Other Image Types::       Various other formats are supported.
+* Defining Images::         Convenient ways to define an image for later use.
+* Showing Images::          Convenient ways to display an image once
+                              it is defined.
+* Image Cache::             Internal mechanisms of image display.
+
+Buttons
+
+* Button Properties::       Button properties with special meanings.
+* Button Types::            Defining common properties for classes of buttons.
+* Making Buttons::          Adding buttons to Emacs buffers.
+* Manipulating Buttons::    Getting and setting properties of buttons.
+* Button Buffer Commands::  Buffer-wide commands and bindings for buttons.
+
+Abstract Display
+
+* Abstract Display Functions::  Functions in the Ewoc package.
+* Abstract Display Example::    Example of using Ewoc.
+
+Display Tables
+
+* Display Table Format::    What a display table consists of.
+* Active Display Table::    How Emacs selects a display table to use.
+* Glyphs::                  How to define a glyph, and what glyphs mean.
+
+Operating System Interface
+
+* Starting Up::             Customizing Emacs start-up processing.
+* Getting Out::             How exiting works (permanent or temporary).
+* System Environment::      Distinguish the name and kind of system.
+* User Identification::     Finding the name and user id of the user.
+* Time of Day::		    Getting the current time.
+* Time Conversion::         Converting a time from numeric form to a string, or
+                              to calendrical data (or vice versa).
+* Time Parsing::            Converting a time from numeric form to text
+                              and vice versa.
+* Processor Run Time::      Getting the run time used by Emacs.
+* Time Calculations::       Adding, subtracting, comparing times, etc.
+* Timers::		    Setting a timer to call a function at a certain time.
+* Idle Timers::             Setting a timer to call a function when Emacs has
+                              been idle for a certain length of time.
+* Terminal Input::          Accessing and recording terminal input.
+* Terminal Output::         Controlling and recording terminal output.
+* Sound Output::            Playing sounds on the computer's speaker.
+* X11 Keysyms::             Operating on key symbols for X Windows
+* Batch Mode::              Running Emacs without terminal interaction.
+* Session Management::      Saving and restoring state with X Session Management.
+
+Starting Up Emacs
+
+* Startup Summary::         Sequence of actions Emacs performs at start-up.
+* Init File::               Details on reading the init file (@file{.emacs}).
+* Terminal-Specific::       How the terminal-specific Lisp file is read.
+* Command-Line Arguments::  How command-line arguments are processed,
+                              and how you can customize them.
+
+Getting Out of Emacs
+
+* Killing Emacs::           Exiting Emacs irreversibly.
+* Suspending Emacs::        Exiting Emacs reversibly.
+
+Terminal Input
+
+* Input Modes::		    Options for how input is processed.
+* Recording Input::	    Saving histories of recent or all input events.
+
+Tips and Conventions
+
+* Coding Conventions::      Conventions for clean and robust programs.
+* Key Binding Conventions:: Which keys should be bound by which programs.
+* Programming Tips::        Making Emacs code fit smoothly in Emacs.
+* Compilation Tips::        Making compiled code run fast.
+* Warning Tips::            Turning off compiler warnings.
+* Documentation Tips::      Writing readable documentation strings.
+* Comment Tips::	    Conventions for writing comments.
+* Library Headers::         Standard headers for library packages.
+
+GNU Emacs Internals
+
+* Building Emacs::          How the dumped Emacs is made.
+* Pure Storage::            A kludge to make preloaded Lisp functions sharable.
+* Garbage Collection::      Reclaiming space for Lisp objects no longer used.
+* Memory Usage::            Info about total size of Lisp objects made so far.
+* Writing Emacs Primitives::  Writing C code for Emacs.
+* Object Internals::        Data formats of buffers, windows, processes.
+
+Object Internals
+
+* Buffer Internals::        Components of a buffer structure.
+* Window Internals::        Components of a window structure.
+* Process Internals::       Components of a process structure.
+@end detailmenu
+@end menu
+
+@c include intro.texi
+@c include objects.texi
+@c include numbers.texi
+@c include strings.texi
+
+@c include lists.texi
+@c include sequences.texi
+@c include hash.texi
+@c include symbols.texi
+@c include eval.texi
+
+@c include control.texi
+@c include variables.texi
+@c include functions.texi
+@c include macros.texi
+
+@c include customize.texi
+@c include loading.texi
+@c include compile.texi
+@c include advice.texi
+
+@c include debugging.texi
+@c include streams.texi
+@c include minibuf.texi
+@c include commands.texi
+
+@c include keymaps.texi
+@c include modes.texi
+@c include help.texi
+@c include files.texi
+
+@c include backups.texi
+
+@c ================ Beginning of Volume 2 ================
+@include buffers.texi
+@include windows.texi
+@include frames.texi
+
+@include positions.texi
+@include markers.texi
+@include text.texi
+@include nonascii.texi
+
+@include searching.texi
+@include syntax.texi
+@include abbrevs.texi
+@include processes.texi
+
+@include display.texi
+@include os.texi
+
+@c MOVE to Emacs Manual:  include misc-modes.texi
+
+@c appendices
+
+@c  REMOVE this:  include non-hacker.texi
+
+@include anti.texi
+@include doclicense.texi
+@include gpl.texi
+@include tips.texi
+@include internals.texi
+@include errors.texi
+@include locals.texi
+@include maps.texi
+@include hooks.texi
+
+@include index.texi
+
+@ignore
+@node New Symbols, , Index, Top
+@unnumbered New Symbols Since the Previous Edition
+
+@printindex tp
+@end ignore
+
+@bye
+
+
+These words prevent "local variables" above from confusing Emacs.
+
+@ignore
+   arch-tag: dfdbecf8-fec2-49c1-8427-3e8ac8b0b849
+@end ignore
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
new file mode 100644
index 00000000000..bd8f7bc2d36
--- /dev/null
+++ b/doc/lispref/windows.texi
@@ -0,0 +1,2446 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/windows
+@node Windows, Frames, Buffers, Top
+@chapter Windows
+
+  This chapter describes most of the functions and variables related to
+Emacs windows.  See @ref{Display}, for information on how text is
+displayed in windows.
+
+@menu
+* Basic Windows::           Basic information on using windows.
+* Splitting Windows::       Splitting one window into two windows.
+* Deleting Windows::        Deleting a window gives its space to other windows.
+* Selecting Windows::       The selected window is the one that you edit in.
+* Cyclic Window Ordering::  Moving around the existing windows.
+* Buffers and Windows::     Each window displays the contents of a buffer.
+* Displaying Buffers::      Higher-level functions for displaying a buffer
+                              and choosing a window for it.
+* Choosing Window::	    How to choose a window for displaying a buffer.
+* Window Point::            Each window has its own location of point.
+* Window Start::            The display-start position controls which text
+                              is on-screen in the window.
+* Textual Scrolling::       Moving text up and down through the window.
+* Vertical Scrolling::      Moving the contents up and down on the window.
+* Horizontal Scrolling::    Moving the contents sideways on the window.
+* Size of Window::          Accessing the size of a window.
+* Resizing Windows::        Changing the size of a window.
+* Coordinates and Windows:: Converting coordinates to windows.
+* Window Tree::             The layout and sizes of all windows in a frame.
+* Window Configurations::   Saving and restoring the state of the screen.
+* Window Hooks::            Hooks for scrolling, window size changes,
+                              redisplay going past a certain point,
+                              or window configuration changes.
+@end menu
+
+@node Basic Windows
+@section Basic Concepts of Emacs Windows
+@cindex window
+@cindex selected window
+
+  A @dfn{window} in Emacs is the physical area of the screen in which a
+buffer is displayed.  The term is also used to refer to a Lisp object that
+represents that screen area in Emacs Lisp.  It should be
+clear from the context which is meant.
+
+  Emacs groups windows into frames.  A frame represents an area of
+screen available for Emacs to use.  Each frame always contains at least
+one window, but you can subdivide it vertically or horizontally into
+multiple nonoverlapping Emacs windows.
+
+  In each frame, at any time, one and only one window is designated as
+@dfn{selected within the frame}.  The frame's cursor appears in that
+window, but the other windows have ``non-selected'' cursors, normally
+less visible.  At any time, one frame is the selected frame; and the
+window selected within that frame is @dfn{the selected window}.  The
+selected window's buffer is usually the current buffer (except when
+@code{set-buffer} has been used).  @xref{Current Buffer}.
+
+@defvar cursor-in-non-selected-windows
+If this variable is @code{nil}, Emacs displays only one cursor,
+in the selected window.  Other windows have no cursor at all.
+@end defvar
+
+  For practical purposes, a window exists only while it is displayed in
+a frame.  Once removed from the frame, the window is effectively deleted
+and should not be used, @emph{even though there may still be references
+to it} from other Lisp objects.  Restoring a saved window configuration
+is the only way for a window no longer on the screen to come back to
+life.  (@xref{Deleting Windows}.)
+
+  Each window has the following attributes:
+
+@itemize @bullet
+@item
+containing frame
+
+@item
+window height
+
+@item
+window width
+
+@item
+window edges with respect to the screen or frame
+
+@item
+the buffer it displays
+
+@item
+position within the buffer at the upper left of the window
+
+@item
+amount of horizontal scrolling, in columns
+
+@item
+point
+
+@item
+the mark
+
+@item
+how recently the window was selected
+
+@item
+fringe settings
+
+@item
+display margins
+
+@item
+scroll-bar settings
+@end itemize
+
+@cindex multiple windows
+  Users create multiple windows so they can look at several buffers at
+once.  Lisp libraries use multiple windows for a variety of reasons, but
+most often to display related information.  In Rmail, for example, you
+can move through a summary buffer in one window while the other window
+shows messages one at a time as they are reached.
+
+  The meaning of ``window'' in Emacs is similar to what it means in the
+context of general-purpose window systems such as X, but not identical.
+The X Window System places X windows on the screen; Emacs uses one or
+more X windows as frames, and subdivides them into
+Emacs windows.  When you use Emacs on a character-only terminal, Emacs
+treats the whole terminal screen as one frame.
+
+@cindex terminal screen
+@cindex screen of terminal
+@cindex tiled windows
+  Most window systems support arbitrarily located overlapping windows.
+In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
+together they fill the whole screen or frame.  Because of the way in
+which Emacs creates new windows and resizes them, not all conceivable
+tilings of windows on an Emacs frame are actually possible.
+@xref{Splitting Windows}, and @ref{Size of Window}.
+
+  @xref{Display}, for information on how the contents of the
+window's buffer are displayed in the window.
+
+@defun windowp object
+This function returns @code{t} if @var{object} is a window.
+@end defun
+
+@node Splitting Windows
+@section Splitting Windows
+@cindex splitting windows
+@cindex window splitting
+
+  The functions described here are the primitives used to split a window
+into two windows.  Two higher level functions sometimes split a window,
+but not always: @code{pop-to-buffer} and @code{display-buffer}
+(@pxref{Displaying Buffers}).
+
+  The functions described here do not accept a buffer as an argument.
+The two ``halves'' of the split window initially display the same buffer
+previously visible in the window that was split.
+
+@deffn Command split-window &optional window size horizontal
+This function splits a new window out of @var{window}'s screen area.
+It returns the new window.
+
+If @var{horizontal} is non-@code{nil}, then @var{window} splits into
+two side by side windows.  The original window @var{window} keeps the
+leftmost @var{size} columns, and gives the rest of the columns to the
+new window.  Otherwise, it splits into windows one above the other, and
+@var{window} keeps the upper @var{size} lines and gives the rest of the
+lines to the new window.  The original window is therefore the
+left-hand or upper of the two, and the new window is the right-hand or
+lower.
+
+If @var{window} is omitted or @code{nil}, that stands for the selected
+window.  When you split the selected window, it remains selected.
+
+If @var{size} is omitted or @code{nil}, then @var{window} is divided
+evenly into two parts.  (If there is an odd line, it is allocated to
+the new window.)  When @code{split-window} is called interactively,
+all its arguments are @code{nil}.
+
+If splitting would result in making a window that is smaller than
+@code{window-min-height} or @code{window-min-width}, the function
+signals an error and does not split the window at all.
+
+The following example starts with one window on a screen that is 50
+lines high by 80 columns wide; then it splits the window.
+
+@smallexample
+@group
+(setq w (selected-window))
+     @result{} #<window 8 on windows.texi>
+(window-edges)          ; @r{Edges in order:}
+     @result{} (0 0 80 50)     ;   @r{left--top--right--bottom}
+@end group
+
+@group
+;; @r{Returns window created}
+(setq w2 (split-window w 15))
+     @result{} #<window 28 on windows.texi>
+@end group
+@group
+(window-edges w2)
+     @result{} (0 15 80 50)    ; @r{Bottom window;}
+                        ;   @r{top is line 15}
+@end group
+@group
+(window-edges w)
+     @result{} (0 0 80 15)     ; @r{Top window}
+@end group
+@end smallexample
+
+The screen looks like this:
+
+@smallexample
+@group
+         __________
+        |          |  line 0
+        |    w     |
+        |__________|
+        |          |  line 15
+        |    w2    |
+        |__________|
+                      line 50
+ column 0   column 80
+@end group
+@end smallexample
+
+Next, split the top window horizontally:
+
+@smallexample
+@group
+(setq w3 (split-window w 35 t))
+     @result{} #<window 32 on windows.texi>
+@end group
+@group
+(window-edges w3)
+     @result{} (35 0 80 15)  ; @r{Left edge at column 35}
+@end group
+@group
+(window-edges w)
+     @result{} (0 0 35 15)   ; @r{Right edge at column 35}
+@end group
+@group
+(window-edges w2)
+     @result{} (0 15 80 50)  ; @r{Bottom window unchanged}
+@end group
+@end smallexample
+
+@need 3000
+Now the screen looks like this:
+
+@smallexample
+@group
+     column 35
+         __________
+        |   |      |  line 0
+        | w |  w3  |
+        |___|______|
+        |          |  line 15
+        |    w2    |
+        |__________|
+                      line 50
+ column 0   column 80
+@end group
+@end smallexample
+
+Normally, Emacs indicates the border between two side-by-side windows
+with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|}
+characters.  The display table can specify alternative border
+characters; see @ref{Display Tables}.
+@end deffn
+
+@deffn Command split-window-vertically &optional size
+This function splits the selected window into two windows, one above the
+other, leaving the upper of the two windows selected, with @var{size}
+lines.  (If @var{size} is negative, then the lower of the two windows
+gets @minus{} @var{size} lines and the upper window gets the rest, but
+the upper window is still the one selected.)  However, if
+@code{split-window-keep-point} (see below) is @code{nil}, then either
+window can be selected.
+
+In other respects, this function is similar to @code{split-window}.
+In particular, the upper window is the original one and the return
+value is the new, lower window.
+@end deffn
+
+@defopt split-window-keep-point
+If this variable is non-@code{nil} (the default), then
+@code{split-window-vertically} behaves as described above.
+
+If it is @code{nil}, then @code{split-window-vertically} adjusts point
+in each of the two windows to avoid scrolling.  (This is useful on
+slow terminals.)  It selects whichever window contains the screen line
+that point was previously on.
+
+This variable only affects the behavior of @code{split-window-vertically}.
+It has no effect on the other functions described here.
+@end defopt
+
+@deffn Command split-window-horizontally &optional size
+This function splits the selected window into two windows
+side-by-side, leaving the selected window on the left with @var{size}
+columns.  If @var{size} is negative, the rightmost window gets
+@minus{} @var{size} columns, but the leftmost window still remains
+selected.
+
+This function is basically an interface to @code{split-window}.
+You could define a simplified version of the function like this:
+
+@smallexample
+@group
+(defun split-window-horizontally (&optional arg)
+  "Split selected window into two windows, side by side..."
+  (interactive "P")
+@end group
+@group
+  (let ((size (and arg (prefix-numeric-value arg))))
+    (and size (< size 0)
+	 (setq size (+ (window-width) size)))
+    (split-window nil size t)))
+@end group
+@end smallexample
+@end deffn
+
+@defun one-window-p &optional no-mini all-frames
+This function returns non-@code{nil} if there is only one window.  The
+argument @var{no-mini}, if non-@code{nil}, means don't count the
+minibuffer even if it is active; otherwise, the minibuffer window is
+counted when it is active.
+
+The argument @var{all-frames} specifies which frames to consider.  Here
+are the possible values and their meanings:
+
+@table @asis
+@item @code{nil}
+Count the windows in the selected frame, plus the minibuffer used
+by that frame even if it lies in some other frame.
+
+@item @code{t}
+Count all windows in all existing frames.
+
+@item @code{visible}
+Count all windows in all visible frames.
+
+@item 0
+Count all windows in all visible or iconified frames.
+
+@item anything else
+Count precisely the windows in the selected frame, and no others.
+@end table
+@end defun
+
+@node Deleting Windows
+@section Deleting Windows
+@cindex deleting windows
+
+A window remains visible on its frame unless you @dfn{delete} it by
+calling certain functions that delete windows.  A deleted window cannot
+appear on the screen, but continues to exist as a Lisp object until
+there are no references to it.  There is no way to cancel the deletion
+of a window aside from restoring a saved window configuration
+(@pxref{Window Configurations}).  Restoring a window configuration also
+deletes any windows that aren't part of that configuration.
+
+  When you delete a window, the space it took up is given to one
+adjacent sibling.
+
+@c Emacs 19 feature
+@defun window-live-p window
+This function returns @code{nil} if @var{window} is deleted, and
+@code{t} otherwise.
+
+@strong{Warning:} Erroneous information or fatal errors may result from
+using a deleted window as if it were live.
+@end defun
+
+@deffn Command delete-window &optional window
+This function removes @var{window} from display, and returns @code{nil}.
+If @var{window} is omitted, then the selected window is deleted.  An
+error is signaled if there is only one window when @code{delete-window}
+is called.
+@end deffn
+
+@deffn Command delete-other-windows &optional window
+This function makes @var{window} the only window on its frame, by
+deleting the other windows in that frame.  If @var{window} is omitted or
+@code{nil}, then the selected window is used by default.
+
+The return value is @code{nil}.
+@end deffn
+
+@deffn Command delete-windows-on buffer-or-name &optional frame
+This function deletes all windows showing @var{buffer-or-name}.  If
+there are no windows showing @var{buffer-or-name}, it does nothing.
+@var{buffer-or-name} must be a buffer or the name of an existing
+buffer.
+
+@code{delete-windows-on} operates frame by frame.  If a frame has
+several windows showing different buffers, then those showing
+@var{buffer-or-name} are removed, and the others expand to fill the
+space.  If all windows in some frame are showing @var{buffer-or-name}
+(including the case where there is only one window), then the frame
+winds up with a single window showing another buffer chosen with
+@code{other-buffer}.  @xref{The Buffer List}.
+
+The argument @var{frame} controls which frames to operate on.  This
+function does not use it in quite the same way as the other functions
+which scan all windows; specifically, the values @code{t} and @code{nil}
+have the opposite of their meanings in other functions.  Here are the
+full details:
+
+@itemize @bullet
+@item
+If it is @code{nil}, operate on all frames.
+@item
+If it is @code{t}, operate on the selected frame.
+@item
+If it is @code{visible}, operate on all visible frames.
+@item
+If it is 0, operate on all visible or iconified frames.
+@item
+If it is a frame, operate on that frame.
+@end itemize
+
+This function always returns @code{nil}.
+@end deffn
+
+@node Selecting Windows
+@section Selecting Windows
+@cindex selecting a window
+
+  When a window is selected, the buffer in the window becomes the current
+buffer, and the cursor will appear in it.
+
+@defun selected-window
+This function returns the selected window.  This is the window in
+which the cursor appears and to which many commands apply.
+@end defun
+
+@defun select-window window &optional norecord
+This function makes @var{window} the selected window.  The cursor then
+appears in @var{window} (on redisplay).  Unless @var{window} was
+already selected, @code{select-window} makes @var{window}'s buffer the
+current buffer.
+
+Normally @var{window}'s selected buffer is moved to the front of the
+buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
+order is unchanged.
+
+The return value is @var{window}.
+
+@example
+@group
+(setq w (next-window))
+(select-window w)
+     @result{} #<window 65 on windows.texi>
+@end group
+@end example
+@end defun
+
+@defmac save-selected-window forms@dots{}
+This macro records the selected frame, as well as the selected window
+of each frame, executes @var{forms} in sequence, then restores the
+earlier selected frame and windows.  It also saves and restores the
+current buffer.  It returns the value of the last form in @var{forms}.
+
+This macro does not save or restore anything about the sizes,
+arrangement or contents of windows; therefore, if the @var{forms}
+change them, the change persists.  If the previously selected window
+of some frame is no longer live at the time of exit from @var{forms},
+that frame's selected window is left alone.  If the previously
+selected window is no longer live, then whatever window is selected at
+the end of @var{forms} remains selected.
+@end defmac
+
+@defmac with-selected-window window forms@dots{}
+This macro selects @var{window} (without changing the buffer list),
+executes @var{forms} in sequence, then restores the previously
+selected window and current buffer.  It is just like
+@code{save-selected-window}, except that it explicitly selects
+@var{window}, also without altering the buffer list sequence.
+@end defmac
+
+@cindex finding windows
+  The following functions choose one of the windows on the screen,
+offering various criteria for the choice.
+
+@defun get-lru-window &optional frame dedicated
+This function returns the window least recently ``used'' (that is,
+selected).  If any full-width windows are present, it only considers
+these.  The selected window is always the most recently used window.
+
+The selected window can be the least recently used window if it is the
+only window.  A newly created window becomes the least recently used
+window until it is selected.  A minibuffer window is never a
+candidate.  Dedicated windows are never candidates unless the
+@var{dedicated} argument is non-@code{nil}, so if all
+existing windows are dedicated, the value is @code{nil}.
+
+The argument @var{frame} controls which windows are considered.
+
+@itemize @bullet
+@item
+If it is @code{nil}, consider windows on the selected frame.
+@item
+If it is @code{t}, consider windows on all frames.
+@item
+If it is @code{visible}, consider windows on all visible frames.
+@item
+If it is 0, consider windows on all visible or iconified frames.
+@item
+If it is a frame, consider windows on that frame.
+@end itemize
+@end defun
+
+@defun get-largest-window &optional frame dedicated
+This function returns the window with the largest area (height times
+width).  If there are no side-by-side windows, then this is the window
+with the most lines.  A minibuffer window is never a candidate.
+Dedicated windows are never candidates unless the
+@var{dedicated} argument is non-@code{nil}, so if all existing windows
+are dedicated, the value is @code{nil}.
+
+If there are two candidate windows of the same size, this function
+prefers the one that comes first in the cyclic ordering of windows
+(see following section), starting from the selected window.
+
+The argument @var{frame} controls which set of windows to
+consider.  See @code{get-lru-window}, above.
+@end defun
+
+@cindex window that satisfies a predicate
+@cindex conditional selection of windows
+@defun get-window-with-predicate predicate &optional minibuf all-frames default
+This function returns a window satisfying @var{predicate}.  It cycles
+through all visible windows using @code{walk-windows} (@pxref{Cyclic
+Window Ordering}), calling @var{predicate} on each one of them
+with that window as its argument.  The function returns the first
+window for which @var{predicate} returns a non-@code{nil} value; if
+that never happens, it returns @var{default}.
+
+The optional arguments @var{minibuf} and @var{all-frames} specify the
+set of windows to include in the scan.  See the description of
+@code{next-window} in @ref{Cyclic Window Ordering}, for details.
+@end defun
+
+@node Cyclic Window Ordering
+@comment  node-name,  next,  previous,  up
+@section Cyclic Ordering of Windows
+@cindex cyclic ordering of windows
+@cindex ordering of windows, cyclic
+@cindex window ordering, cyclic
+
+  When you use the command @kbd{C-x o} (@code{other-window}) to select
+the next window, it moves through all the windows on the screen in a
+specific cyclic order.  For any given configuration of windows, this
+order never varies.  It is called the @dfn{cyclic ordering of windows}.
+
+  This ordering generally goes from top to bottom, and from left to
+right.  But it may go down first or go right first, depending on the
+order in which the windows were split.
+
+  If the first split was vertical (into windows one above each other),
+and then the subwindows were split horizontally, then the ordering is
+left to right in the top of the frame, and then left to right in the
+next lower part of the frame, and so on.  If the first split was
+horizontal, the ordering is top to bottom in the left part, and so on.
+In general, within each set of siblings at any level in the window tree,
+the order is left to right, or top to bottom.
+
+@defun next-window &optional window minibuf all-frames
+@cindex minibuffer window, and @code{next-window}
+This function returns the window following @var{window} in the cyclic
+ordering of windows.  This is the window that @kbd{C-x o} would select
+if typed when @var{window} is selected.  If @var{window} is the only
+window visible, then this function returns @var{window}.  If omitted,
+@var{window} defaults to the selected window.
+
+The value of the argument @var{minibuf} determines whether the
+minibuffer is included in the window order.  Normally, when
+@var{minibuf} is @code{nil}, the minibuffer is included if it is
+currently active; this is the behavior of @kbd{C-x o}.  (The minibuffer
+window is active while the minibuffer is in use.  @xref{Minibuffers}.)
+
+If @var{minibuf} is @code{t}, then the cyclic ordering includes the
+minibuffer window even if it is not active.
+
+If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
+window is not included even if it is active.
+
+The argument @var{all-frames} specifies which frames to consider.  Here
+are the possible values and their meanings:
+
+@table @asis
+@item @code{nil}
+Consider all the windows in @var{window}'s frame, plus the minibuffer
+used by that frame even if it lies in some other frame.  If the
+minibuffer counts (as determined by @var{minibuf}), then all windows on
+all frames that share that minibuffer count too.
+
+@item @code{t}
+Consider all windows in all existing frames.
+
+@item @code{visible}
+Consider all windows in all visible frames.  (To get useful results, you
+must ensure @var{window} is in a visible frame.)
+
+@item 0
+Consider all windows in all visible or iconified frames.
+
+@item a frame
+Consider all windows on that frame.
+
+@item anything else
+Consider precisely the windows in @var{window}'s frame, and no others.
+@end table
+
+This example assumes there are two windows, both displaying the
+buffer @samp{windows.texi}:
+
+@example
+@group
+(selected-window)
+     @result{} #<window 56 on windows.texi>
+@end group
+@group
+(next-window (selected-window))
+     @result{} #<window 52 on windows.texi>
+@end group
+@group
+(next-window (next-window (selected-window)))
+     @result{} #<window 56 on windows.texi>
+@end group
+@end example
+@end defun
+
+@defun previous-window &optional window minibuf all-frames
+This function returns the window preceding @var{window} in the cyclic
+ordering of windows.  The other arguments specify which windows to
+include in the cycle, as in @code{next-window}.
+@end defun
+
+@deffn Command other-window count &optional all-frames
+This function selects the @var{count}th following window in the cyclic
+order.  If count is negative, then it moves back @minus{}@var{count}
+windows in the cycle, rather than forward.  It returns @code{nil}.
+
+The argument @var{all-frames} has the same meaning as in
+@code{next-window}, but the @var{minibuf} argument of @code{next-window}
+is always effectively @code{nil}.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+@end deffn
+
+@c Emacs 19 feature
+@defun walk-windows proc &optional minibuf all-frames
+This function cycles through all windows.  It calls the function
+@code{proc} once for each window, with the window as its sole
+argument.
+
+The optional arguments @var{minibuf} and @var{all-frames} specify the
+set of windows to include in the scan.  See @code{next-window}, above,
+for details.
+@end defun
+
+@defun window-list &optional frame minibuf window
+This function returns a list of the windows on @var{frame}, starting
+with @var{window}.  If @var{frame} is @code{nil} or omitted,
+@code{window-list} uses the selected frame instead; if @var{window} is
+@code{nil} or omitted, it uses the selected window.
+
+The value of @var{minibuf} determines if the minibuffer window is
+included in the result list.  If @var{minibuf} is @code{t}, the result
+always includes the minibuffer window.  If @var{minibuf} is @code{nil}
+or omitted, that includes the minibuffer window if it is active.  If
+@var{minibuf} is neither @code{nil} nor @code{t}, the result never
+includes the minibuffer window.
+@end defun
+
+@node Buffers and Windows
+@section Buffers and Windows
+@cindex examining windows
+@cindex windows, controlling precisely
+@cindex buffers, controlled in windows
+
+  This section describes low-level functions to examine windows or to
+display buffers in windows in a precisely controlled fashion.
+@iftex
+See the following section for
+@end iftex
+@ifnottex
+@xref{Displaying Buffers}, for
+@end ifnottex
+related functions that find a window to use and specify a buffer for it.
+The functions described there are easier to use than these, but they
+employ heuristics in choosing or creating a window; use these functions
+when you need complete control.
+
+@defun set-window-buffer window buffer-or-name &optional keep-margins
+This function makes @var{window} display @var{buffer-or-name} as its
+contents.  It returns @code{nil}.  @var{buffer-or-name} must be a
+buffer, or the name of an existing buffer.  This is the fundamental
+primitive for changing which buffer is displayed in a window, and all
+ways of doing that call this function.
+
+@example
+@group
+(set-window-buffer (selected-window) "foo")
+     @result{} nil
+@end group
+@end example
+
+Normally, displaying @var{buffer} in @var{window} resets the window's
+display margins, fringe widths, scroll bar settings, and position
+based on the local variables of @var{buffer}.  However, if
+@var{keep-margins} is non-@code{nil}, the display margins and fringe
+widths of @var{window} remain unchanged.  @xref{Fringes}.
+@end defun
+
+@defvar buffer-display-count
+This buffer-local variable records the number of times a buffer is
+displayed in a window.  It is incremented each time
+@code{set-window-buffer} is called for the buffer.
+@end defvar
+
+@defun window-buffer &optional window
+This function returns the buffer that @var{window} is displaying.  If
+@var{window} is omitted, this function returns the buffer for the
+selected window.
+
+@example
+@group
+(window-buffer)
+     @result{} #<buffer windows.texi>
+@end group
+@end example
+@end defun
+
+@defun get-buffer-window buffer-or-name &optional all-frames
+This function returns a window currently displaying
+@var{buffer-or-name}, or @code{nil} if there is none.  If there are
+several such windows, then the function returns the first one in the
+cyclic ordering of windows, starting from the selected window.
+@xref{Cyclic Window Ordering}.
+
+The argument @var{all-frames} controls which windows to consider.
+
+@itemize @bullet
+@item
+If it is @code{nil}, consider windows on the selected frame.
+@item
+If it is @code{t}, consider windows on all frames.
+@item
+If it is @code{visible}, consider windows on all visible frames.
+@item
+If it is 0, consider windows on all visible or iconified frames.
+@item
+If it is a frame, consider windows on that frame.
+@end itemize
+@end defun
+
+@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
+This function returns a list of all the windows currently displaying
+@var{buffer-or-name}.
+
+The two optional arguments work like the optional arguments of
+@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
+like the single optional argument of @code{get-buffer-window}.  Perhaps
+we should change @code{get-buffer-window} in the future to make it
+compatible with the other functions.
+@end defun
+
+@defvar buffer-display-time
+This variable records the time at which a buffer was last made visible
+in a window.  It is always local in each buffer; each time
+@code{set-window-buffer} is called, it sets this variable to
+@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
+When a buffer is first created, @code{buffer-display-time} starts out
+with the value @code{nil}.
+@end defvar
+
+@node Displaying Buffers
+@section Displaying Buffers in Windows
+@cindex switching to a buffer
+@cindex displaying a buffer
+
+  In this section we describe convenient functions that choose a window
+automatically and use it to display a specified buffer.  These functions
+can also split an existing window in certain circumstances.  We also
+describe variables that parameterize the heuristics used for choosing a
+window.
+@iftex
+See the preceding section for
+@end iftex
+@ifnottex
+@xref{Buffers and Windows}, for
+@end ifnottex
+low-level functions that give you more precise control.  All of these
+functions work by calling @code{set-window-buffer}.
+
+  Do not use the functions in this section in order to make a buffer
+current so that a Lisp program can access or modify it; they are too
+drastic for that purpose, since they change the display of buffers in
+windows, which would be gratuitous and surprise the user.  Instead, use
+@code{set-buffer} and @code{save-current-buffer} (@pxref{Current
+Buffer}), which designate buffers as current for programmed access
+without affecting the display of buffers in windows.
+
+@deffn Command switch-to-buffer buffer-or-name &optional norecord
+This function makes @var{buffer-or-name} the current buffer, and also
+displays the buffer in the selected window.  This means that a human can
+see the buffer and subsequent keyboard commands will apply to it.
+Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
+the current buffer but does not display it in the selected window.
+@xref{Current Buffer}.
+
+If @var{buffer-or-name} does not identify an existing buffer, then a new
+buffer by that name is created.  The major mode for the new buffer is
+set according to the variable @code{default-major-mode}.  @xref{Auto
+Major Mode}.  If @var{buffer-or-name} is @code{nil},
+@code{switch-to-buffer} chooses a buffer using @code{other-buffer}.
+
+Normally the specified buffer is put at the front of the buffer list
+(both the selected frame's buffer list and the frame-independent buffer
+list).  This affects the operation of @code{other-buffer}.  However, if
+@var{norecord} is non-@code{nil}, this is not done.  @xref{The Buffer
+List}.
+
+The @code{switch-to-buffer} function is often used interactively, as
+the binding of @kbd{C-x b}.  It is also used frequently in programs.  It
+returns the buffer that it switched to.
+@end deffn
+
+The next two functions are similar to @code{switch-to-buffer}, except
+for the described features.
+
+@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
+This function makes @var{buffer-or-name} the current buffer and
+displays it in a window not currently selected.  It then selects that
+window.  The handling of the buffer is the same as in
+@code{switch-to-buffer}.
+
+The currently selected window is absolutely never used to do the job.
+If it is the only window, then it is split to make a distinct window for
+this purpose.  If the selected window is already displaying the buffer,
+then it continues to do so, but another window is nonetheless found to
+display it in as well.
+
+This function updates the buffer list just like @code{switch-to-buffer}
+unless @var{norecord} is non-@code{nil}.
+@end deffn
+
+@defun pop-to-buffer buffer-or-name &optional other-window norecord
+This function makes @var{buffer-or-name} the current buffer and
+switches to it in some window, preferably not the window previously
+selected.  The ``popped-to'' window becomes the selected window within
+its frame.  The return value is the buffer that was switched to.
+If @var{buffer-or-name} is @code{nil}, that means to choose some
+other buffer, but you don't specify which.
+
+If the variable @code{pop-up-frames} is non-@code{nil},
+@code{pop-to-buffer} looks for a window in any visible frame already
+displaying the buffer; if there is one, it returns that window and makes
+it be selected within its frame.  If there is none, it creates a new
+frame and displays the buffer in it.
+
+If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
+operates entirely within the selected frame.  (If the selected frame has
+just a minibuffer, @code{pop-to-buffer} operates within the most
+recently selected frame that was not just a minibuffer.)
+
+If the variable @code{pop-up-windows} is non-@code{nil}, windows may
+be split to create a new window that is different from the original
+window.  For details, see @ref{Choosing Window}.
+
+If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
+creates another window even if @var{buffer-or-name} is already visible
+in the selected window.  Thus @var{buffer-or-name} could end up
+displayed in two windows.  On the other hand, if @var{buffer-or-name} is
+already displayed in the selected window and @var{other-window} is
+@code{nil}, then the selected window is considered sufficient display
+for @var{buffer-or-name}, so that nothing needs to be done.
+
+All the variables that affect @code{display-buffer} affect
+@code{pop-to-buffer} as well.  @xref{Choosing Window}.
+
+If @var{buffer-or-name} is a string that does not name an existing
+buffer, a buffer by that name is created.  The major mode for the new
+buffer is set according to the variable @code{default-major-mode}.
+@xref{Auto Major Mode}.
+
+This function updates the buffer list just like @code{switch-to-buffer}
+unless @var{norecord} is non-@code{nil}.
+@end defun
+
+@deffn Command replace-buffer-in-windows buffer-or-name
+This function replaces @var{buffer-or-name} with some other buffer in all
+windows displaying it.  It chooses the other buffer with
+@code{other-buffer}.  In the usual applications of this function, you
+don't care which other buffer is used; you just want to make sure that
+@var{buffer-or-name} is no longer displayed.
+
+This function returns @code{nil}.
+@end deffn
+
+@node Choosing Window
+@section Choosing a Window for Display
+
+  This section describes the basic facility that chooses a window to
+display a buffer in---@code{display-buffer}.  All the higher-level
+functions and commands use this subroutine.  Here we describe how to use
+@code{display-buffer} and how to customize it.
+
+@deffn Command display-buffer buffer-or-name &optional not-this-window frame
+This command makes @var{buffer-or-name} appear in some window, like
+@code{pop-to-buffer}, but it does not select that window and does not
+make the buffer current.  The identity of the selected window is
+unaltered by this function.  @var{buffer-or-name} must be a buffer, or
+the name of an existing buffer.
+
+If @var{not-this-window} is non-@code{nil}, it means to display the
+specified buffer in a window other than the selected one, even if it is
+already on display in the selected window.  This can cause the buffer to
+appear in two windows at once.  Otherwise, if @var{buffer-or-name} is
+already being displayed in any window, that is good enough, so this
+function does nothing.
+
+@code{display-buffer} returns the window chosen to display
+@var{buffer-or-name}.
+
+If the argument @var{frame} is non-@code{nil}, it specifies which frames
+to check when deciding whether the buffer is already displayed.  If the
+buffer is already displayed in some window on one of these frames,
+@code{display-buffer} simply returns that window.  Here are the possible
+values of @var{frame}:
+
+@itemize @bullet
+@item
+If it is @code{nil}, consider windows on the selected frame.
+(Actually, the last non-minibuffer frame.)
+@item
+If it is @code{t}, consider windows on all frames.
+@item
+If it is @code{visible}, consider windows on all visible frames.
+@item
+If it is 0, consider windows on all visible or iconified frames.
+@item
+If it is a frame, consider windows on that frame.
+@end itemize
+
+Precisely how @code{display-buffer} finds or creates a window depends on
+the variables described below.
+@end deffn
+
+@defopt display-buffer-reuse-frames
+If this variable is non-@code{nil}, @code{display-buffer} searches
+existing frames for a window displaying the buffer.  If the buffer is
+already displayed in a window in some frame, @code{display-buffer} makes
+the frame visible and raises it, to use that window.  If the buffer is
+not already displayed, or if @code{display-buffer-reuse-frames} is
+@code{nil}, @code{display-buffer}'s behavior is determined by other
+variables, described below.
+@end defopt
+
+@defopt pop-up-windows
+This variable controls whether @code{display-buffer} makes new windows.
+If it is non-@code{nil} and there is only one window, then that window
+is split.  If it is @code{nil}, then @code{display-buffer} does not
+split the single window, but uses it whole.
+@end defopt
+
+@defopt split-height-threshold
+This variable determines when @code{display-buffer} may split a window,
+if there are multiple windows.  @code{display-buffer} always splits the
+largest window if it has at least this many lines.  If the largest
+window is not this tall, it is split only if it is the sole window and
+@code{pop-up-windows} is non-@code{nil}.
+@end defopt
+
+@defopt even-window-heights
+This variable determines if @code{display-buffer} should even out window
+heights if the buffer gets displayed in an existing window, above or
+beneath another existing window.  If @code{even-window-heights} is
+@code{t}, the default, window heights will be evened out.  If
+@code{even-window-heights} is @code{nil}, the original window heights
+will be left alone.
+@end defopt
+
+@c Emacs 19 feature
+@defopt pop-up-frames
+This variable controls whether @code{display-buffer} makes new frames.
+If it is non-@code{nil}, @code{display-buffer} looks for an existing
+window already displaying the desired buffer, on any visible frame.  If
+it finds one, it returns that window.  Otherwise it makes a new frame.
+The variables @code{pop-up-windows} and @code{split-height-threshold} do
+not matter if @code{pop-up-frames} is non-@code{nil}.
+
+If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
+splits a window or reuses one.
+
+@xref{Frames}, for more information.
+@end defopt
+
+@c Emacs 19 feature
+@defopt pop-up-frame-function
+This variable specifies how to make a new frame if @code{pop-up-frames}
+is non-@code{nil}.
+
+Its value should be a function of no arguments.  When
+@code{display-buffer} makes a new frame, it does so by calling that
+function, which should return a frame.  The default value of the
+variable is a function that creates a frame using parameters from
+@code{pop-up-frame-alist}.
+@end defopt
+
+@defopt pop-up-frame-alist
+This variable holds an alist specifying frame parameters used when
+@code{display-buffer} makes a new frame.  @xref{Frame Parameters}, for
+more information about frame parameters.
+@end defopt
+
+@defopt special-display-buffer-names
+A list of buffer names for buffers that should be displayed specially.
+If the buffer's name is in this list, @code{display-buffer} handles the
+buffer specially.
+
+By default, special display means to give the buffer a dedicated frame.
+
+If an element is a list, instead of a string, then the @sc{car} of the
+list is the buffer name, and the rest of the list says how to create
+the frame.  There are two possibilities for the rest of the list (its
+@sc{cdr}).  It can be an alist, specifying frame parameters, or it can
+contain a function and arguments to give to it.  (The function's first
+argument is always the buffer to be displayed; the arguments from the
+list come after that.)
+
+For example:
+
+@example
+(("myfile" (minibuffer) (menu-bar-lines . 0)))
+@end example
+
+@noindent
+specifies to display a buffer named @samp{myfile} in a dedicated frame
+with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
+
+The list of frame parameters can also use the phony frame parameters
+@code{same-frame} and @code{same-window}.  If the specified frame
+parameters include @code{(same-window . @var{value})} and @var{value}
+is non-@code{nil}, that means to display the buffer in the current
+selected window.  Otherwise, if they include @code{(same-frame .
+@var{value})} and @var{value} is non-@code{nil}, that means to display
+the buffer in a new window in the currently selected frame.
+@end defopt
+
+@defopt special-display-regexps
+A list of regular expressions that specify buffers that should be
+displayed specially.  If the buffer's name matches any of the regular
+expressions in this list, @code{display-buffer} handles the buffer
+specially.
+
+By default, special display means to give the buffer a dedicated frame.
+
+If an element is a list, instead of a string, then the @sc{car} of the
+list is the regular expression, and the rest of the list says how to
+create the frame.  See above, under @code{special-display-buffer-names}.
+@end defopt
+
+@defun special-display-p buffer-name
+This function returns non-@code{nil} if displaying a buffer
+named @var{buffer-name} with @code{display-buffer} would
+create a special frame.  The value is @code{t} if it would
+use the default frame parameters, or else the specified list
+of frame parameters.
+@end defun
+
+@defvar special-display-function
+This variable holds the function to call to display a buffer specially.
+It receives the buffer as an argument, and should return the window in
+which it is displayed.
+
+The default value of this variable is
+@code{special-display-popup-frame}.
+@end defvar
+
+@defun special-display-popup-frame buffer &optional args
+This function makes @var{buffer} visible in a frame of its own.  If
+@var{buffer} is already displayed in a window in some frame, it makes
+the frame visible and raises it, to use that window.  Otherwise, it
+creates a frame that will be dedicated to @var{buffer}.  This
+function returns the window it used.
+
+If @var{args} is an alist, it specifies frame parameters for the new
+frame.
+
+If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
+@var{args})} is called as a function to actually create and set up the
+frame; it is called with @var{buffer} as first argument, and @code{(cdr
+@var{args})} as additional arguments.
+
+This function always uses an existing window displaying @var{buffer},
+whether or not it is in a frame of its own; but if you set up the above
+variables in your init file, before @var{buffer} was created, then
+presumably the window was previously made by this function.
+@end defun
+
+@defopt special-display-frame-alist
+@anchor{Definition of special-display-frame-alist}
+This variable holds frame parameters for
+@code{special-display-popup-frame} to use when it creates a frame.
+@end defopt
+
+@defopt same-window-buffer-names
+A list of buffer names for buffers that should be displayed in the
+selected window.  If the buffer's name is in this list,
+@code{display-buffer} handles the buffer by switching to it in the
+selected window.
+@end defopt
+
+@defopt same-window-regexps
+A list of regular expressions that specify buffers that should be
+displayed in the selected window.  If the buffer's name matches any of
+the regular expressions in this list, @code{display-buffer} handles the
+buffer by switching to it in the selected window.
+@end defopt
+
+@defun same-window-p buffer-name
+This function returns @code{t} if displaying a buffer
+named @var{buffer-name} with @code{display-buffer} would
+put it in the selected window.
+@end defun
+
+@c Emacs 19 feature
+@defvar display-buffer-function
+This variable is the most flexible way to customize the behavior of
+@code{display-buffer}.  If it is non-@code{nil}, it should be a function
+that @code{display-buffer} calls to do the work.  The function should
+accept two arguments, the first two arguments that @code{display-buffer}
+received.  It should choose or create a window, display the specified
+buffer in it, and then return the window.
+
+This hook takes precedence over all the other options and hooks
+described above.
+@end defvar
+
+@c Emacs 19 feature
+@cindex dedicated window
+A window can be marked as ``dedicated'' to its buffer.  Then
+@code{display-buffer} will not try to use that window to display any
+other buffer.
+
+@defun window-dedicated-p window
+This function returns non-@code{nil} if @var{window} is marked as
+dedicated; otherwise @code{nil}.
+@end defun
+
+@defun set-window-dedicated-p window flag
+This function marks @var{window} as dedicated if @var{flag} is
+non-@code{nil}, and nondedicated otherwise.
+@end defun
+
+@node Window Point
+@section Windows and Point
+@cindex window position
+@cindex window point
+@cindex position in window
+@cindex point in window
+
+  Each window has its own value of point, independent of the value of
+point in other windows displaying the same buffer.  This makes it useful
+to have multiple windows showing one buffer.
+
+@itemize @bullet
+@item
+The window point is established when a window is first created; it is
+initialized from the buffer's point, or from the window point of another
+window opened on the buffer if such a window exists.
+
+@item
+Selecting a window sets the value of point in its buffer from the
+window's value of point.  Conversely, deselecting a window sets the
+window's value of point from that of the buffer.  Thus, when you switch
+between windows that display a given buffer, the point value for the
+selected window is in effect in the buffer, while the point values for
+the other windows are stored in those windows.
+
+@item
+As long as the selected window displays the current buffer, the window's
+point and the buffer's point always move together; they remain equal.
+@end itemize
+
+@noindent
+@xref{Positions}, for more details on buffer positions.
+
+@cindex cursor
+  As far as the user is concerned, point is where the cursor is, and
+when the user switches to another buffer, the cursor jumps to the
+position of point in that buffer.
+
+@defun window-point &optional window
+This function returns the current position of point in @var{window}.
+For a nonselected window, this is the value point would have (in that
+window's buffer) if that window were selected.  If @var{window} is
+@code{nil}, the selected window is used.
+
+When @var{window} is the selected window and its buffer is also the
+current buffer, the value returned is the same as point in that buffer.
+
+Strictly speaking, it would be more correct to return the
+``top-level'' value of point, outside of any @code{save-excursion}
+forms.  But that value is hard to find.
+@end defun
+
+@defun set-window-point window position
+This function positions point in @var{window} at position
+@var{position} in @var{window}'s buffer.  It returns @var{position}.
+
+If @var{window} is selected, and its buffer is current,
+this simply does @code{goto-char}.
+@end defun
+
+@node Window Start
+@section The Window Start Position
+@cindex window start position
+
+  Each window contains a marker used to keep track of a buffer position
+that specifies where in the buffer display should start.  This position
+is called the @dfn{display-start} position of the window (or just the
+@dfn{start}).  The character after this position is the one that appears
+at the upper left corner of the window.  It is usually, but not
+inevitably, at the beginning of a text line.
+
+@defun window-start &optional window
+@cindex window top line
+This function returns the display-start position of window
+@var{window}.  If @var{window} is @code{nil}, the selected window is
+used.  For example,
+
+@example
+@group
+(window-start)
+     @result{} 7058
+@end group
+@end example
+
+When you create a window, or display a different buffer in it, the
+display-start position is set to a display-start position recently used
+for the same buffer, or 1 if the buffer doesn't have any.
+
+Redisplay updates the window-start position (if you have not specified
+it explicitly since the previous redisplay)---for example, to make sure
+point appears on the screen.  Nothing except redisplay automatically
+changes the window-start position; if you move point, do not expect the
+window-start position to change in response until after the next
+redisplay.
+
+For a realistic example of using @code{window-start}, see the
+description of @code{count-lines}.  @xref{Definition of count-lines}.
+@end defun
+
+@defun window-end &optional window update
+This function returns the position of the end of the display in window
+@var{window}.  If @var{window} is @code{nil}, the selected window is
+used.
+
+Simply changing the buffer text or moving point does not update the
+value that @code{window-end} returns.  The value is updated only when
+Emacs redisplays and redisplay completes without being preempted.
+
+If the last redisplay of @var{window} was preempted, and did not finish,
+Emacs does not know the position of the end of display in that window.
+In that case, this function returns @code{nil}.
+
+If @var{update} is non-@code{nil}, @code{window-end} always returns an
+up-to-date value for where the window ends, based on the current
+@code{window-start} value.  If the saved value is valid,
+@code{window-end} returns that; otherwise it computes the correct
+value by scanning the buffer text.
+
+Even if @var{update} is non-@code{nil}, @code{window-end} does not
+attempt to scroll the display if point has moved off the screen, the
+way real redisplay would do.  It does not alter the
+@code{window-start} value.  In effect, it reports where the displayed
+text will end if scrolling is not required.
+@end defun
+
+@defun set-window-start window position &optional noforce
+This function sets the display-start position of @var{window} to
+@var{position} in @var{window}'s buffer.  It returns @var{position}.
+
+The display routines insist that the position of point be visible when a
+buffer is displayed.  Normally, they change the display-start position
+(that is, scroll the window) whenever necessary to make point visible.
+However, if you specify the start position with this function using
+@code{nil} for @var{noforce}, it means you want display to start at
+@var{position} even if that would put the location of point off the
+screen.  If this does place point off screen, the display routines move
+point to the left margin on the middle line in the window.
+
+For example, if point @w{is 1} and you set the start of the window @w{to
+2}, then point would be ``above'' the top of the window.  The display
+routines will automatically move point if it is still 1 when redisplay
+occurs.  Here is an example:
+
+@example
+@group
+;; @r{Here is what @samp{foo} looks like before executing}
+;;   @r{the @code{set-window-start} expression.}
+@end group
+
+@group
+---------- Buffer: foo ----------
+@point{}This is the contents of buffer foo.
+2
+3
+4
+5
+6
+---------- Buffer: foo ----------
+@end group
+
+@group
+(set-window-start
+ (selected-window)
+ (1+ (window-start)))
+@result{} 2
+@end group
+
+@group
+;; @r{Here is what @samp{foo} looks like after executing}
+;;   @r{the @code{set-window-start} expression.}
+---------- Buffer: foo ----------
+his is the contents of buffer foo.
+2
+3
+@point{}4
+5
+6
+---------- Buffer: foo ----------
+@end group
+@end example
+
+If @var{noforce} is non-@code{nil}, and @var{position} would place point
+off screen at the next redisplay, then redisplay computes a new window-start
+position that works well with point, and thus @var{position} is not used.
+@end defun
+
+@defun pos-visible-in-window-p &optional position window partially
+This function returns non-@code{nil} if @var{position} is within the
+range of text currently visible on the screen in @var{window}.  It
+returns @code{nil} if @var{position} is scrolled vertically out of
+view.  Locations that are partially obscured are not considered
+visible unless @var{partially} is non-@code{nil}.  The argument
+@var{position} defaults to the current position of point in
+@var{window}; @var{window}, to the selected window.
+
+If @var{position} is @code{t}, that means to check the last visible
+position in @var{window}.
+
+The @code{pos-visible-in-window-p} function considers only vertical
+scrolling.  If @var{position} is out of view only because @var{window}
+has been scrolled horizontally, @code{pos-visible-in-window-p} returns
+non-@code{nil} anyway.  @xref{Horizontal Scrolling}.
+
+If @var{position} is visible, @code{pos-visible-in-window-p} returns
+@code{t} if @var{partially} is @code{nil}; if @var{partially} is
+non-@code{nil}, and the character after @var{position} is fully
+visible, it returns a list of the form @code{(@var{x} @var{y})}, where
+@var{x} and @var{y} are the pixel coordinates relative to the top left
+corner of the window; otherwise it returns an extended list of the
+form @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh}
+@var{vpos})}, where the @var{rtop} and @var{rbot} specify the number
+of off-window pixels at the top and bottom of the row at
+@var{position}, @var{rowh} specifies the visible height of that row,
+and @var{vpos} specifies the vertical position (zero-based row number)
+of that row.
+
+Here is an example:
+
+@example
+@group
+;; @r{If point is off the screen now, recenter it now.}
+(or (pos-visible-in-window-p
+     (point) (selected-window))
+    (recenter 0))
+@end group
+@end example
+@end defun
+
+@defun window-line-height &optional line window
+This function returns information about text line @var{line} in @var{window}.
+If @var{line} is one of @code{header-line} or @code{mode-line},
+@code{window-line-height} returns information about the corresponding
+line of the window.  Otherwise, @var{line} is a text line number
+starting from 0.  A negative number counts from the end of the window.
+The argument @var{line} defaults to the current line in @var{window};
+@var{window}, to the selected window.
+
+If the display is not up to date, @code{window-line-height} returns
+@code{nil}.  In that case, @code{pos-visible-in-window-p} may be used
+to obtain related information.
+
+If there is no line corresponding to the specified @var{line},
+@code{window-line-height} returns @code{nil}.  Otherwise, it returns
+a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
+where @var{height} is the height in pixels of the visible part of the
+line, @var{vpos} and @var{ypos} are the vertical position in lines and
+pixels of the line relative to the top of the first text line, and
+@var{offbot} is the number of off-window pixels at the bottom of the
+text line.  If there are off-window pixels at the top of the (first)
+text line, @var{ypos} is negative.
+@end defun
+
+@node Textual Scrolling
+@section Textual Scrolling
+@cindex textual scrolling
+@cindex scrolling textually
+
+  @dfn{Textual scrolling} means moving the text up or down through a
+window.  It works by changing the value of the window's display-start
+location.  It may also change the value of @code{window-point} to keep
+point on the screen.
+
+  Textual scrolling was formerly called ``vertical scrolling,'' but we
+changed its name to distinguish it from the new vertical fractional
+scrolling feature (@pxref{Vertical Scrolling}).
+
+  In the commands @code{scroll-up} and @code{scroll-down}, the directions
+``up'' and ``down'' refer to the motion of the text in the buffer at which
+you are looking through the window.  Imagine that the text is
+written on a long roll of paper and that the scrolling commands move the
+paper up and down.  Thus, if you are looking at text in the middle of a
+buffer and repeatedly call @code{scroll-down}, you will eventually see
+the beginning of the buffer.
+
+  Some people have urged that the opposite convention be used: they
+imagine that the window moves over text that remains in place.  Then
+``down'' commands would take you to the end of the buffer.  This view is
+more consistent with the actual relationship between windows and the
+text in the buffer, but it is less like what the user sees.  The
+position of a window on the terminal does not move, and short scrolling
+commands clearly move the text up or down on the screen.  We have chosen
+names that fit the user's point of view.
+
+  The textual scrolling functions (aside from
+@code{scroll-other-window}) have unpredictable results if the current
+buffer is different from the buffer that is displayed in the selected
+window.  @xref{Current Buffer}.
+
+  If the window contains a row which is taller than the height of the
+window (for example in the presence of a large image), the scroll
+functions will adjust the window vscroll to scroll the partially
+visible row.  To disable this feature, Lisp code may bind the variable
+`auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}).
+
+@deffn Command scroll-up &optional count
+This function scrolls the text in the selected window upward
+@var{count} lines.  If @var{count} is negative, scrolling is actually
+downward.
+
+If @var{count} is @code{nil} (or omitted), then the length of scroll
+is @code{next-screen-context-lines} lines less than the usable height of
+the window (not counting its mode line).
+
+@code{scroll-up} returns @code{nil}, unless it gets an error
+because it can't scroll any further.
+@end deffn
+
+@deffn Command scroll-down &optional count
+This function scrolls the text in the selected window downward
+@var{count} lines.  If @var{count} is negative, scrolling is actually
+upward.
+
+If @var{count} is omitted or @code{nil}, then the length of the scroll
+is @code{next-screen-context-lines} lines less than the usable height of
+the window (not counting its mode line).
+
+@code{scroll-down} returns @code{nil}, unless it gets an error because
+it can't scroll any further.
+@end deffn
+
+@deffn Command scroll-other-window &optional count
+This function scrolls the text in another window upward @var{count}
+lines.  Negative values of @var{count}, or @code{nil}, are handled
+as in @code{scroll-up}.
+
+You can specify which buffer to scroll by setting the variable
+@code{other-window-scroll-buffer} to a buffer.  If that buffer isn't
+already displayed, @code{scroll-other-window} displays it in some
+window.
+
+When the selected window is the minibuffer, the next window is normally
+the one at the top left corner.  You can specify a different window to
+scroll, when the minibuffer is selected, by setting the variable
+@code{minibuffer-scroll-window}.  This variable has no effect when any
+other window is selected.  When it is non-@code{nil} and the
+minibuffer is selected, it takes precedence over
+@code{other-window-scroll-buffer}.  @xref{Definition of
+minibuffer-scroll-window}.
+
+When the minibuffer is active, it is the next window if the selected
+window is the one at the bottom right corner.  In this case,
+@code{scroll-other-window} attempts to scroll the minibuffer.  If the
+minibuffer contains just one line, it has nowhere to scroll to, so the
+line reappears after the echo area momentarily displays the message
+@samp{Beginning of buffer}.
+@end deffn
+
+@c Emacs 19 feature
+@defvar other-window-scroll-buffer
+If this variable is non-@code{nil}, it tells @code{scroll-other-window}
+which buffer to scroll.
+@end defvar
+
+@defopt scroll-margin
+This option specifies the size of the scroll margin---a minimum number
+of lines between point and the top or bottom of a window.  Whenever
+point gets within this many lines of the top or bottom of the window,
+redisplay scrolls the text automatically (if possible) to move point
+out of the margin, closer to the center of the window.
+@end defopt
+
+@defopt scroll-conservatively
+This variable controls how scrolling is done automatically when point
+moves off the screen (or into the scroll margin).  If the value is a
+positive integer @var{n}, then redisplay scrolls the text up to
+@var{n} lines in either direction, if that will bring point back into
+proper view.  This action is called @dfn{conservative scrolling}.
+Otherwise, scrolling happens in the usual way, under the control of
+other variables such as @code{scroll-up-aggressively} and
+@code{scroll-down-aggressively}.
+
+The default value is zero, which means that conservative scrolling
+never happens.
+@end defopt
+
+@defopt scroll-down-aggressively
+The value of this variable should be either @code{nil} or a fraction
+@var{f} between 0 and 1.  If it is a fraction, that specifies where on
+the screen to put point when scrolling down.  More precisely, when a
+window scrolls down 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.
+
+A value of @code{nil} is equivalent to .5, since its effect is to center
+point.  This variable automatically becomes buffer-local when set in any
+fashion.
+@end defopt
+
+@defopt scroll-up-aggressively
+Likewise, for scrolling up.  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 scrolls more aggressively.
+@end defopt
+
+@defopt scroll-step
+This variable is an older variant of @code{scroll-conservatively}.  The
+difference is that it if its value is @var{n}, that permits scrolling
+only by precisely @var{n} lines, not a smaller number.  This feature
+does not work with @code{scroll-margin}.  The default value is zero.
+@end defopt
+
+@defopt scroll-preserve-screen-position
+If this option is @code{t}, scrolling which would move the current
+point position out of the window chooses the new position of point
+so that the vertical position of the cursor is unchanged, if possible.
+
+If it is non-@code{nil} and not @code{t}, then the scrolling functions
+always preserve the vertical position of point, if possible.
+@end defopt
+
+@defopt next-screen-context-lines
+The value of this variable is the number of lines of continuity to
+retain when scrolling by full screens.  For example, @code{scroll-up}
+with an argument of @code{nil} scrolls so that this many lines at the
+bottom of the window appear instead at the top.  The default value is
+@code{2}.
+@end defopt
+
+@deffn Command recenter &optional count
+@cindex centering point
+This function scrolls the text in the selected window so that point is
+displayed at a specified vertical position within the window.  It does
+not ``move point'' with respect to the text.
+
+If @var{count} is a nonnegative number, that puts the line containing
+point @var{count} lines down from the top of the window.  If
+@var{count} is a negative number, then it counts upward from the
+bottom of the window, so that @minus{}1 stands for the last usable
+line in the window.  If @var{count} is a non-@code{nil} list, then it
+stands for the line in the middle of the window.
+
+If @var{count} is @code{nil}, @code{recenter} puts the line containing
+point in the middle of the window, then clears and redisplays the entire
+selected frame.
+
+When @code{recenter} is called interactively, @var{count} is the raw
+prefix argument.  Thus, typing @kbd{C-u} as the prefix sets the
+@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
+@var{count} to 4, which positions the current line four lines from the
+top.
+
+With an argument of zero, @code{recenter} positions the current line at
+the top of the window.  This action is so handy that some people make a
+separate key binding to do this.  For example,
+
+@example
+@group
+(defun line-to-top-of-window ()
+  "Scroll current line to top of window.
+Replaces three keystroke sequence C-u 0 C-l."
+  (interactive)
+  (recenter 0))
+
+(global-set-key [kp-multiply] 'line-to-top-of-window)
+@end group
+@end example
+@end deffn
+
+@node Vertical Scrolling
+@section Vertical Fractional Scrolling
+@cindex vertical fractional scrolling
+
+  @dfn{Vertical fractional scrolling} means shifting the image in the
+window up or down by a specified multiple or fraction of a line.
+Each window has a @dfn{vertical scroll position},
+which is a number, never less than zero.  It specifies how far to raise
+the contents of the window.  Raising the window contents generally makes
+all or part of some lines disappear off the top, and all or part of some
+other lines appear at the bottom.  The usual value is zero.
+
+  The vertical scroll position is measured in units of the normal line
+height, which is the height of the default font.  Thus, if the value is
+.5, that means the window contents are scrolled up half the normal line
+height.  If it is 3.3, that means the window contents are scrolled up
+somewhat over three times the normal line height.
+
+  What fraction of a line the vertical scrolling covers, or how many
+lines, depends on what the lines contain.  A value of .5 could scroll a
+line whose height is very short off the screen, while a value of 3.3
+could scroll just part of the way through a tall line or an image.
+
+@defun window-vscroll &optional window pixels-p
+This function returns the current vertical scroll position of
+@var{window}.  If @var{window} is @code{nil}, the selected window is
+used.  If @var{pixels-p} is non-@code{nil}, the return value is
+measured in pixels, rather than in units of the normal line height.
+
+@example
+@group
+(window-vscroll)
+     @result{} 0
+@end group
+@end example
+@end defun
+
+@defun set-window-vscroll window lines &optional pixels-p
+This function sets @var{window}'s vertical scroll position to
+@var{lines}.  The argument @var{lines} should be zero or positive; if
+not, it is taken as zero.
+
+If @var{window} is @code{nil}, the selected window is used.
+
+The actual vertical scroll position must always correspond
+to an integral number of pixels, so the value you specify
+is rounded accordingly.
+
+The return value is the result of this rounding.
+
+@example
+@group
+(set-window-vscroll (selected-window) 1.2)
+     @result{} 1.13
+@end group
+@end example
+
+If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
+pixels.  In this case, the return value is @var{lines}.
+@end defun
+
+@defvar auto-window-vscroll
+If this variable is non-@code{nil}, the line-move, scroll-up, and
+scroll-down functions will automatically modify the window vscroll to
+scroll through display rows that are taller that the height of the
+window, for example in the presence of large images.
+@end defvar
+
+@node Horizontal Scrolling
+@section Horizontal Scrolling
+@cindex horizontal scrolling
+
+  @dfn{Horizontal scrolling} means shifting the image in the window left
+or right by a specified multiple of the normal character width.  Each
+window has a @dfn{horizontal scroll position}, which is a number, never
+less than zero.  It specifies how far to shift the contents left.
+Shifting the window contents left generally makes all or part of some
+characters disappear off the left, and all or part of some other
+characters appear at the right.  The usual value is zero.
+
+  The horizontal scroll position is measured in units of the normal
+character width, which is the width of space in the default font.  Thus,
+if the value is 5, that means the window contents are scrolled left by 5
+times the normal character width.  How many characters actually
+disappear off to the left depends on their width, and could vary from
+line to line.
+
+  Because we read from side to side in the ``inner loop,'' and from top
+to bottom in the ``outer loop,'' the effect of horizontal scrolling is
+not like that of textual or vertical scrolling.  Textual scrolling
+involves selection of a portion of text to display, and vertical
+scrolling moves the window contents contiguously; but horizontal
+scrolling causes part of @emph{each line} to go off screen.
+
+  Usually, no horizontal scrolling is in effect; then the leftmost
+column is at the left edge of the window.  In this state, scrolling to
+the right is meaningless, since there is no data to the left of the edge
+to be revealed by it; so this is not allowed.  Scrolling to the left is
+allowed; it scrolls the first columns of text off the edge of the window
+and can reveal additional columns on the right that were truncated
+before.  Once a window has a nonzero amount of leftward horizontal
+scrolling, you can scroll it back to the right, but only so far as to
+reduce the net horizontal scroll to zero.  There is no limit to how far
+left you can scroll, but eventually all the text will disappear off the
+left edge.
+
+@vindex auto-hscroll-mode
+  If @code{auto-hscroll-mode} is set, redisplay automatically alters
+the horizontal scrolling of a window as necessary to ensure that point
+is always visible.  However, you can still set the horizontal
+scrolling value explicitly.  The value you specify serves as a lower
+bound for automatic scrolling, i.e. automatic scrolling will not
+scroll a window to a column less than the specified one.
+
+@deffn Command scroll-left &optional count set-minimum
+This function scrolls the selected window @var{count} columns to the
+left (or to the right if @var{count} is negative).  The default
+for @var{count} is the window width, minus 2.
+
+The return value is the total amount of leftward horizontal scrolling in
+effect after the change---just like the value returned by
+@code{window-hscroll} (below).
+
+Once you scroll a window as far right as it can go, back to its normal
+position where the total leftward scrolling is zero, attempts to scroll
+any farther right have no effect.
+
+If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
+the lower bound for automatic scrolling; that is, automatic scrolling
+will not scroll a window to a column less than the value returned by
+this function.  Interactive calls pass non-@code{nil} for
+@var{set-minimum}.
+@end deffn
+
+@deffn Command scroll-right &optional count set-minimum
+This function scrolls the selected window @var{count} columns to the
+right (or to the left if @var{count} is negative).  The default
+for @var{count} is the window width, minus 2.  Aside from the direction
+of scrolling, this works just like @code{scroll-left}.
+@end deffn
+
+@defun window-hscroll &optional window
+This function returns the total leftward horizontal scrolling of
+@var{window}---the number of columns by which the text in @var{window}
+is scrolled left past the left margin.
+
+The value is never negative.  It is zero when no horizontal scrolling
+has been done in @var{window} (which is usually the case).
+
+If @var{window} is @code{nil}, the selected window is used.
+
+@example
+@group
+(window-hscroll)
+     @result{} 0
+@end group
+@group
+(scroll-left 5)
+     @result{} 5
+@end group
+@group
+(window-hscroll)
+     @result{} 5
+@end group
+@end example
+@end defun
+
+@defun set-window-hscroll window columns
+This function sets horizontal scrolling of @var{window}.  The value of
+@var{columns} specifies the amount of scrolling, in terms of columns
+from the left margin.  The argument @var{columns} should be zero or
+positive; if not, it is taken as zero.  Fractional values of
+@var{columns} are not supported at present.
+
+Note that @code{set-window-hscroll} may appear not to work if you test
+it by evaluating a call with @kbd{M-:} in a simple way.  What happens
+is that the function sets the horizontal scroll value and returns, but
+then redisplay adjusts the horizontal scrolling to make point visible,
+and this overrides what the function did.  You can observe the
+function's effect if you call it while point is sufficiently far from
+the left margin that it will remain visible.
+
+The value returned is @var{columns}.
+
+@example
+@group
+(set-window-hscroll (selected-window) 10)
+     @result{} 10
+@end group
+@end example
+@end defun
+
+  Here is how you can determine whether a given position @var{position}
+is off the screen due to horizontal scrolling:
+
+@example
+@group
+(defun hscroll-on-screen (window position)
+  (save-excursion
+    (goto-char position)
+    (and
+     (>= (- (current-column) (window-hscroll window)) 0)
+     (< (- (current-column) (window-hscroll window))
+        (window-width window)))))
+@end group
+@end example
+
+@node Size of Window
+@section The Size of a Window
+@cindex window size
+@cindex size of window
+
+  An Emacs window is rectangular, and its size information consists of
+the height (the number of lines) and the width (the number of character
+positions in each line).  The mode line is included in the height.  But
+the width does not count the scroll bar or the column of @samp{|}
+characters that separates side-by-side windows.
+
+  The following three functions return size information about a window:
+
+@defun window-height &optional window
+This function returns the number of lines in @var{window}, including
+its mode line and header line, if any.  If @var{window} fills its
+entire frame except for the echo area, this is typically one less than
+the value of @code{frame-height} on that frame.
+
+If @var{window} is @code{nil}, the function uses the selected window.
+
+@example
+@group
+(window-height)
+     @result{} 23
+@end group
+@group
+(split-window-vertically)
+     @result{} #<window 4 on windows.texi>
+@end group
+@group
+(window-height)
+     @result{} 11
+@end group
+@end example
+@end defun
+
+@defun window-body-height &optional window
+Like @code{window-height} but the value does not include the
+mode line (if any) or the header line (if any).
+@end defun
+
+@defun window-width &optional window
+This function returns the number of columns in @var{window}.  If
+@var{window} fills its entire frame, this is the same as the value of
+@code{frame-width} on that frame.  The width does not include the
+window's scroll bar or the column of @samp{|} characters that separates
+side-by-side windows.
+
+If @var{window} is @code{nil}, the function uses the selected window.
+
+@example
+@group
+(window-width)
+     @result{} 80
+@end group
+@end example
+@end defun
+
+@defun window-full-width-p &optional window
+This function returns non-@code{nil} if @var{window} is as wide as
+the frame that contains it; otherwise @code{nil}.
+If @var{window} is @code{nil}, the function uses the selected window.
+@end defun
+
+@defun window-edges &optional window
+This function returns a list of the edge coordinates of @var{window}.
+If @var{window} is @code{nil}, the selected window is used.
+
+The order of the list is @code{(@var{left} @var{top} @var{right}
+@var{bottom})}, all elements relative to 0, 0 at the top left corner of
+the frame.  The element @var{right} of the value is one more than the
+rightmost column used by @var{window}, and @var{bottom} is one more than
+the bottommost row used by @var{window} and its mode-line.
+
+The edges include the space used by the window's scroll bar, display
+margins, fringes, header line, and mode line, if it has them.  Also,
+if the window has a neighbor on the right, its right edge value
+includes the width of the separator line between the window and that
+neighbor.  Since the width of the window does not include this
+separator, the width does not usually equal the difference between the
+right and left edges.
+@end defun
+
+@defun window-inside-edges &optional window
+This is similar to @code{window-edges}, but the edge values
+it returns include only the text area of the window.  They
+do not include the header line, mode line, scroll bar or
+vertical separator, fringes, or display margins.
+@end defun
+
+Here are the results obtained on a typical 24-line terminal with just
+one window, with menu bar enabled:
+
+@example
+@group
+(window-edges (selected-window))
+     @result{} (0 1 80 23)
+@end group
+@group
+(window-inside-edges (selected-window))
+     @result{} (0 1 80 22)
+@end group
+@end example
+
+@noindent
+The bottom edge is at line 23 because the last line is the echo area.
+The bottom inside edge is at line 22, which is the window's mode line.
+
+If @var{window} is at the upper left corner of its frame, and there is
+no menu bar, then @var{bottom} returned by @code{window-edges} is the
+same as the value of @code{(window-height)}, @var{right} is almost the
+same as the value of @code{(window-width)}, and @var{top} and
+@var{left} are zero.  For example, the edges of the following window
+are @w{@samp{0 0 8 5}}.  Assuming that the frame has more than 8
+columns, the last column of the window (column 7) holds a border
+rather than text.  The last row (row 4) holds the mode line, shown
+here with @samp{xxxxxxxxx}.
+
+@example
+@group
+           0
+           _______
+        0 |       |
+          |       |
+          |       |
+          |       |
+          xxxxxxxxx  4
+
+                  7
+@end group
+@end example
+
+In the following example, let's suppose that the frame is 7
+columns wide.  Then the edges of the left window are @w{@samp{0 0 4 3}}
+and the edges of the right window are @w{@samp{4 0 7 3}}.
+The inside edges of the left window are @w{@samp{0 0 3 2}},
+and the inside edges of the right window are @w{@samp{4 0 7 2}},
+
+@example
+@group
+           ___ ___
+          |   |   |
+          |   |   |
+          xxxxxxxxx
+
+           0  34  7
+@end group
+@end example
+
+@defun window-pixel-edges &optional window
+This function is like @code{window-edges} except that, on a graphical
+display, the edge values are measured in pixels instead of in
+character lines and columns.
+@end defun
+
+@defun window-inside-pixel-edges &optional window
+This function is like @code{window-inside-edges} except that, on a
+graphical display, the edge values are measured in pixels instead of
+in character lines and columns.
+@end defun
+
+@node Resizing Windows
+@section Changing the Size of a Window
+@cindex window resizing
+@cindex resize window
+@cindex changing window size
+@cindex window size, changing
+
+  The window size functions fall into two classes: high-level commands
+that change the size of windows and low-level functions that access
+window size.  Emacs does not permit overlapping windows or gaps between
+windows, so resizing one window affects other windows.
+
+@deffn Command enlarge-window size &optional horizontal
+This function makes the selected window @var{size} lines taller,
+stealing lines from neighboring windows.  It takes the lines from one
+window at a time until that window is used up, then takes from another.
+If a window from which lines are stolen shrinks below
+@code{window-min-height} lines, that window disappears.
+
+If @var{horizontal} is non-@code{nil}, this function makes
+@var{window} wider by @var{size} columns, stealing columns instead of
+lines.  If a window from which columns are stolen shrinks below
+@code{window-min-width} columns, that window disappears.
+
+If the requested size would exceed that of the window's frame, then the
+function makes the window occupy the entire height (or width) of the
+frame.
+
+If there are various other windows from which lines or columns can be
+stolen, and some of them specify fixed size (using
+@code{window-size-fixed}, see below), they are left untouched while
+other windows are ``robbed.''  If it would be necessary to alter the
+size of a fixed-size window, @code{enlarge-window} gets an error
+instead.
+
+If @var{size} is negative, this function shrinks the window by
+@minus{}@var{size} lines or columns.  If that makes the window smaller
+than the minimum size (@code{window-min-height} and
+@code{window-min-width}), @code{enlarge-window} deletes the window.
+
+@code{enlarge-window} returns @code{nil}.
+@end deffn
+
+@deffn Command enlarge-window-horizontally columns
+This function makes the selected window @var{columns} wider.
+It could be defined as follows:
+
+@example
+@group
+(defun enlarge-window-horizontally (columns)
+  (interactive "p")
+  (enlarge-window columns t))
+@end group
+@end example
+@end deffn
+
+@deffn Command shrink-window size &optional horizontal
+This function is like @code{enlarge-window} but negates the argument
+@var{size}, making the selected window smaller by giving lines (or
+columns) to the other windows.  If the window shrinks below
+@code{window-min-height} or @code{window-min-width}, then it disappears.
+
+If @var{size} is negative, the window is enlarged by @minus{}@var{size}
+lines or columns.
+@end deffn
+
+@deffn Command shrink-window-horizontally columns
+This function makes the selected window @var{columns} narrower.
+It could be defined as follows:
+
+@example
+@group
+(defun shrink-window-horizontally (columns)
+  (interactive "p")
+  (shrink-window columns t))
+@end group
+@end example
+@end deffn
+
+@defun adjust-window-trailing-edge window delta horizontal
+This function makes the selected window @var{delta} lines taller or
+@var{delta} columns wider, by moving the bottom or right edge.  This
+function does not delete other windows; if it cannot make the
+requested size adjustment, it signals an error.  On success, this
+function returns @code{nil}.
+@end defun
+
+@defun fit-window-to-buffer &optional window max-height min-height
+This function makes @var{window} the right height to display its
+contents exactly.  If @var{window} is omitted or @code{nil}, it uses
+the selected window.
+
+The argument @var{max-height} specifies the maximum height the window
+is allowed to be; @code{nil} means use the frame height.  The argument
+@var{min-height} specifies the minimum height for the window;
+@code{nil} means use @code{window-min-height}.  All these height
+values include the mode-line and/or header-line.
+@end defun
+
+@deffn Command shrink-window-if-larger-than-buffer &optional window
+This command shrinks @var{window} vertically to be as small as
+possible while still showing the full contents of its buffer---but not
+less than @code{window-min-height} lines.  If @var{window} is not
+given, it defaults to the selected window.
+
+However, the command does nothing if the window is already too small to
+display the whole text of the buffer, or if part of the contents are
+currently scrolled off screen, or if the window is not the full width of
+its frame, or if the window is the only window in its frame.
+
+This command returns non-@code{nil} if it actually shrank the window
+and @code{nil} otherwise.
+@end deffn
+
+@defvar window-size-fixed
+If this variable is non-@code{nil}, in any given buffer,
+then the size of any window displaying the buffer remains fixed
+unless you explicitly change it or Emacs has no other choice.
+
+If the value is @code{height}, then only the window's height is fixed;
+if the value is @code{width}, then only the window's width is fixed.
+Any other non-@code{nil} value fixes both the width and the height.
+
+This variable automatically becomes buffer-local when set.
+
+Explicit size-change functions such as @code{enlarge-window}
+get an error if they would have to change a window size which is fixed.
+Therefore, when you want to change the size of such a window,
+you should bind @code{window-size-fixed} to @code{nil}, like this:
+
+@example
+(let ((window-size-fixed nil))
+   (enlarge-window 10))
+@end example
+
+Note that changing the frame size will change the size of a
+fixed-size window, if there is no other alternative.
+@end defvar
+
+@cindex minimum window size
+  The following two variables constrain the window-structure-changing
+functions to a minimum height and width.
+
+@defopt window-min-height
+The value of this variable determines how short a window may become
+before it is automatically deleted.  Making a window smaller than
+@code{window-min-height} automatically deletes it, and no window may
+be created shorter than this.  The default value is 4.
+
+The absolute minimum window height is one; actions that change window
+sizes reset this variable to one if it is less than one.
+@end defopt
+
+@defopt window-min-width
+The value of this variable determines how narrow a window may become
+before it is automatically deleted.  Making a window smaller than
+@code{window-min-width} automatically deletes it, and no window may be
+created narrower than this.  The default value is 10.
+
+The absolute minimum window width is two; actions that change window
+sizes reset this variable to two if it is less than two.
+@end defopt
+
+@node Coordinates and Windows
+@section Coordinates and Windows
+
+This section describes how to relate screen coordinates to windows.
+
+@defun window-at x y &optional frame
+This function returns the window containing the specified cursor
+position in the frame @var{frame}.  The coordinates @var{x} and @var{y}
+are measured in characters and count from the top left corner of the
+frame.  If they are out of range, @code{window-at} returns @code{nil}.
+
+If you omit @var{frame}, the selected frame is used.
+@end defun
+
+@defun coordinates-in-window-p coordinates window
+This function checks whether a particular frame position falls within
+the window @var{window}.
+
+The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
+. @var{y})}.  The coordinates @var{x} and @var{y} are measured in
+characters, and count from the top left corner of the screen or frame.
+
+The value returned by @code{coordinates-in-window-p} is non-@code{nil}
+if the coordinates are inside @var{window}.  The value also indicates
+what part of the window the position is in, as follows:
+
+@table @code
+@item (@var{relx} . @var{rely})
+The coordinates are inside @var{window}.  The numbers @var{relx} and
+@var{rely} are the equivalent window-relative coordinates for the
+specified position, counting from 0 at the top left corner of the
+window.
+
+@item mode-line
+The coordinates are in the mode line of @var{window}.
+
+@item header-line
+The coordinates are in the header line of @var{window}.
+
+@item vertical-line
+The coordinates are in the vertical line between @var{window} and its
+neighbor to the right.  This value occurs only if the window doesn't
+have a scroll bar; positions in a scroll bar are considered outside the
+window for these purposes.
+
+@item left-fringe
+@itemx right-fringe
+The coordinates are in the left or right fringe of the window.
+
+@item left-margin
+@itemx right-margin
+The coordinates are in the left or right margin of the window.
+
+@item nil
+The coordinates are not in any part of @var{window}.
+@end table
+
+The function @code{coordinates-in-window-p} does not require a frame as
+argument because it always uses the frame that @var{window} is on.
+@end defun
+
+@node Window Tree
+@section The Window Tree
+@cindex window tree
+
+  A @dfn{window tree} specifies the layout, size, and relationship
+between all windows in one frame.
+
+@defun window-tree &optional frame
+This function returns the window tree for frame @var{frame}.
+If @var{frame} is omitted, the selected frame is used.
+
+The return value is a list of the form @code{(@var{root} @var{mini})},
+where @var{root} represents the window tree of the frame's
+root window, and @var{mini} is the frame's minibuffer window.
+
+If the root window is not split, @var{root} is the root window itself.
+Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
+@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split,
+and @code{t} for a vertical split, @var{edges} gives the combined size and
+position of the subwindows in the split, and the rest of the elements
+are the subwindows in the split.  Each of the subwindows may again be
+a window or a list representing a window split, and so on.  The
+@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})}
+similar to the value returned by @code{window-edges}.
+@end defun
+
+@node Window Configurations
+@section Window Configurations
+@cindex window configurations
+@cindex saving window information
+
+  A @dfn{window configuration} records the entire layout of one
+frame---all windows, their sizes, which buffers they contain, what
+part of each buffer is displayed, and the values of point and the
+mark; also their fringes, margins, and scroll bar settings.  It also
+includes the values of @code{window-min-height},
+@code{window-min-width} and @code{minibuffer-scroll-window}.  An
+exception is made for point in the selected window for the current
+buffer; its value is not saved in the window configuration.
+
+  You can bring back an entire previous layout by restoring a window
+configuration previously saved.  If you want to record all frames
+instead of just one, use a frame configuration instead of a window
+configuration.  @xref{Frame Configurations}.
+
+@defun current-window-configuration &optional frame
+This function returns a new object representing @var{frame}'s current
+window configuration.  If @var{frame} is omitted, the selected frame
+is used.
+@end defun
+
+@defun set-window-configuration configuration
+This function restores the configuration of windows and buffers as
+specified by @var{configuration}, for the frame that @var{configuration}
+was created for.
+
+The argument @var{configuration} must be a value that was previously
+returned by @code{current-window-configuration}.  This configuration is
+restored in the frame from which @var{configuration} was made, whether
+that frame is selected or not.  This always counts as a window size
+change and triggers execution of the @code{window-size-change-functions}
+(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
+know how to tell whether the new configuration actually differs from the
+old one.
+
+If the frame which @var{configuration} was saved from is dead, all this
+function does is restore the three variables @code{window-min-height},
+@code{window-min-width} and @code{minibuffer-scroll-window}. In this
+case, the function returns @code{nil}.  Otherwise, it returns @code{t}.
+
+Here is a way of using this function to get the same effect
+as @code{save-window-excursion}:
+
+@example
+@group
+(let ((config (current-window-configuration)))
+  (unwind-protect
+      (progn (split-window-vertically nil)
+             @dots{})
+    (set-window-configuration config)))
+@end group
+@end example
+@end defun
+
+@defspec save-window-excursion forms@dots{}
+This special form records the window configuration, executes @var{forms}
+in sequence, then restores the earlier window configuration.  The window
+configuration includes, for each window, the value of point and the
+portion of the buffer that is visible.  It also includes the choice of
+selected window.  However, it does not include the value of point in
+the current buffer; use @code{save-excursion} also, if you wish to
+preserve that.
+
+Don't use this construct when @code{save-selected-window} is sufficient.
+
+Exit from @code{save-window-excursion} always triggers execution of the
+@code{window-size-change-functions}.  (It doesn't know how to tell
+whether the restored configuration actually differs from the one in
+effect at the end of the @var{forms}.)
+
+The return value is the value of the final form in @var{forms}.
+For example:
+
+@example
+@group
+(split-window)
+     @result{} #<window 25 on control.texi>
+@end group
+@group
+(setq w (selected-window))
+     @result{} #<window 19 on control.texi>
+@end group
+@group
+(save-window-excursion
+  (delete-other-windows w)
+  (switch-to-buffer "foo")
+  'do-something)
+     @result{} do-something
+     ;; @r{The screen is now split again.}
+@end group
+@end example
+@end defspec
+
+@defun window-configuration-p object
+This function returns @code{t} if @var{object} is a window configuration.
+@end defun
+
+@defun compare-window-configurations config1 config2
+This function compares two window configurations as regards the
+structure of windows, but ignores the values of point and mark and the
+saved scrolling positions---it can return @code{t} even if those
+aspects differ.
+
+The function @code{equal} can also compare two window configurations; it
+regards configurations as unequal if they differ in any respect, even a
+saved point or mark.
+@end defun
+
+@defun window-configuration-frame config
+This function returns the frame for which the window configuration
+@var{config} was made.
+@end defun
+
+  Other primitives to look inside of window configurations would make
+sense, but are not implemented because we did not need them.  See the
+file @file{winner.el} for some more operations on windows
+configurations.
+
+@node Window Hooks
+@section Hooks for Window Scrolling and Changes
+@cindex hooks for window operations
+
+This section describes how a Lisp program can take action whenever a
+window displays a different part of its buffer or a different buffer.
+There are three actions that can change this: scrolling the window,
+switching buffers in the window, and changing the size of the window.
+The first two actions run @code{window-scroll-functions}; the last runs
+@code{window-size-change-functions}.
+
+@defvar window-scroll-functions
+This variable holds a list of functions that Emacs should call before
+redisplaying a window with scrolling.  It is not a normal hook, because
+each function is called with two arguments: the window, and its new
+display-start position.
+
+Displaying a different buffer in the window also runs these functions.
+
+These functions must be careful in using @code{window-end}
+(@pxref{Window Start}); if you need an up-to-date value, you must use
+the @var{update} argument to ensure you get it.
+
+@strong{Warning:} don't use this feature to alter the way the window
+is scrolled.  It's not designed for that, and such use probably won't
+work.
+@end defvar
+
+@defvar window-size-change-functions
+This variable holds a list of functions to be called if the size of any
+window changes for any reason.  The functions are called just once per
+redisplay, and just once for each frame on which size changes have
+occurred.
+
+Each function receives the frame as its sole argument.  There is no
+direct way to find out which windows on that frame have changed size, or
+precisely how.  However, if a size-change function records, at each
+call, the existing windows and their sizes, it can also compare the
+present sizes and the previous sizes.
+
+Creating or deleting windows counts as a size change, and therefore
+causes these functions to be called.  Changing the frame size also
+counts, because it changes the sizes of the existing windows.
+
+It is not a good idea to use @code{save-window-excursion} (@pxref{Window
+Configurations}) in these functions, because that always counts as a
+size change, and it would cause these functions to be called over and
+over.  In most cases, @code{save-selected-window} (@pxref{Selecting
+Windows}) is what you need here.
+@end defvar
+
+@defvar redisplay-end-trigger-functions
+This abnormal hook is run whenever redisplay in a window uses text that
+extends past a specified end trigger position.  You set the end trigger
+position with the function @code{set-window-redisplay-end-trigger}.  The
+functions are called with two arguments: the window, and the end trigger
+position.  Storing @code{nil} for the end trigger position turns off the
+feature, and the trigger value is automatically reset to @code{nil} just
+after the hook is run.
+@end defvar
+
+@defun set-window-redisplay-end-trigger window position
+This function sets @var{window}'s end trigger position at
+@var{position}.
+@end defun
+
+@defun window-redisplay-end-trigger &optional window
+This function returns @var{window}'s current end trigger position.
+If @var{window} is @code{nil} or omitted, it uses the selected window.
+@end defun
+
+@defvar window-configuration-change-hook
+A normal hook that is run every time you change the window configuration
+of an existing frame.  This includes splitting or deleting windows,
+changing the sizes of windows, or displaying a different buffer in a
+window.  The frame whose window configuration has changed is the
+selected frame when this hook runs.
+@end defvar
+
+@ignore
+   arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
+@end ignore