@settitle GNU Emacs Lisp Reference Manual
@c %**end of header
-@dircategory Editors
+@c Version of the manual and of Emacs.
+@c Please remember to update the edition number in README as well.
+@set VERSION 2.9
+@set EMACSVER 22.0.50
+
+@dircategory Emacs
@direntry
* Elisp: (elisp). The Emacs Lisp Reference Manual.
@end direntry
@smallbook
-
-@ifinfo
-This Info file contains edition 2.6 of the GNU Emacs Lisp
-Reference Manual, corresponding to Emacs version 21.1.
-@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
-59 Temple Place, Suite 330
-Boston, MA 02111-1307 USA
-
-Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999
- Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries 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
+@setchapternewpage odd
+@finalout
@c Combine indices.
@synindex cp fn
@c We use the "type index" to index new functions and variables.
@c @syncodeindex tp fn
-@setchapternewpage odd
-@finalout
+@copying
+This is edition @value{VERSION} of the GNU Emacs Lisp
+Reference Manual, corresponding to Emacs version @value{EMACSVER}.
+
+Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
+ 2000, 2002, 2003, 2004, 2005, Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', with the
+Front-Cover texts being ``A GNU Manual'', and with the Back-Cover
+Texts as in (a) below. A copy of the license is included in the
+section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
@titlepage
@title GNU Emacs Lisp Reference Manual
-@subtitle For Emacs Version 21
-@c The edition number appears in several places in this file
-@c and also in the file intro.texi.
-@subtitle Revision 2.6, September 1999
+@subtitle For Emacs Version @value{EMACSVER}
+@subtitle Revision @value{VERSION}, January 2002
@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, 1995, 1996, 1998, 1999
-Free Software Foundation, Inc.
-
-@sp 2
-Edition 2.6 @*
-Revised for Emacs Version 21.1,@*
-September 1999.@*
-@sp 2
-ISBN 1-882114-73-6
+@insertcopying
-@sp 2
+@sp 1
Published by the Free Software Foundation @*
-59 Temple Place, Suite 330@*
-Boston, MA 02111-1307 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.
+51 Franklin St, Fifth Floor @*
+Boston, MA 02110-1301 @*
+USA @*
+ISBN 1-882114-73-6
+@sp 1
Cover art by Etienne Suvasa.
@end titlepage
-@page
-@node Top, Copying, (dir), (dir)
-@ifinfo
-This Info file contains edition 2.6 of the GNU Emacs Lisp
-Reference Manual, corresponding to GNU Emacs version 21.1.
-@end ifinfo
+@c Print the tables of contents
+@summarycontents
+@contents
+
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Emacs Lisp
+
+This Info file contains edition @value{VERSION} of the GNU Emacs Lisp
+Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
+@end ifnottex
@menu
-* Copying:: Conditions for copying and changing GNU Emacs.
* Introduction:: Introduction and conventions used.
-* Standards: Coding Conventions. Coding conventions for Emacs Lisp.
* Lisp Data Types:: Data types of objects in Emacs Lisp.
* Numbers:: Numbers and arithmetic functions.
* Abbrevs:: How Abbrev mode works, and its data structures.
* Processes:: Running and communicating with subprocesses.
+* Display:: Features for controlling the screen display.
* System Interface:: Getting the user id, system type, environment
variables, and other such things.
-* Display:: Features for controlling the screen display.
-* Calendar:: Customizing the calendar and diary.
Appendices
+* Antinews:: Info for users downgrading to Emacs 21.
+* GNU Free Documentation License:: The license for this documentation
+* GPL:: Conditions for copying and changing GNU Emacs.
* Tips:: Advice and coding conventions for Emacs Lisp.
* GNU Emacs Internals:: Building and dumping Emacs;
internal data structures.
* Index:: Index including concepts, functions, variables,
and other terms.
-* New Symbols:: New functions and variables in Emacs 21.
+* New Symbols:: New functions and variables in Emacs @value{EMACSVER}.
- --- The Detailed Node Listing ---
+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:
* Caveats:: Flaws and a request for help.
* Lisp History:: Emacs Lisp is descended from Maclisp.
* Conventions:: How the manual is formatted.
+* Version Info:: Which Emacs version is running?
* Acknowledgements:: The authors, editors, and sponsors of this manual.
Conventions
* Buffer Text Notation:: The format we use for buffer contents in examples.
* Format of Descriptions:: Notation for describing functions, variables, etc.
-Tips and Conventions
-
-* Coding Conventions:: Conventions for clean and robust programs.
-* Compilation Tips:: Making compiled code run fast.
-* Documentation Tips:: Writing readable documentation strings.
-* Comment Tips:: Conventions for writing comments.
-* Library Headers:: Standard headers for library packages.
-
Format of Descriptions
-* A Sample Function Description::
-* A Sample Variable Description::
+* A Sample Function Description::
+* A Sample Variable Description::
Lisp Data Types
* Comments:: Comments and their formatting conventions.
* Programming Types:: Types found in all Lisp systems.
* Editing Types:: Types specific to Emacs.
+* Circular Objects:: Read syntax for circular structure.
* Type Predicates:: Tests related to types.
* Equality Predicates:: Tests of equality between any two objects.
* Floating Point Type:: Numbers with fractional parts and with a large range.
* Character Type:: The representation of letters, numbers and
control characters.
+* Symbol Type:: A multi-use object that refers to a function,
+ variable, property list, or itself.
* Sequence Type:: Both lists and arrays are classified as sequences.
* Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
* Array Type:: Arrays include strings and vectors.
* String Type:: An (efficient) array of characters.
* Vector Type:: One-dimensional arrays.
-* Symbol Type:: A multi-use object that refers to a function,
- variable, property list, or itself.
+* Char-Table Type:: One-dimensional sparse arrays indexed by characters.
+* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
+* Hash Table Type:: Super-fast lookup tables.
* Function Type:: A piece of executable code you can call from elsewhere.
* Macro Type:: A method of expanding an expression into another
expression, more fundamental but less pretty.
* Autoload Type:: A type used for automatically loading seldom-used
functions.
-List Type
+Cons Cell and List Types
+* Box Diagrams:: Drawing pictures of lists.
* Dotted Pair Notation:: An alternative syntax for lists.
* Association List Type:: A specially constructed list.
Editing Types
* Buffer Type:: The basic object of editing.
+* Marker Type:: A position in a buffer.
* Window Type:: What makes buffers visible.
+* Frame Type:: Windows subdivide frames.
* Window Configuration Type::Save what the screen looks like.
-* Marker Type:: A position in a buffer.
+* Frame Configuration Type::Recording the status of all frames.
* Process Type:: A process running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
* Float Basics:: Representation and range of floating point.
* Predicates on Numbers:: Testing for numbers.
* Comparison of Numbers:: Equality and inequality predicates.
+* Numeric Conversions:: Converting float to integer and vice versa.
* Arithmetic Operations:: How to add, subtract, multiply and divide.
+* Rounding Operations:: Explicitly rounding floating point numbers.
* Bitwise Operations:: Logical and, or, not, shifting.
-* Numeric Conversions:: Converting float to integer and vice versa.
* Math Functions:: Trig, exponential and logarithmic functions.
* Random Numbers:: Obtaining random integers, predictable or not.
* String Basics:: Basic properties of strings and characters.
* Predicates for Strings:: Testing whether an object is a string or char.
* Creating Strings:: Functions to allocate new strings.
+* Modifying Strings:: Altering the contents of an existing string.
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting characters or strings and vice versa.
* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}.
* Case Conversion:: Case conversion functions.
+* Case Tables:: Customizing case conversion.
Lists
* Cons Cells:: How lists are made out of cons cells.
-* 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.
+* Rings:: Managing a fixed-size ring of objects.
Modifying Existing List Structure
* Arrays:: Characteristics of arrays in Emacs Lisp.
* Array Functions:: Functions specifically for arrays.
* Vectors:: Functions specifically for vectors.
+* Vector Functions:: Functions specifically for vectors.
+* Char-Tables:: How to work with char-tables.
+* Bool-Vectors:: How to work with bool-vectors.
+
+Hash Tables
+
+* Creating Hash:: Functions to create hash tables.
+* Hash Access:: Reading and writing the hash table contents.
+* Defining Hash:: Defining new comparison methods
+* Other Hash:: Miscellaneous.
Symbols
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
+* Quoting:: Avoiding evaluation (to put constants in
the program).
+* Eval:: How to invoke the Lisp interpreter explicitly.
Kinds of Forms
* Self-Evaluating Forms:: Forms that evaluate to themselves.
* Symbol Forms:: Symbols evaluate as variables.
* Classifying Lists:: How to distinguish various sorts of list forms.
+* Function Indirection:: When a symbol appears as the car of a list,
+ we find the real function via the symbol.
* Function Forms:: Forms that call functions.
* Macro Forms:: Forms that call macros.
* Special Forms:: ``Special forms'' are idiosyncratic primitives,
Control Structures
* Sequencing:: Evaluation in textual order.
-* Conditionals:: @code{if}, @code{cond}.
+* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}.
* Combining Conditions:: @code{and}, @code{or}, @code{not}.
* Iteration:: @code{while} loops.
* Nonlocal Exits:: Jumping out of a sequence.
* Local Variables:: Variable values that exist only temporarily.
* Void Variables:: Symbols that lack values.
* Defining Variables:: A definition says a symbol is used as a variable.
+* Tips for Defining:: Things you should think about when you
+ define a variable.
* Accessing Variables:: Examining values of variables whose names
are known only at run time.
* Setting Variables:: Storing new values in variables.
* Variable Scoping:: How Lisp chooses among local and global values.
* Buffer-Local Variables:: Variable values in effect only in one buffer.
+* Frame-Local Variables:: Variable values in effect only in one frame.
+* Future Local Variables:: New kinds of local values we might add some day.
+* File Local Variables:: Handling local variable lists in files.
+* Variable Aliases:: Variables that are aliases for other variables.
+* Variables with Restricted Values:: Non-constant variables whose value can
+ @emph{not} be an arbitrary Lisp object.
Scoping Rules for Variable Bindings
-* Scope:: Scope means where in the program a value
+* 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
+* Using Scoping:: How to use dynamic scoping carefully and
avoid problems.
Buffer-Local Variables
* 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.
+* Anonymous Functions:: Lambda-expressions are functions with no names.
* Function Cells:: Accessing or setting the function definition
of a symbol.
+* Obsolete Functions:: Declaring functions obsolete.
+* Inline Functions:: Defining functions that the compiler will open code.
+* Function Safety:: Determining whether a function is safe to call.
* Related Topics:: Cross-references to specific Lisp primitives
- that have a special bearing on how
+ that have a special bearing on how
functions work.
Lambda Expressions
* Backquote:: Easier construction of list structure.
* Problems with Macros:: Don't evaluate the macro arguments too many times.
Don't hide the user's variables.
+* Indenting Macros:: Specifying how to indent macro calls.
+
+Writing Customization Definitions
+
+* Common Keywords:: Common keyword arguments for all kinds of
+ customization declarations.
+* Group Definitions:: Writing customization group definitions.
+* Variable Definitions:: Declaring user options.
+* Customization Types:: Specifying the type of a user option.
Loading
* How Programs Do Loading:: The @code{load} function and others.
+* Library Search:: Finding a library to load.
+* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
* Autoload:: Setting up a function to autoload.
-* Named Features:: Loading a library if it isn't already loaded.
* Repeated Loading:: Precautions about loading a file twice.
+* Named Features:: Loading a library if it isn't already loaded.
+* Where Defined:: Finding which file defined a certain symbol.
+* Unloading:: How to ``unload'' a library that was loaded.
+* Hooks for Loading:: Providing code to be run when
+ particular libraries are loaded.
Byte Compilation
+* Speed of Byte-Code:: An example of speedup from byte compilation.
* Compilation Functions:: Byte compilation functions.
+* Docs and Compilation:: Dynamic loading of documentation strings.
+* Dynamic Loading:: Dynamic loading of individual functions.
+* Eval During Compile:: Code to be evaluated when you compile.
+* Compiler Errors:: Handling compiler error messages.
+* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
-Advising Functions
+Advising Emacs Lisp Functions
* Simple Advice:: A simple example to explain the basics of advice.
* Defining Advice:: Detailed description of @code{defadvice}.
+* Around-Advice:: Wrapping advice around a function's definition.
* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
* Activation of Advice:: Advice doesn't do anything until you activate it.
* Enabling Advice:: You can enable or disable each piece of advice.
* Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments.
-* Subr Arguments:: Accessing arguments when advising a primitive.
+* Advising Primitives:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented.
Debugging Lisp Programs
* Debugger:: How the Emacs Lisp debugger is implemented.
+* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
-* Compilation Errors:: How to find errors that show up in
+* Test Coverage:: Ensuring you have tested all branches in your code.
+* 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.
+* Infinite Loops:: Stopping and debugging a program that doesn't exit.
* Function Debugging:: Entering it when a certain function is called.
* Explicit Debug:: Entering it at a certain point in the program.
* Using Debugger:: What the debugger does; what you see while in it.
* Invoking the Debugger:: How to call the function @code{debug}.
* Internals of Debugger:: Subroutines of the debugger, and global variables.
+Edebug
+
+* Using Edebug:: Introduction to use of Edebug.
+* Instrumenting:: You must instrument your code
+ in order to debug it with Edebug.
+* Edebug Execution Modes:: Execution modes, stopping more or less often.
+* Jumping:: Commands to jump to a specified place.
+* Edebug Misc:: Miscellaneous commands.
+* Breaks:: Setting breakpoints to make the program stop.
+* Trapping Errors:: Trapping errors with Edebug.
+* Edebug Views:: Views inside and outside of Edebug.
+* Edebug Eval:: Evaluating expressions within Edebug.
+* Eval List:: Expressions whose values are displayed
+ each time you enter Edebug.
+* Printing in Edebug:: Customization of printing.
+* Trace Buffer:: How to produce trace output in a buffer.
+* Coverage Testing:: How to test evaluation coverage.
+* The Outside Context:: Data that Edebug saves and restores.
+* Edebug and Macros:: Specifying how to handle macro calls.
+* Edebug Options:: Option variables for customizing Edebug.
+
Debugging Invalid Lisp Syntax
* Excess Open:: How to find a spurious open paren or missing close.
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:: 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:: Various data types that can be used as
output streams.
* Output Functions:: Functions to print Lisp objects as text.
+* Output Variables:: Variables that control what the printing
+ functions do.
Minibuffers
* Intro to Minibuffers:: Basic information about minibuffers.
* Text from Minibuffer:: How to read a straight text string.
* Object from Minibuffer:: How to read a Lisp object or expression.
+* Minibuffer History:: Recording previous minibuffer inputs
+ so the user can reuse them.
+* Initial Input:: Specifying initial contents for the minibuffer.
* Completion:: How to invoke and customize completion.
* Yes-or-No Queries:: Asking a question with a simple answer.
+* Multiple Queries:: Asking a series of similar questions.
+* Reading a Password:: Reading a password from the terminal.
+* Minibuffer Commands:: Commands used as key bindings in minibuffers.
+* Minibuffer Contents:: How such commands access the minibuffer text.
+* Minibuffer Windows:: Operating on the special minibuffer windows.
+* Recursive Mini:: Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc:: Various customization hooks and variables.
Completion
* Defining Commands:: Specifying how a function should read arguments.
* Interactive Call:: Calling a command, so that it will read arguments.
* Command Loop Info:: Variables set by the command loop for you to examine.
+* Adjusting Point:: Adjustment of point after a command.
* Input Events:: What input looks like when you read it.
* Reading Input:: How to read input events from the keyboard or mouse.
+* Special Events:: Events processed immediately and individually.
* Waiting:: Waiting for user input or elapsed time.
* Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
* Prefix Command Arguments:: How the commands to set prefix args work.
* 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.
+* Remapping Commands:: Bindings that translate one command to another.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
+* Menu Keymaps:: A keymap can define a menu for X
+ or for use from the terminal.
Major and Minor Modes
+* Hooks:: How to use hooks; how to write code that
+ provides hooks.
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
-* Hooks:: How to use hooks; how to write code that
- provides hooks.
+* Imenu:: How a mode can provide a menu
+ of definitions in the buffer.
+* Font Lock Mode:: How modes can highlight text according to syntax.
+* Desktop Save Mode:: How modes can have buffer state saved between
+ Emacs sessions.
Major Modes
+* Major Mode Basics::
* Major Mode Conventions:: Coding conventions for keymaps, etc.
* Example Major Modes:: Text mode and Lisp modes.
* Auto Major Mode:: How Emacs chooses the major mode automatically.
* Mode Help:: Finding out how to use a mode.
+* Derived Modes:: Defining a new major mode based on another major
+ mode.
+* Generic Modes:: Defining a simple major mode that supports
+ comment syntax and Font Lock mode.
+* Mode Hooks:: Hooks run at the end of major mode functions.
Minor Modes
* Minor Mode Conventions:: Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+* Defining Minor Modes:: A convenient facility for defining minor modes.
Mode Line Format
+* Mode Line Basics::
* Mode Line Data:: The data structure that controls the mode line.
* Mode Line Variables:: Variables used in that data structure.
* %-Constructs:: Putting information into a mode line.
+* Properties in Mode:: Using text properties in the mode line.
+* Header Lines:: Like a mode line, but at the top.
+* Emulating Mode Line:: Formatting text as the mode line would.
Documentation
* 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.
+ simultaneous editing by two people.
+* Information about Files:: Testing existence, accessibility, size of files.
* Changing Files:: Renaming files, changing protection, etc.
* File Names:: Decomposing and expanding file names.
+* Contents of Directories:: Getting a list of the files in a directory.
+* Create/Delete Dirs:: Creating and Deleting Directories.
+* Magic File Names:: Defining "magic" special handling
+ for certain file names.
+* Format Conversion:: Conversion to and from various file formats.
Visiting Files
Information about Files
* Testing Accessibility:: Is a given file readable? Writable?
-* Kinds of Files:: Is it a directory? A link?
+* Kinds of Files:: Is it a directory? A symbolic link?
+* Truenames:: Eliminating symbolic links from a file name.
* File Attributes:: How large is it? Any other names? Etc.
File Names
* File Name Components:: The directory part of a file name, and the rest.
+* Relative File Names:: Some file names are relative to a
+ current directory.
* Directory Names:: A directory's name as a directory
is different from its name as a file.
-* 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.
+* Standard File Names:: If your package uses a fixed file name,
+ how to handle various operating systems simply.
Backups and Auto-Saving
-* Backup Files:: How backup files are made; how their names
+* 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
+* 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
+* Rename or Copy:: Two alternatives: renaming the old file
or copying it.
* Numbered Backups:: Keeping multiple backups for each source file.
* Backup Names:: How backup file names are computed; customization.
Buffers
* Buffer Basics:: What is a buffer?
+* Current Buffer:: Designating a buffer as current
+ so primitives will access its contents.
* Buffer Names:: Accessing and changing buffer names.
* Buffer File Name:: The buffer file name indicates which file
is visited.
* 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.
+* Indirect Buffers:: An indirect buffer shares text with some
+ other buffer.
+* Buffer Gap:: The gap in the buffer.
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.
+* Choosing Window:: How to choose a window for displaying a buffer.
* Window Point:: Each window has its own location of point.
* Window Start:: The display-start position controls which text
- is on-screen in the window.
-* Vertical Scrolling:: Moving text up and down in the window.
-* Horizontal Scrolling:: Moving text sideways on the window.
+ is on-screen in the window.
+* Textual Scrolling:: Moving text up and down through the window.
+* Vertical Scrolling:: Moving the contents up and down on the window.
+* Horizontal Scrolling:: Moving the contents sideways on the window.
* Size of Window:: Accessing the size of a window.
* Resizing Windows:: Changing the size of a window.
+* Coordinates and Windows:: Converting coordinates to windows.
* Window Configurations:: Saving and restoring the state of the screen.
+* Window Hooks:: Hooks for scrolling, window size changes,
+ redisplay going past a certain point,
+ or window configuration changes.
Frames
* Pointer Shapes:: Specifying the shape of the mouse pointer.
* Window System Selections::Transferring text to and from other windows.
* Color Names:: Getting the definitions of color names.
+* Text Terminal Colors:: Defining colors for text-only terminals.
* Resources:: Getting resource values from the server.
-* Server Data:: Getting info about the X server.
+* Display Feature Testing:: Determining the features of a terminal.
Positions
* 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.
+* Information from Markers::Finding the marker's buffer or character
+ position.
+* Marker Insertion Types:: Two ways a marker can relocate when you
+ insert where it points.
* Moving Markers:: Moving the marker to a new buffer or position.
* The Mark:: How ``the mark'' is implemented with a marker.
* The Region:: How to access ``the region''.
* Near Point:: Examining text in the vicinity of point.
* Buffer Contents:: Examining text in a general fashion.
+* Comparing Text:: Comparing substrings of buffers.
* Insertion:: Adding new text to a buffer.
* Commands for Insertion:: User-level commands to insert text.
* Deletion:: Removing text from a buffer.
* 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.
+* Maintaining Undo:: How to enable and disable undo information.
+ How to control how much information is kept.
* Filling:: Functions for explicit filling.
* Margins:: How to specify margins for filling commands.
+* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix
+ from context.
+* Auto Filling:: How auto-fill mode is implemented to break lines.
* Sorting:: Functions for sorting parts of the buffer.
-* Indentation:: Functions to insert or adjust indentation.
* Columns:: Computing horizontal positions, and using them.
+* Indentation:: Functions to insert or adjust indentation.
* Case Changes:: Case conversion of parts of the buffer.
* Text Properties:: Assigning Lisp property lists to text characters.
* Substitution:: Replacing a given character wherever it appears.
* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing
the text or position stored in a register.
+* Base 64:: Conversion to or from base 64 encoding.
+* MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''.
+* Atomic Changes:: Installing several buffer changes ``atomically''.
* Change Hooks:: Supplying functions to be run when text is changed.
-
+
The Kill Ring
* Kill Ring Concepts:: What text looks like in the kill ring.
* Kill Functions:: Functions that kill text.
+* Yanking:: How yanking is done.
* Yank Commands:: Commands that access the kill ring.
* Low-Level Kill Ring:: Functions and variables for kill ring access.
* Internals of Kill Ring:: Variables that hold kill-ring data.
them back.
* Lazy Properties:: Computing text properties in a lazy fashion
only when text is examined.
+* Clickable Text:: Using text properties to make regions of text
+ do something when you click on them.
+* Links and Mouse-1:: How to make @key{Mouse-1} follow a link.
+* Fields:: The @code{field} property defines
+ fields within the buffer.
* Not Intervals:: Why text properties do not use
Lisp-visible text intervals.
+Non-ASCII Characters
+
+* Text Representations:: Unibyte and multibyte representations
+* Converting Representations:: Converting unibyte to multibyte and vice versa.
+* Selecting a Representation:: Treating a byte sequence as unibyte or multi.
+* Character Codes:: How unibyte and multibyte relate to
+ codes of individual characters.
+* Character Sets:: The space of possible characters codes
+ is divided into various character sets.
+* Chars and Bytes:: More information about multibyte encodings.
+* Splitting Characters:: Converting a character to its byte sequence.
+* Scanning Charsets:: Which character sets are used in a buffer?
+* Translation of Characters:: Translation tables are used for conversion.
+* Coding Systems:: Coding systems are conversions for saving files.
+* Input Methods:: Input methods allow users to enter various
+ non-ASCII characters without special keyboards.
+* Locales:: Interacting with the POSIX locale.
+
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.
+* POSIX Regexps:: Searching POSIX-style for the longest match.
+* Search and Replace:: Internals of @code{query-replace}.
* 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.
+* Standard Regexps:: Useful regexps for finding sentences, pages,...
Regular Expressions
* Syntax of Regexps:: Rules for writing regular expressions.
* Regexp Example:: Illustrates regular expression syntax.
+* Regexp Functions:: Functions for operating on regular expressions.
Syntax Tables
+* Syntax Basics:: Basic concepts of syntax tables.
* Syntax Descriptors:: How characters are classified.
* Syntax Table Functions:: How to create, examine and alter syntax tables.
+* Syntax Properties:: Overriding syntax with text properties.
+* Motion and Syntax:: Moving over characters with certain syntaxes.
* Parsing Expressions:: Parsing balanced expressions
using the syntax table.
* Standard Syntax Tables:: Syntax tables used by various major modes.
* Syntax Table Internals:: How syntax table information is stored.
+* Categories:: Another way of classifying character syntax.
Syntax Descriptors
Abbrevs And Abbrev Expansion
* Abbrev Mode:: Setting up Emacs for abbreviation.
-* Tables: Abbrev Tables. Creating and working with abbrev 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.
+* Abbrev Files:: Saving abbrevs in files.
+* Abbrev Expansion:: Controlling expansion; expansion subroutines.
* Standard Abbrev Tables:: Abbrev tables used by various major modes.
Processes
* Subprocess Creation:: Functions that start subprocesses.
+* Shell Arguments:: Quoting an argument to pass it to a shell.
* Synchronous Processes:: Details of using synchronous subprocesses.
* Asynchronous Processes:: Starting up an asynchronous subprocess.
* Deleting Processes:: Eliminating an asynchronous subprocess.
an asynchronous subprocess.
* Output from Processes:: Collecting output from an asynchronous subprocess.
* Sentinels:: Sentinels run when process run-status changes.
+* Query Before Exit:: Whether to query if exiting will kill a process.
+* Transaction Queues:: Transaction-based communication with subprocesses.
* Network:: Opening network connections.
+* Network Servers:: Network servers let Emacs accept net connections.
+* Datagrams:: UDP network connections.
+* Low-Level Network:: Lower-level but more general function
+ to create connections and servers.
+* Byte Packing:: Using bindat to pack and unpack binary data.
Receiving Output from Processes
* Process Buffers:: If no filter, output is put in a buffer.
* Filter Functions:: Filter functions accept output from the process.
+* Decoding Output:: Filters can get unibyte or multibyte strings.
* Accepting Output:: How to wait until process output arrives.
+Emacs Display
+
+* Refresh Screen:: Clearing the screen and redrawing everything on it.
+* Forcing Redisplay:: Forcing redisplay.
+* Truncation:: Folding or wrapping long text lines.
+* The Echo Area:: Displaying messages at the bottom of the screen.
+* Warnings:: Displaying warning messages for the user.
+* Invisible Text:: Hiding part of the buffer text.
+* Selective Display:: Hiding part of the buffer text (the old way).
+* Temporary Displays:: Displays that go away automatically.
+* Overlays:: Use overlays to highlight parts of the buffer.
+* Width:: How wide a character or string is on the screen.
+* Line Height:: Controlling the height of lines.
+* Faces:: A face defines a graphics style
+ for text characters: font, colors, etc.
+* Fringes:: Controlling window fringes.
+* Scroll Bars:: Controlling vertical scroll bars.
+* Pointer Shape:: Controlling the mouse pointer shape.
+* Display Property:: Enabling special display features.
+* Images:: Displaying images in Emacs buffers.
+* Buttons:: Adding clickable buttons to Emacs buffers.
+* Blinking:: How Emacs shows the matching open parenthesis.
+* Inverse Video:: Specifying how the screen looks.
+* Usual Display:: The usual conventions for displaying nonprinting chars.
+* Display Tables:: How to specify other conventions.
+* Beeping:: Audible signal to the user.
+* Window Systems:: Which window system is being used.
+
Operating System Interface
* Starting Up:: Customizing Emacs start-up processing.
* Getting Out:: How exiting works (permanent or temporary).
* System Environment:: Distinguish the name and kind of system.
+* User Identification:: Finding the name and user id of the user.
+* Time of Day:: Getting the current time.
+* Time Conversion:: Converting a time from numeric form to a string, or
+ to calendrical data (or vice versa).
+* Processor Run Time:: Getting the run time used by Emacs.
+* Time Calculations:: Adding, subtracting, comparing times, etc.
+* Timers:: Setting a timer to call a function at a certain time.
* 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.
+* Sound Output:: Playing sounds on the computer's speaker.
+* X11 Keysyms:: Operating on key symbols for X Windows
* Batch Mode:: Running Emacs without terminal interaction.
+* Session Management:: Saving and restoring state with X Session Management.
Starting Up Emacs
* Killing Emacs:: Exiting Emacs irreversibly.
* Suspending Emacs:: Exiting Emacs reversibly.
-Emacs Display
+Tips and Conventions
-* 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.
+* Coding Conventions:: Conventions for clean and robust programs.
+* Compilation Tips:: Making compiled code run fast.
+* Documentation Tips:: Writing readable documentation strings.
+* Comment Tips:: Conventions for writing comments.
+* Library Headers:: Standard headers for library packages.
GNU Emacs Internals
* Building Emacs:: How 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.
+* Memory Usage:: Info about total size of Lisp objects made so far.
* Writing Emacs Primitives:: Writing C code for Emacs.
+* Object Internals:: Data formats of buffers, windows, processes.
Object Internals
@include abbrevs.texi
@include processes.texi
-@include os.texi
@include display.texi
-@include calendar.texi
+@include os.texi
@c MOVE to Emacs Manual: include misc-modes.texi
@c REMOVE this: include non-hacker.texi
@include anti.texi
+@include doclicense.texi
+@include gpl.texi
@include tips.texi
@include internals.texi
@include errors.texi
@printindex tp
-@c Print the tables of contents
-@summarycontents
-@contents
-@c That's all
-
@bye
\f
These words prevent "local variables" above from confusing Emacs.
+
+@ignore
+ arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34
+@end ignore