-
-
Notifications
You must be signed in to change notification settings - Fork 39
/
vol1.texi
1548 lines (1270 loc) · 70.5 KB
/
vol1.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo @c -*-texinfo-*-
@c This file is used for printing the GNU Emacs Lisp Reference Manual
@c in two volumes. It is a modified version of elisp.texi.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
@c Free Software Foundation, Inc.
@c %**start of header
@setfilename elisp
@settitle GNU Emacs Lisp Reference Manual: Volume 1
@c %**end of header
@c See two-volume-cross-refs.txt.
@tex
\message{Formatting for two volume edition...Volume 1...}
%
% Read special toc file, set up in two-volume.make.
\gdef\tocreadfilename{elisp1-toc-ready.toc}
%
% Don't make outlines, they're not needed and \readdatafile can't pay
% attention to the special definition above.
\global\let\pdfmakeoutlines=\relax
%
% Start volume 1 chapter numbering at 1; this must be listed as chapno0.
\global\chapno=0
@end tex
@c Version of the manual and of Emacs.
@c Please remember to update the edition number in README as well.
@set VERSION 3.0
@set EMACSVER 23.1.94
@set DATE July 2009
@dircategory Emacs
@direntry
* Elisp: (elisp). The Emacs Lisp Reference Manual.
@end direntry
@c in general, keep the following line commented out, unless doing a
@c copy of this manual that will be published. the manual should go
@c onto the distribution in the full, 8.5 x 11" size.
@set smallbook
@ifset smallbook
@smallbook
@end ifset
@c per rms and peterb, use 10pt fonts for the main text, mostly to
@c save on paper cost.
@c Do this inside @tex for now, so current makeinfo does not complain.
@tex
@ifset smallbook
@fonttextsize 10
\global\let\urlcolor=\Black % don't print links in grayscale
\global\let\linkcolor=\Black
@end ifset
\global\hbadness=6666 % don't worry about not-too-underfull boxes
@end tex
@c Combine indices.
@synindex cp fn
@syncodeindex vr fn
@syncodeindex ky fn
@syncodeindex pg fn
@c We use the "type index" to index new functions and variables.
@c @syncodeindex tp fn
@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, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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.3 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 the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
@end quotation
@end copying
@titlepage
@title GNU Emacs Lisp Reference Manual
@subtitle Volume 1
@subtitle For Emacs Version @value{EMACSVER}
@subtitle Revision @value{VERSION}, @value{DATE}
@author by Bil Lewis, Dan LaLiberte, Richard Stallman
@author and the GNU Manual Group
@page
@vskip 0pt plus 1filll
@insertcopying
@sp 2
Published by the Free Software Foundation @*
51 Franklin St, Fifth Floor @*
Boston, MA 02110-1301 @*
USA @*
ISBN 1-882114-74-4
@sp 2
Cover art by Etienne Suvasa.
@end titlepage
@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
* Introduction:: Introduction and conventions used.
* Lisp Data Types:: Data types of objects in Emacs Lisp.
* Numbers:: Numbers and arithmetic functions.
* Strings and Characters:: Strings, and functions that work on them.
* Lists:: Lists, cons cells, and related functions.
* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences.
Certain functions act on any kind of sequence.
The description of vectors is here as well.
* Hash Tables:: Very fast lookup-tables.
* Symbols:: Symbols represent names, uniquely.
* Evaluation:: How Lisp expressions are evaluated.
* Control Structures:: Conditionals, loops, nonlocal exits.
* Variables:: Using symbols in programs to stand for values.
* Functions:: A function is a Lisp program
that can be invoked from other functions.
* Macros:: Macros are a way to extend the Lisp language.
* Customization:: Writing customization declarations.
* Loading:: Reading files of Lisp code into Lisp.
* Byte Compilation:: Compilation makes programs run faster.
* Advising Functions:: Adding to the definition of a function.
* Debugging:: Tools and tips for debugging Lisp programs.
* Read and Print:: Converting Lisp objects to text and back.
* Minibuffers:: Using the minibuffer to read input.
* Command Loop:: How the editor command loop works,
and how you can call its subroutines.
* Keymaps:: Defining the bindings from keys to commands.
* Modes:: Defining major and minor modes.
* Documentation:: Writing and using documentation strings.
* Files:: Accessing files.
* Backups and Auto-Saving:: Controlling how backups and auto-save
files are made.
* Buffers:: Creating and using buffer objects.
* Windows:: Manipulating windows and displaying buffers.
* Frames:: Making multiple system-level windows.
* Positions:: Buffer positions and motion functions.
* Markers:: Markers represent positions and update
automatically when the text is changed.
* Text:: Examining and changing text in buffers.
* Non-ASCII Characters:: Non-ASCII text in buffers and strings.
* Searching and Matching:: Searching buffers for strings or regexps.
* Syntax Tables:: The syntax table controls word and list parsing.
* Abbrevs:: How Abbrev mode works, and its data structures.
* Processes:: Running and communicating with subprocesses.
* Display:: Features for controlling the screen display.
* System Interface:: Getting the user id, system type, environment
variables, and other such things.
Appendices
* Antinews:: Info for users downgrading to Emacs 22.
* GNU Free Documentation License:: The license for this documentation.
* GPL:: Conditions for copying and changing GNU Emacs.
* Tips:: Advice and coding conventions for Emacs Lisp.
* GNU Emacs Internals:: Building and dumping Emacs;
internal data structures.
* Standard Errors:: List of all error symbols.
* Standard Buffer-Local Variables::
List of variables buffer-local in all buffers.
* Standard Keymaps:: List of standard keymaps.
* Standard Hooks:: List of standard hook variables.
* Index:: Index including concepts, functions, variables,
and other terms.
@ignore
* New Symbols:: New functions and variables in Emacs @value{EMACSVER}.
@end ignore
@c Do NOT modify the following 3 lines! They must have this form to
@c be correctly identified by `texinfo-multiple-files-update'. In
@c particular, the detailed menu header line MUST be identical to the
@c value of `texinfo-master-menu-header'. See texnfo-upd.el.
@detailmenu
--- The Detailed Node Listing ---
---------------------------------
Here are other nodes that are inferiors of those already listed,
mentioned here so you can get to them in one step:
Introduction
* Caveats:: Flaws and a request for help.
* Lisp History:: Emacs Lisp is descended from Maclisp.
* Conventions:: How the manual is formatted.
* Version Info:: Which Emacs version is running?
* Acknowledgements:: The authors, editors, and sponsors of this manual.
Conventions
* Some Terms:: Explanation of terms we use in this manual.
* nil and t:: How the symbols @code{nil} and @code{t} are used.
* Evaluation Notation:: The format we use for examples of evaluation.
* Printing Notation:: The format we use when examples print text.
* Error Messages:: The format we use for examples of errors.
* Buffer Text Notation:: The format we use for buffer contents in examples.
* Format of Descriptions:: Notation for describing functions, variables, etc.
Format of Descriptions
* A Sample Function Description:: A description of an imaginary
function, @code{foo}.
* A Sample Variable Description:: A description of an imaginary
variable, @code{electric-future-map}.
Lisp Data Types
* Printed Representation:: How Lisp objects are represented as text.
* Comments:: Comments and their formatting conventions.
* Programming Types:: Types found in all Lisp systems.
* Editing Types:: Types specific to Emacs.
* Circular Objects:: Read syntax for circular structure.
* Type Predicates:: Tests related to types.
* Equality Predicates:: Tests of equality between any two objects.
Programming Types
* Integer Type:: Numbers without fractional parts.
* Floating Point Type:: Numbers with fractional parts and with a large range.
* Character Type:: The representation of letters, numbers and
control characters.
* Symbol Type:: A multi-use object that refers to a function,
variable, or property list, and has a unique identity.
* 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.
* 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.
Character Type
* Basic Char Syntax:: Syntax for regular characters.
* General Escape Syntax:: How to specify characters by their codes.
* Ctl-Char Syntax:: Syntax for control characters.
* Meta-Char Syntax:: Syntax for meta-characters.
* Other Char Bits:: Syntax for hyper-, super-, and alt-characters.
Cons Cell and List Types
* Box Diagrams:: Drawing pictures of lists.
* Dotted Pair Notation:: A general syntax for cons cells.
* Association List Type:: A specially constructed list.
String Type
* Syntax for Strings:: How to specify Lisp strings.
* Non-ASCII in Strings:: International characters in strings.
* Nonprinting Characters:: Literal unprintable characters in strings.
* Text Props and Strings:: Strings with text properties.
Editing Types
* Buffer Type:: The basic object of editing.
* Marker Type:: A position in a buffer.
* Window Type:: Buffers are displayed in windows.
* Frame Type:: Windows subdivide frames.
* Terminal Type:: A terminal device displays frames.
* Window Configuration Type:: Recording the way a frame is subdivided.
* Frame Configuration Type:: Recording the status of all frames.
* Process Type:: A subprocess of Emacs running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
* Overlay Type:: How an overlay is represented.
* Font Type:: Fonts for displaying text.
Numbers
* Integer Basics:: Representation and range of integers.
* Float Basics:: Representation and range of floating point.
* Predicates on Numbers:: Testing for numbers.
* Comparison of Numbers:: Equality and inequality predicates.
* 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.
* Math Functions:: Trig, exponential and logarithmic functions.
* Random Numbers:: Obtaining random integers, predictable or not.
Strings and Characters
* String Basics:: Basic properties of strings and characters.
* Predicates for Strings:: Testing whether an object is a string or char.
* Creating Strings:: Functions to allocate new strings.
* Modifying Strings:: Altering the contents of an existing string.
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting to and from characters and strings.
* 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.
* List-related Predicates:: Is this object a list? Comparing two lists.
* List Elements:: Extracting the pieces of a list.
* Building Lists:: Creating list structure.
* List Variables:: Modifying lists stored in variables.
* 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
* Setcar:: Replacing an element in a list.
* Setcdr:: Replacing part of the list backbone.
This can be used to remove or add elements.
* Rearrangement:: Reordering the elements in a list; combining lists.
Sequences, Arrays, and Vectors
* Sequence Functions:: Functions that accept any kind of sequence.
* Arrays:: Characteristics of arrays in Emacs Lisp.
* Array Functions:: Functions specifically for arrays.
* Vectors:: Special characteristics of Emacs Lisp 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
* Symbol Components:: Symbols have names, values, function definitions
and property lists.
* Definitions:: A definition says how a symbol will be used.
* Creating Symbols:: How symbols are kept unique.
* Property Lists:: Each symbol has a property list
for recording miscellaneous information.
Property Lists
* Plists and Alists:: Comparison of the advantages of property
lists and association lists.
* Symbol Plists:: Functions to access symbols' property lists.
* Other Plists:: Accessing property lists stored elsewhere.
Evaluation
* Intro Eval:: Evaluation in the scheme of things.
* Forms:: How various sorts of objects are evaluated.
* 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,
most of them extremely important.
* Autoloading:: Functions set up to load files
containing their real definitions.
Control Structures
* Sequencing:: Evaluation in textual order.
* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}.
* Combining Conditions:: @code{and}, @code{or}, @code{not}.
* Iteration:: @code{while} loops.
* Nonlocal Exits:: Jumping out of a sequence.
Nonlocal Exits
* Catch and Throw:: Nonlocal exits for the program's own purposes.
* Examples of Catch:: Showing how such nonlocal exits can be written.
* Errors:: How errors are signaled and handled.
* Cleanups:: Arranging to run a cleanup form if an
error happens.
Errors
* Signaling Errors:: How to report an error.
* Processing of Errors:: What Emacs does when you report an error.
* Handling Errors:: How you can trap errors and continue execution.
* Error Symbols:: How errors are classified for trapping them.
Variables
* Global Variables:: Variable values that exist permanently, everywhere.
* Constant Variables:: Certain "variables" have values that never change.
* Local Variables:: Variable values that exist only temporarily.
* Void Variables:: Symbols that lack values.
* Defining Variables:: A definition says a symbol is used as a variable.
* 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.
* File Local Variables:: Handling local variable lists in files.
* Directory Local Variables:: Local variables common to all files in a
directory.
* Frame-Local Variables:: Frame-local bindings for variables.
* 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
is visible. Comparison with other languages.
* Extent:: Extent means how long in time a value exists.
* Impl of Scope:: Two ways to implement dynamic scoping.
* Using Scoping:: How to use dynamic scoping carefully and
avoid problems.
Buffer-Local Variables
* Intro to Buffer-Local:: Introduction and concepts.
* Creating Buffer-Local:: Creating and destroying buffer-local bindings.
* Default Value:: The default value is seen in buffers
that don't have their own buffer-local values.
Functions
* What Is a Function:: Lisp functions vs. primitives; terminology.
* Lambda Expressions:: How functions are expressed as Lisp objects.
* Function Names:: A symbol can serve as the name of a function.
* Defining Functions:: Lisp expressions for defining functions.
* Calling Functions:: How to use an existing function.
* Mapping Functions:: Applying a function to each element of a list, etc.
* Anonymous Functions:: Lambda expressions are functions with no names.
* Function Cells:: Accessing or setting the function definition
of a symbol.
* Obsolete Functions:: Declaring functions obsolete.
* Inline Functions:: Defining functions that the compiler
will open code.
* Declaring Functions:: Telling the compiler that a function is defined.
* Function Safety:: Determining whether a function is safe to call.
* Related Topics:: Cross-references to specific Lisp primitives
that have a special bearing on how
functions work.
Lambda Expressions
* Lambda Components:: The parts of a lambda expression.
* Simple Lambda:: A simple example.
* Argument List:: Details and special features of argument lists.
* Function Documentation:: How to put documentation in a function.
Macros
* Simple Macro:: A basic example.
* Expansion:: How, when and why macros are expanded.
* Compiling Macros:: How macros are expanded by the compiler.
* Defining Macros:: How to write a macro definition.
* Backquote:: Easier construction of list structure.
* Problems with Macros:: Don't evaluate the macro arguments too many times.
Don't hide the user's variables.
* Indenting Macros:: Specifying how to indent macro calls.
Common Problems Using Macros
* Wrong Time:: Do the work in the expansion, not in the macro.
* Argument Evaluation:: The expansion should evaluate each macro arg once.
* Surprising Local Vars:: Local variable bindings in the expansion
require special care.
* Eval During Expansion:: Don't evaluate them; put them in the expansion.
* Repeated Expansion:: Avoid depending on how many times expansion is done.
Writing Customization Definitions
* 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.
Customization Types
* Simple Types:: Simple customization types: sexp, integer, number,
string, file, directory, alist.
* Composite Types:: Build new types from other types or data.
* Splicing into Lists:: Splice elements into list with @code{:inline}.
* Type Keywords:: Keyword-argument pairs in a customization type.
* Defining New Types:: Give your type a name.
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.
* 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 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.
* 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.
* Test Coverage:: Ensuring you have tested all branches in your code.
* Compilation Errors:: How to find errors that show up in
byte compilation.
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.
* Debugger Commands:: Commands used while in the debugger.
* Invoking the Debugger:: How to call the function @code{debug}.
* Internals of Debugger:: Subroutines of the debugger, and global variables.
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.
Breaks
* Breakpoints:: Breakpoints at stop points.
* Global Break Condition:: Breaking on an event.
* Source Breakpoints:: Embedding breakpoints in source code.
The Outside Context
* Checking Whether to Stop::When Edebug decides what to do.
* Edebug Display Update:: When Edebug updates the display.
* Edebug Recursive Edit:: When Edebug stops execution.
Edebug and Macros
* Instrumenting Macro Calls::The basic problem.
* Specification List:: How to specify complex patterns of evaluation.
* Backtracking:: What Edebug does when matching fails.
* Specification Examples:: To help understand specifications.
Debugging Invalid Lisp Syntax
* Excess Open:: How to find a spurious open paren or missing close.
* Excess Close:: How to find a spurious close paren or missing open.
Reading and Printing Lisp Objects
* Streams Intro:: Overview of streams, reading and printing.
* Input Streams:: Various data types that can be used as
input streams.
* Input Functions:: Functions to read Lisp objects from text.
* Output Streams:: Various data types that can be used as
output streams.
* Output Functions:: Functions to print Lisp objects as text.
* 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
* Basic Completion:: Low-level functions for completing strings.
(These are too low level to use the minibuffer.)
* Minibuffer Completion:: Invoking the minibuffer with completion.
* Completion Commands:: Minibuffer commands that do completion.
* High-Level Completion:: Convenient special cases of completion
(reading buffer name, file name, etc.).
* Reading File Names:: Using completion to read file names and
shell commands.
* Completion Styles:: Specifying rules for performing completion.
* Programmed Completion:: Writing your own completion-function.
Command Loop
* Command Overview:: How the command loop reads commands.
* Defining Commands:: Specifying how a function should read arguments.
* Interactive Call:: Calling a command, so that it will read arguments.
* Distinguish Interactive:: Making a command distinguish interactive calls.
* 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.
* Recursive Editing:: Entering a recursive edit,
and why you usually shouldn't.
* Disabling Commands:: How the command loop handles disabled commands.
* Command History:: How the command history is set up, and how accessed.
* Keyboard Macros:: How keyboard macros are implemented.
Defining Commands
* Using Interactive:: General rules for @code{interactive}.
* Interactive Codes:: The standard letter-codes for reading arguments
in various ways.
* Interactive Examples:: Examples of how to read interactive arguments.
Input Events
* Keyboard Events:: Ordinary characters--keys with symbols on them.
* Function Keys:: Function keys--keys with names, not symbols.
* Mouse Events:: Overview of mouse events.
* Click Events:: Pushing and releasing a mouse button.
* Drag Events:: Moving the mouse before releasing the button.
* Button-Down Events:: A button was pushed and not yet released.
* Repeat Events:: Double and triple click (or drag, or down).
* Motion Events:: Just moving the mouse, not pushing a button.
* Focus Events:: Moving the mouse between frames.
* Misc Events:: Other events the system can generate.
* Event Examples:: Examples of the lists for mouse events.
* Classifying Events:: Finding the modifier keys in an event symbol.
Event types.
* Accessing Mouse:: Functions to extract info from mouse events.
* Accessing Scroll:: Functions to get info from scroll bar events.
* Strings of Events:: Special considerations for putting
keyboard character events in a string.
Reading Input
* Key Sequence Input:: How to read one key sequence.
* Reading One Event:: How to read just one event.
* Event Mod:: How Emacs modifies events as they are read.
* Invoking the Input Method:: How reading an event uses the input method.
* Quoted Character Input:: Asking the user to specify a character.
* Event Input Misc:: How to reread or throw away input events.
Keymaps
* Key Sequences:: Key sequences as Lisp objects.
* Keymap Basics:: Basic concepts of keymaps.
* Format of Keymaps:: What a keymap looks like as a Lisp object.
* Creating Keymaps:: Functions to create and copy keymaps.
* Inheritance and Keymaps:: How one keymap can inherit the bindings
of another keymap.
* Prefix Keys:: Defining a key with a keymap as its definition.
* Active Keymaps:: How Emacs searches the active keymaps
for a key binding.
* Searching Keymaps:: A pseudo-Lisp summary of searching active maps.
* Controlling Active Maps:: Each buffer has a local keymap
to override the standard (global) bindings.
A minor mode can also override them.
* Key Lookup:: Finding a key's binding in one keymap.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
* Remapping Commands:: A keymap can translate one command to another.
* Translation Keymaps:: Keymaps for translating sequences of events.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
* Menu Keymaps:: Defining a menu as a keymap.
Menu Keymaps
* Defining Menus:: How to make a keymap that defines a menu.
* Mouse Menus:: How users actuate the menu with the mouse.
* Keyboard Menus:: How users actuate the menu with the keyboard.
* Menu Example:: Making a simple menu.
* Menu Bar:: How to customize the menu bar.
* Tool Bar:: A tool bar is a row of images.
* Modifying Menus:: How to add new items to a menu.
Defining Menus
* Simple Menu Items:: A simple kind of menu key binding,
limited in capabilities.
* Extended Menu Items:: More powerful menu item definitions
let you specify keywords to enable
various features.
* Menu Separators:: Drawing a horizontal line through a menu.
* Alias Menu Items:: Using command aliases in menu items.
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.
* 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.
Hooks
* Running Hooks:: How to run a hook.
* Setting Hooks:: How to put functions on a hook, or remove them.
Major Modes
* Major Mode Basics::
* Major Mode Conventions:: Coding conventions for keymaps, etc.
* 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.
* Example Major Modes:: Text mode and Lisp modes.
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:: Basic ideas of mode line control.
* Mode Line Data:: The data structure that controls the mode line.
* Mode Line Top:: The top level variable, mode-line-format.
* 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.
Font Lock Mode
* Font Lock Basics:: Overview of customizing Font Lock.
* Search-based Fontification:: Fontification based on regexps.
* Customizing Keywords:: Customizing search-based fontification.
* Other Font Lock Variables:: Additional customization facilities.
* Levels of Font Lock:: Each mode can define alternative levels
so that the user can select more or less.
* Precalculated Fontification:: How Lisp programs that produce the buffer
contents can also specify how to fontify it.
* Faces for Font Lock:: Special faces specifically for Font Lock.
* Syntactic Font Lock:: Fontification based on syntax tables.
* Setting Syntax Properties:: Defining character syntax based on context
using the Font Lock mechanism.
* Multiline Font Lock:: How to coerce Font Lock into properly
highlighting multiline constructs.
Multiline Font Lock Constructs
* Font Lock Multiline:: Marking multiline chunks with a text property.
* Region to Fontify:: Controlling which region gets refontified
after a buffer change.
Documentation
* Documentation Basics:: Good style for doc strings.
Where to put them. How Emacs stores them.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
* Describing Characters:: Making printable descriptions of
non-printing characters and key sequences.
* Help Functions:: Subroutines used by Emacs help facilities.
Files
* Visiting Files:: Reading files into Emacs buffers for editing.
* Saving Buffers:: Writing changed buffers back into files.
* Reading from Files:: Reading files into buffers without visiting.
* 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.
* 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
* Visiting Functions:: The usual interface functions for visiting.
* Subroutines of Visiting:: Lower-level subroutines that they use.
Information about Files
* Testing Accessibility:: Is a given file readable? Writable?
* Kinds of Files:: Is it a directory? A symbolic link?
* Truenames:: Eliminating symbolic links from a file name.
* File Attributes:: How large is it? Any other names? Etc.
* Locating Files:: How to find a file in standard places.
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.
* 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.
File Format Conversion
* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}.
* Format Conversion Round-Trip:: Using @code{format-alist}.
* Format Conversion Piecemeal:: Specifying non-paired conversion.
Backups and Auto-Saving
* Backup Files:: How backup files are made; how their names
are chosen.
* Auto-Saving:: How auto-save files are made; how their
names are chosen.
* Reverting:: @code{revert-buffer}, and how to customize
what it does.
Backup Files
* Making Backups:: How Emacs makes backup files, and when.
* Rename or Copy:: Two alternatives: renaming the old file
or copying it.
* Numbered Backups:: Keeping multiple backups for each source file.
* Backup Names:: How backup file names are computed; customization.
Buffers
* Buffer Basics:: What is a buffer?
* Current Buffer:: Designating a buffer as current
so that primitives will access its contents.
* Buffer Names:: Accessing and changing buffer names.
* Buffer File Name:: The buffer file name indicates which file
is visited.
* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
* Modification Time:: Determining whether the visited file was changed
``behind Emacs's back''.
* Read Only Buffers:: Modifying text is not allowed in a
read-only buffer.
* The Buffer List:: How to look at all the existing buffers.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some
other buffer.
* Swapping Text:: Swapping text between two buffers.
* Buffer Gap:: The gap in the buffer.
Windows
* Basic Windows:: Basic information on using windows.
* Splitting Windows:: Splitting one window into two windows.
* Deleting Windows:: Deleting a window gives its space to other windows.
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
* Displaying Buffers:: Higher-level functions for displaying a buffer
and choosing a window for it.
* Choosing Window:: How to choose a window for displaying a buffer.
* Dedicated Windows:: How to avoid displaying another buffer in
a specific window.
* Window Point:: Each window has its own location of point.
* Window Start and End:: Buffer positions indicating which text is
on-screen in a 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 Tree:: The layout and sizes of all windows in a frame.
* Window Configurations:: Saving and restoring the state of the screen.
* Window Parameters:: Associating additional information with windows.
* Window Hooks:: Hooks for scrolling, window size changes,
redisplay going past a certain point,
or window configuration changes.
Frames
* Creating Frames:: Creating additional frames.
* Multiple Terminals:: Displaying on several different devices.
* Frame Parameters:: Controlling frame size, position, font, etc.
* Terminal Parameters:: Parameters common for all frames on terminal.
* Frame Titles:: Automatic updating of frame titles.
* Deleting Frames:: Frames last until explicitly deleted.
* Finding All Frames:: How to examine all existing frames.
* Frames and Windows:: A frame contains windows;
display of text always works through windows.
* Minibuffers and Frames:: How a frame finds the minibuffer to use.
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
* Raising and Lowering:: Raising a frame makes it hide other windows;
lowering it makes the others hide it.
* Frame Configurations:: Saving the state of all frames.
* Mouse Tracking:: Getting events that say when the mouse moves.
* Mouse Position:: Asking where the mouse is, or moving it.
* Pop-Up Menus:: Displaying a menu for the user to select from.
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shape:: Specifying the shape of the mouse pointer.
* Window System Selections::Transferring text to and from other X clients.
* Drag and Drop:: Internals of Drag-and-Drop implementation.