comparison man/lispref/lispref.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children 05472e90ae02
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1 \input ../texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename ../../info/lispref.info
4 @c @smallbook
5 @settitle XEmacs Lisp Reference Manual
6 @c %**end of header
7
8 @ifinfo
9 Edition History:
10
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993
12 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993
13 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995
16 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995
17 XEmacs Lisp Programmer's Manual (for 19.14) v3.1, March 1996
18 @c Please REMEMBER to update edition number in *four* places in this file
19 @c and also in *one* place in intro.texi
20
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
22 Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
24
25
26 Permission is granted to make and distribute verbatim copies of this
27 manual provided the copyright notice and this permission notice are
28 preserved on all copies.
29
30 @ignore
31 Permission is granted to process this file through TeX and print the
32 results, provided the printed document carries copying permission notice
33 identical to this one except for the removal of this paragraph (this
34 paragraph not being relevant to the printed manual).
35
36 @end ignore
37 Permission is granted to copy and distribute modified versions of this
38 manual under the conditions for verbatim copying, provided that the
39 entire resulting derived work is distributed under the terms of a
40 permission notice identical to this one.
41
42 Permission is granted to copy and distribute translations of this manual
43 into another language, under the above conditions for modified versions,
44 except that this permission notice may be stated in a translation
45 approved by the Foundation.
46
47 Permission is granted to copy and distribute modified versions of this
48 manual under the conditions for verbatim copying, provided also that the
49 section entitled ``GNU General Public License'' is included exactly as
50 in the original, and provided that the entire resulting derived work is
51 distributed under the terms of a permission notice identical to this
52 one.
53
54 Permission is granted to copy and distribute translations of this manual
55 into another language, under the above conditions for modified versions,
56 except that the section entitled ``GNU General Public License'' may be
57 included in a translation approved by the Free Software Foundation
58 instead of in the original English.
59 @end ifinfo
60
61 @c Combine indices.
62 @synindex cp fn
63 @syncodeindex vr fn
64 @syncodeindex ky fn
65 @syncodeindex pg fn
66 @syncodeindex tp fn
67
68 @setchapternewpage odd
69 @finalout
70
71 @titlepage
72 @title XEmacs Lisp Reference Manual
73 @c The edition number appears in several places in this file
74 @c and also in the file intro.texi.
75 @c This manual documents XEmacs 19.14 and was based on the
76 @c documentation for FSF Emacs 19.29 (v2.4).
77 @subtitle Version 3.1 (for XEmacs 19.14), March 1996
78
79 @author by Ben Wing
80 @author
81 @author Based on the GNU Emacs Lisp Reference Manual
82 @author by Bil Lewis, Dan LaLiberte, Richard Stallman
83 @author and the GNU Manual Group
84 @page
85 @vskip 0pt plus 1filll
86 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
87 Copyright @copyright{} 1994, 1995 Sun Microsystems, Inc.
88 Copyright @copyright{} 1995, 1996 Ben Wing.
89 @sp 2
90 Version 3.1 @*
91 Revised for XEmacs Version 19.14,@*
92 March, 1996.@*
93
94 Permission is granted to make and distribute verbatim copies of this
95 manual provided the copyright notice and this permission notice are
96 preserved on all copies.
97
98 Permission is granted to copy and distribute modified versions of this
99 manual under the conditions for verbatim copying, provided also that the
100 section entitled ``GNU General Public License'' is included
101 exactly as in the original, and provided that the entire resulting
102 derived work is distributed under the terms of a permission notice
103 identical to this one.
104
105 Permission is granted to copy and distribute translations of this manual
106 into another language, under the above conditions for modified versions,
107 except that the section entitled ``GNU General Public License'' may be
108 included in a translation approved by the Free Software Foundation
109 instead of in the original English.
110
111 Cover art by Etienne Suvasa.
112 @end titlepage
113 @page
114
115 @node Top, Copying, (dir), (dir)
116
117 @ifinfo
118 This Info file contains the third edition of the XEmacs Lisp
119 Reference Manual, corresponding to XEmacs version 19.14.
120 @end ifinfo
121
122 @menu
123 * Copying:: Conditions for copying and changing XEmacs.
124 * Introduction:: Introduction and conventions used.
125
126 * Lisp Data Types:: Data types of objects in XEmacs Lisp.
127 * Numbers:: Numbers and arithmetic functions.
128 * Strings and Characters:: Strings, and functions that work on them.
129 * Lists:: Lists, cons cells, and related functions.
130 * Sequences Arrays Vectors:: Lists, strings and vectors are called sequences.
131 Certain functions act on any kind of sequence.
132 The description of vectors is here as well.
133 * Symbols:: Symbols represent names, uniquely.
134
135 * Evaluation:: How Lisp expressions are evaluated.
136 * Control Structures:: Conditionals, loops, nonlocal exits.
137 * Variables:: Using symbols in programs to stand for values.
138 * Functions:: A function is a Lisp program
139 that can be invoked from other functions.
140 * Macros:: Macros are a way to extend the Lisp language.
141
142 * Loading:: Reading files of Lisp code into Lisp.
143 * Byte Compilation:: Compilation makes programs run faster.
144 * Debugging:: Tools and tips for debugging Lisp programs.
145
146 * Read and Print:: Converting Lisp objects to text and back.
147 * Minibuffers:: Using the minibuffer to read input.
148 * Command Loop:: How the editor command loop works,
149 and how you can call its subroutines.
150 * Keymaps:: Defining the bindings from keys to commands.
151 * Menus:: Defining pull-down and pop-up menus.
152 * Dialog Boxes:: Creating dialog boxes.
153 * Toolbar:: Controlling the toolbar.
154 * Scrollbars:: Controlling the scrollbars.
155 * Modes:: Defining major and minor modes.
156 * Documentation:: Writing and using documentation strings.
157
158 * Files:: Accessing files.
159 * Backups and Auto-Saving:: Controlling how backups and auto-save
160 files are made.
161 * Buffers:: Creating and using buffer objects.
162 * Windows:: Manipulating windows and displaying buffers.
163 * Frames:: Making multiple X windows.
164 * Consoles and Devices:: Opening frames on multiple TTY's or X displays.
165 * Positions:: Buffer positions and motion functions.
166 * Markers:: Markers represent positions and update
167 automatically when the text is changed.
168
169 * Text:: Examining and changing text in buffers.
170 * Searching and Matching:: Searching buffers for strings or regexps.
171 * Syntax Tables:: The syntax table controls word and list parsing.
172 * Abbrevs:: How Abbrev mode works, and its data structures.
173
174 * Extents:: Extents are regions of text with particular
175 display characteristics.
176 * Specifiers:: How faces and glyphs are specified.
177 * Faces and Window-System Objects::
178 A face is a set of display characteristics
179 specifying how text is to be displayed.
180 * Glyphs:: General interface to pixmaps displayed in a
181 buffer or frame.
182 * Annotations:: Higher-level interface to glyphs in a buffer.
183 * Display:: Parameters controlling screen usage.
184 The bell. Waiting for input.
185
186 * Hash Tables:: Fast data structures for mappings.
187 * Range Tables:: Keeping track of ranges of numbers.
188 * Databases:: An interface to standard DBM and DB databases.
189
190 * Processes:: Running and communicating with subprocesses.
191 * System Interface:: Getting the user id, system type, environment
192 variables, and other such things.
193 * X-Windows:: Functions specific to the X Window System.
194 * ToolTalk Support:: Interfacing with the ToolTalk message service.
195 * Internationalization:: How Emacs supports different languages and
196 cultural conventions.
197 * MULE:: Specifics of the Asian-language support.
198
199 Appendices
200
201 * Tips:: Advice for writing Lisp programs.
202 * Building XEmacs and Object Allocation::
203 Behind-the-scenes information about XEmacs.
204 * Standard Errors:: List of all error symbols.
205 * Standard Buffer-Local Variables:: List of variables local in all buffers.
206 * Standard Keymaps:: List of standard keymaps.
207 * Standard Hooks:: List of standard hook variables.
208
209 * Index:: Index including concepts, functions, variables,
210 and other terms.
211
212 --- The Detailed Node Listing ---
213
214 Here are other nodes that are inferiors of those already listed,
215 mentioned here so you can get to them in one step:
216
217 Introduction
218
219 * Caveats:: Flaws and a request for help.
220 * Lisp History:: XEmacs Lisp is descended from Maclisp.
221 * Conventions:: How the manual is formatted.
222 * Acknowledgements:: The authors, editors, and sponsors of this manual.
223
224 Conventions
225
226 * Some Terms:: Explanation of terms we use in this manual.
227 * nil and t:: How the symbols @code{nil} and @code{t} are used.
228 * Evaluation Notation:: The format we use for examples of evaluation.
229 * Printing Notation:: The format we use for examples that print output.
230 * Error Messages:: The format we use for examples of errors.
231 * Buffer Text Notation:: The format we use for buffer contents in examples.
232 * Format of Descriptions:: Notation for describing functions, variables, etc.
233
234 Format of Descriptions
235
236 * A Sample Function Description::
237 * A Sample Variable Description::
238
239 Lisp Data Types
240
241 * Printed Representation:: How Lisp objects are represented as text.
242 * Comments:: Comments and their formatting conventions.
243 * Programming Types:: Types found in all Lisp systems.
244 * Editing Types:: Types specific to XEmacs.
245 * Type Predicates:: Tests related to types.
246 * Equality Predicates:: Tests of equality between any two objects.
247
248 Programming Types
249
250 * Integer Type:: Numbers without fractional parts.
251 * Floating Point Type:: Numbers with fractional parts and with a large range.
252 * Character Type:: The representation of letters, numbers and
253 control characters.
254 * Sequence Type:: Both lists and arrays are classified as sequences.
255 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
256 * Array Type:: Arrays include strings and vectors.
257 * String Type:: An (efficient) array of characters.
258 * Vector Type:: One-dimensional arrays.
259 * Symbol Type:: A multi-use object that refers to a function,
260 variable, property list, or itself.
261 * Function Type:: A piece of executable code you can call from elsewhere.
262 * Macro Type:: A method of expanding an expression into another
263 expression, more fundamental but less pretty.
264 * Primitive Function Type:: A function written in C, callable from Lisp.
265 * Compiled-Function Type:: A function written in Lisp, then compiled.
266 * Autoload Type:: A type used for automatically loading seldom-used
267 functions.
268
269 Cons Cell Type
270
271 * Dotted Pair Notation:: An alternative syntax for lists.
272 * Association List Type:: A specially constructed list.
273
274 Editing Types
275
276 * Buffer Type:: The basic object of editing.
277 * Window Type:: What makes buffers visible.
278 * Window Configuration Type::Save what the screen looks like.
279 * Marker Type:: A position in a buffer.
280 * Process Type:: A process running on the underlying OS.
281 * Stream Type:: Receive or send characters.
282 * Keymap Type:: What function a keystroke invokes.
283 * Syntax Table Type:: What a character means.
284
285 Numbers
286
287 * Integer Basics:: Representation and range of integers.
288 * Float Basics:: Representation and range of floating point.
289 * Predicates on Numbers:: Testing for numbers.
290 * Comparison of Numbers:: Equality and inequality predicates.
291 * Arithmetic Operations:: How to add, subtract, multiply and divide.
292 * Bitwise Operations:: Logical and, or, not, shifting.
293 * Numeric Conversions:: Converting float to integer and vice versa.
294 * Math Functions:: Trig, exponential and logarithmic functions.
295 * Random Numbers:: Obtaining random integers, predictable or not.
296
297 Strings and Characters
298
299 * Basics: String Basics. Basic properties of strings and characters.
300 * Predicates for Strings:: Testing whether an object is a string or char.
301 * Creating Strings:: Functions to allocate new strings.
302 * Predicates for Characters:: Testing whether an object is a character.
303 * Character Codes:: Each character has an equivalent integer.
304 * Text Comparison:: Comparing characters or strings.
305 * String Conversion:: Converting characters or strings and vice versa.
306 * Modifying Strings:: Changing characters in a string.
307 * String Properties:: Additional information attached to strings.
308 * Formatting Strings:: @code{format}: XEmacs's analog of @code{printf}.
309 * Character Case:: Case conversion functions.
310 * Char Tables:: Mapping from characters to Lisp objects.
311 * Case Tables:: Customizing case conversion.
312
313 Lists
314
315 * Cons Cells:: How lists are made out of cons cells.
316 * Lists as Boxes:: Graphical notation to explain lists.
317 * List-related Predicates:: Is this object a list? Comparing two lists.
318 * List Elements:: Extracting the pieces of a list.
319 * Building Lists:: Creating list structure.
320 * Modifying Lists:: Storing new pieces into an existing list.
321 * Sets And Lists:: A list can represent a finite mathematical set.
322 * Association Lists:: A list can represent a finite relation or mapping.
323 * Property Lists:: A different way to represent a finite mapping.
324 * Weak Lists:: A list with special garbage-collection behavior.
325
326 Modifying Existing List Structure
327
328 * Setcar:: Replacing an element in a list.
329 * Setcdr:: Replacing part of the list backbone.
330 This can be used to remove or add elements.
331 * Rearrangement:: Reordering the elements in a list; combining lists.
332
333 Sequences, Arrays, and Vectors
334
335 * Sequence Functions:: Functions that accept any kind of sequence.
336 * Arrays:: Characteristics of arrays in XEmacs Lisp.
337 * Array Functions:: Functions specifically for arrays.
338 * Vectors:: Functions specifically for vectors.
339
340 Symbols
341
342 * Symbol Components:: Symbols have names, values, function definitions
343 and property lists.
344 * Definitions:: A definition says how a symbol will be used.
345 * Creating Symbols:: How symbols are kept unique.
346 * Symbol Properties:: Each symbol has a property list
347 for recording miscellaneous information.
348
349 Evaluation
350
351 * Intro Eval:: Evaluation in the scheme of things.
352 * Eval:: How to invoke the Lisp interpreter explicitly.
353 * Forms:: How various sorts of objects are evaluated.
354 * Quoting:: Avoiding evaluation (to put constants in
355 the program).
356
357 Kinds of Forms
358
359 * Self-Evaluating Forms:: Forms that evaluate to themselves.
360 * Symbol Forms:: Symbols evaluate as variables.
361 * Classifying Lists:: How to distinguish various sorts of list forms.
362 * Function Forms:: Forms that call functions.
363 * Macro Forms:: Forms that call macros.
364 * Special Forms:: ``Special forms'' are idiosyncratic primitives,
365 most of them extremely important.
366 * Autoloading:: Functions set up to load files
367 containing their real definitions.
368
369 Control Structures
370
371 * Sequencing:: Evaluation in textual order.
372 * Conditionals:: @code{if}, @code{cond}.
373 * Combining Conditions:: @code{and}, @code{or}, @code{not}.
374 * Iteration:: @code{while} loops.
375 * Nonlocal Exits:: Jumping out of a sequence.
376
377 Nonlocal Exits
378
379 * Catch and Throw:: Nonlocal exits for the program's own purposes.
380 * Examples of Catch:: Showing how such nonlocal exits can be written.
381 * Errors:: How errors are signaled and handled.
382 * Cleanups:: Arranging to run a cleanup form if an
383 error happens.
384
385 Errors
386
387 * Signaling Errors:: How to report an error.
388 * Processing of Errors:: What XEmacs does when you report an error.
389 * Handling Errors:: How you can trap errors and continue execution.
390 * Error Symbols:: How errors are classified for trapping them.
391
392 Variables
393
394 * Global Variables:: Variable values that exist permanently, everywhere.
395 * Constant Variables:: Certain "variables" have values that never change.
396 * Local Variables:: Variable values that exist only temporarily.
397 * Void Variables:: Symbols that lack values.
398 * Defining Variables:: A definition says a symbol is used as a variable.
399 * Accessing Variables:: Examining values of variables whose names
400 are known only at run time.
401 * Setting Variables:: Storing new values in variables.
402 * Variable Scoping:: How Lisp chooses among local and global values.
403 * Buffer-Local Variables:: Variable values in effect only in one buffer.
404
405 Scoping Rules for Variable Bindings
406
407 * Scope:: Scope means where in the program a value
408 is visible. Comparison with other languages.
409 * Extent:: Extent means how long in time a value exists.
410 * Impl of Scope:: Two ways to implement dynamic scoping.
411 * Using Scoping:: How to use dynamic scoping carefully and
412 avoid problems.
413
414 Buffer-Local Variables
415
416 * Intro to Buffer-Local:: Introduction and concepts.
417 * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
418 * Default Value:: The default value is seen in buffers
419 that don't have their own local values.
420
421 Functions
422
423 * What Is a Function:: Lisp functions vs primitives; terminology.
424 * Lambda Expressions:: How functions are expressed as Lisp objects.
425 * Function Names:: A symbol can serve as the name of a function.
426 * Defining Functions:: Lisp expressions for defining functions.
427 * Calling Functions:: How to use an existing function.
428 * Mapping Functions:: Applying a function to each element of a list, etc.
429 * Anonymous Functions:: Lambda-expressions are functions with no names.
430 * Function Cells:: Accessing or setting the function definition
431 of a symbol.
432 * Related Topics:: Cross-references to specific Lisp primitives
433 that have a special bearing on how
434 functions work.
435
436 Lambda Expressions
437
438 * Lambda Components:: The parts of a lambda expression.
439 * Simple Lambda:: A simple example.
440 * Argument List:: Details and special features of argument lists.
441 * Function Documentation:: How to put documentation in a function.
442
443 Macros
444
445 * Simple Macro:: A basic example.
446 * Expansion:: How, when and why macros are expanded.
447 * Compiling Macros:: How macros are expanded by the compiler.
448 * Defining Macros:: How to write a macro definition.
449 * Backquote:: Easier construction of list structure.
450 * Problems with Macros:: Don't evaluate the macro arguments too many times.
451 Don't hide the user's variables.
452
453 Loading
454
455 * How Programs Do Loading:: The @code{load} function and others.
456 * Autoload:: Setting up a function to autoload.
457 * Named Features:: Loading a library if it isn't already loaded.
458 * Repeated Loading:: Precautions about loading a file twice.
459
460 Byte Compilation
461
462 * Compilation Functions:: Byte compilation functions.
463 * Disassembly:: Disassembling byte-code; how to read byte-code.
464
465 Debugging Lisp Programs
466
467 * Debugger:: How the XEmacs Lisp debugger is implemented.
468 * Syntax Errors:: How to find syntax errors.
469 * Compilation Errors:: How to find errors that show up in
470 byte compilation.
471 * Edebug:: A source-level XEmacs Lisp debugger.
472
473 The Lisp Debugger
474
475 * Error Debugging:: Entering the debugger when an error happens.
476 * Function Debugging:: Entering it when a certain function is called.
477 * Explicit Debug:: Entering it at a certain point in the program.
478 * Using Debugger:: What the debugger does; what you see while in it.
479 * Debugger Commands:: Commands used while in the debugger.
480 * Invoking the Debugger:: How to call the function @code{debug}.
481 * Internals of Debugger:: Subroutines of the debugger, and global variables.
482
483 Debugging Invalid Lisp Syntax
484
485 * Excess Open:: How to find a spurious open paren or missing close.
486 * Excess Close:: How to find a spurious close paren or missing open.
487
488 Reading and Printing Lisp Objects
489
490 * Streams Intro:: Overview of streams, reading and printing.
491 * Input Streams:: Various data types that can be used as
492 input streams.
493 * Input Functions:: Functions to read Lisp objects from text.
494 * Output Streams:: Various data types that can be used as
495 output streams.
496 * Output Functions:: Functions to print Lisp objects as text.
497
498 Minibuffers
499
500 * Intro to Minibuffers:: Basic information about minibuffers.
501 * Text from Minibuffer:: How to read a straight text string.
502 * Object from Minibuffer:: How to read a Lisp object or expression.
503 * Completion:: How to invoke and customize completion.
504 * Yes-or-No Queries:: Asking a question with a simple answer.
505 * Minibuffer Misc:: Various customization hooks and variables.
506
507 Completion
508
509 * Basic Completion:: Low-level functions for completing strings.
510 (These are too low level to use the minibuffer.)
511 * Minibuffer Completion:: Invoking the minibuffer with completion.
512 * Completion Commands:: Minibuffer commands that do completion.
513 * High-Level Completion:: Convenient special cases of completion
514 (reading buffer name, file name, etc.)
515 * Reading File Names:: Using completion to read file names.
516 * Programmed Completion:: Finding the completions for a given file name.
517
518 Command Loop
519
520 * Command Overview:: How the command loop reads commands.
521 * Defining Commands:: Specifying how a function should read arguments.
522 * Interactive Call:: Calling a command, so that it will read arguments.
523 * Command Loop Info:: Variables set by the command loop for you to examine.
524 * Events:: What input looks like when you read it.
525 * Reading Input:: How to read input events from the keyboard or mouse.
526 * Waiting:: Waiting for user input or elapsed time.
527 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
528 * Prefix Command Arguments:: How the commands to set prefix args work.
529 * Recursive Editing:: Entering a recursive edit,
530 and why you usually shouldn't.
531 * Disabling Commands:: How the command loop handles disabled commands.
532 * Command History:: How the command history is set up, and how accessed.
533 * Keyboard Macros:: How keyboard macros are implemented.
534
535 Defining Commands
536
537 * Using Interactive:: General rules for @code{interactive}.
538 * Interactive Codes:: The standard letter-codes for reading arguments
539 in various ways.
540 * Interactive Examples:: Examples of how to read interactive arguments.
541
542 Events
543
544 * Event Types:: Events come in different types.
545 * Event Contents:: What the contents of each event type are.
546 * Event Predicates:: Querying whether an event is of a
547 particular type.
548 * Accessing Mouse Event Positions::
549 Determining where a mouse event occurred,
550 and over what.
551 * Accessing Other Event Info:: Accessing non-positional event info.
552 * Working With Events:: Creating, copying, and destroying events.
553 * Converting Events:: Converting between events, keys, and
554 characters.
555
556 Accessing Mouse Event Positions
557
558 * Frame-Level Event Position Info::
559 * Window-Level Event Position Info::
560 * Event Text Position Info::
561 * Event Glyph Position Info::
562 * Event Toolbar Position Info::
563 * Other Event Position Info::
564
565 Reading Input
566
567 * Key Sequence Input:: How to read one key sequence.
568 * Reading One Event:: How to read just one event.
569 * Dispatching an Event:: What to do with an event once it has been read.
570 * Quoted Character Input:: Asking the user to specify a character.
571 * Peeking and Discarding:: How to reread or throw away input events.
572
573 Keymaps
574
575 * Keymap Terminology:: Definitions of terms pertaining to keymaps.
576 * Format of Keymaps:: What a keymap looks like as a Lisp object.
577 * Creating Keymaps:: Functions to create and copy keymaps.
578 * Inheritance and Keymaps:: How one keymap can inherit the bindings
579 of another keymap.
580 * Key Sequences:: How to specify key sequences.
581 * Prefix Keys:: Defining a key with a keymap as its definition.
582 * Active Keymaps:: Each buffer has a local keymap
583 to override the standard (global) bindings.
584 Each minor mode can also override them.
585 * Key Lookup:: How extracting elements from keymaps works.
586 * Functions for Key Lookup:: How to request key lookup.
587 * Changing Key Bindings:: Redefining a key in a keymap.
588 * Key Binding Commands:: Interactive interfaces for redefining keys.
589 * Scanning Keymaps:: Looking through all keymaps, for printing help.
590 * Other Keymap Functions:: Miscellaneous keymap functions.
591
592 Menus
593
594 * Menu Format:: Format of a menu description.
595 * Menubar Format:: How to specify a menubar.
596 * Menubar:: Functions for controlling the menubar.
597 * Modifying Menus:: Modifying a menu description.
598 * Pop-Up Menus:: Functions for specifying pop-up menus.
599 * Menu Filters:: Filter functions for the default menubar.
600 * Buffers Menu:: The menu that displays the list of buffers.
601
602 Dialog Boxes
603
604 * Dialog Box Format::
605 * Dialog Box Functions::
606
607 Toolbar
608
609 * Toolbar Intro:: An introduction.
610 * Toolbar Descriptor Format:: How to create a toolbar.
611 * Specifying the Toolbar:: Setting a toolbar.
612 * Other Toolbar Variables:: Controlling the size of toolbars.
613
614 Scrollbars
615
616 Major and Minor Modes
617
618 * Major Modes:: Defining major modes.
619 * Minor Modes:: Defining minor modes.
620 * Modeline Format:: Customizing the text that appears in the modeline.
621 * Hooks:: How to use hooks; how to write code that
622 provides hooks.
623
624 Major Modes
625
626 * Major Mode Conventions:: Coding conventions for keymaps, etc.
627 * Example Major Modes:: Text mode and Lisp modes.
628 * Auto Major Mode:: How XEmacs chooses the major mode automatically.
629 * Mode Help:: Finding out how to use a mode.
630
631 Minor Modes
632
633 * Minor Mode Conventions:: Tips for writing a minor mode.
634 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
635
636 Modeline Format
637
638 * Modeline Data:: The data structure that controls the modeline.
639 * Modeline Variables:: Variables used in that data structure.
640 * %-Constructs:: Putting information into a modeline.
641
642 Documentation
643
644 * Documentation Basics:: Good style for doc strings.
645 Where to put them. How XEmacs stores them.
646 * Accessing Documentation:: How Lisp programs can access doc strings.
647 * Keys in Documentation:: Substituting current key bindings.
648 * Describing Characters:: Making printable descriptions of
649 non-printing characters and key sequences.
650 * Help Functions:: Subroutines used by XEmacs help facilities.
651
652 Files
653
654 * Visiting Files:: Reading files into Emacs buffers for editing.
655 * Saving Buffers:: Writing changed buffers back into files.
656 * Reading from Files:: Reading files into other buffers.
657 * Writing to Files:: Writing new files from parts of buffers.
658 * File Locks:: Locking and unlocking files, to prevent
659 simultaneous editing by two people.
660 * Information about Files:: Testing existence, accessibility, size of files.
661 * Contents of Directories:: Getting a list of the files in a directory.
662 * Changing File Attributes:: Renaming files, changing protection, etc.
663 * File Names:: Decomposing and expanding file names.
664
665 Visiting Files
666
667 * Visiting Functions:: The usual interface functions for visiting.
668 * Subroutines of Visiting:: Lower-level subroutines that they use.
669
670 Information about Files
671
672 * Testing Accessibility:: Is a given file readable? Writable?
673 * Kinds of Files:: Is it a directory? A link?
674 * File Attributes:: How large is it? Any other names? Etc.
675
676 File Names
677
678 * File Name Components:: The directory part of a file name, and the rest.
679 * Directory Names:: A directory's name as a directory
680 is different from its name as a file.
681 * Relative File Names:: Some file names are relative to a
682 current directory.
683 * File Name Expansion:: Converting relative file names to absolute ones.
684 * Unique File Names:: Generating names for temporary files.
685 * File Name Completion:: Finding the completions for a given file name.
686
687 Backups and Auto-Saving
688
689 * Backup Files:: How backup files are made; how their names
690 are chosen.
691 * Auto-Saving:: How auto-save files are made; how their
692 names are chosen.
693 * Reverting:: @code{revert-buffer}, and how to customize
694 what it does.
695
696 Backup Files
697
698 * Making Backups:: How XEmacs makes backup files, and when.
699 * Rename or Copy:: Two alternatives: renaming the old file
700 or copying it.
701 * Numbered Backups:: Keeping multiple backups for each source file.
702 * Backup Names:: How backup file names are computed; customization.
703
704 Buffers
705
706 * Buffer Basics:: What is a buffer?
707 * Buffer Names:: Accessing and changing buffer names.
708 * Buffer File Name:: The buffer file name indicates which file
709 is visited.
710 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
711 * Modification Time:: Determining whether the visited file was changed
712 ``behind XEmacs's back''.
713 * Read Only Buffers:: Modifying text is not allowed in a
714 read-only buffer.
715 * The Buffer List:: How to look at all the existing buffers.
716 * Creating Buffers:: Functions that create buffers.
717 * Killing Buffers:: Buffers exist until explicitly killed.
718 * Current Buffer:: Designating a buffer as current
719 so primitives will access its contents.
720
721 Windows
722
723 * Basic Windows:: Basic information on using windows.
724 * Splitting Windows:: Splitting one window into two windows.
725 * Deleting Windows:: Deleting a window gives its space to other windows.
726 * Selecting Windows:: The selected window is the one that you edit in.
727 * Cyclic Window Ordering:: Moving around the existing windows.
728 * Buffers and Windows:: Each window displays the contents of a buffer.
729 * Displaying Buffers:: Higher-lever functions for displaying a buffer
730 and choosing a window for it.
731 * Window Point:: Each window has its own location of point.
732 * Window Start:: The display-start position controls which text
733 is on-screen in the window.
734 * Vertical Scrolling:: Moving text up and down in the window.
735 * Horizontal Scrolling:: Moving text sideways on the window.
736 * Size of Window:: Accessing the size of a window.
737 * Resizing Windows:: Changing the size of a window.
738 * Window Configurations:: Saving and restoring the state of the screen.
739
740 Frames
741
742 * Creating Frames:: Creating additional frames.
743 * Frame Parameters:: Controlling frame size, position, font, etc.
744 * Frame Titles:: Automatic updating of frame titles.
745 * Deleting Frames:: Frames last until explicitly deleted.
746 * Finding All Frames:: How to examine all existing frames.
747 * Frames and Windows:: A frame contains windows;
748 display of text always works through windows.
749 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
750 * Input Focus:: Specifying the selected frame.
751 * Visibility of Frames:: Frames may be visible or invisible, or icons.
752 * Raising and Lowering:: Raising a frame makes it hide other X windows;
753 lowering it makes the others hide them.
754 * Frame Hooks:: Hooks for customizing frame behavior.
755
756 Positions
757
758 * Point:: The special position where editing takes place.
759 * Motion:: Changing point.
760 * Excursions:: Temporary motion and buffer changes.
761 * Narrowing:: Restricting editing to a portion of the buffer.
762
763 Motion
764
765 * Character Motion:: Moving in terms of characters.
766 * Word Motion:: Moving in terms of words.
767 * Buffer End Motion:: Moving to the beginning or end of the buffer.
768 * Text Lines:: Moving in terms of lines of text.
769 * Screen Lines:: Moving in terms of lines as displayed.
770 * List Motion:: Moving by parsing lists and sexps.
771 * Skipping Characters:: Skipping characters belonging to a certain set.
772
773 Markers
774
775 * Overview of Markers:: The components of a marker, and how it relocates.
776 * Predicates on Markers:: Testing whether an object is a marker.
777 * Creating Markers:: Making empty markers or markers at certain places.
778 * Information from Markers:: Finding the marker's buffer or character
779 position.
780 * Changing Markers:: Moving the marker to a new buffer or position.
781 * The Mark:: How ``the mark'' is implemented with a marker.
782 * The Region:: How to access ``the region''.
783
784 Text
785
786 * Near Point:: Examining text in the vicinity of point.
787 * Buffer Contents:: Examining text in a general fashion.
788 * Comparing Text:: Comparing substrings of buffers.
789 * Insertion:: Adding new text to a buffer.
790 * Commands for Insertion:: User-level commands to insert text.
791 * Deletion:: Removing text from a buffer.
792 * User-Level Deletion:: User-level commands to delete text.
793 * The Kill Ring:: Where removed text sometimes is saved for later use.
794 * Undo:: Undoing changes to the text of a buffer.
795 * Maintaining Undo:: How to enable and disable undo information.
796 How to control how much information is kept.
797 * Filling:: Functions for explicit filling.
798 * Margins:: How to specify margins for filling commands.
799 * Auto Filling:: How auto-fill mode is implemented to break lines.
800 * Sorting:: Functions for sorting parts of the buffer.
801 * Columns:: Computing horizontal positions, and using them.
802 * Indentation:: Functions to insert or adjust indentation.
803 * Case Changes:: Case conversion of parts of the buffer.
804 * Text Properties:: Assigning Lisp property lists to text characters.
805 * Substitution:: Replacing a given character wherever it appears.
806 * Registers:: How registers are implemented. Accessing the text or
807 position stored in a register.
808 * Transposition:: Swapping two portions of a buffer.
809 * Change Hooks:: Supplying functions to be run when text is changed.
810
811 The Kill Ring
812
813 * Kill Ring Concepts:: What text looks like in the kill ring.
814 * Kill Functions:: Functions that kill text.
815 * Yank Commands:: Commands that access the kill ring.
816 * Low-Level Kill Ring:: Functions and variables for kill ring access.
817 * Internals of Kill Ring:: Variables that hold kill-ring data.
818
819 Indentation
820
821 * Primitive Indent:: Functions used to count and insert indentation.
822 * Mode-Specific Indent:: Customize indentation for different modes.
823 * Region Indent:: Indent all the lines in a region.
824 * Relative Indent:: Indent the current line based on previous lines.
825 * Indent Tabs:: Adjustable, typewriter-like tab stops.
826 * Motion by Indent:: Move to first non-blank character.
827
828 Searching and Matching
829
830 * String Search:: Search for an exact match.
831 * Regular Expressions:: Describing classes of strings.
832 * Regexp Search:: Searching for a match for a regexp.
833 * Match Data:: Finding out which part of the text matched
834 various parts of a regexp, after regexp search.
835 * Saving Match Data:: Saving and restoring this information.
836 * Standard Regexps:: Useful regexps for finding sentences, pages,...
837 * Searching and Case:: Case-independent or case-significant searching.
838
839 Regular Expressions
840
841 * Syntax of Regexps:: Rules for writing regular expressions.
842 * Regexp Example:: Illustrates regular expression syntax.
843
844 Syntax Tables
845
846 * Syntax Descriptors:: How characters are classified.
847 * Syntax Table Functions:: How to create, examine and alter syntax tables.
848 * Parsing Expressions:: Parsing balanced expressions
849 using the syntax table.
850 * Standard Syntax Tables:: Syntax tables used by various major modes.
851 * Syntax Table Internals:: How syntax table information is stored.
852
853 Syntax Descriptors
854
855 * Syntax Class Table:: Table of syntax classes.
856 * Syntax Flags:: Additional flags each character can have.
857
858 Abbrevs And Abbrev Expansion
859
860 * Abbrev Mode:: Setting up XEmacs for abbreviation.
861 * Tables: Abbrev Tables. Creating and working with abbrev tables.
862 * Defining Abbrevs:: Specifying abbreviations and their expansions.
863 * Files: Abbrev Files. Saving abbrevs in files.
864 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
865 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
866
867 Extents
868
869 * Intro to Extents:: Extents are regions over a buffer or string.
870 * Creating and Modifying Extents::
871 Basic extent functions.
872 * Extent Endpoints:: Accessing and setting the bounds of an extent.
873 * Finding Extents:: Determining which extents are in an object.
874 * Mapping Over Extents:: More sophisticated functions for extent scanning.
875 * Extent Properties:: Extents have built-in and user-definable properties.
876 * Detached Extents:: Extents that are not in a buffer.
877 * Extent Parents:: Inheriting properties from another extent.
878 * Duplicable Extents:: Extents can be marked to be copied into strings.
879 * Extents and Events:: Extents can interact with the keyboard and mouse.
880 * Atomic Extents:: Treating a block of text as a single entity.
881
882 Specifiers
883
884 * Introduction to Specifiers:: Specifiers provide a clean way for
885 display and other properties to vary
886 (under user control) in a wide variety
887 of contexts.
888 * Specifiers In-Depth:: Gory details about specifier innards.
889 * Specifier Instancing:: Instancing means obtaining the ``value'' of
890 a specifier in a particular context.
891 * Specifier Types:: Specifiers come in different flavors.
892 * Adding Specifications:: Specifications control a specifier's ``value''
893 by giving conditions under which a
894 particular value is valid.
895 * Retrieving Specifications:: Querying a specifier's specifications.
896 * Specifier Instancing Functions::
897 Functions to instance a specifier.
898 * Specifier Example:: Making all this stuff clearer.
899 * Creating Specifiers:: Creating specifiers for your own use.
900 * Specifier Validation Functions::
901 Validating the components of a specifier.
902 * Other Specification Functions::
903 Other ways of working with specifications.
904
905 Faces and Window-System Objects
906
907 * Faces:: Controlling the way text looks.
908 * Fonts:: Controlling the typeface of text.
909 * Colors:: Controlling the color of text and pixmaps.
910
911 Faces
912
913 * Merging Faces:: How XEmacs decides which face to use
914 for a character.
915 * Basic Face Functions:: How to define and examine faces.
916 * Face Properties:: How to access and modify a face's properties.
917 * Face Convenience Functions:: Convenience functions for accessing
918 particular properties of a face.
919 * Other Face Display Functions:: Other functions pertaining to how a
920 a face appears.
921
922 Fonts
923
924 * Font Specifiers:: Specifying how a font will appear.
925 * Font Instances:: What a font specifier gets instanced as.
926 * Font Instance Names:: The name of a font instance.
927 * Font Instance Size:: The size of a font instance.
928 * Font Instance Characteristics:: Display characteristics of font instances.
929 * Font Convenience Functions:: Convenience functions that automatically
930 instance and retrieve the properties
931 of a font specifier.
932
933 Colors
934
935 * Color Specifiers:: Specifying how a color will appear.
936 * Color Instances:: What a color specifier gets instanced as.
937 * Color Instance Properties:: Properties of color instances.
938 * Color Convenience Functions:: Convenience functions that automatically
939 instance and retrieve the properties
940 of a color specifier.
941
942 Glyphs
943
944 * Glyph Functions:: Functions for working with glyphs.
945 * Images:: Graphical images displayed in a frame.
946 * Glyph Types:: Each glyph has a particular type.
947 * Mouse Pointer:: Controlling the mouse pointer.
948 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
949 * Subwindows:: Inserting an externally-controlled subwindow
950 into a buffer.
951
952 Glyph Functions
953
954 * Creating Glyphs:: Creating new glyphs.
955 * Glyph Properties:: Accessing and modifying a glyph's properties.
956 * Glyph Convenience Functions::
957 Convenience functions for accessing particular
958 properties of a glyph.
959 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
960
961 Images
962
963 * Image Specifiers:: Specifying how an image will appear.
964 * Image Instantiator Conversion::
965 Conversion is applied to image instantiators
966 at the time they are added to an
967 image specifier or at the time they
968 are passed to @code{make-image-instance}.
969 * Image Instances:: What an image specifier gets instanced as.
970
971 Image Instances
972
973 * Image Instance Types:: Each image instances has a particular type.
974 * Image Instance Functions:: Functions for working with image instances.
975
976 Annotations
977
978 * Annotation Basics:: Introduction to annotations.
979 * Annotation Primitives:: Creating and deleting annotations.
980 * Annotation Properties:: Retrieving and changing the characteristics
981 of an annotation.
982 * Margin Primitives:: Controlling the size of the margins.
983 * Locating Annotations:: Looking for annotations in a buffer.
984 * Annotation Hooks:: Hooks called at certain times during an
985 annotation's lifetime.
986
987 Hash Tables
988
989 * Introduction to Hash Tables:: Hash tables are fast data structures for
990 implementing simple tables (i.e. finite
991 mappings from keys to values).
992 * Working With Hash Tables:: Hash table functions.
993 * Weak Hash Tables:: Hash tables with special garbage-collection
994 behavior.
995
996 Range Tables
997
998 * Introduction to Range Tables:: Range tables efficiently map ranges of
999 integers to values.
1000 * Working With Range Tables:: Range table functions.
1001
1002
1003 XEmacs Display
1004
1005 * Refresh Screen:: Clearing the screen and redrawing everything on it.
1006 * Truncation:: Folding or wrapping long text lines.
1007 * The Echo Area:: Where messages are displayed.
1008 * Selective Display:: Hiding part of the buffer text.
1009 * Overlay Arrow:: Display of an arrow to indicate position.
1010 * Temporary Displays:: Displays that go away automatically.
1011 * Blinking:: How XEmacs shows the matching open parenthesis.
1012 * Usual Display:: The usual conventions for displaying nonprinting chars.
1013 * Display Tables:: How to specify other conventions.
1014 * Beeping:: Audible signal to the user.
1015
1016 Processes
1017
1018 * Subprocess Creation:: Functions that start subprocesses.
1019 * Synchronous Processes:: Details of using synchronous subprocesses.
1020 * Asynchronous Processes:: Starting up an asynchronous subprocess.
1021 * Deleting Processes:: Eliminating an asynchronous subprocess.
1022 * Process Information:: Accessing run-status and other attributes.
1023 * Input to Processes:: Sending input to an asynchronous subprocess.
1024 * Signals to Processes:: Stopping, continuing or interrupting
1025 an asynchronous subprocess.
1026 * Output from Processes:: Collecting output from an asynchronous subprocess.
1027 * Sentinels:: Sentinels run when process run-status changes.
1028 * Network:: Opening network connections.
1029
1030 Receiving Output from Processes
1031
1032 * Process Buffers:: If no filter, output is put in a buffer.
1033 * Filter Functions:: Filter functions accept output from the process.
1034 * Accepting Output:: How to wait until process output arrives.
1035
1036 Operating System Interface
1037
1038 * Starting Up:: Customizing XEmacs start-up processing.
1039 * Getting Out:: How exiting works (permanent or temporary).
1040 * System Environment:: Distinguish the name and kind of system.
1041 * Terminal Input:: Recording terminal input for debugging.
1042 * Terminal Output:: Recording terminal output for debugging.
1043 * Flow Control:: How to turn output flow control on or off.
1044 * Batch Mode:: Running XEmacs without terminal interaction.
1045
1046 Starting Up XEmacs
1047
1048 * Start-up Summary:: Sequence of actions XEmacs performs at start-up.
1049 * Init File:: Details on reading the init file (@file{.emacs}).
1050 * Terminal-Specific:: How the terminal-specific Lisp file is read.
1051 * Command Line Arguments:: How command line arguments are processed,
1052 and how you can customize them.
1053
1054 Getting out of XEmacs
1055
1056 * Killing XEmacs:: Exiting XEmacs irreversibly.
1057 * Suspending XEmacs:: Exiting XEmacs reversibly.
1058
1059 X-Windows
1060
1061 * X Selections:: Transferring text to and from other X clients.
1062 * X Server:: Information about the X server connected to
1063 a particular device.
1064 * Resources:: Getting resource values from the server.
1065 * Server Data:: Getting info about the X server.
1066 * Grabs:: Restricting access to the server by other apps.
1067 * X Miscellaneous:: Other X-specific functions and variables.
1068
1069 ToolTalk Support
1070
1071 * XEmacs ToolTalk API Summary::
1072 * Sending Messages::
1073 * Receiving Messages::
1074
1075 Internationalization
1076
1077 * I18N Levels 1 and 2:: Support for different time, date, and currency formats.
1078 * I18N Level 3:: Support for localized messages.
1079 * I18N Level 4:: Support for Asian languages.
1080
1081 MULE
1082
1083 * Internationalization Terminology::
1084 Definition of various internationalization terms.
1085 * Charsets:: Sets of related characters.
1086 * MULE Characters:: Working with characters in XEmacs/MULE.
1087 * Composite Characters:: Making new characters by overstriking other ones.
1088 * ISO 2022:: An international standard for charsets and encodings.
1089 * Coding Systems:: Ways of representing a string of chars using integers.
1090 * CCL:: A special language for writing fast converters.
1091 * Category Tables:: Subdividing charsets into groups.
1092
1093 Tips
1094
1095 * Style Tips:: Writing clean and robust programs.
1096 * Compilation Tips:: Making compiled code run fast.
1097 * Documentation Tips:: Writing readable documentation strings.
1098 * Comment Tips:: Conventions for writing comments.
1099 * Library Headers:: Standard headers for library packages.
1100
1101 Building XEmacs and Object Allocation
1102
1103 * Building XEmacs:: How to preload Lisp libraries into XEmacs.
1104 * Pure Storage:: A kludge to make preloaded Lisp functions sharable.
1105 * Garbage Collection:: Reclaiming space for Lisp objects no longer used.
1106
1107 @end menu
1108
1109 @include intro.texi
1110 @include objects.texi
1111 @include numbers.texi
1112 @include strings.texi
1113
1114 @include lists.texi
1115 @include sequences.texi
1116 @include symbols.texi
1117 @include eval.texi
1118
1119 @include control.texi
1120 @include variables.texi
1121 @include functions.texi
1122 @include macros.texi
1123
1124 @include loading.texi
1125 @include compile.texi
1126 @include debugging.texi
1127 @include streams.texi
1128
1129 @include minibuf.texi
1130 @include commands.texi
1131 @include keymaps.texi
1132 @include menus.texi
1133 @include dialog.texi
1134 @include toolbar.texi
1135 @include scrollbars.texi
1136 @include modes.texi
1137
1138 @include help.texi
1139 @include files.texi
1140 @include backups.texi
1141 @include buffers.texi
1142
1143 @include windows.texi
1144 @include frames.texi
1145 @include consoles-devices.texi
1146 @include positions.texi
1147 @include markers.texi
1148 @include text.texi
1149
1150 @include searching.texi
1151 @include syntax.texi
1152 @include abbrevs.texi
1153
1154 @include extents.texi
1155 @include specifiers.texi
1156 @include faces.texi
1157 @include glyphs.texi
1158 @include annotations.texi
1159 @include display.texi
1160
1161 @include hash-tables.texi
1162 @include range-tables.texi
1163 @include databases.texi
1164
1165 @include processes.texi
1166 @include os.texi
1167 @include x-windows.texi
1168 @include tooltalk.texi
1169 @include internationalization.texi
1170 @include mule.texi
1171
1172 @c MOVE to User's Manual: include calendar.texi
1173
1174 @c MOVE to User's Manual: include misc-modes.texi
1175
1176 @c appendices
1177
1178 @c REMOVE this: include non-hacker.texi
1179
1180 @include tips.texi
1181 @include building.texi
1182 @include errors.texi
1183 @include locals.texi
1184 @include maps.texi
1185 @include hooks.texi
1186
1187 @include index.texi
1188
1189 @c Print the tables of contents
1190 @summarycontents
1191 @contents
1192 @c That's all
1193
1194 @bye
1195
1196
1197 These words prevent "local variables" above from confusing XEmacs.