Initial revision

4 files changed, 3207 insertions, 0 deletions

diff --git a/lispref/elisp.texi b/lispref/elisp.texi
new file mode 100644
index 00000000000..3b54cb66444
--- /dev/null
+++ b/lispref/elisp.texi
@@ -0,0 +1,903 @@
+\input texinfo  @c -*-texinfo-*-
+@c %**start of header
+@setfilename elisp
+@smallbook
+@settitle GNU Emacs Lisp Reference Manual
+@c %**end of header
+
+@ifinfo
+This version is the edition 2.3 of the GNU Emacs Lisp
+Reference Manual.  It corresponds to Emacs Version 19.23.
+@c Please REMEMBER to update edition number in *four* places in this file
+@c                 and also in *one* place in intro.texi
+
+Published by the Free Software Foundation
+675 Massachusetts Avenue
+Cambridge, MA 02139 USA
+
+Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Foundation.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided that the entire resulting derived work is
+distributed under the terms of a permission notice identical to this
+one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the Free Software Foundation
+instead of in the original English.
+@end ifinfo
+
+@c Combine indices.
+@synindex cp fn
+@syncodeindex vr fn
+@syncodeindex ky fn
+@syncodeindex pg fn
+@syncodeindex tp fn
+
+@setchapternewpage odd
+@finalout
+
+@titlepage
+@title GNU Emacs Lisp Reference Manual
+@subtitle GNU Emacs Version 19
+@subtitle for Unix Users
+@c The edition number appears in several places in this file
+@c and also in the file intro.texi.
+@subtitle Second Edition, June 1993
+@subtitle Revision 2.3, April 1994
+
+@author by Bil Lewis, Dan LaLiberte, Richard Stallman
+@author and the GNU Manual Group
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+
+@sp 2
+Second Edition @*
+Revised for Emacs Version 19.23,@*
+April 1994.@*
+@sp 2
+ISBN 1-882114-40-X
+
+@sp 2
+Published by the Free Software Foundation @*
+675 Massachusetts Avenue @*
+Cambridge, MA 02139 USA
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the Free Software Foundation
+instead of in the original English.
+
+Cover art by Etienne Suvasa.
+@end titlepage
+@page
+
+@node Top, Copying, (dir), (dir)
+
+@ifinfo
+This Info file contains edition 2.3 of the GNU Emacs Lisp
+Reference Manual, corresponding to GNU Emacs version 19.23.
+@end ifinfo
+
+@menu
+* Copying::                 Conditions for copying and changing GNU Emacs.
+* Introduction::            Introduction and conventions used.
+
+* Types of Lisp Object::    Data types 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.
+* 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.
+
+* Loading::                 Reading files of Lisp code into Lisp.
+* Byte Compilation::        Compilation makes programs run faster.
+* Debugging::               Tools and tips for debugging Lisp programs.
+
+* Streams::                 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 X 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.
+* 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.
+* System Interface::        Getting the user id, system type, environment
+                              variables, and other such things.
+* Display::                 Parameters controlling screen usage.
+                              The bell.  Waiting for input.
+* Calendar::                Customizing the calendar and diary.
+
+Appendices
+
+* Tips::                    Advice for writing Lisp programs.
+* GNU Emacs Internals::     Building and dumping Emacs;
+                              internal data structures.
+* Standard Errors::         List of all error symbols.
+* Standard Buffer-Local Variables::  List of variables local in all buffers.
+* Standard Keymaps::        List of standard keymaps.
+* Standard Hooks::          List of standard hook variables.
+
+* Antinews::                Information about Emacs 18.
+
+* Index::                   Index including concepts, functions, variables,
+                              and other terms.
+
+      --- 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.
+* 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 Sample Variable Description::   
+
+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.
+* 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.
+* Sequence Type::       Both lists and arrays are classified as sequences.
+* List Type::           Lists gave Lisp its name (not to mention reputation).
+* Array Type::          Arrays include strings and vectors.
+* String Type::         An (efficient) array of characters.
+* Vector Type::         One-dimensional arrays.
+* Symbol Type::         A multi-use object that refers to a function,
+                        variable, property list, or itself.
+* Lisp Function Type::  A piece of executable code you can call from elsewhere.
+* Lisp 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.
+
+List Type
+
+* Dotted Pair Notation::    An alternative syntax for lists.
+* Association List Type::   A specially constructed list.
+
+Editing Types
+
+* Buffer Type::             The basic object of editing.
+* Window Type::             What makes buffers visible.
+* Window Configuration Type::Save what the screen looks like.
+* Marker Type::             A position in a buffer.
+* Process Type::            A process running on the underlying OS.
+* Stream Type::             Receive or send characters.
+* Keymap Type::             What function a keystroke invokes.
+* Syntax Table Type::       What a character means.
+
+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.
+* Arithmetic Operations::     How to add, subtract, multiply and divide.
+* Bitwise Operations::        Logical and, or, not, shifting.
+* Numeric Conversions::       Converting float to integer and vice versa.
+* Transcendental 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.
+* Text Comparison::         Comparing characters or strings.
+* String Conversion::       Converting characters or strings and vice versa.
+* Formatting Strings::      @code{format}: Emacs's analog of @code{printf}.
+* Character Case::          Case conversion functions.
+
+Lists
+
+* Cons Cells::              How lists are made out of cons cells.
+* Lists as Boxes::          Graphical notation to explain lists.
+* List-related Predicates:: Is this object a list?  Comparing two lists.
+* List Elements::           Extracting the pieces of a list.
+* Building Lists::          Creating list structure.
+* 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.
+
+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::                 Functions specifically for vectors.
+
+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.
+
+Evaluation
+
+* Intro Eval::              Evaluation in the scheme of things.
+* Eval::                    How to invoke the Lisp interpreter explicitly.
+* Forms::                   How various sorts of objects are evaluated.
+* Quoting::                 Avoiding evaluation (to put constants in 
+                              the program).
+
+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 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}.
+* 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 Names::             How errors are classified for trapping them.
+
+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.
+* 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.
+
+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 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.
+* 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.
+
+Loading
+
+* How Programs Do Loading:: The @code{load} function and others.
+* Autoload::                Setting up a function to autoload.
+* Features::                Loading a library if it isn't already loaded.
+* Repeated Loading::        Precautions about loading a file twice.
+
+Byte Compilation
+
+* Compilation Functions::   Byte compilation functions.
+* Disassembly::             Disassembling byte-code; how to read byte-code.
+
+Debugging Lisp Programs
+
+* Debugger::                How the Emacs Lisp debugger is implemented.
+* Syntax Errors::           How to find syntax errors.
+* Compilation Errors::      How to find errors that show up in 
+                              byte compilation.
+* Edebug::                  A source-level Emacs Lisp debugger.
+                                
+The Lisp Debugger
+
+* Error Debugging::         Entering the debugger when an error happens.
+* 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.
+
+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.
+
+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.
+* Completion::              How to invoke and customize completion.
+* Yes-or-No Queries::       Asking a question with a simple answer.
+* 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.
+* Input Events::        What input looks like when you read it.
+* Reading Input::       How to read input events from the keyboard or mouse.
+* 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.
+
+Keymaps
+
+* Keymap Terminology::          Definitions of terms pertaining to 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.
+* Menu Keymaps::                A keymap can define a menu for X windows
+                                  or for use from the terminal.
+* Active Keymaps::              Each buffer has a local keymap
+                                  to override the standard (global) bindings.
+                                Each 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.
+* Key Binding Commands::        Interactive interfaces for redefining keys.
+* Scanning Keymaps::            Looking through all keymaps, for printing help.
+
+Major and Minor Modes
+
+* Major Modes::             Defining major modes.
+* Minor Modes::             Defining minor modes.
+* Mode Line Format::        Customizing the text that appears in the mode line.
+* Hooks::                   How to use hooks; how to write code that 
+                              provides hooks.
+
+Major Modes
+
+* 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.
+
+Minor Modes
+
+* Minor Mode Conventions::  Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+
+Mode Line Format
+
+* 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.
+
+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.
+* Contents of Directories::   Getting a list of the files in a directory.
+* Changing File Attributes::  Renaming files, changing protection, etc.
+* File Names::                Decomposing and expanding file names.
+
+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 link?
+* File Attributes::         How large is it?  Any other names?  Etc.
+
+File Names
+
+* File Name Components::    The directory part of a file name, and the rest.
+* Directory Names::         A directory's name as a directory
+                              is different from its name as a file.
+* Relative File Names::     Some file names are relative to a 
+                              current directory.
+* 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.
+
+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?
+* 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.
+* Current Buffer::          Designating a buffer as current
+                              so primitives will access its contents.
+
+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-lever functions for displaying a buffer
+                              and choosing a window for it.
+* 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. 
+* Vertical Scrolling::      Moving text up and down in the window.
+* Horizontal Scrolling::    Moving text sideways on the window.
+* Size of Window::          Accessing the size of a window.
+* Resizing Windows::        Changing the size of a window.
+* Window Configurations::   Saving and restoring the state of the screen.
+
+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.
+* Vertical Motion::         Implementation of @code{next-line} and
+                              @code{previous-line}.
+* 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. 
+* Changing 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.
+* 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.
+* Auto Filling::            How auto-fill mode is implemented to break lines.
+* Filling::                 Functions for explicit filling.
+* Sorting::                 Functions for sorting parts of the buffer.
+* Indentation::             Functions to insert or adjust indentation.
+* Columns::                 Computing horizontal positions, and using them.
+* Case Changes::            Case conversion of parts of the buffer.
+* Substitution::            Replacing a given character wherever it appears.
+* Underlining::             Inserting or deleting underlining-by-overstrike.
+* Registers::               How registers are implemented.  Accessing
+                              the text or position stored in a register.
+                              
+The Kill Ring
+
+* Kill Ring Concepts::      What text looks like in the kill ring.
+* Kill Functions::          Functions that kill text.
+* 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.
+
+Searching and Matching
+
+* String Search::           Search for an exact match.
+* Regular Expressions::     Describing classes of strings.
+* Regexp Search::           Searching for a match for a regexp.
+* Match Data::              Finding out which part of the text matched
+                              various parts of a regexp, after regexp search.
+* Saving Match Data::       Saving and restoring this information.
+* Standard Regexps::        Useful regexps for finding sentences, pages,...
+* Searching and Case::      Case-independent or case-significant searching.
+
+Regular Expressions
+
+* Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Example::          Illustrates regular expression syntax.
+
+Syntax Tables
+
+* Syntax Descriptors::      How characters are classified.
+* Syntax Table Functions::  How to create, examine and alter syntax tables.
+* 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.
+
+Syntax Descriptors
+
+* Syntax Class Table::      Table of syntax classes.
+* Syntax Flags::            Additional flags each character can have.
+
+Abbrevs And Abbrev Expansion
+
+* 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.
+
+Processes
+
+* Subprocess Creation::     Functions that start subprocesses.
+* 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.
+* TCP::                     Opening network connections.
+
+Receiving Output from Processes
+
+* Process Buffers::         If no filter, output is put in a buffer.
+* Filter Functions::        Filter functions accept output from the process.
+* Accepting Output::        How to wait until process output arrives.
+
+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.
+* Terminal Input::          Recording terminal input for debugging.
+* Terminal Output::         Recording terminal output for debugging.
+* Flow Control::            How to turn output flow control on or off.
+* Batch Mode::              Running Emacs without terminal interaction.
+
+Starting Up Emacs
+
+* Start-up 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.
+
+Emacs Display
+
+* Refresh Screen::          Clearing the screen and redrawing everything on it.
+* Truncation::              Folding or wrapping long text lines.
+* The Echo Area::           Where messages are displayed.
+* Selective Display::       Hiding part of the buffer text.
+* Overlay Arrow::           Display of an arrow to indicate position.
+* Temporary Displays::      Displays that go away automatically.
+* Waiting::                 Forcing display update and waiting for user.
+* Blinking::                How Emacs shows the matching open parenthesis.
+* Usual Display::           How control characters are displayed.
+* Beeping::                 Audible signal to the user.
+* Window Systems::          Which window system is being used.
+
+GNU Emacs Internals
+
+* Building Emacs::          How to preload Lisp libraries into Emacs.
+* Pure Storage::            A kludge to make preloaded Lisp functions sharable.
+* Garbage Collection::      Reclaiming space for Lisp objects no longer used.
+* Object Internals::        Data formats of buffers, windows, processes.
+* Writing Emacs Primitives::  Writing C code for Emacs.
+
+Object Internals
+
+* Buffer Internals::        Components of a buffer structure.
+* Window Internals::        Components of a window structure.
+* Process Internals::       Components of a process structure.
+@end menu
+
+@include intro.texi
+@include objects.texi
+@include numbers.texi
+@include strings.texi
+
+@include lists.texi
+@include sequences.texi
+@include symbols.texi
+@include eval.texi
+
+@include control.texi
+@include variables.texi
+@include functions.texi
+@include macros.texi
+
+@include loading.texi
+@include compile.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 searching.texi
+@include syntax.texi
+@include abbrevs.texi
+
+@include processes.texi
+@include os.texi
+@include display.texi
+@include calendar.texi
+
+@c MOVE to Emacs Manual:  include misc-modes.texi
+
+@c appendices
+
+@c  REMOVE this:  include non-hacker.texi
+
+@include tips.texi
+@include internals.texi
+@include errors.texi
+@include locals.texi
+@include maps.texi
+@include hooks.texi
+@include anti.texi
+
+@include index.texi
+
+@c Print the tables of contents
+@summarycontents
+@contents
+@c That's all
+
+@bye
+
+
+These words prevent "local variables" above from confusing Emacs.
diff --git a/lispref/internals.texi b/lispref/internals.texi
new file mode 100644
index 00000000000..64892ae6aed
--- /dev/null
+++ b/lispref/internals.texi
@@ -0,0 +1,807 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993 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 to preload Lisp libraries into Emacs.
+* Pure Storage::        A kludge to make preloaded Lisp functions sharable.
+* Garbage Collection::  Reclaiming space for Lisp objects no longer used.
+* Writing Emacs Primitives::   Writing C code for Emacs.
+* Object Internals::    Data formats of buffers, windows, processes.
+@end menu
+
+@node Building Emacs, Pure Storage, GNU Emacs Internals, GNU Emacs Internals
+@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 which is still impure but no longer
+bare.
+
+  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} which 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 long 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} which loads them.  You may need to increase the
+value of @code{PURESIZE}, in @file{src/puresize.h}, to make room for 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.
+
+@cindex @file{site-init.el}
+  You can specify other things to be done in Lisp just before dumping by
+putting them in a library named @file{site-init.el}.  However, if these
+things might alter the behavior that users expect from an ordinary
+unmodified Emacs, it is better to do them in @file{default.el}, so that
+users can override them if they wish.  @xref{Start-up Summary}.
+
+  Before @file{emacs} is dumped, the documentation strings for primitive
+and preloaded functions (and variables) need to be found in the file
+where they are stored.  This is done by calling
+@code{Snarf-documentation} (@pxref{Accessing Documentation}).  These
+strings were moved out of @file{emacs} to make it smaller.
+@xref{Documentation Basics}.
+
+@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 use this function in an Emacs that was already dumped, you must
+set @code{command-line-processed} to @code{nil} first for good results.
+@xref{Command Line Arguments}.
+@end defun
+
+@deffn Command emacs-version
+  This function returns a string describing the version of Emacs that is
+running.  It is useful to include this string in bug reports.
+
+@example
+@group
+(emacs-version)
+  @result{} "GNU Emacs 19.22.1 of Fri Feb 27 1994 \
+on slug (berkeley-unix)"
+@end group
+@end example
+
+Called interactively, the function prints the same information in the
+echo area.
+@end deffn
+
+@defvar emacs-build-time
+  The value of this variable is the time at which Emacs was built at the
+local site.
+
+@example
+@group
+emacs-build-time
+     @result{} "Fri Feb 27 14:55:57 1994"
+@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{"19.22.1"}.
+@end defvar
+
+@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals
+@appendixsec Pure Storage
+@cindex pure storage
+
+  There are two types of storage in GNU Emacs Lisp for user-created Lisp
+objects: @dfn{normal storage} and @dfn{pure storage}.  Normal storage is
+where all the new data which is created during an Emacs session is 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 which 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} crashes.  If that happens, you will
+have to increase the compilation parameter @code{PURESIZE} in the file
+@file{src/puresize.h}.  This normally won't happen unless you try to
+preload additional libraries or add features to the standard ones.
+
+@defun purecopy object
+  This function makes a copy of @var{object} in pure storage and returns
+it.  It copies strings by simply making a new string with the same
+characters in pure storage.  It recursively copies the contents of
+vectors and cons cells.  It does not make copies of symbols, or any
+other objects, but just returns them unchanged.  It signals an error if
+asked to copy markers.
+
+This function is used only while Emacs is being built and dumped; it is
+called only in the file @file{emacs/lisp/loaddefs.el}.
+@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).  It is set to @code{nil} when Emacs is saved out
+as @file{emacs}.  The flag is set and reset in the C sources.
+
+ You should not change this flag in a running Emacs.
+@end defvar
+
+@node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals
+@appendixsec Garbage Collection
+@cindex garbage collector
+
+@cindex memory allocation
+  When a program creates a list or the user defines a new function (such
+as by loading a library), then 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, buffers and certain
+other editing types, which are fairly large, are allocated in individual
+blocks, one per object, while 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 scanning all the objects that have
+been allocated and marking those that are still accessible to Lisp
+programs.  To begin with, all the symbols, their values and associated
+function definitions, and any data presently on the stack, are
+accessible.  Any objects which can be reached indirectly through other
+accessible objects are also accessible.
+
+  When this is finished, all inaccessible objects 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 notice.  That is what
+the garbage collector arranges to do.
+
+@cindex free list
+  Unused cons cells are chained together onto a @dfn{free list} for
+future allocation; likewise for symbols and markers.  The accessible
+strings are compacted so they are contiguous in memory; then the rest of
+the space formerly occupied by strings is made available to the string
+creation functions.  Vectors, buffers, windows and other large objects
+are individually allocated and freed using @code{malloc}.
+
+@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:
+
+@smallexample
+@group
+((@var{used-conses} . @var{free-conses})
+ (@var{used-syms} . @var{free-syms})
+ (@var{used-markers} . @var{free-markers})
+ @var{used-string-chars} 
+ @var{used-vector-slots}
+ (@var{used-floats} . @var{free-floats}))
+
+(garbage-collect)
+     @result{} ((3435 . 2332) (1688 . 0)
+           (57 . 417) 24510 3839 (4 . 1))
+@end group
+@end smallexample
+
+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-markers
+The number of markers in use.
+
+@item free-markers
+The number of markers 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.
+@end table
+@end deffn
+
+@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
+request 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 new 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 100,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 which 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
+
+@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
+
+@node Writing Emacs Primitives, Object Internals, Garbage Collection, GNU Emacs Internals
+@appendixsec Writing Emacs Primitives
+@cindex primitive function internals
+
+  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,
+  "Eval args until one of them yields non-NIL, then return that value.\n\
+The remaining args are not evalled at all.\n\
+@end group
+@group
+If all args return NIL, return NIL.")
+  (args)
+     Lisp_Object args;
+@{
+  register Lisp_Object val;
+  Lisp_Object args_left;
+  struct gcpro gcpro1;
+@end group
+
+@group
+  if (NULL(args))
+    return Qnil;
+
+  args_left = args;
+  GCPRO1 (args_left);
+@end group
+
+@group
+  do
+    @{
+      val = Feval (Fcar (args_left));
+      if (!NULL (val))
+        break;
+      args_left = Fcdr (args_left);
+    @}
+  while (!NULL(args_left));
+@end group
+
+@group
+  UNGCPRO;
+  return val;
+@}
+@end group
+@end smallexample
+
+  Let's start with a precise explanation of the arguments to the
+@code{DEFUN} macro.  Here are the general names 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 with this
+function; 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.  For
+@code{or}, no arguments are required.
+
+@item max
+This is the maximum number of arguments that the function accepts.
+Alternatively, it can be @code{UNEVALLED}, indicating a special form
+that receives unevaluated arguments.  A function with the equivalent of
+an @code{&rest} argument would have @code{MANY} in this position.  Both
+@code{UNEVALLED} and @code{MANY} are macros.  This argument must be one
+of these macros or a number at least as large as @var{min}.  It may not
+be greater than six.
+
+@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 an interactive
+function taking no arguments.
+
+@item doc
+This is the documentation string.  It is written just like a
+documentation string for a function defined in Lisp, except you must
+write @samp{\n\} at the end of each line.  In particular, the first line
+should be a single sentence.
+@end table
+
+  After the call to the @code{DEFUN} macro, you must write the list
+of argument names that every C function must have, followed by
+ordinary C declarations for them.  Normally, all the arguments must
+be declared as @code{Lisp_Object}.  If the function has no upper limit
+on the number of arguments in Lisp, then in C it receives two arguments:
+the number of Lisp arguments, and the address of a block containing their
+values.  These have types @code{int} and @w{@code{Lisp_Object *}}.
+
+  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.  This 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 you intend to refer to again must be protected somehow.
+@code{UNGCPRO} cancels the protection of the variables that are
+protected in the current function.  It is necessary to do this explicitly.
+
+  For most data types, it suffices to know that one pointer to the
+object is protected; as long as the object is not recycled, all pointers
+to it remain valid.  This is not so for strings, because the garbage
+collector can move them.  When a string is moved, any pointers to it
+that the garbage collector does not know about will not be properly
+relocated.  Therefore, all pointers to strings must be protected across
+any point where garbage collection may be possible.
+
+  The macro @code{GCPRO1} protects just one local variable.  If you
+want to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1}
+will not work.  There are also @code{GCPRO3} and @code{GCPRO4}.
+
+  In addition to using these macros, you must declare the local
+variables such as @code{gcpro1} which they implicitly use.  If you
+protect two variables, with @code{GCPRO2}, you must declare
+@code{gcpro1} and @code{gcpro2}, as it uses them both.  Alas, we can't
+explain all the tricky details here.
+
+  Defining the C function is not enough; you must also create the
+Lisp symbol for the primitive and store a suitable subr object
+in its function cell.  This is done by adding code to an initialization
+routine.  The code looks like this:
+
+@example
+defsubr (&@var{subr-structure-name});
+@end example
+
+@noindent
+@var{subr-structure-name} is the name you used as the third argument to
+@code{DEFUN}.
+
+  If you are adding a 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 that function call to it.
+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.
+
+  This function @code{syms_of_@var{filename}} is also the place to
+define any C variables which are to be visible as Lisp variables.
+@code{DEFVAR_LISP} is used to make a C variable of type
+@code{Lisp_Object} visible in Lisp.  @code{DEFVAR_INT} is used to make a
+C variable of type @code{int} visible in Lisp with a value that is an
+integer.
+
+  Here is another function, with more complicated arguments.  This comes
+from the code for the X Window System, 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 POSITIONS is in WINDOW.\n\  
+  \(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\
+@end group
+@group
+  Returned value is list of positions expressed\n\
+  relative to window upper left corner.")
+  (coordinate, window)
+     register Lisp_Object coordinate, window;
+@{
+  register Lisp_Object xcoord, ycoord;
+@end group
+
+@group
+  if (!CONSP (coordinate)) wrong_type_argument (Qlistp, coordinate);
+  CHECK_WINDOW (window, 2);
+  xcoord = Fcar (coordinate);
+  ycoord = Fcar (Fcdr (coordinate));
+  CHECK_NUMBER (xcoord, 0);
+  CHECK_NUMBER (ycoord, 1);
+@end group
+@group
+  if ((XINT (xcoord) < XINT (XWINDOW (window)->left))
+      || (XINT (xcoord) >= (XINT (XWINDOW (window)->left)
+                            + XINT (XWINDOW (window)->width))))
+    @{
+      return Qnil;
+    @}
+  XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
+@end group
+@group
+  if (XINT (ycoord) == (screen_height - 1))
+    return Qnil;
+@end group
+@group
+  if ((XINT (ycoord) < XINT (XWINDOW (window)->top))
+      || (XINT (ycoord) >= (XINT (XWINDOW (window)->top)
+                            + XINT (XWINDOW (window)->height)) - 1))
+    @{
+      return Qnil;
+    @}
+@end group
+@group
+  XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top);
+  return (Fcons (xcoord, Fcons (ycoord, Qnil)));
+@}
+@end group
+@end smallexample
+
+  Note that you cannot directly call functions defined in Lisp as, for
+example, the primitive function @code{Fcons} is called above.  You must
+create the appropriate Lisp form, protect everything from garbage
+collection, and @code{Feval} the form, as was done in @code{For} above.
+
+  @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.
+
+@node Object Internals,  , Writing Emacs Primitives, GNU Emacs 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-four to twenty-six bits are used to
+address the object, and the remaining six to eight bits are used for a
+tag that identifies the object's type.
+
+  Because all access to data is through tagged pointers, it is always
+possible to determine the type of any object.  This allows variables to
+be untyped, and the values assigned to them to be changed without regard
+to type.  Function arguments also can be of any type; 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, Window Internals, Object Internals, Object 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.
+
+@table @code
+@item name
+The buffer name is a string which names the buffer.  It is guaranteed to
+be unique.  @xref{Buffer Names}.
+
+@item save_modified
+This field contains the time when the buffer was last saved, as an integer.
+@xref{Buffer Modification}.
+
+@item modtime
+This field contains the modification time of the visited file.  It is
+set when the file is written or read.  Every time the buffer is written
+to the file, this field is compared to the modification time of the
+file.  @xref{Buffer Modification}.
+
+@item auto_save_modified
+This field contains the time when the buffer was last auto-saved.
+
+@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 undodata
+This field points to the buffer's undo stack.  @xref{Undo}.
+
+@item syntax_table_v
+This field contains the syntax table for the buffer.  @xref{Syntax Tables}.
+
+@item downcase_table
+This field contains the conversion table for converting text to lower case.
+@xref{Case Table}.
+
+@item upcase_table
+This field contains the conversion table for converting text to upper case.
+@xref{Case Table}.
+
+@item case_canon_table
+This field contains the conversion table for canonicalizing text for
+case-folding search.  @xref{Case Table}.
+
+@item case_eqv_table
+This field contains the equivalence table for case-folding search.
+@xref{Case Table}.
+
+@item display_table
+This field contains the buffer's display table, or @code{nil} if it doesn't
+have one.  @xref{Display Tables}.
+
+@item markers
+This field contains the chain of all markers that point into the
+buffer.  At each deletion or motion of the buffer gap, all of these
+markers must be checked and perhaps updated.  @xref{Markers}.
+
+@item backed_up
+This field is a flag which tells whether a backup file has been made
+for the visited file of this buffer.
+
+@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 containing all of the variables
+local in this buffer, and their values.  The function
+@code{buffer-local-variables} returns a copy of this list.
+@xref{Buffer-Local Variables}.
+
+@item mode_line_format
+This field contains a Lisp object which controls how to display the mode
+line for this buffer.  @xref{Mode Line Format}.
+@end table
+
+@node Window Internals, Process Internals, Buffer Internals, Object 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 height
+  The height of the window, measured in lines.
+
+@item width
+  The width of the window, measured in columns.
+
+@item buffer
+  The buffer which the window is displaying.  This may change often during
+the life of the window.
+
+@item dedicated
+  Non-@code{nil} if this window is dedicated to its buffer.
+
+@item start
+ The position in the buffer which 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 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 next
+  This is the window that is the next in the chain of siblings.
+
+@item prev
+  This is the window that is the previous in the chain of siblings.
+
+@item force_start
+  This is a flag which, if non-@code{nil}, says that the window has been
+scrolled explicitly by the Lisp program.  At the next redisplay, if
+point is off the screen, instead of scrolling the window to show the
+text around point, point will be moved to a location that is on the
+screen.
+
+@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 use_time
+  This is the last time that the window was selected.  The function
+@code{get-lru-window} uses this field.
+
+@item display_table
+  The window's display table, or @code{nil} if none is specified for it.
+@end table
+
+@node Process Internals,  , Window Internals, Object 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 Unix process @sc{id}.
+
+@item childp
+A flag, non-@code{nil} if this is really a child process.
+It is @code{nil} for a network connection.
+
+@item flags
+A symbol indicating the state of the process.  Possible values include
+@code{run}, @code{stop}, @code{closed}, etc.
+
+@item reason
+An integer, the Unix signal number that the process received that
+caused the process to terminate or stop.  If the process has exited,
+then this is the exit code it specified.
+
+@item mark
+A marker indicating the position of end of last output from this process
+inserted into the buffer.  This is usually the end of the buffer.
+
+@item kill_without_query
+A flag, non-@code{nil} meaning this process should not cause
+confirmation to be needed if Emacs is killed.
+@end table
diff --git a/lispref/maps.texi b/lispref/maps.texi
new file mode 100644
index 00000000000..b0cb0ab0bc8
--- /dev/null
+++ b/lispref/maps.texi
@@ -0,0 +1,133 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993 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
+
+The following symbols are used as the names for various keymaps.
+Some of these exist when Emacs is first started, others are
+only loaded when their respective mode is used.  This is not
+an exhaustive list.
+
+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 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 in C mode as a local map.
+
+@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-map
+A full keymap for @kbd{C-x} commands.
+
+@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 doctor-mode-map
+@vindex doctor-mode-map
+A sparse keymap used by Doctor mode.
+
+@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 in Emacs Lisp mode.
+
+@item function-key-map
+@vindex function-key-map
+The keymap for translating keypad and function keys.@*
+If there are none, then it contains an empty sparse keymap.
+
+@item fundamental-mode-map
+@vindex fundamental-mode-map
+The local keymap for Fundamental mode.@*
+It is empty and should not be changed.
+
+@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
+A keymap that defines the characters you can type within incremental
+search.
+
+@item key-translation-map
+@vindex key-translation-map
+Another keymap for translating keys.  This one overrides ordinary key
+bindings.
+
+@item lisp-interaction-mode-map
+@vindex lisp-interaction-mode-map
+A sparse keymap used in Lisp mode.
+
+@item lisp-mode-map
+@vindex lisp-mode-map
+A sparse keymap used in Lisp mode.
+
+@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 local keymap used in Occur mode.
+
+@item query-replace-map
+A local 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 view-mode-map
+@vindex view-mode-map
+A full keymap used by View mode.
+@end table
diff --git a/lispref/modes.texi b/lispref/modes.texi
new file mode 100644
index 00000000000..c15ca5a9cd0
--- /dev/null
+++ b/lispref/modes.texi
@@ -0,0 +1,1364 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 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
+* Major Modes::        Defining major modes.
+* Minor Modes::        Defining minor modes.
+* Mode Line Format::   Customizing the text that appears in the mode line.
+* Hooks::              How to use hooks; how to write code that provides hooks.
+@end menu
+
+@node Major Modes
+@section Major Modes
+@cindex major mode
+@cindex Fundamental mode
+
+  Major modes specialize Emacs for editing particular kinds of text.
+Each buffer has only one major mode at a time.
+
+  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
+@key{LFD} (@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 define a @dfn{derived mode} (@pxref{Derived
+Modes}).  For example, Rmail Edit mode, which is in
+@file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
+Text mode except that it provides three additional commands.  Its
+definition is distinct from that of Text mode, but was derived from it.
+
+  Rmail Edit mode is an example of a case where one piece of text is put
+temporarily into a different major mode so it can be edited in a
+different way (with ordinary Emacs commands rather than Rmail).  In such
+cases, the temporary major mode usually has 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 alternative major modes avoids this limitation.  @xref{Recursive
+Editing}.
+
+  The standard GNU Emacs Lisp library directory contains the code for
+several major modes, in files including @file{text-mode.el},
+@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
+@file{rmail.el}.  You can look at 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.
+
+@menu
+* 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.
+@end menu
+
+@node Major Mode Conventions
+@subsection Major Mode Conventions
+
+  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:
+
+@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 local variables in an
+existing buffer without changing the buffer's text.
+
+@item
+Write a documentation string for this command which 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}>}, that 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 is what gets rid of the local
+variables of the major mode previously in effect.
+
+@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 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{Style Tips}.
+
+@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 function
+should call @code{use-local-map} to install this local map.
+@xref{Active Keymaps}, for more information.
+
+This keymap should be kept in a global variable named
+@code{@var{modename}-mode-map}.  Normally the library that defines the
+mode sets this variable.  Use @code{defvar} to set the variable, so that
+it is not reinitialized if it already has a value.  (Such
+reinitialization could discard customizations made by the user.)
+
+@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}.  The reasons
+for this are the same as for using a keymap variable.  @xref{Syntax
+Tables}.
+
+@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}.  @xref{Abbrev
+Tables}.
+
+@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}.
+
+It's ok to use @code{make-variable-buffer-local}, if you wish, for a
+variable used only within a single Lisp package.
+
+@item
+@cindex mode hook
+@cindex major mode hook
+Each major mode should have a @dfn{mode hook} named
+@code{@var{modename}-mode-hook}.  The major mode command should run that
+hook, with @code{run-hooks}, as the very last thing it
+does. @xref{Hooks}.
+
+@item
+The major mode command may also run the hooks of some more basic modes.
+For example, @code{indented-text-mode} runs @code{text-mode-hook} as
+well as @code{indented-text-mode-hook}.  It may run these other hooks
+immediately before the mode's own hook (that is, after everything else),
+or it may run them earlier.
+
+@item
+If something special should be done if the user switches a buffer from
+this mode to any other major mode, the mode can set a local value for
+@code{change-major-mode-hook}.
+
+@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:
+
+@cindex @code{mode-class} 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 has
+Funny mode should not inherit Funny mode.  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.  If you define the mode command to
+autoload, you should add this element in the same file that calls
+@code{autoload}.  Otherwise, it is sufficient to add the element in the
+file that contains the mode definition.  @xref{Auto Major Mode}.
+
+@item
+@cindex @file{.emacs} customization
+In the documentation, 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 @file{.emacs} files.
+
+@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
+
+@defvar change-major-mode-hook
+This normal hook is run by @code{kill-all-local-variables} 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.  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.
+@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 mode-specific tables.}
+(defvar text-mode-syntax-table nil 
+  "Syntax table used while in text mode.")
+@end group
+
+@group
+(if text-mode-syntax-table
+    ()              ; @r{Do not change the table if it is already set up.}
+  (setq text-mode-syntax-table (make-syntax-table))
+  (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
+  (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
+  (modify-syntax-entry ?' "w   " text-mode-syntax-table))
+@end group
+
+@group
+(defvar text-mode-abbrev-table nil
+  "Abbrev table used while in text mode.")
+(define-abbrev-table 'text-mode-abbrev-table ())
+@end group
+
+@group
+(defvar text-mode-map nil)   ; @r{Create a mode-specific keymap.}
+
+(if text-mode-map
+    ()              ; @r{Do not change the keymap if it is already set up.}
+  (setq text-mode-map (make-sparse-keymap))
+  (define-key text-mode-map "\t" 'tab-to-tab-stop)
+  (define-key text-mode-map "\es" 'center-line)
+  (define-key text-mode-map "\eS" 'center-paragraph))
+@end group
+@end smallexample
+
+  Here is the complete major mode function definition for Text mode:
+
+@smallexample
+@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)
+@end group
+@group
+  (use-local-map text-mode-map)     ; @r{This provides the local keymap.}
+  (setq mode-name "Text")           ; @r{This name goes into the mode line.}
+  (setq major-mode 'text-mode)      ; @r{This is how @code{describe-mode}}
+                                    ;   @r{finds the doc string to print.}
+  (setq local-abbrev-table text-mode-abbrev-table)
+  (set-syntax-table text-mode-syntax-table)
+  (run-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 emacs-lisp-mode-syntax-table nil "")
+(defvar lisp-mode-abbrev-table nil "")
+@end group
+
+@group
+(if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
+                                       ;   @r{if it is already set.}
+    (let ((i 0))
+      (setq emacs-lisp-mode-syntax-table (make-syntax-table))
+@end group
+
+@group
+      ;; @r{Set syntax of chars up to 0 to class of chars that are}
+      ;;   @r{part of symbol names but not words.}
+      ;;   @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)}
+      (while (< i ?0) 
+        (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
+        (setq i (1+ i)))
+      @dots{}
+@end group
+@group
+      ;; @r{Set the syntax for other characters.}
+      (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
+      (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
+      @dots{}
+@end group
+@group
+      (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
+      (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
+      @dots{}))
+;; @r{Create an abbrev table for lisp-mode.}
+(define-abbrev-table 'lisp-mode-abbrev-table ())
+@end group
+@end smallexample
+
+  Much code is shared among the three Lisp modes.  The following
+function sets various variables; it is called by each of the major Lisp
+mode functions:
+
+@smallexample
+@group
+(defun lisp-mode-variables (lisp-syntax)
+  ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
+  ;;   @r{and @code{t} in the other two Lisp modes.}
+  (cond (lisp-syntax
+         (if (not lisp-mode-syntax-table)
+             ;; @r{The Emacs Lisp mode syntax table always exists, but}
+             ;;   @r{the Lisp Mode syntax table is created the first time a}
+             ;;   @r{mode that needs it is called.  This is to save space.}
+@end group
+@group
+             (progn (setq lisp-mode-syntax-table
+                       (copy-syntax-table emacs-lisp-mode-syntax-table))
+                    ;; @r{Change some entries for Lisp mode.}
+                    (modify-syntax-entry ?\| "\"   "
+                                         lisp-mode-syntax-table)
+                    (modify-syntax-entry ?\[ "_   "
+                                         lisp-mode-syntax-table)
+                    (modify-syntax-entry ?\] "_   "
+                                         lisp-mode-syntax-table)))
+@end group
+@group
+          (set-syntax-table lisp-mode-syntax-table)))
+  (setq local-abbrev-table lisp-mode-abbrev-table)
+  @dots{})
+@end group
+@end smallexample
+
+  Functions such as @code{forward-paragraph} use the value of the
+@code{paragraph-start} variable.  Since Lisp code is different from
+ordinary text, the @code{paragraph-start} variable needs to be set
+specially to handle Lisp.  Also, comments are indented in a special
+fashion in Lisp and the Lisp modes need their own mode-specific
+@code{comment-indent-function}.  The code to set these variables is the
+rest of @code{lisp-mode-variables}.
+
+@smallexample
+@group
+  (make-local-variable 'paragraph-start)
+  (setq paragraph-start (concat "^$\\|" page-delimiter))
+  @dots{}
+@end group
+@group
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'lisp-comment-indent))
+@end group
+@end smallexample
+
+  Each of the different Lisp modes has a slightly different keymap.  For
+example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
+Lisp modes do not.  However, all Lisp modes have some commands in
+common.  The following function adds these common commands to a given
+keymap.
+
+@smallexample
+@group
+(defun lisp-mode-commands (map)
+  (define-key map "\e\C-q" 'indent-sexp)
+  (define-key map "\177" 'backward-delete-char-untabify)
+  (define-key map "\t" 'lisp-indent-line))
+@end group
+@end smallexample
+
+  Here is an example of using @code{lisp-mode-commands} to initialize a
+keymap, as part of the code for Emacs Lisp mode.  First we declare a
+variable with @code{defvar} to hold the mode-specific keymap.  When this
+@code{defvar} executes, it sets the variable to @code{nil} if it was
+void.  Then we set up the keymap if the variable is @code{nil}.
+
+  This code avoids changing the keymap or the variable if it is already
+set up.  This lets the user customize the keymap if he or she so
+wishes.
+
+@smallexample
+@group
+(defvar emacs-lisp-mode-map () "") 
+(if emacs-lisp-mode-map
+    ()
+  (setq emacs-lisp-mode-map (make-sparse-keymap))
+  (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
+  (lisp-mode-commands emacs-lisp-mode-map))
+@end group
+@end smallexample
+
+  Finally, here is the complete major mode function definition for
+Emacs Lisp mode.  
+
+@smallexample
+@group
+(defun emacs-lisp-mode ()
+  "Major mode for editing Lisp code to run in Emacs.
+Commands:
+Delete converts tabs to spaces as it moves back.
+Blank lines separate paragraphs.  Semicolons start comments.
+\\@{emacs-lisp-mode-map@}
+@end group
+@group
+Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+  (interactive)
+  (kill-all-local-variables)
+  (use-local-map emacs-lisp-mode-map)    ; @r{This provides the local keymap.}
+  (set-syntax-table emacs-lisp-mode-syntax-table)
+@end group
+@group
+  (setq major-mode 'emacs-lisp-mode)     ; @r{This is how @code{describe-mode}}
+                                         ;   @r{finds out what to describe.}
+  (setq mode-name "Emacs-Lisp")          ; @r{This goes into the mode line.}
+  (lisp-mode-variables nil)              ; @r{This define various variables.}
+  (run-hooks 'emacs-lisp-mode-hook))     ; @r{This permits the user to use a}
+                                         ;   @r{hook to customize the mode.}
+@end group
+@end smallexample
+
+@node Auto Major Mode
+@subsection How Emacs Chooses a Major Mode
+
+  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.
+
+@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 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 local variable
+bindings for the current buffer.  First it calls @code{set-auto-mode},
+then it runs @code{hack-local-variables} to parse, and bind or
+evaluate as appropriate, any 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 a local variables
+list at the end of the file.  The variable @code{enable-local-variables}
+controls whether to do so.
+
+  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 local variables list.
+@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
+Manual}, for the syntax of the local variables section of a file.
+
+@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
+
+@defopt enable-local-variables
+This variable controls processing of local variables lists in files
+being visited.  A value of @code{t} means process the local variables
+lists unconditionally; @code{nil} means ignore them; anything else means
+ask the user what to do for each file.  The default value is @code{t}.
+@end defopt
+
+@defopt enable-local-eval
+This variable controls processing of @samp{Eval:} in 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
+
+@defun set-auto-mode
+@cindex visited file mode
+  This function selects the major mode that is appropriate for the
+current buffer.  It may base its decision on the value of the @w{@samp{-*-}}
+line, on the visited file name (using @code{auto-mode-alist}), or on the
+value of a local variable).  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.  @xref{Choosing Modes, ,
+How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
+@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 for the major mode of a new
+buffer.  However, if the 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
+
+@defvar 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 name.  The default value is @code{lisp-interaction-mode}.
+@end defvar
+
+@defvar auto-mode-alist
+This variable contains an association list of file name patterns
+(regular expressions; @pxref{Regular Expressions}) and corresponding
+major mode functions.  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}) 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 match-again feature is useful for uncompression packages: an entry
+of the form @code{("\\.gz\\'" . @var{function})} 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
+@file{.emacs} file.)
+
+@smallexample
+@group
+(setq auto-mode-alist
+  (append 
+   ;; @r{Filename starts with a dot.}
+   '(("/\\.[^/]*$" . fundamental-mode)  
+     ;; @r{Filename has no dot.}
+     ("[^\\./]*$" . fundamental-mode)   
+     ("\\.C$" . c++-mode))
+   auto-mode-alist))
+@end group
+@end smallexample
+@end defvar
+
+@defvar interpreter-mode-alist
+This variable specifes major modes to use for scripts that specify a
+command interpreter in an @samp{!#} line.  Its value is a list of
+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
+@var{interpreter}.
+
+This variable is applicable only when the file name doesn't indicate
+which major mode to use.
+@end defvar
+
+@defun hack-local-variables &optional force
+  This function parses, and binds or evaluates as appropriate, any local
+variables for the current buffer.
+
+  The handling of @code{enable-local-variables} documented for
+@code{normal-mode} actually takes place here.  The argument @var{force}
+reflects the argument @var{find-file} given to @code{normal-mode}.
+@end defun
+
+@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 variable holds the symbol for the current buffer's major mode.
+This symbol should have a function definition which is the command to
+switch to that major mode.  The @code{describe-mode} function uses the
+documentation string of this symbol as the documentation of the major
+mode.
+@end defvar
+
+@node Derived Modes
+@subsection Defining Derived Modes
+
+  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 doc body@dots{}
+This construct defines @var{variant} as a major mode command, using
+@var{name} as the string form of the mode which.
+
+The definition of the command is to call the function @var{parent}, then
+override certain aspects of that parent mode:
+
+@itemize @bullet 
+@item
+The new mode has its own keymap, named @code{@var{variant}-map}.
+@code{define-derived-mode} initializes this map to inherit from
+@code{@var{parent}-map}, if it is not already set.
+
+@item
+The new mode has its own syntax table, taken from the variable
+@code{@var{variant}-syntax-table}.
+@code{define-derived-mode} initializes this variable by copying 
+@code{@var{parent}-syntax-table}, if it is not already set.
+
+@item
+The new mode has its own abbrev table, taken from the variable
+@code{@var{variant}-abbrev-table}.
+@code{define-derived-mode} initializes this variable by copying 
+@code{@var{parent}-abbrev-table}, if it is not already set.
+
+@item
+The new mode has its own mode hook, @code{@var{variant}-hook},
+which it runs in standard fashion as the very last thing that it does.
+(The new mode also runs the mode hook of @var{parent} as part 
+of calling @var{parent}.)
+@end itemize
+
+In addition, you can specify how to override other aspects of
+@var{parent-mode} with @var{body}.  The command @var{variant}
+evaluates the forms in @var{body} after setting up all its usual 
+overrides, just before running @code{@var{variant}-hook}.
+
+The argument @var{docstring} specifies the documentation string for the
+new mode.  If you omit @var{docstring}, @code{define-derived-mode}
+generates a documentation string.
+
+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
+@end defmac
+
+@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 is
+unwieldy.
+
+  A minor mode is not usually a modification of single major mode.  For
+example, Auto Fill mode may be used in 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.
+
+and restore the environment of the major mode to the state it was in
+before the minor mode was activated.
+
+  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 in Emacs 19 than it used to be.
+
+@menu
+* Minor Mode Conventions::      Tips for writing a minor mode.
+* Keymaps and Minor Modes::     How a minor mode can have its own keymap.
+@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, and the use of keymaps and
+other tables.
+
+  In addition, there are several conventions that are specific to
+minor modes.
+
+@itemize @bullet
+@item
+@cindex mode variable
+Make a variable whose name ends in @samp{-mode} to represent the minor
+mode.  Its value should enable or disable the mode (@code{nil} to
+disable; anything else to enable.)  We call this the @dfn{mode
+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).  Otherwise, it should turn the mode on if the argument is
+a positive integer, a symbol other than @code{nil} or @code{-}, or a
+list whose @sc{car} is such an integer or symbol; it should turn the
+mode off otherwise.
+
+Here is an example taken from the definition of @code{overwrite-mode}.
+It shows the use of @code{overwrite-mode} as a variable which enables or
+disables the mode's behavior.
+
+@smallexample
+@group
+(setq overwrite-mode
+      (if (null arg) (not overwrite-mode)
+        (> (prefix-numeric-value arg) 0)))
+@end group
+@end smallexample
+
+@item
+Add an element to @code{minor-mode-alist} for each minor mode
+(@pxref{Mode Line Variables}).  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 enablement 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
+(or (assq 'leif-mode minor-mode-alist)
+    (setq minor-mode-alist
+          (cons '(leif-mode " Leif") minor-mode-alist)))
+@end group
+@end smallexample
+@end itemize
+
+@node Keymaps and Minor Modes
+@subsection Keymaps and Minor Modes
+
+As of Emacs version 19, each minor mode can have its own keymap which is
+active when the mode is enabled.  @xref{Active Keymaps}.  To set up a
+keymap for a minor mode, add an element to the alist
+@code{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.)
+
+@defvar minor-mode-map-alist
+This variable is an alist of elements that look like this:
+
+@example
+(@var{variable} . @var{keymap})
+@end example
+
+@noindent
+where @var{variable} is the variable which indicates whether the minor
+mode is enabled, and @var{keymap} is the keymap.  The keymap
+@var{keymap} is active whenever @var{variable} has a non-@code{nil}
+value.
+
+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.
+
+What's more, the keymap itself must appear in the @sc{cdr}.  It does not
+work to store a variable in the @sc{cdr} and make the map the value of
+that variable.
+
+When more than one minor mode keymap is active, their order of priority
+is the order of @code{minor-mode-map-alist}.  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.
+@end defvar
+
+@node Mode Line Format
+@section Mode Line Format
+@cindex mode line
+
+  Each Emacs window (aside from minibuffer windows) includes a mode line
+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 the major and
+minor modes of the buffer.
+
+  This section describes how the contents of the mode line are
+controlled.  It is in the chapter on modes because much of the
+information displayed in the mode line relates to the enabled major and
+minor modes.
+
+  @code{mode-line-format} is a buffer-local variable that holds a
+template used to display the mode line of the current buffer.  All
+windows for the same buffer use the same @code{mode-line-format} and the
+mode lines will appear the same (except for scrolling percentages and
+line numbers).
+
+  The mode line of a window is normally updated whenever a different
+buffer is shown in the window, or when the buffer's modified-status
+changes from @code{nil} to @code{t} or vice-versa.  If you modify any of
+the variables referenced by @code{mode-line-format}, you may want to
+force an update of the mode line so as to display the new information.
+
+@c Emacs 19 feature
+@defun force-mode-line-update
+Force redisplay of the current buffer's mode line.
+@end defun
+
+  The mode line is usually displayed in inverse video; see
+@code{mode-line-inverse-video} in @ref{Inverse Video}.
+
+@menu
+* 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.
+@end menu
+
+@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 of lists,
+strings, symbols and numbers kept in the buffer-local variable
+@code{mode-line-format}.  The data structure is called a @dfn{mode line
+construct}, and it is built in recursive fashion out of simpler mode line
+constructs.
+
+@defvar mode-line-format
+The value of this variable is a mode line construct with overall
+responsibility for the mode line format.  The value of this variable
+controls which other variables are used to form the mode line text, and
+where they appear.
+@end defvar
+
+  A mode line construct may be as simple as a fixed string of text, but
+it usually specifies how to use other variables to construct the text.
+Many of these variables are themselves defined to have mode line
+constructs as their values.
+
+  The default value of @code{mode-line-format} incorporates the values
+of variables such as @code{mode-name} and @code{minor-mode-alist}.
+Because of this, very few modes need to alter @code{mode-line-format}.
+For most purposes, it is sufficient to alter the variables referenced by
+@code{mode-line-format}.
+
+  A mode line construct may be a list, cons cell, symbol, or string.  If
+the value is a list, each element may be a list, a cons cell, a symbol,
+or a string.
+
+@table @code
+@cindex percent symbol in mode line
+@item @var{string}
+A string as a mode line construct is displayed verbatim in the mode line
+except for @dfn{@code{%}-constructs}.  Decimal digits after the @code{%}
+specify the field width for space filling on the right (i.e., the data
+is left justified).  @xref{%-Constructs}.
+
+@item @var{symbol}
+A symbol as a mode line construct stands for its value.  The value of
+@var{symbol} is used in place of @var{symbol} unless @var{symbol} is
+@code{t} or @code{nil}, or is void, in which case @var{symbol} is
+ignored.
+
+There is one exception: if the value of @var{symbol} is a string, it is
+processed verbatim in that the @code{%}-constructs are not recognized.
+
+@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
+A list whose first element is a string or list, means to concatenate all
+the elements.  This is the most common form of mode line construct.
+
+@item (@var{symbol} @var{then} @var{else})
+A list whose first element is a symbol is a conditional.  Its meaning
+depends on the value of @var{symbol}.  If the value is non-@code{nil},
+the second element of the list (@var{then}) is processed recursively as
+a mode line element.  But if the value of @var{symbol} is @code{nil},
+the third element of the list (if there is one) is processed
+recursively.
+
+@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.  Then the result is space filled (if
+@var{width} is positive) or truncated (to @minus{}@var{width} columns,
+if @var{width} is negative) on the right.
+
+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
+
+  If you do alter @code{mode-line-format} itself, the new value should
+use all the same variables that are used by the default value, rather
+than duplicating their contents or displaying the information in another
+fashion.  This way, customizations made by the user, by libraries (such
+as @code{display-time}) and by major modes via changes to those
+variables remain effective.
+
+@cindex Shell mode @code{mode-line-format}
+  Here is an example of a @code{mode-line-format} that might be
+useful for @code{shell-mode} since it contains the hostname and default
+directory.
+
+@example
+@group
+(setq mode-line-format
+  (list ""
+   'mode-line-modified
+   "%b--" 
+@end group
+   (getenv "HOST")      ; @r{One element is not constant.}
+   ":" 
+   'default-directory
+   "   "
+   'global-mode-string
+   "   %[(" 'mode-name 
+   'minor-mode-alist 
+   "%n" 
+   'mode-line-process  
+   ")%]----"
+@group
+   (line-number-mode "L%l--")
+   '(-3 . "%p")
+   "-%-"))
+@end group
+@end example
+
+@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} were changed to use them.
+
+@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, and @samp{--%%-} if the buffer is read only.
+
+Changing this variable does not force an update of the mode line.
+@end defvar
+
+@defvar mode-line-buffer-identification
+  This variable identifies the buffer being displayed in the window.
+Its default value is @samp{Emacs: %17b}, which means that it displays
+@samp{Emacs:} followed by the buffer name.  You may want to change this
+in modes such as Rmail that do not behave like a ``normal'' Emacs.
+@end defvar
+
+@defvar global-mode-string
+This variable holds a mode line spec that appears in the mode line by
+default, just after the buffer name.  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 this is obsolete, since the variable is
+included directly in the mode line.
+@end defvar
+
+@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 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.
+
+The default value of @code{minor-mode-alist} is:
+
+@example
+@group
+minor-mode-alist
+@result{} ((abbrev-mode " Abbrev") 
+    (overwrite-mode " Ovwrt") 
+    (auto-fill-function " Fill")         
+    (defining-kbd-macro " Def"))
+@end group
+@end example
+
+@noindent
+(In earlier Emacs versions, @code{auto-fill-function} was called
+@code{auto-fill-hook}.)
+
+  @code{minor-mode-alist} is not buffer-local.  The variables mentioned
+in the alist should be buffer-local if the minor mode can be enabled
+separately in each buffer.
+@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 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)}.
+
+  The default value of @code{default-mode-line-format} is:
+
+@example
+@group
+(""
+ mode-line-modified
+ mode-line-buffer-identification
+ "   "
+ global-mode-string
+ "   %[("
+ mode-name 
+@end group
+@group
+ minor-mode-alist 
+ "%n" 
+ mode-line-process
+ ")%]----"
+ (-3 . "%p")
+ "-%-")
+@end group
+@end example
+@end defvar
+
+@node %-Constructs
+@subsection @code{%}-Constructs in the Mode Line
+
+  The following table lists the recognized @code{%}-constructs and what
+they mean.
+
+@table @code
+@item %b
+The current buffer name, obtained with the @code{buffer-name} function.
+@xref{Buffer Names}.
+
+@item %f
+The visited file name, obtained with the @code{buffer-file-name}
+function.  @xref{Buffer File Name}.
+
+@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, and otherwise @samp{-}.
+
+@item %s
+The status of the subprocess belonging to the current buffer, obtained with
+@code{process-status}.  @xref{Process Information}.
+
+@item %p
+The percent of the buffer above the @strong{top} of window, or
+@samp{Top}, @samp{Bottom} or @samp{All}.
+
+@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 %n
+@samp{Narrow} when narrowing is in effect; nothing otherwise (see
+@code{narrow-to-region} in @ref{Narrowing}).
+
+@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 %%
+The character @samp{%}---this is how to include a literal @samp{%} in a
+string in which @code{%}-constructs are allowed.
+
+@item %-
+Dashes sufficient to fill the remainder of the mode line.
+@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}.  Currently, only
+@code{display-time} modifies the value of @code{global-mode-string}.
+@end table
+
+@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 @file{.emacs} file, but Lisp programs can set them also.
+@xref{Standard Hooks}, for a list of standard hook variables.
+
+  Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
+contain lists of functions to be called with no arguments.  The reason
+most hooks are normal hooks is so that you can use them in a uniform
+way.  You can always tell when a hook is a normal hook, because its 
+name ends in @samp{-hook}.
+
+  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.
+
+  As for abnormal hooks, those whose names end in @samp{-function} have
+a value which is a single function.  Those whose names end in
+@samp{-hooks} have a value which is a list of functions.  Any hook which
+is abnormal is abnormal because a normal hook won't do the job; either
+the functions are called with arguments, or their values are meaningful.
+The name shows you that the hook is abnormal and that you should look at
+its documentation string to see how to use it properly.
+
+  Most major modes run hooks as the last step of initialization.  This
+makes it easy for a user to customize the behavior of the mode, by
+overriding the local variable assignments already made by the mode.  But
+hooks are used in other contexts too.  For example, the hook
+@code{suspend-hook} runs just before Emacs suspends itself
+(@pxref{Suspending Emacs}).
+
+  Here's an expression you can put in your @file{.emacs} file to turn on
+Auto Fill mode when in Lisp Interaction mode:
+
+@example
+(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+@end example
+
+  The next example shows how to use a hook to customize the way Emacs
+formats C code.  (People often have strong personal preferences for one
+format or another.)  Here the hook function is an anonymous lambda
+expression.
+
+@cindex lambda expression in hook
+@example
+@group
+(add-hook 'c-mode-hook 
+  (function (lambda ()
+              (setq c-indent-level 4
+                    c-argdecl-indent 0
+                    c-label-offset -4
+@end group
+@group
+                    c-continued-statement-indent 0
+                    c-brace-offset 0
+                    comment-column 40))))
+
+(setq c++-mode-hook c-mode-hook)
+@end group
+@end example
+
+  Finally, here is an example of how to use the Text mode hook to
+provide a customized mode line for buffers in Text mode, displaying the
+default directory in addition to the standard components of the
+mode line.  (This may cause the mode line to run out of space if you
+have very long file names or display the time and load.)
+
+@example
+@group
+(add-hook 'text-mode-hook
+  (function (lambda ()
+              (setq mode-line-format
+                    '(mode-line-modified
+                      "Emacs: %14b"
+                      "  "  
+@end group
+                      default-directory
+                      " "
+                      global-mode-string
+                      "%[(" 
+                      mode-name 
+                      minor-mode-alist 
+@group
+                      "%n" 
+                      mode-line-process  
+                      ") %]---"
+                      (-3 . "%p")
+                      "-%-")))))
+@end group
+@end example
+
+  At the appropriate time, Emacs uses the @code{run-hooks} function to
+run particular hooks.  This function calls the hook functions you have
+added with @code{add-hooks}.
+
+@defun run-hooks &rest hookvar
+This function takes one or more hook variable names as arguments, and
+runs each hook in turn.  Each @var{hookvar} argument should be a symbol
+that is a hook variable.  These arguments are processed in the order
+specified.
+
+If a hook variable has a non-@code{nil} value, that value may be a
+function or a list of functions.  If the value is a function (either a
+lambda expression or a symbol with a function definition), it is
+called.  If it is a list, the elements are called, in order.
+The hook functions are called with no arguments.
+
+For example, here's how @code{emacs-lisp-hooks} runs its mode hook:
+
+@example
+(run-hooks 'emacs-lisp-mode-hook)
+@end example
+@end defun
+
+@defun add-hook hook function &optional append
+This function is the handy way to add function @var{function} to hook
+variable @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}.
+
+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.
+@end defun
+
+@defun remove-hook hook function 
+This function removes @var{function} from the hook variable @var{hook}.
+@end defun