\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename elisp
+
+@ifset VOL1
+@set volflag
+@set voltitle Volume 1
+@end ifset
+
+@ifset VOL2
+@set volflag
+@set voltitle Volume 2
+@end ifset
+
+@ifset volflag
+@settitle GNU Emacs Lisp Reference Manual: @value{voltitle}
+@end ifset
+@ifclear volflag
@settitle GNU Emacs Lisp Reference Manual
+@end ifclear
+
@c %**end of header
+@c See two-volume-cross-refs.txt.
+@tex
+@ifset VOL1
+\message{Formatting for two volume edition...Volume 1...}
+%
+% Read special toc file, set up in two-volume.make.
+\gdef\tocreadfilename{elisp1-toc-ready.toc}
+%
+% Don't make outlines, they're not needed and \readdatafile can't pay
+% attention to the special definition above.
+\global\let\pdfmakeoutlines=\relax
+%
+% Start volume 1 chapter numbering at 1; this must be listed as chapno0.
+\global\chapno=0
+@end ifset
+@ifset VOL2
+\message{Formatting for two volume edition...Volume 2...}
+%
+% Read special toc file, set up in two-volume.make.
+\gdef\tocreadfilename{elisp2-toc-ready.toc}
+%
+% Don't make outlines, they're not needed and \readdatafile can't pay
+% attention to the special definition above.
+\global\let\pdfmakeoutlines=\relax
+%
+% Start volume 2 chapter numbering at 27; this must be listed as chapno26
+\global\chapno=26
+@end ifset
+@end tex
+
+
@c Version of the manual and of Emacs.
-@c Please remember to update the edition number in README as well.
-@c And also the copies in vol1.texi and vol2.texi.
-@set VERSION 3.0
+@c (See comments for EDITION in emacs.texi)
+@set VERSION 3.1
@include emacsver.texi
-@set DATE July 2009
+@set DATE January 2013
@c in general, keep the following line commented out, unless doing a
@c copy of this manual that will be published. The manual should go
@c onto the distribution in the full, 8.5 x 11" size.
-@c @smallbook
+@c @set smallbook
+
+@ifset volflag
+@smallbook
+@end ifset
@ifset smallbook
@smallbook
@tex
@ifset smallbook
@fonttextsize 10
-\global\let\urlcolor=\Black % don't print links in grayscale
-\global\let\linkcolor=\Black
@end ifset
\global\hbadness=6666 % don't worry about not-too-underfull boxes
@end tex
@c @syncodeindex tp fn
@copying
-This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@*
+@iftex
+This is edition @value{VERSION} of the @cite{GNU Emacs Lisp Reference Manual},@*
+@end iftex
+@ifnottex
+This is the @cite{GNU Emacs Lisp Reference Manual}
+@end ifnottex
corresponding to Emacs version @value{EMACSVER}.
-Copyright @copyright{} 1990-1996, 1998-2012 Free Software
-Foundation, Inc.
+Copyright @copyright{} 1990--1996, 1998--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end quotation
@end copying
-@documentencoding ISO-8859-1
+@documentencoding UTF-8
-@dircategory GNU Emacs Lisp
+@dircategory Emacs lisp
@direntry
-* Elisp: (elisp). The Emacs Lisp Reference Manual.
+* Elisp: (elisp). The Emacs Lisp Reference Manual.
@end direntry
@titlepage
@title GNU Emacs Lisp Reference Manual
+@ifset volflag
+@subtitle @value{voltitle}
+@end ifset
@subtitle For Emacs Version @value{EMACSVER}
@subtitle Revision @value{VERSION}, @value{DATE}
-@author by Bil Lewis, Dan LaLiberte, Richard Stallman
-@author and the GNU Manual Group
+@author by Bil Lewis, Dan LaLiberte, Richard Stallman,
+@author the GNU Manual Group, et al.
@page
@vskip 0pt plus 1filll
@insertcopying
@ifnottex
-@node Top, Introduction, (dir), (dir)
+@node Top
@top Emacs Lisp
+@ifset WWW_GNU_ORG
+@html
+<p>The homepage for GNU Emacs is at
+<a href="/software/emacs/">http://www.gnu.org/software/emacs/</a>.<br>
+For information on using Emacs, refer to the
+<a href="/software/emacs/manual/emacs.html">Emacs Manual</a>.<br>
+To view this manual in other formats, click
+<a href="/software/emacs/manual/elisp.html">here</a>.
+@end html
+@end ifset
+
@insertcopying
@end ifnottex
-@c Copy any updates to vol1.texi and vol2.texi.
@menu
* Introduction:: Introduction and conventions used.
* Functions:: A function is a Lisp program
that can be invoked from other functions.
* Macros:: Macros are a way to extend the Lisp language.
-* Customization:: Writing customization declarations.
+* Customization:: Making variables and faces customizable.
* Loading:: Reading files of Lisp code into Lisp.
* Byte Compilation:: Compilation makes programs run faster.
-* Advising Functions:: Adding to the definition of a function.
* Debugging:: Tools and tips for debugging Lisp programs.
* Read and Print:: Converting Lisp objects to text and back.
Appendices
-* Antinews:: Info for users downgrading to Emacs 22.
+* Antinews:: Info for users downgrading to Emacs 23.
* GNU Free Documentation License:: The license for this documentation.
* GPL:: Conditions for copying and changing GNU Emacs.
* Tips:: Advice and coding conventions for Emacs Lisp.
* GNU Emacs Internals:: Building and dumping Emacs;
internal data structures.
-* Standard Errors:: List of main error symbols.
-* Standard Buffer-Local Variables::
- List of variables buffer-local in all buffers.
-* Standard Keymaps:: List of standard keymaps.
-* Standard Hooks:: List of standard hook variables.
+* Standard Errors:: List of some standard error symbols.
+* Standard Keymaps:: List of some standard keymaps.
+* Standard Hooks:: List of some standard hook variables.
* Index:: Index including concepts, functions, variables,
and other terms.
@c be correctly identified by `texinfo-multiple-files-update'. In
@c particular, the detailed menu header line MUST be identical to the
@c value of `texinfo-master-menu-header'. See texnfo-upd.el.
-@c Copy any updates to vol1.texi and vol2.texi.
@detailmenu
--- The Detailed Node Listing ---
* 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.
+* Acknowledgments:: The authors, editors, and sponsors of this manual.
Conventions
Programming Types
* Integer Type:: Numbers without fractional parts.
-* Floating Point Type:: Numbers with fractional parts and with a large range.
+* 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,
* 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.
+* Rounding Operations:: Explicitly rounding floating-point numbers.
* Bitwise Operations:: Logical and, or, not, shifting.
* Math Functions:: Trig, exponential and logarithmic functions.
* Random Numbers:: Obtaining random integers, predictable or not.
* 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.
+* Property Lists:: A list of paired elements.
Modifying Existing List Structure
This can be used to remove or add elements.
* Rearrangement:: Reordering the elements in a list; combining lists.
+Property Lists
+
+* Plists and Alists:: Comparison of the advantages of property
+ lists and association lists.
+* Plist Access:: Accessing property lists stored elsewhere.
+
Sequences, Arrays, and Vectors
* Sequence Functions:: Functions that accept any kind of sequence.
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
+* Symbol Properties:: Each symbol has a property list
for recording miscellaneous information.
-Property Lists
+Symbol Properties
-* Plists and Alists:: Comparison of the advantages of property
- lists and association lists.
-* Symbol Plists:: Functions to access symbols' property lists.
-* Other Plists:: Accessing property lists stored elsewhere.
+* Symbol Plists:: Accessing symbol properties.
+* Standard Properties:: Standard meanings of symbol properties.
Evaluation
* 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.
+* Generalized Variables:: Extending the concept of variables.
Scoping Rules for Variable Bindings
* Default Value:: The default value is seen in buffers
that don't have their own buffer-local values.
+Generalized Variables
+
+* Setting Generalized Variables:: The @code{setf} macro.
+* Adding Generalized Variables:: Defining new @code{setf} forms.
+
Functions
* What Is a Function:: Lisp functions vs. primitives; terminology.
* Closures:: Functions that enclose a lexical environment.
* Obsolete Functions:: Declaring functions obsolete.
* Inline Functions:: Defining functions that the compiler
- will open code.
+ will expand inline.
+* Declare Form:: Adding additional information about a function.
* Declaring Functions:: Telling the compiler that a function is defined.
* Function Safety:: Determining whether a function is safe to call.
* Related Topics:: Cross-references to specific Lisp primitives
* Eval During Expansion:: Don't evaluate them; put them in the expansion.
* Repeated Expansion:: Avoid depending on how many times expansion is done.
-Writing Customization Definitions
+Customization Settings
* 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.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes:: Writing Custom themes.
Customization Types
* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
-Advising Emacs Lisp Functions
-
-* Simple Advice:: A simple example to explain the basics of advice.
-* Defining Advice:: Detailed description of @code{defadvice}.
-* Around-Advice:: Wrapping advice around a function's definition.
-* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
-* Activation of Advice:: Advice doesn't do anything until you activate it.
-* Enabling Advice:: You can enable or disable each piece of advice.
-* Preactivation:: Preactivation is a way of speeding up the
- loading of compiled advice.
-* Argument Access in Advice:: How advice can access the function's arguments.
-* Combined Definition:: How advice is implemented.
-
Debugging Lisp Programs
* Debugger:: A debugger for the Emacs Lisp evaluator.
* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Test Coverage:: Ensuring you have tested all branches in your code.
+* Profiling:: Measuring the resources that your code uses.
The Lisp Debugger
* 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.
+* Minibuffer Contents:: How such commands access the minibuffer text.
* Recursive Mini:: Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc:: Various customization hooks and variables.
* 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 buffer names, variable names, etc.).
* Reading File Names:: Using completion to read file names and
shell commands.
-* Completion Styles:: Specifying rules for performing completion.
-* Programmed Completion:: Writing your own completion-function.
+* Completion Variables:: Variables controlling completion behavior.
+* Programmed Completion:: Writing your own completion function.
* Completion in Buffers:: Completing text in ordinary buffers.
Command Loop
* Interactive Codes:: The standard letter-codes for reading arguments
in various ways.
* Interactive Examples:: Examples of how to read interactive arguments.
+* Generic Commands:: Select among command alternatives.
+
Input Events
* Menu Bar:: How to customize the menu bar.
* Tool Bar:: A tool bar is a row of images.
* Modifying Menus:: How to add new items to a menu.
+* Easy Menu:: A convenience macro for defining menus.
Defining Menus
-* Simple Menu Items:: A simple kind of menu key binding,
- limited in capabilities.
-* Extended Menu Items:: More powerful menu item definitions
- let you specify keywords to enable
- various features.
+* Simple Menu Items:: A simple kind of menu key binding.
+* Extended Menu Items:: More complex menu item definitions.
* Menu Separators:: Drawing a horizontal line through a menu.
* Alias Menu Items:: Using command aliases in menu items.
* Region to Refontify:: Controlling which region gets refontified
after a buffer change.
+Automatic Indentation of code
+
+* SMIE:: A simple minded indentation engine.
+
+Simple Minded Indentation Engine
+
+* SMIE setup:: SMIE setup and features.
+* Operator Precedence Grammars:: A very simple parsing technique.
+* SMIE Grammar:: Defining the grammar of a language.
+* SMIE Lexer:: Defining tokens.
+* SMIE Tricks:: Working around the parser's limitations.
+* SMIE Indentation:: Specifying indentation rules.
+* SMIE Indentation Helpers:: Helper functions for indentation rules.
+* SMIE Indentation Example:: Sample indentation rules.
+* SMIE Customization:: Customizing indentation.
+
Documentation
* Documentation Basics:: Where doc strings are defined and stored.
* Testing Accessibility:: Is a given file readable? Writable?
* Kinds of Files:: Is it a directory? A symbolic link?
* Truenames:: Eliminating symbolic links from a file name.
-* File Attributes:: How large is it? Any other names? Etc.
+* File Attributes:: File sizes, modification times, etc.
+* Extended Attributes:: Extended file attributes for access control.
* Locating Files:: How to find a file in standard places.
File Names
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''.
+ "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.
+* Buffer List:: How to look at all the existing buffers.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some
* Resizing Windows:: Changing the sizes of windows.
* Splitting Windows:: Splitting one window into two windows.
* Deleting Windows:: Deleting a window gives its space to other windows.
+* Recombining Windows:: Preserving the frame layout when splitting and
+ deleting 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.
* Window System Selections::Transferring text to and from other X clients.
* Drag and Drop:: Internals of Drag-and-Drop implementation.
* Color Names:: Getting the definitions of color names.
-* Text Terminal Colors:: Defining colors for text-only terminals.
+* Text Terminal Colors:: Defining colors for text terminals.
* Resources:: Getting resource values from the server.
* Display Feature Testing:: Determining the features of a terminal.
* 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.
+* Transposition:: Swapping two portions of a buffer.
+* Decompression:: Dealing with compressed data.
* Base 64:: Conversion to or from base 64 encoding.
-* Checksum/Hash:: Computing "message digests"/"checksums"/"hashes".
+* Checksum/Hash:: Computing cryptographic hashes.
+* Parsing HTML/XML:: Parsing HTML and XML.
* Atomic Changes:: Installing several buffer changes "atomically".
* Change Hooks:: Supplying functions to be run when text is changed.
Non-@acronym{ASCII} Characters
* Text Representations:: How Emacs represents text.
+* Disabling Multibyte:: Controlling whether to use multibyte characters.
* 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
for a single file operation.
* Explicit Encoding:: Encoding or decoding text without doing I/O.
* Terminal I/O Encoding:: Use of encoding for terminal I/O.
-* MS-DOS File Types:: How DOS "text" and "binary" files
- relate to coding systems.
Searching and Matching
* 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.
Abbrevs and Abbrev Expansion
-* Abbrev Mode:: Setting up Emacs for abbreviation.
* Abbrev Tables:: Creating and working with abbrev tables.
* Defining Abbrevs:: Specifying abbreviations and their expansions.
* Abbrev Files:: Saving abbrevs in files.
* Datagrams:: UDP network connections.
* Low-Level Network:: Lower-level but more general function
to create connections and servers.
-* Misc Network:: Additional relevant functions for
- network connections.
+* Misc Network:: Additional relevant functions for net connections.
* Serial Ports:: Communicating with serial ports.
* 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.
+* Process Buffers:: By default, 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.
* 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.
+* Size of Displayed Text:: How large displayed text is.
* 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.
+* Window Dividers:: Separating windows visually.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
-* Abstract Display:: Emacs' Widget for Object Collections.
+* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Usual Display:: The usual conventions for displaying
- nonprinting chars.
-* Display Tables:: How to specify other conventions.
+* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
-* Glyphless Chars:: How glyphless characters are drawn.
The Echo Area
* Warning Variables:: Variables programs bind to customize
their warnings.
* Warning Options:: Variables users set to control display of warnings.
+* Delayed Warnings:: Deferring a warning until the end of a command.
Overlays
Faces
-* Defining Faces:: How to define a face with @code{defface}.
* Face Attributes:: What is in a face?
+* Defining Faces:: How to define a face.
* Attribute Functions:: Functions to examine and set face attributes.
* Displaying Faces:: How Emacs combines the faces specified for
a character.
-* Face Remapping:: Remapping faces to alternative definitions.
+* Face Remapping:: Remapping faces to alternative definitions.
* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
-* Basic Faces:: Faces that are defined by default.
+* Basic Faces:: Faces that are defined by default.
* Font Selection:: Finding the best available font for a face.
* Font Lookup:: Looking up the names of available fonts
and information about them.
* Image Descriptors:: How to specify an image for use in @code{:display}.
* XBM Images:: Special features for XBM format.
* XPM Images:: Special features for XPM format.
-* GIF Images:: Special features for GIF format.
-* TIFF Images:: Special features for TIFF format.
* PostScript Images:: Special features for PostScript format.
+* ImageMagick Images:: Special features available through ImageMagick.
* Other Image Types:: Various other formats are supported.
* Defining Images:: Convenient ways to define an image for later use.
* Showing Images:: Convenient ways to display an image once
it is defined.
-* Animated Images:: Some image formats can be animated.
+* Multi-Frame Images:: Some images contain more than one frame.
* Image Cache:: Internal mechanisms of image display.
Buttons
* Abstract Display Functions:: Functions in the Ewoc package.
* Abstract Display Example:: Example of using Ewoc.
-Display Tables
+Character Display
-* Display Table Format:: What a display table consists of.
-* Active Display Table:: How Emacs selects a display table to use.
-* Glyphs:: How to define a glyph, and what glyphs mean.
+* Usual Display:: The usual conventions for displaying characters.
+* Display Tables:: What a display table consists of.
+* Active Display Table:: How Emacs selects a display table to use.
+* Glyphs:: How to define a glyph, and what glyphs mean.
+* Glyphless Chars:: How glyphless characters are drawn.
Operating System Interface
* Batch Mode:: Running Emacs without terminal interaction.
* Session Management:: Saving and restoring state with
X Session Management.
-
-Preparing Lisp code for distribution
-
-* Packaging Basics:: The basic concepts of Emacs Lisp packages.
-* Simple Packages:: How to package a single .el file.
-* Multi-file Packages:: How to package multiple files.
-* Package Archives:: Maintaining package archives.
+* Desktop Notifications:: Desktop notifications.
+* File Notifications:: File notifications.
+* Dynamic Libraries:: On-demand loading of support libraries.
Starting Up Emacs
* Input Modes:: Options for how input is processed.
* Recording Input:: Saving histories of recent or all input events.
+Preparing Lisp code for distribution
+
+* Packaging Basics:: The basic concepts of Emacs Lisp packages.
+* Simple Packages:: How to package a single .el file.
+* Multi-file Packages:: How to package multiple files.
+* Package Archives:: Maintaining package archives.
+
Tips and Conventions
* Coding Conventions:: Conventions for clean and robust programs.
@end detailmenu
@end menu
+@ifclear VOL2
@include intro.texi
@include objects.texi
@include numbers.texi
@include customize.texi
@include loading.texi
@include compile.texi
-@include advice.texi
@c This includes edebug.texi.
@include debugging.texi
@include files.texi
@include backups.texi
+
+@end ifclear
+
+@c ================ Beginning of Volume 2 ================
+@ifclear VOL1
+
@include buffers.texi
@include windows.texi
@include frames.texi
@include package.texi
-@c MOVE to Emacs Manual: include misc-modes.texi
-
@c appendices
-@c REMOVE this: include non-hacker.texi
-
@include anti.texi
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include doclicense.texi
+@node GPL
+@appendix GNU General Public License
@include gpl.texi
@include tips.texi
@include internals.texi
@include errors.texi
-@include locals.texi
@include maps.texi
@include hooks.texi
@include index.texi
+@end ifclear
+
@ignore
-@node New Symbols, , Index, Top
+@node New Symbols
@unnumbered New Symbols Since the Previous Edition
@printindex tp