GNU Emacs Lisp Reference ManualFor Emacs Version 25.1.50Revision 3.1, October 2014

by Bil Lewis, Dan LaLiberte, Richard Stallman,the GNU Manual Group, et al.

This is edition 3.1 of the GNU Emacs Lisp Reference Manual,corresponding to Emacs version 25.1.50.

Copyright c 19901996, 19982015 Free Software Foundation, Inc.Permission is granted to copy, distribute and/or modify this document underthe terms of the GNU Free Documentation License, Version 1.3 or any laterversion published by the Free Software Foundation; with the Invariant Sectionsbeing GNU General Public License, with the Front-Cover Texts being AGNU Manual, and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled GNU Free Documentation License.

(a) The FSFs Back-Cover Text is: You have the freedom to copy and modifythis GNU manual. Buying copies from the FSF supports it in developing GNUand promoting software freedom.

Published by the Free Software Foundation51 Franklin St, Fifth FloorBoston, MA 02110-1301USAISBN 1-882114-74-4

Cover art by Etienne Suvasa.

iShort Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Lisp Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Strings and Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 Sequences, Arrays, and Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 887 Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

8 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

10 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13311 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

12 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18313 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20914 Customization Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

15 Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23616 Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25117 Debugging Lisp Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26118 Reading and Printing Lisp Objects . . . . . . . . . . . . . . . . . . . . . 293

19 Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

20 Command Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33621 Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

22 Major and Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42023 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

24 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48525 Backups and Auto-Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52826 Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53827 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55528 Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61529 Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65730 Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

31 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67932 Non-ASCII Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74333 Searching and Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771

ii

34 Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79735 Abbrevs and Abbrev Expansion . . . . . . . . . . . . . . . . . . . . . . . . 81336 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82037 Emacs Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86538 Operating System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96039 Preparing Lisp code for distribution . . . . . . . . . . . . . . . . . . . . 1000

A Emacs 23 Antinews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006B GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . 1008C GNU General Public License . . . . . . . . . . . . . . . . . . . . . . . . . 1016D Tips and Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027E GNU Emacs Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040

F Standard Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064G Standard Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068H Standard Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075

iii

Table of Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Lisp History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.3.1 Some Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3.2 nil and t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3.3 Evaluation Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3.4 Printing Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3.5 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3.6 Buffer Text Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.7 Format of Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3.7.1 A Sample Function Description . . . . . . . . . . . . . . . . . . . . . . . 41.3.7.2 A Sample Variable Description . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4 Version Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.5 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Lisp Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1 Printed Representation and Read Syntax . . . . . . . . . . . . . . . . . . . . . . . . 82.2 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3 Programming Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.3.1 Integer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3.2 Floating-Point Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.3.3 Character Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.3.3.1 Basic Char Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.3.3.2 General Escape Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.3.3.3 Control-Character Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.3.3.4 Meta-Character Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.3.3.5 Other Character Modifier Bits . . . . . . . . . . . . . . . . . . . . . . . 13

2.3.4 Symbol Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3.5 Sequence Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.3.6 Cons Cell and List Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.3.6.1 Drawing Lists as Box Diagrams . . . . . . . . . . . . . . . . . . . . . . 152.3.6.2 Dotted Pair Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.3.6.3 Association List Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.3.7 Array Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.3.8 String Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.3.8.1 Syntax for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.3.8.2 Non-ASCII Characters in Strings . . . . . . . . . . . . . . . . . . . . . 192.3.8.3 Nonprinting Characters in Strings . . . . . . . . . . . . . . . . . . . . 202.3.8.4 Text Properties in Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.3.9 Vector Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.3.10 Char-Table Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.3.11 Bool-Vector Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

iv

2.3.12 Hash Table Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.3.13 Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3.14 Macro Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3.15 Primitive Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3.16 Byte-Code Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.3.17 Autoload Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.3.18 Finalizer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.4 Editing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.4.1 Buffer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.4.2 Marker Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.4.3 Window Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.4.4 Frame Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.4.5 Terminal Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.4.6 Window Configuration Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.4.7 Frame Configuration Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.4.8 Process Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.4.9 Stream Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.4.10 Keymap Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.4.11 Overlay Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.4.12 Font Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2.5 Read Syntax for Circular Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.6 Type Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.7 Equality Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.1 Integer Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.2 Floating-Point Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.3 Type Predicates for Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.4 Comparison of Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373.5 Numeric Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393.6 Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403.7 Rounding Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.8 Bitwise Operations on Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.9 Standard Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473.10 Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

4 Strings and Characters . . . . . . . . . . . . . . . . . . . . . . . . 494.1 String and Character Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494.2 Predicates for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.3 Creating Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.4 Modifying Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.5 Comparison of Characters and Strings . . . . . . . . . . . . . . . . . . . . . . . . . 544.6 Conversion of Characters and Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 584.7 Formatting Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594.8 Case Conversion in Lisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624.9 The Case Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

v5 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665.1 Lists and Cons Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665.2 Predicates on Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665.3 Accessing Elements of Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.4 Building Cons Cells and Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705.5 Modifying List Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735.6 Modifying Existing List Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

5.6.1 Altering List Elements with setcar . . . . . . . . . . . . . . . . . . . . . . . 755.6.2 Altering the CDR of a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775.6.3 Functions that Rearrange Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

5.7 Using Lists as Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795.8 Association Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825.9 Property Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

5.9.1 Property Lists and Association Lists . . . . . . . . . . . . . . . . . . . . . . 865.9.2 Property Lists Outside Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

6 Sequences, Arrays, and Vectors . . . . . . . . . . . . . . . 886.1 Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886.2 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996.3 Functions that Operate on Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006.4 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016.5 Functions for Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016.6 Char-Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026.7 Bool-vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056.8 Managing a Fixed-Size Ring of Objects . . . . . . . . . . . . . . . . . . . . . . . 106

7 Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097.1 Creating Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097.2 Hash Table Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117.3 Defining Hash Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127.4 Other Hash Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

8 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148.1 Symbol Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148.2 Defining Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158.3 Creating and Interning Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1168.4 Symbol Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

8.4.1 Accessing Symbol Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198.4.2 Standard Symbol Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

vi

9 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229.1 Kinds of Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

9.1.1 Self-Evaluating Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1239.1.2 Symbol Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1239.1.3 Classification of List Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249.1.4 Symbol Function Indirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249.1.5 Evaluation of Function Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259.1.6 Lisp Macro Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269.1.7 Special Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269.1.8 Autoloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

9.2 Quoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289.3 Backquote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289.4 Eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

10 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . 13310.1 Sequencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13310.2 Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

10.2.1 Pattern matching case statement . . . . . . . . . . . . . . . . . . . . . . . 13610.3 Constructs for Combining Conditions . . . . . . . . . . . . . . . . . . . . . . . . 13810.4 Iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13910.5 Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14010.6 Nonlocal Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

10.6.1 Explicit Nonlocal Exits: catch and throw . . . . . . . . . . . . . . 14210.6.2 Examples of catch and throw . . . . . . . . . . . . . . . . . . . . . . . . . . 14410.6.3 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

10.6.3.1 How to Signal an Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14510.6.3.2 How Emacs Processes Errors . . . . . . . . . . . . . . . . . . . . . . . 14610.6.3.3 Writing Code to Handle Errors . . . . . . . . . . . . . . . . . . . . 14710.6.3.4 Error Symbols and Condition Names . . . . . . . . . . . . . . . 150

10.6.4 Cleaning Up from Nonlocal Exits . . . . . . . . . . . . . . . . . . . . . . . 152

11 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15411.1 Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15411.2 Variables that Never Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15411.3 Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15511.4 When a Variable is Void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15711.5 Defining Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15811.6 Tips for Defining Variables Robustly . . . . . . . . . . . . . . . . . . . . . . . . . 16011.7 Accessing Variable Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16111.8 Setting Variable Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16211.9 Scoping Rules for Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 163

11.9.1 Dynamic Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16311.9.2 Proper Use of Dynamic Binding . . . . . . . . . . . . . . . . . . . . . . . . 16511.9.3 Lexical Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16511.9.4 Using Lexical Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

11.10 Buffer-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16811.10.1 Introduction to Buffer-Local Variables . . . . . . . . . . . . . . . . . 168

vii

11.10.2 Creating and Deleting Buffer-Local Bindings . . . . . . . . . . . 16911.10.3 The Default Value of a Buffer-Local Variable . . . . . . . . . . 172

11.11 File Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17411.12 Directory Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17611.13 Variable Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17811.14 Variables with Restricted Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 17911.15 Generalized Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

11.15.1 The setf Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18011.15.2 Defining new setf forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

12 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18312.1 What Is a Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18312.2 Lambda Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

12.2.1 Components of a Lambda Expression . . . . . . . . . . . . . . . . . . . 18512.2.2 A Simple Lambda Expression Example . . . . . . . . . . . . . . . . . 18512.2.3 Other Features of Argument Lists . . . . . . . . . . . . . . . . . . . . . . 18612.2.4 Documentation Strings of Functions . . . . . . . . . . . . . . . . . . . . 187

12.3 Naming a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18812.4 Defining Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18912.5 Calling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19012.6 Mapping Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19212.7 Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19312.8 Accessing Function Cell Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19512.9 Closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19612.10 Advising Emacs Lisp Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

12.10.1 Primitives to manipulate advices . . . . . . . . . . . . . . . . . . . . . . 19712.10.2 Advising Named Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19912.10.3 Ways to compose advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20012.10.4 Adapting code using the old defadvice . . . . . . . . . . . . . . . . . 202

12.11 Declaring Functions Obsolete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20312.12 Inline Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20412.13 The declare Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20512.14 Telling the Compiler that a Function is Defined . . . . . . . . . . . . . 20612.15 Determining whether a Function is Safe to Call . . . . . . . . . . . . . 20712.16 Other Topics Related to Functions . . . . . . . . . . . . . . . . . . . . . . . . . 208

13 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20913.1 A Simple Example of a Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20913.2 Expansion of a Macro Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20913.3 Macros and Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21013.4 Defining Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21113.5 Common Problems Using Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

13.5.1 Wrong Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21213.5.2 Evaluating Macro Arguments Repeatedly . . . . . . . . . . . . . . . 21213.5.3 Local Variables in Macro Expansions . . . . . . . . . . . . . . . . . . . 21413.5.4 Evaluating Macro Arguments in Expansion . . . . . . . . . . . . . 21413.5.5 How Many Times is the Macro Expanded? . . . . . . . . . . . . . . 215

13.6 Indenting Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

viii

14 Customization Settings . . . . . . . . . . . . . . . . . . . . . 21714.1 Common Item Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21714.2 Defining Customization Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21914.3 Defining Customization Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22014.4 Customization Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

14.4.1 Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22414.4.2 Composite Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22514.4.3 Splicing into Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23014.4.4 Type Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23014.4.5 Defining New Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

14.5 Applying Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23314.6 Custom Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

15 Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23615.1 How Programs Do Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23615.2 Load Suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23815.3 Library Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23915.4 Loading Non-ASCII Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24115.5 Autoload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24115.6 Repeated Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24415.7 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24515.8 Which File Defined a Certain Symbol . . . . . . . . . . . . . . . . . . . . . . . . 24715.9 Unloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24815.10 Hooks for Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

16 Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25116.1 Performance of Byte-Compiled Code . . . . . . . . . . . . . . . . . . . . . . . . . 25116.2 Byte-Compilation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25116.3 Documentation Strings and Compilation . . . . . . . . . . . . . . . . . . . . . 25416.4 Dynamic Loading of Individual Functions . . . . . . . . . . . . . . . . . . . . 25416.5 Evaluation During Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25516.6 Compiler Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25616.7 Byte-Code Function Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25716.8 Disassembled Byte-Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

17 Debugging Lisp Programs . . . . . . . . . . . . . . . . . . 26117.1 The Lisp Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

17.1.1 Entering the Debugger on an Error . . . . . . . . . . . . . . . . . . . . . 26117.1.2 Debugging Infinite Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26317.1.3 Entering the Debugger on a Function Call . . . . . . . . . . . . . . 26317.1.4 Explicit Entry to the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . 26417.1.5 Using the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26417.1.6 Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26517.1.7 Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26617.1.8 Internals of the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

17.2 Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26917.2.1 Using Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

ix

17.2.2 Instrumenting for Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27117.2.3 Edebug Execution Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27117.2.4 Jumping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27317.2.5 Miscellaneous Edebug Commands . . . . . . . . . . . . . . . . . . . . . . 27417.2.6 Breaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

17.2.6.1 Edebug Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27417.2.6.2 Global Break Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . 27517.2.6.3 Source Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

17.2.7 Trapping Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27617.2.8 Edebug Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27617.2.9 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27717.2.10 Evaluation List Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27717.2.11 Printing in Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27817.2.12 Trace Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27917.2.13 Coverage Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28017.2.14 The Outside Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

17.2.14.1 Checking Whether to Stop . . . . . . . . . . . . . . . . . . . . . . . . 28117.2.14.2 Edebug Display Update . . . . . . . . . . . . . . . . . . . . . . . . . . 28117.2.14.3 Edebug Recursive Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

17.2.15 Edebug and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28217.2.15.1 Instrumenting Macro Calls . . . . . . . . . . . . . . . . . . . . . . . 28217.2.15.2 Specification List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28317.2.15.3 Backtracking in Specifications . . . . . . . . . . . . . . . . . . . . 28617.2.15.4 Specification Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

17.2.16 Edebug Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28717.3 Debugging Invalid Lisp Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

17.3.1 Excess Open Parentheses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29017.3.2 Excess Close Parentheses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

17.4 Test Coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29117.5 Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

18 Reading and Printing Lisp Objects . . . . . . . . 29318.1 Introduction to Reading and Printing . . . . . . . . . . . . . . . . . . . . . . . . 29318.2 Input Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29318.3 Input Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29518.4 Output Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29718.5 Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29918.6 Variables Affecting Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

19 Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30419.1 Introduction to Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30419.2 Reading Text Strings with the Minibuffer . . . . . . . . . . . . . . . . . . . . 30519.3 Reading Lisp Objects with the Minibuffer . . . . . . . . . . . . . . . . . . . 30819.4 Minibuffer History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30919.5 Initial Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31119.6 Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

19.6.1 Basic Completion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

x19.6.2 Completion and the Minibuffer . . . . . . . . . . . . . . . . . . . . . . . . . 31519.6.3 Minibuffer Commands that Do Completion . . . . . . . . . . . . . 31719.6.4 High-Level Completion Functions . . . . . . . . . . . . . . . . . . . . . . . 31919.6.5 Reading File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32119.6.6 Completion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32419.6.7 Programmed Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32519.6.8 Completion in Ordinary Buffers . . . . . . . . . . . . . . . . . . . . . . . . 327

19.7 Yes-or-No Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32819.8 Asking Multiple Y-or-N Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . 33019.9 Reading a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33119.10 Minibuffer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33119.11 Minibuffer Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33219.12 Minibuffer Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33319.13 Recursive Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33419.14 Minibuffer Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

20 Command Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33620.1 Command Loop Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33620.2 Defining Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

20.2.1 Using interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33720.2.2 Code Characters for interactive . . . . . . . . . . . . . . . . . . . . . . 33920.2.3 Examples of Using interactive . . . . . . . . . . . . . . . . . . . . . . . . 34220.2.4 Select among Command Alternatives . . . . . . . . . . . . . . . . . . . 343

20.3 Interactive Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34320.4 Distinguish Interactive Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34520.5 Information from the Command Loop . . . . . . . . . . . . . . . . . . . . . . . 34620.6 Adjusting Point After Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 34820.7 Input Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

20.7.1 Keyboard Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34920.7.2 Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35020.7.3 Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35120.7.4 Click Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35120.7.5 Drag Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35320.7.6 Button-Down Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35420.7.7 Repeat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35420.7.8 Motion Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35520.7.9 Focus Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35620.7.10 Miscellaneous System Events . . . . . . . . . . . . . . . . . . . . . . . . . . 35620.7.11 Event Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35820.7.12 Classifying Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35820.7.13 Accessing Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36020.7.14 Accessing Scroll Bar Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 36320.7.15 Putting Keyboard Events in Strings . . . . . . . . . . . . . . . . . . . 363

20.8 Reading Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36420.8.1 Key Sequence Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36420.8.2 Reading One Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36620.8.3 Modifying and Translating Input Events . . . . . . . . . . . . . . . . 36820.8.4 Invoking the Input Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

xi

20.8.5 Quoted Character Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37020.8.6 Miscellaneous Event Input Features . . . . . . . . . . . . . . . . . . . . . 371

20.9 Special Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37220.10 Waiting for Elapsed Time or Input . . . . . . . . . . . . . . . . . . . . . . . . . 37320.11 Quitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37320.12 Prefix Command Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37520.13 Recursive Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37720.14 Disabling Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37920.15 Command History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38020.16 Keyboard Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

21 Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38221.1 Key Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38221.2 Keymap Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38321.3 Format of Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38321.4 Creating Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38521.5 Inheritance and Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38621.6 Prefix Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38721.7 Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38921.8 Searching the Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39021.9 Controlling the Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39121.10 Key Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39321.11 Functions for Key Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39521.12 Changing Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39721.13 Remapping Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40021.14 Keymaps for Translating Sequences of Events . . . . . . . . . . . . . . . 400

21.14.1 Interaction with normal keymaps . . . . . . . . . . . . . . . . . . . . . . 40221.15 Commands for Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40221.16 Scanning Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40421.17 Menu Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

21.17.1 Defining Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40621.17.1.1 Simple Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40621.17.1.2 Extended Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40721.17.1.3 Menu Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40921.17.1.4 Alias Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

21.17.2 Menus and the Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41121.17.3 Menus and the Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41121.17.4 Menu Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41121.17.5 The Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41221.17.6 Tool bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41421.17.7 Modifying Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41721.17.8 Easy Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

xii

22 Major and Minor Modes . . . . . . . . . . . . . . . . . . . . 42022.1 Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

22.1.1 Running Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42022.1.2 Setting Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

22.2 Major Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42222.2.1 Major Mode Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42322.2.2 How Emacs Chooses a Major Mode . . . . . . . . . . . . . . . . . . . . . 42622.2.3 Getting Help about a Major Mode . . . . . . . . . . . . . . . . . . . . . . 42922.2.4 Defining Derived Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42922.2.5 Basic Major Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43122.2.6 Mode Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43122.2.7 Tabulated List mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43222.2.8 Generic Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43422.2.9 Major Mode Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

22.3 Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43722.3.1 Conventions for Writing Minor Modes . . . . . . . . . . . . . . . . . . 43722.3.2 Keymaps and Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43922.3.3 Defining Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

22.4 Mode Line Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44222.4.1 Mode Line Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44222.4.2 The Data Structure of the Mode Line . . . . . . . . . . . . . . . . . . . 44322.4.3 The Top Level of Mode Line Control . . . . . . . . . . . . . . . . . . . 44422.4.4 Variables Used in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . 44522.4.5 %-Constructs in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . . . . 44722.4.6 Properties in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44922.4.7 Window Header Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44922.4.8 Emulating Mode Line Formatting . . . . . . . . . . . . . . . . . . . . . . . 450

22.5 Imenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45022.6 Font Lock Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

22.6.1 Font Lock Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45322.6.2 Search-based Fontification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45422.6.3 Customizing Search-Based Fontification . . . . . . . . . . . . . . . . . 45722.6.4 Other Font Lock Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45822.6.5 Levels of Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45922.6.6 Precalculated Fontification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45922.6.7 Faces for Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46022.6.8 Syntactic Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46122.6.9 Multiline Font Lock Constructs . . . . . . . . . . . . . . . . . . . . . . . . . 461

22.6.9.1 Font Lock Multiline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46222.6.9.2 Region to Fontify after a Buffer Change . . . . . . . . . . . . 463

22.7 Automatic Indentation of code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46322.7.1 Simple Minded Indentation Engine . . . . . . . . . . . . . . . . . . . . . 464

22.7.1.1 SMIE Setup and Features . . . . . . . . . . . . . . . . . . . . . . . . . . 46522.7.1.2 Operator Precedence Grammars . . . . . . . . . . . . . . . . . . . 46522.7.1.3 Defining the Grammar of a Language . . . . . . . . . . . . . . 46622.7.1.4 Defining Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46722.7.1.5 Living With a Weak Parser . . . . . . . . . . . . . . . . . . . . . . . . 46822.7.1.6 Specifying Indentation Rules . . . . . . . . . . . . . . . . . . . . . . . 469

xiii

22.7.1.7 Helper Functions for Indentation Rules . . . . . . . . . . . . . 47022.7.1.8 Sample Indentation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . 47122.7.1.9 Customizing Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

22.8 Desktop Save Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

23 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47523.1 Documentation Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47523.2 Access to Documentation Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47623.3 Substituting Key Bindings in Documentation . . . . . . . . . . . . . . . . 47823.4 Describing Characters for Help Messages . . . . . . . . . . . . . . . . . . . . 48023.5 Help Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

24 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48524.1 Visiting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

24.1.1 Functions for Visiting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48524.1.2 Subroutines of Visiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488

24.2 Saving Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48924.3 Reading from Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49124.4 Writing to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49224.5 File Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49424.6 Information about Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

24.6.1 Testing Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49524.6.2 Distinguishing Kinds of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 49724.6.3 Truenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49824.6.4 File Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49924.6.5 Extended File Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50224.6.6 Locating Files in Standard Places . . . . . . . . . . . . . . . . . . . . . . . 503

24.7 Changing File Names and Attributes . . . . . . . . . . . . . . . . . . . . . . . . 50324.8 File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

24.8.1 File Name Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50824.8.2 Absolute and Relative File Names . . . . . . . . . . . . . . . . . . . . . . 50924.8.3 Directory Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51024.8.4 Functions that Expand Filenames . . . . . . . . . . . . . . . . . . . . . . . 51124.8.5 Generating Unique File Names . . . . . . . . . . . . . . . . . . . . . . . . . 51324.8.6 File Name Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51524.8.7 Standard File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516

24.9 Contents of Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51724.10 Creating, Copying and Deleting Directories . . . . . . . . . . . . . . . . . 51824.11 Making Certain File Names Magic . . . . . . . . . . . . . . . . . . . . . . . 51924.12 File Format Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523

24.12.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52324.12.2 Round-Trip Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52424.12.3 Piecemeal Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

xiv

25 Backups and Auto-Saving . . . . . . . . . . . . . . . . . . . 52825.1 Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528

25.1.1 Making Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52825.1.2 Backup by Renaming or by Copying? . . . . . . . . . . . . . . . . . . . 53025.1.3 Making and Deleting Numbered Backup Files . . . . . . . . . . . 53125.1.4 Naming Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531

25.2 Auto-Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53325.3 Reverting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

26 Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53826.1 Buffer Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53826.2 The Current Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53826.3 Buffer Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54126.4 Buffer File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54226.5 Buffer Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54426.6 Buffer Modification Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54526.7 Read-Only Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54626.8 The Buffer List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54726.9 Creating Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55026.10 Killing Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55126.11 Indirect Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55226.12 Swapping Text Between Two Buffers . . . . . . . . . . . . . . . . . . . . . . . 55326.13 The Buffer Gap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554

27 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55527.1 Basic Concepts of Emacs Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 55527.2 Windows and Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55627.3 Window Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55927.4 Resizing Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56427.5 Preserving Window Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56727.6 Splitting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56927.7 Deleting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57127.8 Recombining Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57227.9 Selecting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57727.10 Cyclic Ordering of Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57827.11 Buffers and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58127.12 Switching to a Buffer in a Window . . . . . . . . . . . . . . . . . . . . . . . . . 58227.13 Choosing a Window for Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58527.14 Action Functions for display-buffer . . . . . . . . . . . . . . . . . . . . . . 58627.15 Additional Options for Displaying Buffers . . . . . . . . . . . . . . . . . . 59027.16 Window History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59227.17 Dedicated Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59327.18 Quitting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59427.19 Windows and Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59627.20 The Window Start and End Positions . . . . . . . . . . . . . . . . . . . . . . 59727.21 Textual Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60027.22 Vertical Fractional Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603

xv

27.23 Horizontal Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60427.24 Coordinates and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60627.25 Window Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60927.26 Window Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61127.27 Hooks for Window Scrolling and Changes . . . . . . . . . . . . . . . . . . . 613

28 Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61528.1 Creating Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61628.2 Multiple Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61628.3 Frame Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620

28.3.1 Frame Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62028.3.2 Frame Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62428.3.3 Size and Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62428.3.4 Implied Frame Resizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

28.4 Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62728.4.1 Access to Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62828.4.2 Initial Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62828.4.3 Window Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629

28.4.3.1 Basic Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62928.4.3.2 Position Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63028.4.3.3 Size Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63128.4.3.4 Layout Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63228.4.3.5 Buffer Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63328.4.3.6 Window Management Parameters . . . . . . . . . . . . . . . . . . 63428.4.3.7 Cursor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63528.4.3.8 Font and Color Parameters . . . . . . . . . . . . . . . . . . . . . . . . 636

28.4.4 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63828.5 Terminal Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63828.6 Frame Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63928.7 Deleting Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63928.8 Finding All Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64028.9 Minibuffers and Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64128.10 Input Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64128.11 Visibility of Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64328.12 Raising and Lowering Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64428.13 Frame Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64528.14 Mouse Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64528.15 Mouse Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64628.16 Pop-Up Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64728.17 Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64828.18 Pointer Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64928.19 Window System Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64928.20 Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65028.21 Color Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65128.22 Text Terminal Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65228.23 X Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65328.24 Display Feature Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654

xvi

29 Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65729.1 Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65729.2 Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

29.2.1 Motion by Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65829.2.2 Motion by Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65929.2.3 Motion to an End of the Buffer . . . . . . . . . . . . . . . . . . . . . . . . . 65929.2.4 Motion by Text Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66029.2.5 Motion by Screen Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66129.2.6 Moving over Balanced Expressions . . . . . . . . . . . . . . . . . . . . . . 66429.2.7 Skipping Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

29.3 Excursions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66629.4 Narrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667

30 Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67030.1 Overview of Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67030.2 Predicates on Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67130.3 Functions that Create Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67130.4 Information from Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67330.5 Marker Insertion Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67330.6 Moving Marker Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67430.7 The Mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67430.8 The Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678

31 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67931.1 Examining Text Near Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67931.2 Examining Buffer Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68031.3 Comparing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68331.4 Inserting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68331.5 User-Level Insertion Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68531.6 Deleting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68631.7 User-Level Deletion Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68731.8 The Kill Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689

31.8.1 Kill Ring Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69031.8.2 Functions for Killing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69031.8.3 Yanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69131.8.4 Functions for Yanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69231.8.5 Low-Level Kill Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69331.8.6 Internals of the Kill Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694

31.9 Undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69531.10 Maintaining Undo Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69731.11 Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69831.12 Margins for Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70131.13 Adaptive Fill Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70231.14 Auto Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70431.15 Sorting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70431.16 Counting Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70831.17 Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709

xvii

31.17.1 Indentation Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70931.17.2 Indentation Controlled by Major Mode . . . . . . . . . . . . . . . . 70931.17.3 Indenting an Entire Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71131.17.4 Indentation Relative to Previous Lines . . . . . . . . . . . . . . . . . 71231.17.5 Adjustable Tab Stops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71231.17.6 Indentation-Based Motion Commands . . . . . . . . . . . . . . . . . 713

31.18 Case Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71331.19 Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714

31.19.1 Examining Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71531.19.2 Changing Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71631.19.3 Text Property Search Functions . . . . . . . . . . . . . . . . . . . . . . . 71831.19.4 Properties with Special Meanings . . . . . . . . . . . . . . . . . . . . . . 72031.19.5 Formatted Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72631.19.6 Stickiness of Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 72631.19.7 Lazy Computation of Text Properties . . . . . . . . . . . . . . . . . . 72731.19.8 Defining Clickable Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72831.19.9 Defining and Using Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73131.19.10 Why Text Properties are not Intervals . . . . . . . . . . . . . . . . 732

31.20 Substituting for a Character Code . . . . . . . . . . . . . . . . . . . . . . . . . . 73331.21 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73431.22 Transposition of Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73531.23 Dealing With Compressed Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73631.24 Base 64 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73631.25 Checksum/Hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73731.26 Parsing HTML and XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738

31.26.1 Document Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73831.27 Atomic Change Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74031.28 Change Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741

32 Non-ASCII Characters . . . . . . . . . . . . . . . . . . . . . . 74332.1 Text Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74332.2 Disabling Multibyte Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74432.3 Converting Text Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74532.4 Selecting a Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74632.5 Character Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74732.6 Character Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74832.7 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75132.8 Scanning for Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75332.9 Translation of Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75332.10 Coding Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755

32.10.1 Basic Concepts of Coding Systems . . . . . . . . . . . . . . . . . . . . . 75532.10.2 Encoding and I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75632.10.3 Coding Systems in Lisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75832.10.4 User-Chosen Coding Systems . . . . . . . . . . . . . . . . . . . . . . . . . . 76032.10.5 Default Coding Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76132.10.6 Specifying a Coding System for One Operation . . . . . . . . 76432.10.7 Explicit Encoding and Decoding . . . . . . . . . . . . . . . . . . . . . . . 76532.10.8 Terminal I/O Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767

xviii

32.11 Input Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76832.12 Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769

33 Searching and Matching . . . . . . . . . . . . . . . . . . . . 77133.1 Searching for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77133.2 Searching and Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77333.3 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774

33.3.1 Syntax of Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 77433.3.1.1 Special Characters in Regular Expressions . . . . . . . . . 77433.3.1.2 Character Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77733.3.1.3 Backslash Constructs in Regular Expressions . . . . . . . 779

33.3.2 Complex Regexp Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78233.3.3 Regular Expression Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

33.4 Regular Expression Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78433.5 POSIX Regular Expression Searching . . . . . . . . . . . . . . . . . . . . . . . . 78733.6 The Match Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787

33.6.1 Replacing the Text that Matched . . . . . . . . . . . . . . . . . . . . . . . 78833.6.2 Simple Match Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78933.6.3 Accessing the Entire Match Data . . . . . . . . . . . . . . . . . . . . . . . 79133.6.4 Saving and Restoring the Match Data . . . . . . . . . . . . . . . . . . 792

33.7 Search and Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79233.8 Standard Regular Expressions Used in Editing . . . . . . . . . . . . . . . 795

34 Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79734.1 Syntax Table Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79734.2 Syntax Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798

34.2.1 Table of Syntax Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79834.2.2 Syntax Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801

34.3 Syntax Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80234.4 Syntax Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80434.5 Motion and Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80534.6 Parsing Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805

34.6.1 Motion Commands Based on Parsing . . . . . . . . . . . . . . . . . . . 80634.6.2 Finding the Parse State for a Position . . . . . . . . . . . . . . . . . . 80634.6.3 Parser State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80734.6.4 Low-Level Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80834.6.5 Parameters to Control Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . 809

34.7 Syntax Table Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80934.8 Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810

35 Abbrevs and Abbrev Expansion . . . . . . . . . . . . 81335.1 Abbrev Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81335.2 Defining Abbrevs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81435.3 Saving Abbrevs in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81535.4 Looking Up and Expanding Abbreviations . . . . . . . . . . . . . . . . . . . 81635.5 Standard Abbrev Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81835.6 Abbrev Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81835.7 Abbrev Table Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819

xix

36 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82036.1 Functions that Create Subprocesses . . . . . . . . . . . . . . . . . . . . . . . . . . 82036.2 Shell Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82136.3 Creating a Synchronous Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82336.4 Creating an Asynchronous Process . . . . . . . . . . . . . . . . . . . . . . . . . . 82736.5 Deleting Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83036.6 Process Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83136.7 Sending Input to Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83436.8 Sending Signals to Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83536.9 Receiving Output from Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836

36.9.1 Process Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83736.9.2 Process Filter Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83836.9.3 Decoding Process Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84036.9.4 Accepting Output from Processes . . . . . . . . . . . . . . . . . . . . . . . 840

36.10 Sentinels: Detecting Process Status Changes . . . . . . . . . . . . . . . . 84136.11 Querying Before Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84236.12 Accessing Other Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84336.13 Transaction Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84536.14 Network Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84636.15 Network Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84836.16 Datagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84936.17 Low-Level Network Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849

36.17.1 make-network-process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84936.17.2 Network Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85236.17.3 Testing Availability of Network Features . . . . . . . . . . . . . . . 853

36.18 Misc Network Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85436.19 Communicating with Serial Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . 85436.20 Packing and Unpacking Byte Arrays . . . . . . . . . . . . . . . . . . . . . . . . 857

36.20.1 Describing Data Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85736.20.2 Functions to Unpack and Pack Bytes . . . . . . . . . . . . . . . . . . 85936.20.3 Examples of Byte Unpacking and Packing . . . . . . . . . . . . . 860

37 Emacs Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86537.1 Refreshing the Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86537.2 Forcing Redisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86537.3 Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86637.4 The Echo Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867

37.4.1 Displaying Messages in the Echo Area . . . . . . . . . . . . . . . . . . 86737.4.2 Reporting Operation Progress . . . . . . . . . . . . . . . . . . . . . . . . . . 86937.4.3 Logging Messages in *Messages* . . . . . . . . . . . . . . . . . . . . . . . 87137.4.4 Echo Area Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871

37.5 Reporting Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87237.5.1 Warning Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87237.5.2 Warning Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87337.5.3 Warning Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87437.5.4 Delayed Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875

37.6 Invisible Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87537.7 Selective Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878

xx

37.8 Temporary Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87937.9 Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883

37.9.1 Managing Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88337.9.2 Overlay Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88637.9.3 Searching for Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889

37.10 Size of Displayed Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89037.11 Line Height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89237.12 Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893

37.12.1 Face Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89437.12.2 Defining Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89737.12.3 Face Attribute Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89937.12.4 Displaying Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90237.12.5 Face Remapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90337.12.6 Functions for Working with Faces . . . . . . . . . . . . . . . . . . . . . . 90437.12.7 Automatic Face Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . 90537.12.8 Basic Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90537.12.9 Font Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90637.12.10 Looking Up Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90837.12.11 Fontsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90837.12.12 Low-Level Font Representation . . . . . . . . . . . . . . . . . . . . . . . 910

37.13 Fringes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91537.13.1 Fringe Size and Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91537.13.2 Fringe Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91537.13.3 Fringe Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91737.13.4 Fringe Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91737.13.5 Customizing Fringe Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . 91837.13.6 The Overlay Arrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919

37.14 Scroll Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92037.15 Window Dividers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92237.16 The display Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923

37.16.1 Display Specs That Replace The Text . . . . . . . . . . . . . . . . . 92337.16.2 Specified Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92437.16.3 Pixel Specification for Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . 92537.16.4 Other Display Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . 92637.16.5 Displaying in the Margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927

37.17 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92837.17.1 Image Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92837.17.2 Image Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92937.17.3 XBM Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93237.17.4 XPM Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93237.17.5 PostScript Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93337.17.6 ImageMagick Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93337.17.7 Other Image Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93437.17.8 Defining Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93537.17.9 Showing Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93637.17.10 Multi-Frame Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93837.17.11 Image Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939

37.18 Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940

xxi

37.18.1 Button Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94037.18.2 Button Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94137.18.3 Making Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94137.18.4 Manipulating Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94237.18.5 Button Buffer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943

37.19 Abstract Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94437.19.1 Abstract Display Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94537.19.2 Abstract Display Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946

37.20 Blinking Parentheses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94837.21 Character Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949

37.21.1 Usual Display Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94937.21.2 Display Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95137.21.3 Active Display Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95237.21.4 Glyphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .