X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/ebc6903b2989b2de3154afd59fece90ba3882306..0df333e5c914cd21820d87a8e4380af0ff28a926:/lispref/elisp.texi diff --git a/lispref/elisp.texi b/lispref/elisp.texi index ad38389805..bd2cbee479 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -4,54 +4,19 @@ @settitle GNU Emacs Lisp Reference Manual @c %**end of header -@smallbook - -@ifinfo -This version is the edition 2.5 of the GNU Emacs Lisp -Reference Manual. It corresponds to Emacs Version 20.3 -@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 Free Software Foundation, Inc. +@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 -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. +@dircategory Emacs +@direntry +* Elisp: (elisp). The Emacs Lisp Reference Manual. +@end direntry -@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 +@smallbook +@setchapternewpage odd +@finalout @c Combine indices. @synindex cp fn @@ -61,66 +26,67 @@ instead of in the original English. @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 @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, +1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, +Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'', with the +Front-Cover texts being ``A GNU Manual'', and with the Back-Cover +Texts as in (a) below. A copy of the license is included in the +section entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You 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 20.3 -@c The edition number appears in several places in this file -@c and also in the file intro.texi. -@subtitle Revision 2.5, May 1998 +@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 Free Software Foundation, Inc. - -@sp 2 -Edition 2.5 @* -Revised for Emacs Version 20.3,@* -May 1998.@* -@sp 2 -ISBN 1-882114-72-8 +@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.5 of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version 20.3. -@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. @@ -129,6 +95,7 @@ Reference Manual, corresponding to GNU Emacs version 20.3. * Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. Certain functions act on any kind of sequence. The description of vectors is here as well. +* Hash Tables:: Very fast lookup-tables. * Symbols:: Symbols represent names, uniquely. * Evaluation:: How Lisp expressions are evaluated. @@ -157,7 +124,7 @@ Reference Manual, corresponding to GNU Emacs version 20.3. files are made. * Buffers:: Creating and using buffer objects. * Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple X windows. +* Frames:: Making multiple system-level windows. * Positions:: Buffer positions and motion functions. * Markers:: Markers represent positions and update automatically when the text is changed. @@ -169,14 +136,15 @@ Reference Manual, corresponding to GNU Emacs version 20.3. * 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:: Parameters controlling screen usage. - The bell. Waiting for input. -* 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. @@ -189,9 +157,10 @@ Appendices * Index:: Index including concepts, functions, variables, and other terms. -* New Symbols:: New functions and variables in Emacs 20. +* 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: @@ -201,6 +170,7 @@ Introduction * Caveats:: Flaws and a request for help. * Lisp History:: Emacs Lisp is descended from Maclisp. * Conventions:: How the manual is formatted. +* Version Info:: Which Emacs version is running? * Acknowledgements:: The authors, editors, and sponsors of this manual. Conventions @@ -213,18 +183,10 @@ 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 @@ -232,6 +194,7 @@ 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. @@ -240,33 +203,39 @@ 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. + 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. * 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. + 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. @@ -278,9 +247,10 @@ Numbers * 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. @@ -289,21 +259,23 @@ Strings and Characters * String Basics:: Basic properties of strings and characters. * Predicates for Strings:: Testing whether an object is a string or char. * Creating Strings:: Functions to allocate new strings. +* Modifying Strings:: Altering the contents of an existing string. * Text Comparison:: Comparing characters or strings. * String Conversion:: Converting characters 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 @@ -318,6 +290,16 @@ Sequences, Arrays, and Vectors * 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 @@ -331,16 +313,18 @@ 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, @@ -351,7 +335,7 @@ Kinds of Forms 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. @@ -378,19 +362,27 @@ Variables * 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 @@ -408,11 +400,14 @@ Functions * 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 @@ -431,43 +426,68 @@ Macros * 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. +* Load Suffixes:: Details about the suffixes that @code{load} tries. +* Library Search:: Finding a library to load. +* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. * Autoload:: Setting up a function to autoload. -* 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. @@ -475,6 +495,27 @@ The Lisp Debugger * Invoking the Debugger:: How to call the function @code{debug}. * Internals of Debugger:: Subroutines of the debugger, and global variables. +Edebug + +* Using Edebug:: Introduction to use of Edebug. +* Instrumenting:: You must instrument your code + in order to debug it with Edebug. +* Edebug Execution Modes:: Execution modes, stopping more or less often. +* Jumping:: Commands to jump to a specified place. +* Edebug Misc:: Miscellaneous commands. +* Breaks:: Setting breakpoints to make the program stop. +* Trapping Errors:: Trapping errors with Edebug. +* Edebug Views:: Views inside and outside of Edebug. +* Edebug Eval:: Evaluating expressions within Edebug. +* Eval List:: Expressions whose values are displayed + each time you enter Edebug. +* Printing in Edebug:: Customization of printing. +* Trace Buffer:: How to produce trace output in a buffer. +* Coverage Testing:: How to test evaluation coverage. +* The Outside Context:: Data that Edebug saves and restores. +* Edebug and Macros:: Specifying how to handle macro calls. +* Edebug Options:: Option variables for customizing Edebug. + Debugging Invalid Lisp Syntax * Excess Open:: How to find a spurious open paren or missing close. @@ -483,20 +524,31 @@ Debugging Invalid Lisp Syntax 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 @@ -516,8 +568,10 @@ Command Loop * 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. @@ -542,42 +596,59 @@ 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. + 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 @@ -596,11 +667,15 @@ 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. + 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 @@ -610,33 +685,36 @@ 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. @@ -644,6 +722,8 @@ Backup Files 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. @@ -655,8 +735,9 @@ Buffers * 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 @@ -668,14 +749,20 @@ 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 @@ -700,8 +787,9 @@ 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 @@ -725,8 +813,10 @@ 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. +* 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''. @@ -735,6 +825,7 @@ Text * Near Point:: Examining text in the vicinity of point. * Buffer Contents:: Examining text in a general fashion. +* Comparing Text:: Comparing substrings of buffers. * Insertion:: Adding new text to a buffer. * Commands for Insertion:: User-level commands to insert text. * Deletion:: Removing text from a buffer. @@ -742,24 +833,32 @@ 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. +* 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. @@ -786,33 +885,62 @@ Text Properties 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. +* Searching and Case:: Case-independent or case-significant searching. * 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. +* POSIX Regexps:: Searching POSIX-style for the longest match. +* Match Data:: Finding out which part of the text matched, + after a string or regexp search. +* Search and Replace:: Commands that loop, searching and replacing. * Standard Regexps:: Useful regexps for finding sentences, pages,... -* 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. +* 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 @@ -822,15 +950,16 @@ 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. @@ -840,30 +969,77 @@ Processes an asynchronous subprocess. * Output from Processes:: Collecting output from an asynchronous subprocess. * Sentinels:: Sentinels run when process run-status changes. +* Query Before Exit:: Whether to query if exiting will kill a process. +* Transaction Queues:: Transaction-based communication with subprocesses. * Network:: Opening network connections. +* Network Servers:: Network servers let Emacs accept net connections. +* Datagrams:: UDP network connections. +* Low-Level Network:: Lower-level but more general function + to create connections and servers. +* Misc Network:: Additional relevant functions for network connections. +* Byte Packing:: Using bindat to pack and unpack binary data. Receiving Output from Processes * Process Buffers:: If no filter, output is put in a buffer. * Filter Functions:: Filter functions accept output from the process. +* Decoding Output:: Filters can get unibyte or multibyte strings. * Accepting Output:: How to wait until process output arrives. +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. +* 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). +* Time Parsing:: Converting a time from numeric form to text + and vice versa. +* Processor Run Time:: Getting the run time used by Emacs. +* Time Calculations:: Adding, subtracting, comparing times, etc. +* Timers:: Setting a timer to call a function at a certain time. * 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 -* Start-up Summary:: Sequence of actions Emacs performs at start-up. +* Startup Summary:: Sequence of actions Emacs performs at start-up. * Init File:: Details on reading the init file (@file{.emacs}). * Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command Line Arguments:: How command line arguments are processed, +* Command-Line Arguments:: How command line arguments are processed, and how you can customize them. Getting out of Emacs @@ -871,27 +1047,25 @@ Getting out of 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. +* Key Binding Conventions:: Which keys should be bound by which programs. +* Programming Tips:: Making Emacs code fit smoothly in Emacs. +* Compilation Tips:: Making compiled code run fast. +* Warning Tips:: Turning off compiler warnings. +* Documentation Tips:: Writing readable documentation strings. +* Comment Tips:: Conventions for writing comments. +* Library Headers:: Standard headers for library packages. GNU Emacs Internals * Building Emacs:: How 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 @@ -907,6 +1081,7 @@ Object Internals @include lists.texi @include sequences.texi +@include hash.texi @include symbols.texi @include eval.texi @@ -945,9 +1120,8 @@ 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 @@ -955,6 +1129,9 @@ Object Internals @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 @@ -969,12 +1146,11 @@ Object Internals @printindex tp -@c Print the tables of contents -@summarycontents -@contents -@c That's all - @bye These words prevent "local variables" above from confusing Emacs. + +@ignore + arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34 +@end ignore