1 This is ../info/xemacs.info, produced by makeinfo version 4.6 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Top, Next: License, Up: (dir)
38 XEmacs is the extensible, customizable, self-documenting real-time
39 display editor. This Info file describes how to edit with Emacs and
40 some of how to customize it, but not how to extend it. It corresponds
41 to XEmacs version 21.0.
43 This manual is intended as a detailed reference to XEmacs. If you
44 are looking for an introductory manual, see the New User's Guide.
48 * License:: The GNU General Public License gives you permission
49 to redistribute XEmacs on certain terms; and also
50 explains that there is no warranty.
51 * Distrib:: How to get XEmacs.
52 * Intro:: An introduction to XEmacs concepts.
53 * Glossary:: The glossary.
54 * Manifesto:: What's GNU? Gnu's Not Unix!
56 Indices, nodes containing large menus
57 * Key Index:: An item for each standard XEmacs key sequence.
58 * Command Index:: An item for each command name.
59 * Variable Index:: An item for each documented variable.
60 * Concept Index:: An item for each concept.
62 Important General Concepts
63 * Frame:: How to interpret what you see on the screen.
64 * Keystrokes:: Keyboard gestures XEmacs recognizes.
66 The XEmacs Pull-down Menus available under X.
68 Starting Emacs from the shell.
69 * Exiting:: Stopping or killing XEmacs.
71 Hairy startup options.
73 How XEmacs finds Directories and Files.
74 * Packages:: How XEmacs organizes its high-level functionality.
76 Fundamental Editing Commands
77 * Basic:: The most basic editing commands.
78 * Undo:: Undoing recently made changes in the text.
79 * Minibuffer:: Entering arguments that are prompted for.
80 * M-x:: Invoking commands by their names.
81 * Help:: Commands for asking XEmacs about its commands.
83 Important Text-Changing Commands
84 * Mark:: The mark: how to delimit a ``region'' of text.
86 Selecting text with the mouse.
87 * Additional Mouse Operations::
88 Other operations available from the mouse.
89 * Killing:: Killing text.
90 * Yanking:: Recovering killed text. Moving text.
91 * Using X Selections::
92 Using primary selection, cut buffers, and highlighted regions.
94 Other ways of copying text.
95 * Rectangles:: Operating on the text inside a rectangle on the screen.
96 * Registers:: Saving a text string or a location in the buffer.
97 * Display:: Controlling what text is displayed.
98 * Search:: Finding or replacing occurrences of a string.
99 * Fixit:: Commands especially useful for fixing typos.
102 * Files:: All about handling files.
103 * Buffers:: Multiple buffers; editing several files at once.
104 * Windows:: Viewing two pieces of text at once.
105 * Mule:: Using world scripts.
108 * Major Modes:: Text mode vs. Lisp mode vs. C mode ...
109 * Indentation:: Editing the white space at the beginnings of lines.
110 * Text:: Commands and modes for editing English.
111 * Programs:: Commands and modes for editing programs.
112 * Running:: Compiling, running and debugging programs.
113 * Abbrevs:: How to define text abbreviations to reduce
114 the number of characters you must type.
115 * Picture:: Editing pictures made up of characters
116 using the quarter-plane screen model.
117 * Sending Mail:: Sending mail in XEmacs.
118 * Reading Mail:: Reading mail in XEmacs.
119 * Calendar/Diary:: A Calendar and diary facility in XEmacs.
120 * Sorting:: Sorting lines, paragraphs or pages within XEmacs.
121 * Shell:: Executing shell commands from XEmacs.
122 * Narrowing:: Restricting display and editing to a portion
124 * Hardcopy:: Printing buffers or regions.
126 A command can allow you to do editing
127 "within the command". This is called a
128 `recursive editing level'.
129 * Dissociated Press:: Dissociating text for fun.
130 * CONX:: A different kind of dissociation.
131 * Amusements:: Various games and hacks.
132 * Emulation:: Emulating some other editors with XEmacs.
133 * Customization:: Modifying the behavior of XEmacs.
135 Recovery from Problems.
136 * Quitting:: Quitting and aborting.
137 * Lossage:: What to do if XEmacs is hung or malfunctioning.
138 * Bugs:: How and when to report a bug.
140 Here are some other nodes which are really inferiors of the ones
141 already listed, mentioned here so you can get to them in one step:
143 --- The Detailed Node Listing ---
145 The Organization of the Frame
147 * Point:: The place in the text where editing commands operate.
148 * Echo Area:: Short messages appear at the bottom of the frame.
149 * Mode Line:: Interpreting the mode line.
150 * XEmacs under X:: Some information on using XEmacs under the X
155 * Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
156 * Representing Keystrokes:: Using lists of modifiers and keysyms to
157 represent keystrokes.
158 * Key Sequences:: Combine key strokes into key sequences you can
160 * String Key Sequences:: Available for upward compatibility.
161 * Meta Key:: Using <ESC> to represent <Meta>
162 * Super and Hyper Keys:: Adding modifier keys on certain keyboards.
163 * Character Representation:: How characters appear in XEmacs buffers.
164 * Commands:: How commands are bound to key sequences.
168 * File Menu:: Items on the File menu.
169 * Edit Menu:: Items on the Edit menu.
170 * Apps Menu:: Items on the Apps menu.
171 * Options Menu:: Items on the Options menu.
172 * Buffers Menu:: Information about the Buffers menu.
173 * Tools Menu:: Items on the Tools menu.
174 * Help Menu:: Items on the Help menu.
175 * Menu Customization:: Adding and removing menu items and related
180 * Packages:: Introduction to XEmacs Packages.
181 * Package Terminology:: Understanding different kinds of packages.
182 * Installing Packages:: How to install packages.
183 * Building Packages:: Building packages from sources.
184 * Local.rules File:: An important part of building packages.
185 * Available Packages:: A brief directory of packaged LISP.
187 Basic Editing Commands
189 * Blank Lines:: Commands to make or delete blank lines.
190 * Continuation Lines:: Lines too wide for the frame.
191 * Position Info:: What page, line, row, or column is point on?
192 * Arguments:: Numeric arguments for repeating a command.
196 * File: Minibuffer File. Entering file names with the minibuffer.
197 * Edit: Minibuffer Edit. How to edit in the minibuffer.
198 * Completion:: An abbreviation facility for minibuffer input.
199 * Repetition:: Re-executing commands that used the minibuffer.
201 The Mark and the Region
203 * Setting Mark:: Commands to set the mark.
204 * Using Region:: Summary of ways to operate on contents of the region.
205 * Marking Objects:: Commands to put region around textual units.
206 * Mark Ring:: Previous mark positions saved so you can go back there.
210 * Kill Ring:: Where killed text is stored. Basic yanking.
211 * Appending Kills:: Several kills in a row all yank together.
212 * Earlier Kills:: Yanking something killed some time ago.
216 * X Clipboard Selection:: Pasting to the X clipboard.
217 * X Selection Commands:: Other operations on the selection.
218 * X Cut Buffers:: X cut buffers are available for compatibility.
219 * Active Regions:: Using zmacs-style highlighting of the
224 * Position: RegPos. Saving positions in registers.
225 * Text: RegText. Saving text in registers.
226 * Rectangle: RegRect. Saving rectangles in registers.
227 * Configurations: RegConfig. Saving window configurations in registers.
228 * Files: RegFiles. File names in registers.
229 * Numbers: RegNumbers. Numbers in registers.
230 * Bookmarks:: Bookmarks are like registers, but persistent.
232 Controlling the Display
234 * Scrolling:: Moving text up and down in a window.
235 * Horizontal Scrolling:: Moving text left and right in a window.
236 * Selective Display:: Hiding lines with lots of indentation.
237 * Display Vars:: Information on variables for customizing display.
239 Searching and Replacement
241 * Incremental Search:: Search happens as you type the string.
242 * Non-Incremental Search:: Specify entire string and then search.
243 * Word Search:: Search for sequence of words.
244 * Regexp Search:: Search for match for a regexp.
245 * Regexps:: Syntax of regular expressions.
246 * Search Case:: To ignore case while searching, or not.
247 * Replace:: Search, and replace some or all matches.
248 * Other Repeating Search:: Operating on all matches for some regexp.
252 * Unconditional Replace:: Replacing all matches for a string.
253 * Regexp Replace:: Replacing all matches for a regexp.
254 * Replacement and Case:: How replacements preserve case of letters.
255 * Query Replace:: How to use querying.
257 Commands for Fixing Typos
259 * Kill Errors:: Commands to kill a batch of recently entered text.
260 * Transpose:: Exchanging two characters, words, lines, lists...
261 * Fixing Case:: Correcting case of last word entered.
262 * Spelling:: Apply spelling checker to a word, or a whole file.
266 * File Names:: How to type and edit file name arguments.
267 * Visiting:: Visiting a file prepares XEmacs to edit the file.
268 * Saving:: Saving makes your changes permanent.
269 * Reverting:: Reverting cancels all the changes not saved.
270 * Auto Save:: Auto Save periodically protects against loss of data.
271 * Version Control:: Version control systems (RCS and SCCS).
272 * ListDir:: Listing the contents of a file directory.
273 * Comparing Files:: Finding where two files differ.
274 * Dired:: ``Editing'' a directory to delete, rename, etc.
276 * Misc File Ops:: Other things you can do on files.
280 * Backup:: How XEmacs saves the old version of your file.
281 * Interlocking:: How XEmacs protects against simultaneous editing
282 of one file by two users.
286 * Names: Backup Names. How backup files are named;
287 Choosing single or numbered backup files.
288 * Deletion: Backup Deletion. XEmacs deletes excess numbered backups.
289 * Copying: Backup Copying. Backups can be made by copying or renaming.
291 Auto-Saving: Protection Against Disasters
293 * Files: Auto Save Files.
294 * Control: Auto Save Control.
295 * Recover:: Recovering text from auto-save files.
299 * Concepts of VC:: Basic version control information;
300 checking files in and out.
301 * Editing with VC:: Commands for editing a file maintained
302 with version control.
303 * Variables for Check-in/out:: Variables that affect the commands used
304 to check files in or out.
305 * Log Entries:: Logging your changes.
306 * Change Logs and VC:: Generating a change log file from log
308 * Old Versions:: Examining and comparing old versions.
309 * VC Status:: Commands to view the VC status of files and
311 * Renaming and VC:: A command to rename both the source and
312 master file correctly.
313 * Snapshots:: How to make and use snapshots, a set of
314 file versions that can be treated as a unit.
315 * Version Headers:: Inserting version control headers into
320 * Making Snapshots:: The snapshot facilities.
321 * Snapshot Caveats:: Things to be careful of when using snapshots.
323 Dired, the Directory Editor
325 * Enter: Dired Enter. How to invoke Dired.
326 * Edit: Dired Edit. Editing the Dired buffer.
327 * Deletion: Dired Deletion. Deleting files with Dired.
328 * Immed: Dired Immed. Other file operations through Dired.
330 Using Multiple Buffers
332 * Select Buffer:: Creating a new buffer or reselecting an old one.
333 * List Buffers:: Getting a list of buffers that exist.
334 * Misc Buffer:: Renaming; changing read-onliness; copying text.
335 * Kill Buffer:: Killing buffers you no longer need.
336 * Several Buffers:: How to go through the list of all buffers
337 and operate variously on several of them.
341 * Basic Window:: Introduction to XEmacs windows.
342 * Split Window:: New windows are made by splitting existing windows.
343 * Other Window:: Moving to another window or doing something to it.
344 * Pop Up Window:: Finding a file or buffer in another window.
345 * Change Window:: Deleting windows and changing their sizes.
349 * Choosing Modes:: How major modes are specified or chosen.
353 * Indentation Commands:: Various commands and techniques for indentation.
354 * Tab Stops:: You can set arbitrary "tab stops" and then
355 indent to the next tab stop when you want to.
356 * Just Spaces:: You can request indentation using just spaces.
358 Commands for Human Languages
360 * Text Mode:: The major modes for editing text files.
361 * Nroff Mode:: The major mode for editing input to the formatter nroff.
362 * TeX Mode:: The major modes for editing input to the formatter TeX.
363 * Outline Mode:: The major mode for editing outlines.
364 * Words:: Moving over and killing words.
365 * Sentences:: Moving over and killing sentences.
366 * Paragraphs:: Moving over paragraphs.
367 * Pages:: Moving over pages.
368 * Filling:: Filling or justifying text
369 * Case:: Changing the case of text
373 * Editing: TeX Editing. Special commands for editing in TeX mode.
374 * Printing: TeX Print. Commands for printing part of a file with TeX.
378 * Format: Outline Format. What the text of an outline looks like.
379 * Motion: Outline Motion. Special commands for moving through outlines.
380 * Visibility: Outline Visibility. Commands to control what is visible.
384 * Auto Fill:: Auto Fill mode breaks long lines automatically.
385 * Fill Commands:: Commands to refill paragraphs and center lines.
386 * Fill Prefix:: Filling when every line is indented or in a comment, etc.
390 * Program Modes:: Major modes for editing programs.
391 * Lists:: Expressions with balanced parentheses.
392 There are editing commands to operate on them.
393 * Defuns:: Each program is made up of separate functions.
394 There are editing commands to operate on them.
395 * Grinding:: Adjusting indentation to show the nesting.
396 * Matching:: Insertion of a close-delimiter flashes matching open.
397 * Comments:: Inserting, filling and aligning comments.
398 * Balanced Editing:: Inserting two matching parentheses at once, etc.
399 * Lisp Completion:: Completion on symbol names in Lisp code.
400 * Documentation:: Getting documentation of functions you plan to call.
401 * Change Log:: Maintaining a change history for your program.
402 * Tags:: Go directly to any function in your program in one
403 command. Tags remembers which file it is in.
404 * Fortran:: Fortran mode and its special features.
405 * Asm Mode:: Asm mode and its special features.
407 Indentation for Programs
410 * Multi-line Indent:: Commands to reindent many lines at once.
411 * Lisp Indent:: Specifying how each Lisp function should be indented.
412 * C Indent:: Choosing an indentation style for C code.
416 * Tag Syntax:: Tag syntax for various types of code and text files.
417 * Create Tags Table:: Creating a tags table with `etags'.
418 * Select Tags Table:: How to visit a tags table.
419 * Find Tag:: Commands to find the definition of a specific tag.
420 * Tags Search:: Using a tags table for searching and replacing.
421 * List Tags:: Listing and finding tags defined in a file.
425 * Motion: Fortran Motion. Moving point by statements or subprograms.
426 * Indent: Fortran Indent. Indentation commands for Fortran.
427 * Comments: Fortran Comments. Inserting and aligning comments.
428 * Columns: Fortran Columns. Measuring columns for valid Fortran.
429 * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
433 * Commands: ForIndent Commands. Commands for indenting Fortran.
434 * Numbers: ForIndent Num. How line numbers auto-indent.
435 * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
436 * Vars: ForIndent Vars. Variables controlling Fortran indent style.
438 Compiling and Testing Programs
440 * Compilation:: Compiling programs in languages other than Lisp
442 * Modes: Lisp Modes. Various modes for editing Lisp programs, with
443 different facilities for running the Lisp programs.
444 * Libraries: Lisp Libraries. Creating Lisp programs to run in XEmacs.
445 * Eval: Lisp Eval. Executing a single Lisp expression in XEmacs.
446 * Debug: Lisp Debug. Debugging Lisp programs running in XEmacs.
447 * Interaction: Lisp Interaction. Executing Lisp in an XEmacs buffer.
448 * External Lisp:: Communicating through XEmacs with a separate Lisp.
452 * Loading:: Loading libraries of Lisp code into XEmacs for use.
453 * Compiling Libraries:: Compiling a library makes it load and run faster.
454 * Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
458 * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
459 * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
460 * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
461 * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
462 * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
466 * Basic Picture:: Basic concepts and simple commands of Picture Mode.
467 * Insert in Picture:: Controlling direction of cursor motion
468 after "self-inserting" characters.
469 * Tabs in Picture:: Various features for tab stops and indentation.
470 * Rectangles in Picture:: Clearing and superimposing rectangles.
474 * Format: Mail Format. Format of the mail being composed.
475 * Headers: Mail Headers. Details of allowed mail header fields.
476 * Mode: Mail Mode. Special commands for editing mail being composed.
478 Running Shell Commands from XEmacs
480 * Single Shell:: How to run one shell command and return.
481 * Interactive Shell:: Permanent shell taking input via XEmacs.
482 * Shell Mode:: Special XEmacs commands used with permanent shell.
486 * Minor Modes:: Each minor mode is one feature you can turn on
487 independently of any others.
488 * Variables:: Many XEmacs commands examine XEmacs variables
489 to decide what to do; by setting variables,
490 you can control their functioning.
491 * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
492 to be replayed with a single command.
493 * Key Bindings:: The keymaps say what command each key runs.
494 By changing them, you can "redefine keys".
495 * Syntax:: The syntax table controls how words and expressions
497 * Init File:: How to write common customizations in the init file.
498 * Audible Bell:: Changing how XEmacs sounds the bell.
499 * Faces:: Changing the fonts and colors of a region of text.
500 * X Resources:: X resources controlling various aspects of the
505 * Examining:: Examining or setting one variable's value.
506 * Easy Customization:: Convenient and easy customization of variables.
507 * Edit Options:: Examining or editing list of all variables' values.
508 * Locals:: Per-buffer values of variables.
509 * File Variables:: How files can specify variable values.
513 * Basic Kbd Macro:: Defining and running keyboard macros.
514 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
515 * Kbd Macro Query:: Keyboard macros that do different things each use.
517 Customizing Key Bindings
519 * Keymaps:: Definition of the keymap data structure.
520 Names of XEmacs's standard keymaps.
521 * Rebinding:: How to redefine one key's meaning conveniently.
522 * Disabling:: Disabling a command means confirmation is required
523 before it can be executed. This is done to protect
524 beginners from surprises.
528 * Entry: Syntax Entry. What the syntax table records for each character.
529 * Change: Syntax Change. How to change the information.
533 * Init Syntax:: Syntax of constants in Emacs Lisp.
534 * Init Examples:: How to do some things with an init file.
535 * Terminal Init:: Each terminal type can have an init file.
537 Dealing with XEmacs Trouble
539 * Stuck Recursive:: `[...]' in mode line around the parentheses.
540 * Screen Garbled:: Garbage on the screen.
541 * Text Garbled:: Garbage in the text.
542 * Unasked-for Search:: Spontaneous entry to incremental search.
543 * Emergency Escape:: Emergency escape---
544 What to do if XEmacs stops responding.
545 * Total Frustration:: When you are at your wits' end.
548 File: xemacs.info, Node: License, Next: Distrib, Prev: Top, Up: Top
550 GNU GENERAL PUBLIC LICENSE
551 **************************
553 Version 1, February 1989
555 Copyright (C) 1989 Free Software Foundation, Inc.
556 675 Mass Ave, Cambridge, MA 02139, USA
558 Everyone is permitted to copy and distribute verbatim copies
559 of this license document, but changing it is not allowed.
564 The license agreements of most software companies try to keep users at
565 the mercy of those companies. By contrast, our General Public License
566 is intended to guarantee your freedom to share and change free
567 software--to make sure the software is free for all its users. The
568 General Public License applies to the Free Software Foundation's
569 software and to any other program whose authors commit to using it.
570 You can use it for your programs, too.
572 When we speak of free software, we are referring to freedom, not
573 price. Specifically, the General Public License is designed to make
574 sure that you have the freedom to give away or sell copies of free
575 software, that you receive source code or can get it if you want it,
576 that you can change the software or use pieces of it in new free
577 programs; and that you know you can do these things.
579 To protect your rights, we need to make restrictions that forbid
580 anyone to deny you these rights or to ask you to surrender the rights.
581 These restrictions translate to certain responsibilities for you if you
582 distribute copies of the software, or if you modify it.
584 For example, if you distribute copies of a such a program, whether
585 gratis or for a fee, you must give the recipients all the rights that
586 you have. You must make sure that they, too, receive or can get the
587 source code. And you must tell them their rights.
589 We protect your rights with two steps: (1) copyright the software,
590 and (2) offer you this license which gives you legal permission to copy,
591 distribute and/or modify the software.
593 Also, for each author's protection and ours, we want to make certain
594 that everyone understands that there is no warranty for this free
595 software. If the software is modified by someone else and passed on, we
596 want its recipients to know that what they have is not the original, so
597 that any problems introduced by others will not reflect on the original
598 authors' reputations.
600 The precise terms and conditions for copying, distribution and
604 1. This License Agreement applies to any program or other work which
605 contains a notice placed by the copyright holder saying it may be
606 distributed under the terms of this General Public License. The
607 "Program", below, refers to any such program or work, and a "work
608 based on the Program" means either the Program or any work
609 containing the Program or a portion of it, either verbatim or with
610 modifications. Each licensee is addressed as "you".
612 2. You may copy and distribute verbatim copies of the Program's source
613 code as you receive it, in any medium, provided that you
614 conspicuously and appropriately publish on each copy an
615 appropriate copyright notice and disclaimer of warranty; keep
616 intact all the notices that refer to this General Public License
617 and to the absence of any warranty; and give any other recipients
618 of the Program a copy of this General Public License along with
619 the Program. You may charge a fee for the physical act of
622 3. You may modify your copy or copies of the Program or any portion of
623 it, and copy and distribute such modifications under the terms of
624 Paragraph 1 above, provided that you also do the following:
626 * cause the modified files to carry prominent notices stating
627 that you changed the files and the date of any change; and
629 * cause the whole of any work that you distribute or publish,
630 that in whole or in part contains the Program or any part
631 thereof, either with or without modifications, to be licensed
632 at no charge to all third parties under the terms of this
633 General Public License (except that you may choose to grant
634 warranty protection to some or all third parties, at your
637 * If the modified program normally reads commands interactively
638 when run, you must cause it, when started running for such
639 interactive use in the simplest and most usual way, to print
640 or display an announcement including an appropriate copyright
641 notice and a notice that there is no warranty (or else,
642 saying that you provide a warranty) and that users may
643 redistribute the program under these conditions, and telling
644 the user how to view a copy of this General Public License.
646 * You may charge a fee for the physical act of transferring a
647 copy, and you may at your option offer warranty protection in
650 Mere aggregation of another independent work with the Program (or
651 its derivative) on a volume of a storage or distribution medium
652 does not bring the other work under the scope of these terms.
654 4. You may copy and distribute the Program (or a portion or
655 derivative of it, under Paragraph 2) in object code or executable
656 form under the terms of Paragraphs 1 and 2 above provided that you
657 also do one of the following:
659 * accompany it with the complete corresponding machine-readable
660 source code, which must be distributed under the terms of
661 Paragraphs 1 and 2 above; or,
663 * accompany it with a written offer, valid for at least three
664 years, to give any third party free (except for a nominal
665 charge for the cost of distribution) a complete
666 machine-readable copy of the corresponding source code, to be
667 distributed under the terms of Paragraphs 1 and 2 above; or,
669 * accompany it with the information you received as to where the
670 corresponding source code may be obtained. (This alternative
671 is allowed only for noncommercial distribution and only if you
672 received the program in object code or executable form alone.)
674 Source code for a work means the preferred form of the work for
675 making modifications to it. For an executable file, complete
676 source code means all the source code for all modules it contains;
677 but, as a special exception, it need not include source code for
678 modules which are standard libraries that accompany the operating
679 system on which the executable file runs, or for standard header
680 files or definitions files that accompany that operating system.
682 5. You may not copy, modify, sublicense, distribute or transfer the
683 Program except as expressly provided under this General Public
684 License. Any attempt otherwise to copy, modify, sublicense,
685 distribute or transfer the Program is void, and will automatically
686 terminate your rights to use the Program under this License.
687 However, parties who have received copies, or rights to use
688 copies, from you under this General Public License will not have
689 their licenses terminated so long as such parties remain in full
692 6. By copying, distributing or modifying the Program (or any work
693 based on the Program) you indicate your acceptance of this license
694 to do so, and all its terms and conditions.
696 7. Each time you redistribute the Program (or any work based on the
697 Program), the recipient automatically receives a license from the
698 original licensor to copy, distribute or modify the Program
699 subject to these terms and conditions. You may not impose any
700 further restrictions on the recipients' exercise of the rights
703 8. The Free Software Foundation may publish revised and/or new
704 versions of the General Public License from time to time. Such
705 new versions will be similar in spirit to the present version, but
706 may differ in detail to address new problems or concerns.
708 Each version is given a distinguishing version number. If the
709 Program specifies a version number of the license which applies to
710 it and "any later version", you have the option of following the
711 terms and conditions either of that version or of any later
712 version published by the Free Software Foundation. If the Program
713 does not specify a version number of the license, you may choose
714 any version ever published by the Free Software Foundation.
716 9. If you wish to incorporate parts of the Program into other free
717 programs whose distribution conditions are different, write to the
718 author to ask for permission. For software which is copyrighted
719 by the Free Software Foundation, write to the Free Software
720 Foundation; we sometimes make exceptions for this. Our decision
721 will be guided by the two goals of preserving the free status of
722 all derivatives of our free software and of promoting the sharing
723 and reuse of software generally.
727 10. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
728 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
729 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
730 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
731 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
732 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
733 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
734 QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
735 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
736 SERVICING, REPAIR OR CORRECTION.
738 11. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
739 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
740 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
741 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
742 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
743 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
744 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
745 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
746 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
747 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
749 END OF TERMS AND CONDITIONS
751 Appendix: How to Apply These Terms to Your New Programs
752 =======================================================
754 If you develop a new program, and you want it to be of the greatest
755 possible use to humanity, the best way to achieve this is to make it
756 free software which everyone can redistribute and change under these
759 To do so, attach the following notices to the program. It is safest
760 to attach them to the start of each source file to most effectively
761 convey the exclusion of warranty; and each file should have at least the
762 "copyright" line and a pointer to where the full notice is found.
764 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
765 Copyright (C) 19YY NAME OF AUTHOR
767 This program is free software; you can redistribute it and/or modify
768 it under the terms of the GNU General Public License as published by
769 the Free Software Foundation; either version 1, or (at your option)
772 This program is distributed in the hope that it will be useful,
773 but WITHOUT ANY WARRANTY; without even the implied warranty of
774 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
775 GNU General Public License for more details.
777 You should have received a copy of the GNU General Public License
778 along with this program; if not, write to the Free Software
779 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
781 Also add information on how to contact you by electronic and paper
784 If the program is interactive, make it output a short notice like
785 this when it starts in an interactive mode:
787 Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
788 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
789 This is free software, and you are welcome to redistribute it
790 under certain conditions; type `show c' for details.
792 The hypothetical commands `show w' and `show c' should show the
793 appropriate parts of the General Public License. Of course, the
794 commands you use may be called something other than `show w' and `show
795 c'; they could even be mouse-clicks or menu items--whatever suits your
798 You should also get your employer (if you work as a programmer) or
799 your school, if any, to sign a "copyright disclaimer" for the program,
800 if necessary. Here a sample; alter the names:
802 Yoyodyne, Inc., hereby disclaims all copyright interest in the
803 program `Gnomovision' (a program to direct compilers to make passes
804 at assemblers) written by James Hacker.
806 SIGNATURE OF TY COON, 1 April 1989
807 Ty Coon, President of Vice
809 That's all there is to it!
812 File: xemacs.info, Node: Distrib, Next: Intro, Prev: License, Up: Top
817 XEmacs is "free"; this means that everyone is free to use it and free
818 to redistribute it on a free basis. XEmacs is not in the public
819 domain; it is copyrighted and there are restrictions on its
820 distribution, but these restrictions are designed to permit everything
821 that a good cooperating citizen would want to do. What is not allowed
822 is to try to prevent others from further sharing any version of XEmacs
823 that they might get from you. The precise conditions are found in the
824 GNU General Public License that comes with XEmacs and also appears
825 following this section.
827 The easiest way to get a copy of XEmacs is from someone else who has
828 it. You need not ask for permission to do so, or tell any one else;
831 If you have access to the Internet, you can get the latest version of
832 XEmacs from the anonymous FTP server `ftp.xemacs.org' in the directory
833 `/pub/xemacs'. It can also be found at numerous other archive sites
834 around the world; check the file `etc/DISTRIB' in an XEmacs
835 distribution for the latest known list.
837 Getting Other Versions of Emacs
838 ===============================
840 The Free Software Foundation's version of Emacs (called "FSF Emacs" in
841 this manual and often referred to as "GNU Emacs") is available by
842 anonymous FTP from `prep.ai.mit.edu'.
844 Win-Emacs, an older version of XEmacs that runs on Microsoft Windows
845 and Windows NT, is available by anonymous FTP from `ftp.netcom.com' in
846 the directory `/pub/pe/pearl', or from `ftp.cica.indiana.edu' as the
847 files `wemdemo*.zip' in the directory `/pub/pc/win3/demo'.
850 File: xemacs.info, Node: Intro, Next: Glossary, Prev: Distrib, Up: Top
855 You are reading about XEmacs, an incarnation of the advanced,
856 self-documenting, customizable, extensible real-time display editor
857 Emacs. XEmacs provides many powerful display and user-interface
858 capabilities not found in other Emacsen and is mostly upwardly
859 compatible with GNU Emacs from the Free Software Foundation (referred
860 to as "FSF Emacs" in this manual). XEmacs also comes standard with a
861 great number of useful packages.
863 We say that XEmacs is a "display" editor because normally the text
864 being edited is visible on the screen and is updated automatically as
865 you type. *Note Display: Frame.
867 We call XEmacs a "real-time" editor because the display is updated
868 very frequently, usually after each character or pair of characters you
869 type. This minimizes the amount of information you must keep in your
870 head as you edit. *Note Real-time: Basic.
872 We call XEmacs advanced because it provides facilities that go beyond
873 simple insertion and deletion: filling of text; automatic indentation of
874 programs; viewing two or more files at once; and dealing in terms of
875 characters, words, lines, sentences, paragraphs, and pages, as well as
876 expressions and comments in several different programming languages.
877 It is much easier to type one command meaning "go to the end of the
878 paragraph" than to find that spot with simple cursor keys.
880 "Self-documenting" means that at any time you can type a special
881 character, `Control-h', to find out what your options are. You can
882 also use `C-h' to find out what a command does, or to find all the
883 commands relevant to a topic. *Note Help::.
885 "Customizable" means you can change the definitions of XEmacs
886 commands. For example, if you use a programming language in which
887 comments start with `<**' and end with `**>', you can tell the XEmacs
888 comment manipulation commands to use those strings (*note Comments::).
889 Another sort of customization is rearrangement of the command set. For
890 example, you can set up the four basic cursor motion commands (up,
891 down, left and right) on keys in a diamond pattern on the keyboard if
892 you prefer. *Note Customization::.
894 "Extensible" means you can go beyond simple customization and write
895 entirely new commands, programs in the Lisp language to be run by
896 XEmacs's own Lisp interpreter. XEmacs is an "on-line extensible"
897 system: it is divided into many functions that call each other. You can
898 redefine any function in the middle of an editing session and replace
899 any part of XEmacs without making a separate copy of all of XEmacs.
900 Most of the editing commands of XEmacs are written in Lisp; the few
901 exceptions could have been written in Lisp but are written in C for
902 efficiency. Only a programmer can write an extension to XEmacs, but
903 anybody can use it afterward.
906 File: xemacs.info, Node: Frame, Next: Keystrokes, Prev: Concept Index, Up: Top
912 In many environments, such as a tty terminal, an XEmacs frame
913 literally takes up the whole screen. If you are running XEmacs in
914 a multi-window system like the X Window System, the XEmacs frame
915 takes up one X window. *Note XEmacs under X::, for more
919 No matter what environment you are running in, XEmacs allows you
920 to look at several buffers at the same time by having several
921 windows be part of the frame. Often, the whole frame is taken up
922 by just one window, but you can split the frame into two or more
923 subwindows. If you are running XEmacs under the X window system,
924 that means you can have several "XEmacs windows" inside the X
925 window that contains the XEmacs frame. You can even have multiple
926 frames in different X windows, each with their own set of
930 Each XEmacs frame displays a variety of information:
931 * The biggest area usually displays the text you are editing. It may
932 consist of one window or of two or more windows if you need to
933 look at two buffers a the same time.
935 * Below each text window's last line is a "mode line" (*note Mode
936 Line::), which describes what is going on in that window. The
937 mode line is in inverse video if the terminal supports that. If
938 there are several XEmacs windows in one frame, each window has its
941 * At the bottom of each XEmacs frame is the "echo area" or
942 "minibuffer window"(*note Echo Area::). It is used by XEmacs to
943 exchange information with the user. There is only one echo area
946 * If you are running XEmacs under a graphical windowing system, a
947 menu bar at the top of the frame makes shortcuts to several of the
948 commands available (*note Pull-down Menus::).
950 * Under a graphical windowing system, a toolbar at the top of the
951 frame, just under the menu bar if it exists, provides "one-touch"
952 shortcuts to several commands. (Not yet documented.)
954 * Under a graphical windowing system, a gutter at the top (under the
955 toolbar) and/or bottom of the frame provides advanced GUI
956 facilities like tab controls for rapid switching among related
957 windows and progress bars for time-consuming operations like
958 downloads across the Internet. Gutters are an experimental feature
959 introduced in XEmacs version 21.2. (Not yet documented.)
961 You can subdivide the XEmacs frame into multiple text windows, and
962 use each window for a different file (*note Windows::). Multiple XEmacs
963 windows are tiled vertically on the XEmacs frame. The upper XEmacs
964 window is separated from the lower window by its mode line.
966 When there are multiple, tiled XEmacs windows on a single XEmacs
967 frame, the XEmacs window receiving input from the keyboard has the
968 "keyboard focus" and is called the "selected window". The selected
969 window contains the cursor, which indicates the insertion point. If
970 you are working in an environment that permits multiple XEmacs frames,
971 and you move the focus from one XEmacs frame into another, the selected
972 window is the one that was last selected in that frame.
974 The same text can be displayed simultaneously in several XEmacs
975 windows, which can be in different XEmacs frames. If you alter the text
976 in an XEmacs buffer by editing it in one XEmacs window, the changes are
977 visible in all XEmacs windows containing that buffer.
981 * Point:: The place in the text where editing commands operate.
982 * Echo Area:: Short messages appear at the bottom of the frame.
983 * Mode Line:: Interpreting the mode line.
984 * GUI Components:: Menubar, toolbars, gutters.
985 * XEmacs under X:: Some information on using XEmacs under the X
987 * XEmacs under MS Windows:: Some information on using XEmacs under
991 File: xemacs.info, Node: Point, Next: Echo Area, Prev: Frame, Up: Frame
996 When XEmacs is running, the cursor shows the location at which editing
997 commands will take effect. This location is called "point". You can
998 use keystrokes or the mouse cursor to move point through the text and
999 edit the text at different places.
1001 While the cursor appears to point AT a character, you should think
1002 of point as BETWEEN two characters: it points BEFORE the character on
1003 which the cursor appears. The exception is at the end of the line,
1004 where the cursor appears after the last character of the line. Where
1005 the display is capable, the cursor at the end of the line will appear
1006 differently from a cursor over whitespace at the end of the line. (In
1007 an X Windows frame, the end-of-line cursor is half the width of a
1008 within-line cursor.) Sometimes people speak of "the cursor" when they
1009 mean "point," or speak of commands that move point as "cursor motion"
1012 Each XEmacs frame has only one cursor. When output is in progress,
1013 the cursor must appear where the typing is being done. This does not
1014 mean that point is moving. It is only that XEmacs has no way to show
1015 you the location of point except when the terminal is idle.
1017 If you are editing several files in XEmacs, each file has its own
1018 point location. A file that is not being displayed remembers where
1019 point is. Point becomes visible at the correct location when you look
1022 When there are multiple text windows, each window has its own point
1023 location. The cursor shows the location of point in the selected
1024 window. The visible cursor also shows you which window is selected. If
1025 the same buffer appears in more than one window, point can be moved in
1026 each window independently.
1028 The term `point' comes from the character `.', which was the command
1029 in TECO (the language in which the original Emacs was written) for
1030 accessing the value now called `point'.
1033 File: xemacs.info, Node: Echo Area, Next: Mode Line, Prev: Point, Up: Frame
1038 The line at the bottom of the frame (below the mode line) is the "echo
1039 area". XEmacs uses this area to communicate with the user:
1041 * "Echoing" means printing out the characters that the user types.
1042 XEmacs never echoes single-character commands. Multi-character
1043 commands are echoed only if you pause while typing them: As soon
1044 as you pause for more than one second in the middle of a command,
1045 all the characters of the command so far are echoed. This is
1046 intended to "prompt" you for the rest of the command. Once
1047 echoing has started, the rest of the command is echoed immediately
1048 as you type it. This behavior is designed to give confident users
1049 fast response, while giving hesitant users maximum feedback. You
1050 can change this behavior by setting a variable (*note Display
1053 * If you issue a command that cannot be executed, XEmacs may print
1054 an "error message" in the echo area. Error messages are
1055 accompanied by a beep or by flashing the frame. Any input you
1056 have typed ahead is thrown away when an error happens.
1058 * Some commands print informative messages in the echo area. These
1059 messages look similar to error messages, but are not announced
1060 with a beep and do not throw away input. Sometimes a message
1061 tells you what the command has done, when this is not obvious from
1062 looking at the text being edited. Sometimes the sole purpose of a
1063 command is to print a message giving you specific information.
1064 For example, the command `C-x =' is used to print a message
1065 describing the character position of point in the text and its
1066 current column in the window. Commands that take a long time
1067 often display messages ending in `...' while they are working, and
1068 add `done' at the end when they are finished.
1070 * The echo area is also used to display the "minibuffer", a window
1071 that is used for reading arguments to commands, such as the name
1072 of a file to be edited. When the minibuffer is in use, the echo
1073 area displays with a prompt string that usually ends with a colon.
1074 The cursor appears after the prompt. You can always get out of
1075 the minibuffer by typing `C-g'. *Note Minibuffer::.
1078 File: xemacs.info, Node: Mode Line, Next: GUI Components, Prev: Echo Area, Up: Frame
1083 Each text window's last line is a "mode line" which describes what is
1084 going on in that window. When there is only one text window, the mode
1085 line appears right above the echo area. The mode line is in inverse
1086 video if the terminal supports that, starts and ends with dashes, and
1087 contains text like `XEmacs: SOMETHING'.
1089 If a mode line has something else in place of `XEmacs: SOMETHING',
1090 the window above it is in a special subsystem such as Dired. The mode
1091 line then indicates the status of the subsystem.
1093 Normally, the mode line has the following appearance:
1095 --CH-XEmacs: BUF (MAJOR MINOR)----POS------
1097 This gives information about the buffer being displayed in the window:
1098 the buffer's name, what major and minor modes are in use, whether the
1099 buffer's text has been changed, and how far down the buffer you are
1102 CH contains two stars (`**') if the text in the buffer has been
1103 edited (the buffer is "modified"), or two dashes (`--') if the buffer
1104 has not been edited. Exception: for a read-only buffer, it is `%%'.
1106 BUF is the name of the window's chosen "buffer". The chosen buffer
1107 in the selected window (the window that the cursor is in) is also
1108 XEmacs's selected buffer, the buffer in which editing takes place. When
1109 we speak of what some command does to "the buffer", we mean the
1110 currently selected buffer. *Note Buffers::.
1112 POS tells you whether there is additional text above the top of the
1113 screen or below the bottom. If your file is small and it is completely
1114 visible on the screen, POS is `All'. Otherwise, POS is `Top' if you
1115 are looking at the beginning of the file, `Bot' if you are looking at
1116 the end of the file, or `NN%', where NN is the percentage of the file
1117 above the top of the screen.
1119 MAJOR is the name of the "major mode" in effect in the buffer. At
1120 any time, each buffer is in one and only one major mode. The available
1121 major modes include Fundamental mode (the least specialized), Text
1122 mode, Lisp mode, and C mode. *Note Major Modes::, for details on how
1123 the modes differ and how you select one.
1125 MINOR is a list of some of the "minor modes" that are turned on in
1126 the window's chosen buffer. For example, `Fill' means that Auto Fill
1127 mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means
1128 that Overwrite mode is on. *Note Minor Modes::, for more information.
1129 `Narrow' means that the buffer being displayed has editing restricted
1130 to only a portion of its text. This is not really a minor mode, but is
1131 like one. *Note Narrowing::. `Def' means that a keyboard macro is
1132 being defined. *Note Keyboard Macros::.
1134 Some buffers display additional information after the minor modes.
1135 For example, Rmail buffers display the current message number and the
1136 total number of messages. Compilation buffers and Shell mode display
1137 the status of the subprocess.
1139 If XEmacs is currently inside a recursive editing level, square
1140 brackets (`[...]') appear around the parentheses that surround the
1141 modes. If XEmacs is in one recursive editing level within another,
1142 double square brackets appear, and so on. Since information on
1143 recursive editing applies to XEmacs in general and not to any one
1144 buffer, the square brackets appear in every mode line on the screen or
1145 not in any of them. *Note Recursive Edit::.
1147 XEmacs can optionally display the time and system load in all mode
1148 lines. To enable this feature, type `M-x display-time'. The
1149 information added to the mode line usually appears after the file name,
1150 before the mode names and their parentheses. It looks like this:
1154 (Some fields may be missing if your operating system cannot support
1155 them.) HH and MM are the hour and minute, followed always by `am' or
1156 `pm'. L.LL is the average number of running processes in the whole
1157 system recently. D is an approximate index of the ratio of disk
1158 activity to CPU activity for all users.
1160 The word `Mail' appears after the load level if there is mail for
1161 you that you have not read yet.
1163 Customization note: the variable `mode-line-inverse-video' controls
1164 whether the mode line is displayed in inverse video (assuming the
1165 terminal supports it); `nil' means no inverse video. The default is
1166 `t'. For X frames, simply set the foreground and background colors
1170 File: xemacs.info, Node: GUI Components, Next: XEmacs under X, Prev: Mode Line, Up: Frame
1175 When executed in a graphical windowing environment such as the X Window
1176 System or Microsoft Windows, XEmacs displays several graphical user
1177 interface components such as scrollbars, menubars, toolbars, and
1178 gutters. By default there is a vertical scrollbar at the right of each
1179 frame, and at the top of the frame there is a menubar, a toolbar, and a
1180 gutter, in that order. Gutters can contain any of several widgets, but
1181 the default configuration puts a set of "notebook tabs" which you can
1182 use as a shortcut for selecting any of several related buffers in a
1183 given frame. Operating the GUI components is "obvious": click on the
1184 menubar to pull down a menu, on a button in the toolbar to invoke a
1185 function, and on a tab in the gutter to switch buffers.
1189 * Menubar Basics:: How XEmacs uses the menubar.
1190 * Scrollbar Basics:: How XEmacs uses scrollbars.
1191 * Mode Line Basics:: How XEmacs uses modelines.
1192 * Toolbar Basics:: How XEmacs uses toolbars.
1193 * Gutter Basics:: How XEmacs uses gutters.
1194 * Inhibiting:: What if you don't like GUI?
1195 * Customizing:: Position, orientation, and appearance of GUI objects.
1198 File: xemacs.info, Node: Menubar Basics, Next: Scrollbar Basics, Up: GUI Components
1203 The XEmacs menubar is intended to be conformant to the usual conventions
1204 for menubars, although conformance is not yet perfect. The menu at the
1205 extreme right is the `Help' menu, which should always be available. It
1206 provides access to all the XEmacs help facilities available through
1207 `C-h', as well as samples of various configuration files like
1208 `~/.Xdefaults' and `~/.emacs'. At the extreme left is the `Files'
1209 menu, which provides the usual file reading, writing, and printing
1210 operations, as well as operations like revert buffer from most recent
1211 save. The next menu from the left is the `Edit' menu, which provides
1212 the `Undo' operation as well as cutting and pasting, searching, and
1213 keyboard macro definition and execution.
1215 XEmacs provides a very dynamic environment, and the Lisp language
1216 makes for highly flexible applications. The menubar reflects this:
1217 many menus (eg, the `Buffers' menu, *note Buffers Menu::) contain items
1218 determined by the current state of XEmacs, and most major modes and many
1219 minor modes add items to menus and even whole menus to the menubar. In
1220 fact, some applications like w3.el and VM provide so many menus that
1221 they define a whole new menubar and add a button that allows convenient
1222 switching between the "XEmacs menubar" and the "application menubar".
1223 Such applications normally bind themselves to a particular frame, and
1224 this switching only takes place on frames where such an application is
1225 active (ie, the current window of the frame is displaying a buffer in
1226 the appropriate major mode).
1228 Other menus which are typically available are the `Options',
1229 `Tools', `Buffers', `Apps', and `Mule' menus. For detailed
1230 descriptions of these menus, *Note Pull-down Menus::. (In 21.2
1231 XEmacsen, the `Mule' menu will be moved under `Options'.)
1234 File: xemacs.info, Node: Scrollbar Basics, Next: Mode Line Basics, Prev: Menubar Basics, Up: GUI Components
1239 XEmacs scrollbars provide the usual interface. Arrow buttons at either
1240 end allow for line by line scrolling, including autorepeat. Clicking in
1241 the scrollbar itself provides scrolling by windowsfull, depending on
1242 which side of the slider is clicked. The slider itself may be dragged
1243 for smooth scrolling.
1245 The position of the slider corresponds to the position of the window
1246 in the buffer. In particular, the length of the slider is proportional
1247 to the fraction of the buffer which appears in the window.
1249 The presence of the scrollbars is under control of the application or
1250 may be customized by the user. By default a vertical scrollbar is
1251 present in all windows (except the minibuffer), and there is no
1252 horizontal scrollbar.
1255 File: xemacs.info, Node: Mode Line Basics, Next: Toolbar Basics, Prev: Scrollbar Basics, Up: GUI Components
1260 When used in a windowing system, the XEmacs modelines can be dragged
1261 vertically. The effect is to resize the windows above and below the
1262 modeline (this includes the minibuffer window).
1264 Additionally, a modeline can be dragged horizontally, in which case
1265 it scrolls its own text. This behavior is not enabled by default
1266 because it could be considered as disturbing when dragging vertically.
1267 When this behavior is enabled, the modeline's text can be dragged
1268 either in the same direction as the mouse, or in the opposite sense,
1269 making the modeline act as a scrollbar for its own text.
1271 You can select the behavior you want from the `Display' submenu of
1275 File: xemacs.info, Node: Toolbar Basics, Next: Gutter Basics, Prev: Mode Line Basics, Up: GUI Components
1280 XEmacs has a default toolbar which provides shortcuts for some of the
1281 commonly used operations (such as opening files) and applications (such
1282 as the Info manual reader). Operations which require arguments will pop
1283 up dialogs to get them.
1285 The position of the default toolbar can be customized. Also, several
1286 toolbars may be present simultaneously (in different positions). VM,
1287 for example, provides an application toolbar which shortcuts for
1288 mail-specific operations like sending, saving, and deleting messages.
1291 File: xemacs.info, Node: Gutter Basics, Next: Inhibiting, Prev: Toolbar Basics, Up: GUI Components
1296 Gutters are the most flexible of the GUI components described in this
1297 section. In theory, the other GUI components could be implemented by
1298 customizing a gutter, but in practice the other components were
1299 introduced earlier and have their own special implementations. Gutters
1300 tend to be more transient than the other components. Buffer tabs, for
1301 example, change every time the selected buffer in the frame changes.
1302 And for progress gauges a gutter to contain the gauge is typically
1303 created on the fly when needed, then destroyed when the operation whose
1304 staus is being displayed is completed.
1306 Buffer tabs, having somewhat complex behavior, deserve a closer look.
1307 By default, a row of buffer tabs is displayed at the top of every frame.
1308 (The tabs could be placed in the bottom gutter, but would be oriented
1309 the same way and look rather odd. The horizontal orientation makes
1310 putting them in a side gutter utterly impractical.) The buffer
1311 displayed in the current window of a frame can be changed to a specific
1312 buffer by clicking [mouse-1] on the corresponding tab in the gutter.
1314 Each tab contains the name of its buffer. The tab for the current
1315 buffer in each frame is displayed in raised relief. The list of buffers
1316 chosen for display in the buffer tab row is derived by filtering the
1317 buffer list (like the `Buffers' menu). The list starts out with all
1318 existing buffers, with more recently selected buffers coming earlier in
1321 Then "uninteresting" buffers, like internal XEmacs buffers, the
1322 `*Message Log*' buffer, and so on are deleted from the list. Next, the
1323 frame's selected buffer is determined. Buffers with a different major
1324 mode from the selected buffer are removed from the list. Finally, if
1325 the list is too long, the least recently used buffers are deleted from
1326 the list. By default up to 6 most recently used buffers with the same
1327 mode are displayed on tabs in the gutter.
1329 This behavior can be altered by customizing
1330 `buffers-tab-filter-functions'. Setting this variable to `nil' forces
1331 display of all buffers, up to `buffers-tab-max-size' (also
1332 customizable). More complex behavior may be available in 3rd party
1333 libraries. These, and some more rarely customized options, are in the
1334 `buffers-tab' Customize group.
1337 File: xemacs.info, Node: Inhibiting, Next: Customizing, Prev: Gutter Basics, Up: GUI Components
1339 Inhibiting Display of GUI Components
1340 ====================================
1342 Use of GUI facilities is a personal thing. Almost everyone agrees that
1343 drawing via keyboard-based "turtle graphics" is acceptable to hardly
1344 anyone if a mouse is available, but conversely emulating a keyboard with
1345 a screenful of buttons is a painful experience. But between those
1346 extremes the complete novice will require a fair amount of time before
1347 toolbars and menus become dispensable, but many an "Ancien Haquer" sees
1348 them as a complete waste of precious frame space that could be filled
1351 Display of all of the GUI components created by XEmacs can be
1352 inhibited through the use of Customize. Customize can be accessed
1353 through `Options | Customize' in the menu bar, or via `M-x customize'.
1354 Then navigate through the Customize tree to `Emacs | Environment'.
1355 Scrollbar and toolbar visibility is controlled via the `Display' group,
1356 options `Scrollbars visible' and `Toolbar visible' respectively.
1357 Gutter visibility is controlled by group `Gutter', option `Visible'.
1359 Or they can be controlled directly by `M-x customize-variable', by
1360 changing the values of the variables `menubar-visible-p',
1361 `scrollbars-visible-p', `toolbar-visible-p', or
1362 `gutter-buffers-tab-visible-p' respectively. (The strange form of the
1363 last variable is due to the fact that gutters are often used to display
1364 transient widgets like progress gauges, which you probably don't want
1365 to inhibit. It is more likely that you want to inhibit the default
1366 display of the buffers tab widget, which is what that variable controls.
1367 This interface is subject to change depending on developer experience
1370 Control of frame configuration can controlled automatically
1371 according to various parameters such as buffer or frame because these
1372 are "specifiers" *Note Specifiers: (lispref)Specifiers. Using these
1373 features requires programming in Lisp; Customize is not yet that
1374 sophisticated. Also, components that appear in various positions and
1375 orientations can have display suppressed according to position. `C-h a
1376 visible-p' gives a list of variables which can be customized. E.g., to
1377 control the visibility of specifically the left-side toolbar only,
1378 customize `left-toolbar-visible-p'.
1381 File: xemacs.info, Node: Customizing, Prev: Inhibiting, Up: GUI Components
1383 Changing the Position, Orientation, and Appearance of GUI Components
1384 ====================================================================
1386 #### Not documented yet.
1389 File: xemacs.info, Node: XEmacs under X, Next: XEmacs under MS Windows, Prev: GUI Components, Up: Frame
1391 Using XEmacs Under the X Window System
1392 ======================================
1394 XEmacs can be used with the X Window System and a window manager like
1395 MWM or TWM. In that case, the X window manager opens, closes, and
1396 resizes XEmacs frames. You use the window manager's mouse gestures to
1397 perform the operations. Consult your window manager guide or reference
1398 manual for information on manipulating X windows.
1400 When you are working under X, each X window (that is, each XEmacs
1401 frame) has a menu bar for mouse-controlled operations (*note Pull-down
1404 XEmacs under X is also a multi-frame XEmacs. You can use the New
1405 Frame menu item from the File menu to create a new XEmacs frame in a
1406 new X window from the same process. The different frames will share the
1407 same buffer list, but you can look at different buffers in the different
1410 The function `find-file-other-frame' is just like `find-file', but
1411 creates a new frame to display the buffer in first. This is normally
1412 bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
1415 The function `switch-to-buffer-other-frame' is just like
1416 `switch-to-buffer', but creates a new frame to display the buffer in
1417 first. This is normally bound to `C-x 5 b'.
1419 You can specify a different default frame size other than the one
1420 provided. Use the variable `default-frame-plist', which is a plist of
1421 default values for frame creation other than the first one. These may
1422 be set in your init file, like this:
1424 (setq default-frame-plist '(width 80 height 55))
1426 This variable has replaced `default-frame-alist', which is
1427 considered obsolete.
1429 For values specific to the first XEmacs frame, you must use X
1430 resources. The variable `x-frame-defaults' takes an alist of default
1431 frame creation parameters for X window frames. These override what is
1432 specified in `~/.Xdefaults' but are overridden by the arguments to the
1433 particular call to `x-create-frame'.
1435 When you create a new frame, the variable `create-frame-hook' is
1436 called with one argument, the frame just created.
1438 If you want to close one or more of the X windows you created using
1439 New Frame, use the Delete Frame menu item from the File menu.
1441 If you are working with multiple frames, some special information
1443 * Two variables, `frame-title-format' and `frame-icon-title-format'
1444 determine the title of the frame and the title of the icon that
1445 results if you shrink the frame.
1447 * The variables `auto-lower-frame' and `auto-raise-frame' position a
1448 frame. If true, `auto-lower-frame' lowers a frame to the bottom
1449 when it is no longer selected. If true, `auto-raise-frame' raises
1450 a frame to the top when it is selected. Under X, most
1451 ICCCM-compliant window managers will have options to do this for
1452 you, but these variables are provided in case you are using a
1453 broken window manager.
1455 * There is a new frame/modeline format directive, %S, which expands
1456 to the name of the current frame (a frame's name is distinct from
1457 its title; the name is used for resource lookup, among other
1458 things, and the title is simply what appears above the window.)
1461 File: xemacs.info, Node: XEmacs under MS Windows, Prev: XEmacs under X, Up: Frame
1463 Using XEmacs Under Microsoft Windows
1464 ====================================
1466 Use of XEmacs under MS Windows is not separately documented here, but
1467 most operations available under the X Window System are also available
1470 Where possible, native MS Windows GUI components and capabilities are
1474 File: xemacs.info, Node: Keystrokes, Next: Pull-down Menus, Prev: Frame, Up: Top
1476 Keystrokes, Key Sequences, and Key Bindings
1477 *******************************************
1481 * Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
1482 * Representing Keystrokes:: Using lists of modifiers and keysyms to
1483 represent keystrokes.
1484 * Key Sequences:: Combine key strokes into key sequences you can
1486 * String Key Sequences:: Available for upward compatibility.
1487 * Meta Key:: Using <ESC> to represent <Meta>
1488 * Super and Hyper Keys:: Adding modifier keys on certain keyboards.
1489 * Character Representation:: How characters appear in Emacs buffers.
1490 * Commands:: How commands are bound to key sequences.
1493 File: xemacs.info, Node: Intro to Keystrokes, Next: Representing Keystrokes, Prev: Keystrokes, Up: Keystrokes
1495 Keystrokes as Building Blocks of Key Sequences
1496 ==============================================
1498 Earlier versions of Emacs used only the ASCII character set, which
1499 defines 128 different character codes. Some of these codes are
1500 assigned graphic symbols like `a' and `='; the rest are control
1501 characters, such as `Control-a' (also called `C-a'). `C-a' means you
1502 hold down the <CTRL> key and then press `a'.
1504 Keybindings in XEmacs are not restricted to the set of keystrokes
1505 that can be represented in ASCII. XEmacs can tell the difference
1506 between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
1508 A keystroke is like a piano chord: you get it by simultaneously
1509 striking several keys. To be more precise, a keystroke consists of a
1510 possibly empty set of modifiers followed by a single "keysym". The set
1511 of modifiers is small; it consists of `Control', `Meta', `Super',
1512 `Hyper', and `Shift'.
1514 The rest of the keys on your keyboard, along with the mouse buttons,
1515 make up the set of keysyms. A keysym is usually what is printed on the
1516 keys on your keyboard. Here is a table of some of the symbolic names
1534 upstroke on the left mouse button
1537 upstroke on the middle mouse button
1540 upstroke on the right mouse button
1545 Use the variable `keyboard-translate-table' only if you are on a
1546 dumb tty, as it cannot handle input that cannot be represented as ASCII.
1547 The value of this variable is a string used as a translate table for
1548 keyboard input or `nil'. Each character is looked up in this string
1549 and the contents used instead. If the string is of length `n',
1550 character codes `N' and up are untranslated. If you are running Emacs
1551 under X, you should do the translations with the `xmodmap' program
1555 File: xemacs.info, Node: Representing Keystrokes, Next: Key Sequences, Prev: Intro to Keystrokes, Up: Keystrokes
1557 Representing Keystrokes
1558 -----------------------
1560 XEmacs represents keystrokes as lists. Each list consists of an
1561 arbitrary combination of modifiers followed by a single keysym at the
1562 end of the list. If the keysym corresponds to an ASCII character, you
1563 can use its character code. (A keystroke may also be represented by an
1564 event object, as returned by the `read-key-sequence' function;
1565 non-programmers need not worry about this.)
1567 The following table gives some examples of how to list
1568 representations for keystrokes. Each list consists of sets of
1569 modifiers followed by keysyms:
1572 Pressing <CTRL> and `a' simultaneously.
1575 Another way of writing the keystroke `C-a'.
1578 Yet another way of writing the keystroke `C-a'.
1581 Pressing the <BREAK> key.
1583 `(control meta button2up)'
1584 Release the middle mouse button, while pressing <CTRL> and <META>.
1585 Note: As you define keystrokes, you can use the `shift' key only
1586 as a modifier with characters that do not have a second keysym on the
1587 same key, such as `backspace' and `tab'. It is an error to define a
1588 keystroke using the <shift> modifier with keysyms such as `a' and `='.
1589 The correct forms are `A' and `+'.
1592 File: xemacs.info, Node: Key Sequences, Next: String Key Sequences, Prev: Representing Keystrokes, Up: Keystrokes
1594 Representing Key Sequences
1595 --------------------------
1597 A "complete key sequence" is a sequence of keystrokes that Emacs
1598 understands as a unit. Key sequences are significant because you can
1599 bind them to commands. Note that not all sequences of keystrokes are
1600 possible key sequences. In particular, the initial keystrokes in a key
1601 sequence must make up a "prefix key sequence".
1603 Emacs represents a key sequence as a vector of keystrokes. Thus, the
1604 schematic representation of a complete key sequence is as follows:
1606 [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]
1608 Here are some examples of complete key sequences:
1610 `[(control c) (control a)]'
1611 Typing `C-c' followed by `C-a'
1613 `[(control c) (control 65)]'
1614 Typing `C-c' followed by `C-a'. (Using the ASCII code for the
1617 `[(control c) (break)]'
1618 Typing `C-c' followed by the `break' character.
1620 A "prefix key sequence" is the beginning of a series of longer
1621 sequences that are valid key sequences; adding any single keystroke to
1622 the end of a prefix results in a valid key sequence. For example,
1623 `control-x' is standardly defined as a prefix. Thus there is a
1624 two-character key sequence starting with `C-x' for each valid
1625 keystroke, giving numerous possibilities. Here are some samples:
1627 * `[(control x) (c)]'
1629 * `[(control x) (control c)]'
1631 Adding one character to a prefix key does not have to form a complete
1632 key. It could make another, longer prefix. For example, `[(control x)
1633 (\4)]' is itself a prefix that leads to any number of different
1634 three-character keys, including `[(control x) (\4) (f)]', `[(control x)
1635 (\4) (b)]' and so on. It would be possible to define one of those
1636 three-character sequences as a prefix, creating a series of
1637 four-character keys, but we did not define any of them this way.
1639 By contrast, the two-character sequence `[(control f) (control k)]'
1640 is not a key, because the `(control f)' is a complete key sequence in
1641 itself. You cannot give `[(control f (control k)]' an independent
1642 meaning as a command while `(control f)' is a complete sequence,
1643 because Emacs would understand <C-f C-k> as two commands.
1645 The predefined prefix key sequences in Emacs are `(control c)',
1646 `(control x)', `(control h)', `[(control x) (\4)]', and `escape'. You
1647 can customize Emacs and could make new prefix keys or eliminate the
1648 default key sequences. *Note Key Bindings::. For example, if you
1649 redefine `(control f)' as a prefix, `[(control f) (control k)]'
1650 automatically becomes a valid key sequence (complete, unless you define
1651 it as a prefix as well). Conversely, if you remove the prefix
1652 definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
1653 `[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
1655 Note that the above paragraphs uses \4 instead of simply 4, because
1656 \4 is the symbol whose name is "4", and plain 4 is the integer 4, which
1657 would have been interpreted as the ASCII value. Another way of
1658 representing the symbol whose name is "4" is to write ?4, which would be
1659 interpreted as the number 52, which is the ASCII code for the character
1660 "4". We could therefore actually have written 52 directly, but that is
1664 File: xemacs.info, Node: String Key Sequences, Next: Meta Key, Prev: Key Sequences, Up: Keystrokes
1666 String Key Sequences
1667 --------------------
1669 For backward compatibility, you may also represent a key sequence using
1670 strings. For example, we have the following equivalent representations:
1673 `[(control c) (control c)]'
1676 `[(meta control c)]'
1679 File: xemacs.info, Node: Meta Key, Next: Super and Hyper Keys, Prev: String Key Sequences, Up: Keystrokes
1681 Assignment of the <META> Key
1682 ----------------------------
1684 Not all terminals have the complete set of modifiers. Terminals that
1685 have a <Meta> key allow you to type Meta characters by just holding
1686 that key down. To type `Meta-a', hold down <META> and press `a'. On
1687 those terminals, the <META> key works like the <SHIFT> key. Such a key
1688 is not always labeled <META>, however, as this function is often a
1689 special option for a key with some other primary purpose.
1691 If there is no <META> key, you can still type Meta characters using
1692 two-character sequences starting with <ESC>. To enter `M-a', you could
1693 type `<ESC> a'. To enter `C-M-a', you would type `ESC C-a'. <ESC> is
1694 allowed on terminals with Meta keys, too, in case you have formed a
1697 If you are running under X and do not have a <META> key, it is
1698 possible to reconfigure some other key to be a <META> key. *Note Super
1701 Emacs believes the terminal has a <META> key if the variable
1702 `meta-flag' is non-`nil'. Normally this is set automatically according
1703 to the termcap entry for your terminal type. However, sometimes the
1704 termcap entry is wrong, and then it is useful to set this variable
1705 yourself. *Note Variables::, for how to do this.
1707 Note: If you are running under the X window system, the setting of
1708 the `meta-flag' variable is irrelevant.
1711 File: xemacs.info, Node: Super and Hyper Keys, Next: Character Representation, Prev: Meta Key, Up: Keystrokes
1713 Assignment of the <SUPER> and <HYPER> Keys
1714 ------------------------------------------
1716 Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
1717 keys. Under X, you can simulate the <SUPER> or <HYPER> key if you want
1718 to bind keys to sequences using `super' and `hyper'. You can use the
1719 `xmodmap' program to do this.
1721 For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
1724 Create a file called `~/.xmodmap'. In this file, place the lines
1726 remove Lock = Caps_Lock
1727 keysym Caps_Lock = Super_L
1730 The first line says that the key that is currently called `Caps_Lock'
1731 should no longer behave as a "lock" key. The second line says that
1732 this should now be called `Super_L' instead. The third line says that
1733 the key called `Super_L' should be a modifier key, which produces the
1736 To create a <META> or <HYPER> key instead of a <SUPER> key, replace
1737 the word `Super' above with `Meta' or `Hyper'.
1739 Just after you start up X, execute the command `xmodmap /.xmodmap'.
1740 You can add this command to the appropriate initialization file to have
1741 the command executed automatically.
1743 If you have problems, see the documentation for the `xmodmap'
1744 program. The X keyboard model is quite complicated, and explaining it
1745 is beyond the scope of this manual. However, we reprint the following
1746 description from the X Protocol document for your convenience:
1748 A list of keysyms is associated with each keycode. If that list
1749 (ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
1750 list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
1751 the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
1752 `K1 K2', then the list is treated as if it were the list ```K1 K2 K1
1753 K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
1754 of keysyms `K1 K2 K3', then the list is treated as if it were the list
1755 ```K1 K2 K3 NoSymbol'''.
1757 The first four elements of the list are split into two groups of
1758 keysyms. Group 1 contains the first and second keysyms; Group 2 contains
1759 third and fourth keysyms. Within each group, if the second element of
1760 the group is NoSymbol, then the group should be treated as if the second
1761 element were the same as the first element, except when the first
1762 element is an alphabetic keysym `K' for which both lowercase and
1763 uppercase forms are defined. In that case, the group should be treated
1764 as if the first element were the lowercase form of `K' and the second
1765 element were the uppercase form of `K'.
1767 The standard rules for obtaining a keysym from a KeyPress event make
1768 use of only the Group 1 and Group 2 keysyms; no interpretation of other
1769 keysyms in the list is given here. (That is, the last four keysyms are
1772 Which group to use is determined by modifier state. Switching between
1773 groups is controlled by the keysym named `Mode_switch'. Attach that
1774 keysym to some keycode and attach that keycode to any one of the
1775 modifiers Mod1 through Mod5. This modifier is called the "group
1776 modifier". For any keycode, Group 1 is used when the group modifier is
1777 off, and Group 2 is used when the group modifier is on.
1779 Within a group, which keysym to use is also determined by modifier
1780 state. The first keysym is used when the `Shift' and `Lock' modifiers
1781 are off. The second keysym is used when the `Shift' modifier is on, or
1782 when the `Lock' modifier is on and the second keysym is uppercase
1783 alphabetic, or when the `Lock' modifier is on and is interpreted as
1784 `ShiftLock'. Otherwise, when the `Lock' modifier is on and is
1785 interpreted as `CapsLock', the state of the `Shift' modifier is applied
1786 first to select a keysym, but if that keysym is lower-case alphabetic,
1787 then the corresponding upper-case keysym is used instead.
1789 In addition to the above information on keysyms, we also provide the
1790 following description of modifier mapping from the InterClient
1791 Communications Conventions Manual:
1793 X11 supports 8 modifier bits, of which 3 are pre-assigned to
1794 `Shift', `Lock', and `Control'. Each modifier bit is controlled by the
1795 state of a set of keys, and these sets are specified in a table
1796 accessed by `GetModifierMapping()' and `SetModifierMapping()'.
1798 A client needing to use one of the pre-assigned modifiers should
1799 assume that the modifier table has been set up correctly to control
1800 these modifiers. The `Lock' modifier should be interpreted as `Caps
1801 Lock' or `Shift Lock' according to whether the keycodes in its
1802 controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
1804 Clients should determine the meaning of a modifier bit from the
1805 keysyms being used to control it.
1807 A client needing to use an extra modifier, for example `Meta',
1810 1. Scan the existing modifier mappings.
1812 1. If it finds a modifier that contains a keycode whose set of
1813 keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
1816 2. If there is no existing modifier controlled by `XK_Meta_L' or
1817 `XK_Meta_R', it should select an unused modifier bit (one with
1818 an empty controlling set) and:
1820 2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
1821 that keycode to the set for the chosen modifier, and then:
1823 1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
1824 add that keycode to the set for the chosen modifier, and then:
1826 2. If the controlling set is still empty, interact with the user
1827 to select one or more keys to be `Meta'.
1829 3. If there are no unused modifier bits, ask the user to take
1832 This means that the `Mod1' modifier does not necessarily mean
1833 `Meta', although some applications (such as twm and emacs 18) assume
1834 that. Any of the five unassigned modifier bits could mean `Meta'; what
1835 matters is that a modifier bit is generated by a keycode which is bound
1836 to the keysym `Meta_L' or `Meta_R'.
1838 Therefore, if you want to make a <META> key, the right way is to
1839 make the keycode in question generate both a `Meta' keysym and some
1840 previously-unassigned modifier bit.
1843 File: xemacs.info, Node: Character Representation, Next: Commands, Prev: Super and Hyper Keys, Up: Keystrokes
1845 Representation of Characters
1846 ============================
1848 This section briefly discusses how characters are represented in Emacs
1849 buffers. *Note Key Sequences::, for information on representing key
1850 sequences to create key bindings.
1852 ASCII graphic characters in Emacs buffers are displayed with their
1853 graphics. <LFD> is the same as a newline character; it is displayed by
1854 starting a new line. <TAB> is displayed by moving to the next tab stop
1855 column (usually every 8 spaces). Other control characters are
1856 displayed as a caret (`^') followed by the non-control version of the
1857 character; thus, `C-a' is displayed as `^A'. Non-ASCII characters 128
1858 and up are displayed with octal escape sequences; thus, character code
1859 243 (octal), also called `M-#' when used as an input character, is
1860 displayed as `\243'.
1862 The variable `ctl-arrow' may be used to alter this behavior. *Note
1866 File: xemacs.info, Node: Commands, Prev: Character Representation, Up: Keystrokes
1871 This manual is full of passages that tell you what particular keys do.
1872 But Emacs does not assign meanings to keys directly. Instead, Emacs
1873 assigns meanings to "functions", and then gives keys their meanings by
1874 "binding" them to functions.
1876 A function is a Lisp object that can be executed as a program.
1877 Usually it is a Lisp symbol that has been given a function definition;
1878 every symbol has a name, usually made of a few English words separated
1879 by dashes, such as `next-line' or `forward-word'. It also has a
1880 "definition", which is a Lisp program. Only some functions can be the
1881 bindings of keys; these are functions whose definitions use
1882 `interactive' to specify how to call them interactively. Such
1883 functions are called "commands", and their names are "command names".
1884 More information on this subject will appear in the XEmacs Lisp
1887 The bindings between keys and functions are recorded in various
1888 tables called "keymaps". *Note Key Bindings::, for more information on
1889 key sequences you can bind commands to. *Note Keymaps::, for
1890 information on creating keymaps.
1892 When we say "`C-n' moves down vertically one line" we are glossing
1893 over a distinction that is irrelevant in ordinary use but is vital in
1894 understanding how to customize Emacs. The function `next-line' is
1895 programmed to move down vertically. `C-n' has this effect because it
1896 is bound to that function. If you rebind `C-n' to the function
1897 `forward-word' then `C-n' will move forward by words instead.
1898 Rebinding keys is a common method of customization.
1900 The rest of this manual usually ignores this subtlety to keep things
1901 simple. To give the customizer the information needed, we often state
1902 the name of the command that really does the work in parentheses after
1903 mentioning the key that runs it. For example, we will say that "The
1904 command `C-n' (`next-line') moves point vertically down," meaning that
1905 `next-line' is a command that moves vertically down and `C-n' is a key
1906 that is standardly bound to it.
1908 While we are on the subject of information for customization only,
1909 it's a good time to tell you about "variables". Often the description
1910 of a command will say, "To change this, set the variable `mumble-foo'."
1911 A variable is a name used to remember a value. Most of the variables
1912 documented in this manual exist just to facilitate customization: some
1913 command or other part of Emacs uses the variable and behaves
1914 differently depending on its setting. Until you are interested in
1915 customizing, you can ignore the information about variables. When you
1916 are ready to be interested, read the basic information on variables, and
1917 then the information on individual variables will make sense. *Note
1921 File: xemacs.info, Node: Pull-down Menus, Next: Entering Emacs, Prev: Keystrokes, Up: Top
1923 XEmacs Pull-down Menus
1924 ======================
1926 If you are running XEmacs under X, a menu bar on top of the Emacs frame
1927 provides access to pull-down menus of file, edit, and help-related
1928 commands. The menus provide convenient shortcuts and an easy interface
1929 for novice users. They do not provide additions to the functionality
1930 available via key commands; you can still invoke commands from the
1931 keyboard as in previous versions of Emacs.
1934 Perform file and buffer-related operations, such as opening and
1935 closing files, saving and printing buffers, as well as exiting
1939 Perform standard editing operations, such as cutting, copying,
1940 pasting, and killing selected text.
1943 Access to sub-applications implemented within XEmacs, such as the
1944 mail reader, the World Wide Web browser, the spell-checker, and
1945 the calendar program.
1948 Control various options regarding the way XEmacs works, such as
1949 controlling which elements of the frame are visible, selecting the
1950 fonts to be used for text, specifying whether searches are
1951 case-sensitive, etc.
1954 Present a menu of buffers for selection as well as the option to
1955 display a buffer list.
1958 Perform various actions designed to automate software development
1959 and similar technical work, such as searching through many files,
1960 compiling a program, and comparing or merging two or three files.
1963 Access to Emacs Info.
1965 There are two ways of selecting an item from a pull-down menu:
1967 * Select an item in the menu bar by moving the cursor over it and
1968 click the left mouse-button. Then move the cursor over the menu
1969 item you want to choose and click left again.
1971 * Select an item in the menu bar by moving the cursor over it and
1972 click and hold the left mouse-button. With the mouse-button
1973 depressed, move the cursor over the menu item you want, then
1974 release it to make your selection.
1976 If a command in the pull-down menu is not applicable in a given
1977 situation, the command is disabled and its name appears faded. You
1978 cannot invoke items that are faded. For example, many commands on the
1979 Edit menu appear faded until you select text on which they are to
1980 operate; after you select a block of text, edit commands are enabled.
1981 *Note Mouse Selection::, for information on using the mouse to select
1982 text. *Note Using X Selections::, for related information.
1984 There are also `M-x' equivalents for each menu item. To find the
1985 equivalent for any left-button menu item, do the following:
1987 1. Type `C-h k' to get the `Describe Key' prompt.
1989 2. Select the menu item and click.
1991 Emacs displays the function associated with the menu item in a
1992 separate window, usually together with some documentation.
1996 * File Menu:: Items on the File menu.
1997 * Edit Menu:: Items on the Edit menu.
1998 * Apps Menu:: Items on the Apps menu.
1999 * Options Menu:: Items on the Options menu.
2000 * Buffers Menu:: Information about the Buffers menu.
2001 * Tools Menu:: Items on the Tools menu.
2002 * Help Menu:: Items on the Help menu.
2003 * Menu Customization:: Adding and removing menu items and related
2007 File: xemacs.info, Node: File Menu, Next: Edit Menu, Up: Pull-down Menus
2012 The File menu bar item contains the items New Frame, Open File..., Save
2013 Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete Frame,
2014 Kill Buffer and Exit Emacs on the pull-down menu. If you select a menu
2015 item, Emacs executes the equivalent command.
2017 Open File, New Frame...
2018 Prompts you for a filename and loads that file into a new buffer
2019 in a new Emacs frame, that is, a new X window running under the
2020 same Emacs process. You can remove the frame using the Delete
2021 Frame menu item. When you remove the last frame, you exit Emacs
2022 and are prompted for confirmation.
2025 Prompts you for a filename and loads that file into a new buffer.
2026 Open File... is equivalent to the Emacs command `find-file' (`C-x
2030 Prompts you for a filename and inserts the contents of that file
2031 into the current buffer. The file associated with the current
2032 buffer is not changed by this command. This is equivalent to the
2033 Emacs command `insert-file' (`C-x i').
2036 Writes and saves the current Emacs buffer as the latest version of
2037 the current visited file. Save Buffer is equivalent to the Emacs
2038 command `save-buffer' (`C-x C-s').
2041 Writes and saves the current Emacs buffer to the filename you
2042 specify. Save Buffer As... is equivalent to the Emacs command
2043 `write-file' (`C-x C-w').
2046 Restores the last saved version of the file to the current buffer.
2047 When you edit a buffer containing a text file, you must save the
2048 buffer before your changes become effective. Use Revert Buffer if
2049 you do not want to keep the changes you have made in the buffer.
2050 Revert Buffer is equivalent to the Emacs command `revert-file'
2051 (`M-x revert-buffer').
2054 Kills the current buffer, prompting you first if there are unsaved
2055 changes. This is roughly equivalent to the Emacs command
2056 `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
2057 name of a buffer to kill.
2060 Prints a hardcopy of the current buffer. Equivalent to the Emacs
2061 command `print-buffer' (`M-x print-buffer').
2064 Creates a new Emacs frame displaying the `*scratch*' buffer. This
2065 is like the Open File, New Frame... menu item, except that it does
2066 not prompt for or load a file.
2069 Allows you to close all but one of the frames created by New Frame.
2070 If you created several Emacs frames belonging to the same Emacs
2071 process, you can close all but one of them. When you attempt to
2072 close the last frame, Emacs informs you that you are attempting to
2073 delete the last frame. You have to choose Exit Emacs for that.
2076 Divides the current window on the current frame into two
2077 equal-sized windows, both displaying the same buffer. Equivalent
2078 to the Emacs command `split-window-vertically' (`C-x 2').
2080 Un-split (Keep This)
2081 If the frame is divided into multiple windows, this removes all
2082 windows other than the selected one. Equivalent to the Emacs
2083 command `delete-other-windows' (`C-x 1').
2085 Un-split (Keep Others)
2086 If the frame is divided into multiple windows, this removes the
2087 selected window from the frame, giving the space back to one of the
2088 other windows. Equivalent to the Emacs command `delete-window'
2092 Shuts down (kills) the Emacs process. Equivalent to the Emacs
2093 command `save-buffers-kill-emacs' (`C-x C-c'). Before killing the
2094 Emacs process, the system asks which unsaved buffers to save by
2095 going through the list of all buffers in that Emacs process.
2098 File: xemacs.info, Node: Edit Menu, Next: Apps Menu, Prev: File Menu, Up: Pull-down Menus
2103 The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and Clear
2104 menu items. When you select a menu item, Emacs executes the equivalent
2105 command. Most commands on the Edit menu work on a block of text, the X
2106 selection. They appear faded until you select a block of text
2107 (activate a region) with the mouse. *Note Using X Selections::, *note
2108 Killing::, and *note Yanking:: for more information.
2111 Undoes the previous command. Undo is equivalent to the Emacs
2112 command `undo' (`C-x u').
2115 Removes the selected text block from the current buffer, makes it
2116 the X clipboard selection, and places it in the kill ring. Before
2117 executing this command, you have to select a region using Emacs
2118 region selection commands or with the mouse.
2121 Makes a selected text block the X clipboard selection, and places
2122 it in the kill ring. You can select text using one of the Emacs
2123 region selection commands or by selecting a text region with the
2127 Inserts the current value of the X clipboard selection in the
2128 current buffer. Note that this is not necessarily the same as the
2129 Emacs `yank' command, because the Emacs kill ring and the X
2130 clipboard selection are not the same thing. You can paste in text
2131 you have placed in the clipboard using Copy or Cut. You can also
2132 use Paste to insert text that was pasted into the clipboard from
2136 Removes the selected text block from the current buffer but does
2137 not place it in the kill ring or the X clipboard selection.
2139 Start Macro Recording
2140 After selecting this, Emacs will remember every keystroke you type
2141 until End Macro Recording is selected. This is the same as the
2142 Emacs command `start-kbd-macro' (`C-x (').
2145 Selecting this tells emacs to stop remembering your keystrokes.
2146 This is the same as the Emacs command `end-kbd-macro' (`C-x )').
2149 Selecting this item will cause emacs to re-interpret all of the
2150 keystrokes which were saved between selections of the Start Macro
2151 Recording and End Macro Recording menu items. This is the same as
2152 the Emacs command `call-last-kbd-macro' (`C-x e').
2155 File: xemacs.info, Node: Apps Menu, Next: Options Menu, Prev: Edit Menu, Up: Pull-down Menus
2160 The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
2161 (MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
2162 Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
2163 When you select a menu item, Emacs executes the equivalent command.
2164 For some of the menu items, there are sub-menus which you will need to
2168 File: xemacs.info, Node: Options Menu, Next: Buffers Menu, Prev: Apps Menu, Up: Pull-down Menus
2173 The Options pull-down menu contains the Read Only, Case Sensitive
2174 Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
2175 Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
2176 Menu Length..., Buffers Sub-Menus and Save Options menu items. When
2177 you select a menu item, Emacs executes the equivalent command. For
2178 some of the menu items, there are sub-menus which you will need to
2182 Selecting this item will cause the buffer to visit the file in a
2183 read-only mode. Changes to the file will not be allowed. This is
2184 equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
2186 Case Sensitive Search
2187 Selecting this item will cause searches to be case-sensitive. If
2188 its not selected then searches will ignore case. This option is
2189 local to the buffer.
2192 After selecting this item, when you type letters they will replace
2193 existing text on a one-to-one basis, rather than pushing it to the
2194 right. At the end of a line, such characters extend the line.
2195 Before a tab, such characters insert until the tab is filled in.
2196 This is the same as Emacs command `quoted-insert' (`C-q').
2198 Auto Delete Selection
2199 Selecting this item will cause automatic deletion of the selected
2200 region. The typed text will replace the selection if the selection
2201 is active (i.e. if its highlighted). If the option is not selected
2202 then the typed text is just inserted at the point.
2204 Teach Extended Commands
2205 After you select this item, any time you execute a command with
2206 `M-x'which has a shorter keybinding, you will be shown the
2207 alternate binding before the command executes.
2210 You can customize your init file to include the font-lock mode so
2211 that when you select this item, the comments will be displayed in
2212 one face, strings in another, reserved words in another, and so
2213 on. *Note Init File::. When Fonts is selected, different parts of
2214 the program will appear in different Fonts. When Colors is
2215 selected, then the program will be displayed in different colors.
2216 Selecting None causes the program to appear in just one Font and
2217 Color. Selecting Less resets the Fonts and Colors to a fast,
2218 minimal set of decorations. Selecting More resets the Fonts and
2219 Colors to a larger set of decorations. For example, if Less is
2220 selected (which is the default setting) then you might have all
2221 comments in green color. Whereas, if More is selected then a
2222 function name in the comments themselves might appear in a
2223 different Color or Font.
2226 After selecting Blink from this item, if you place the cursor on a
2227 parenthesis, the matching parenthesis will blink. If you select
2228 Highlight and place the cursor on a parenthesis, the whole
2229 expression of the parenthesis under the cursor will be highlighted.
2230 Selecting None will turn off the options (regarding Paren
2231 Highlighting) which you had selected earlier.
2234 You can select any Font for your program by choosing from one of
2235 the available Fonts.
2238 You can select any size ranging from 2 to 24 by selecting the
2242 You can choose either Bold or Medium for the weight.
2244 Buffers Menu Length...
2245 Prompts you for the number of buffers to display. Then it will
2246 display that number of most recently selected buffers.
2249 After selection of this item the Buffers menu will contain several
2250 commands, as submenus of each buffer line. If this item is
2251 unselected, then there are no submenus for each buffer line, the
2252 only command available will be selecting that buffer.
2255 Selecting this item will save the current settings of your Options
2256 menu to your init file. *Note Init File::.
2259 File: xemacs.info, Node: Buffers Menu, Next: Tools Menu, Prev: Options Menu, Up: Pull-down Menus
2264 The Buffers menu provides a selection of up to ten buffers and the item
2265 List All Buffers, which provides a Buffer List. *Note List Buffers::,
2266 for more information.
2269 File: xemacs.info, Node: Tools Menu, Next: Help Menu, Prev: Buffers Menu, Up: Pull-down Menus
2274 The Tools pull-down menu contains the Grep..., Compile..., Shell
2275 Command..., Shell Command on Region..., Debug(GDB)... and
2276 Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
2277 sub-menus. When you select a menu item, Emacs executes the equivalent
2278 command. For some of the menu items, there are sub-menus which you
2279 will need to select.
2282 File: xemacs.info, Node: Help Menu, Next: Menu Customization, Prev: Tools Menu, Up: Pull-down Menus
2287 The Help Menu gives you access to Emacs Info and provides a menu
2288 equivalent for each of the choices you have when using `C-h'. *Note
2289 Help::, for more information.
2291 The Help menu also gives access to UNIX online manual pages via the
2292 UNIX Manual Page option.
2295 File: xemacs.info, Node: Menu Customization, Prev: Help Menu, Up: Pull-down Menus
2297 Customizing XEmacs Menus
2298 ------------------------
2300 You can customize any of the pull-down menus by adding or removing menu
2301 items and disabling or enabling existing menu items.
2303 The following functions are available:
2304 `add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)'
2305 Add a menu to the menu bar or one of its submenus.
2307 `add-menu-item: (MENU-PATH ITEM-NAME FUNCTION'
2308 ENABLED-P &optional BEFORE) Add a menu item to a menu, creating
2309 the menu first if necessary.
2311 `delete-menu-item: (PATH)'
2312 Remove the menu item defined by PATH from the menu hierarchy.
2314 `disable-menu-item: (PATH)'
2315 Disable the specified menu item.
2317 `enable-menu-item: (PATH)'
2318 Enable the specified previously disabled menu item.
2320 `relabel-menu-item: (PATH NEW-NAME)'
2321 Change the string of the menu item specified by PATH to NEW-NAME.
2324 Use the function `add-menu' to add a new menu or submenu. If a menu
2325 or submenu of the given name exists already, it is changed.
2327 MENU-PATH identifies the menu under which the new menu should be
2328 inserted. It is a list of strings; for example, `("File")' names the
2329 top-level File menu. `("File" "Foo")' names a hypothetical submenu of
2330 File. If MENU-PATH is `nil', the menu is added to the menu bar itself.
2332 MENU-NAME is the string naming the menu to be added.
2334 MENU-ITEMS is a list of menu item descriptions. Each menu item
2335 should be a vector of three elements:
2337 * A string, which is the name of the menu item
2339 * A symbol naming a command, or a form to evaluate
2341 * `t' or `nil' to indicate whether the item is selectable
2343 The optional argument BEFORE is the name of the menu before which
2344 the new menu or submenu should be added. If the menu is already
2345 present, it is not moved.
2347 The function `add-menu-item' adds a menu item to the specified menu,
2348 creating the menu first if necessary. If the named item already
2349 exists, the menu remains unchanged.
2351 MENU-PATH identifies the menu into which the new menu item should be
2352 inserted. It is a list of strings; for example, `("File")' names the
2353 top-level File menu. `("File" "Foo")' names a hypothetical submenu of
2356 ITEM-NAME is the string naming the menu item to add.
2358 FUNCTION is the command to invoke when this menu item is selected.
2359 If it is a symbol, it is invoked with `call-interactively', in the same
2360 way that functions bound to keys are invoked. If it is a list, the
2361 list is simply evaluated.
2363 ENABLED-P controls whether the item is selectable or not. It should
2364 be `t', `nil', or a form to evaluate to decide. This form will be
2365 evaluated just before the menu is displayed, and the menu item will be
2366 selectable if that form returns non-`nil'.
2368 For example, to make the `rename-file' command available from the
2369 File menu, use the following code:
2371 (add-menu-item '("File") "Rename File" 'rename-file t)
2373 To add a submenu of file management commands using a File Management
2374 item, use the following code:
2376 (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
2377 (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
2378 (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
2380 The optional BEFORE argument is the name of a menu item before which
2381 the new item should be added. If the item is already present, it is
2384 To remove a specified menu item from the menu hierarchy, use
2387 PATH is a list of strings that identify the position of the menu
2388 item in the menu hierarchy. `("File" "Save")' means the menu item
2389 called Save under the top level File menu. `("Menu" "Foo" "Item")'
2390 means the menu item called Item under the Foo submenu of Menu.
2392 To disable a menu item, use `disable-menu-item'. The disabled menu
2393 item is grayed and can no longer be selected. To make the item
2394 selectable again, use `enable-menu-item'. `disable-menu-item' and
2395 `enable-menu-item' both have the argument PATH.
2397 To change the string of the specified menu item, use
2398 `relabel-menu-item'. This function also takes the argument PATH.
2400 NEW-NAME is the string to which the menu item will be changed.
2403 File: xemacs.info, Node: Entering Emacs, Next: Exiting, Prev: Pull-down Menus, Up: Top
2405 Entering and Exiting Emacs
2406 **************************
2408 The usual way to invoke XEmacs is to type `xemacs <RET>' at the shell.
2409 XEmacs clears the screen and then displays an initial advisory message
2410 and copyright notice. You can begin typing XEmacs commands immediately
2413 Some operating systems insist on discarding all type-ahead when
2414 XEmacs starts up; they give XEmacs no way to prevent this. Therefore,
2415 it is advisable to wait until XEmacs clears the screen before typing
2416 your first editing command.
2418 If you run XEmacs from a shell window under the X Window System, run
2419 it in the background with `xemacs&'. This way, XEmacs does not tie up
2420 the shell window, so you can use that to run other shell commands while
2421 XEmacs operates its own X windows. You can begin typing XEmacs commands
2422 as soon as you direct your keyboard input to the XEmacs frame.
2424 Before Emacs reads the first command, you have not had a chance to
2425 give a command to specify a file to edit. Since Emacs must always have
2426 a current buffer for editing, it presents a buffer, by default, a buffer
2427 named `*scratch*'. The buffer is in Lisp Interaction mode; you can use
2428 it to type Lisp expressions and evaluate them, or you can ignore that
2429 capability and simply doodle. (You can specify a different major mode
2430 for this buffer by setting the variable `initial-major-mode' in your
2431 init file. *Note Init File::.)
2433 It is possible to specify files to be visited, Lisp files to be
2434 loaded, and functions to be called, by giving Emacs arguments in the
2435 shell command line. *Note Command Switches::. But we don't recommend
2436 doing this. The feature exists mainly for compatibility with other
2439 Many other editors are designed to be started afresh each time you
2440 want to edit. You edit one file and then exit the editor. The next
2441 time you want to edit either another file or the same one, you must run
2442 the editor again. With these editors, it makes sense to use a
2443 command-line argument to say which file to edit.
2445 But starting a new Emacs each time you want to edit a different file
2446 does not make sense. For one thing, this would be annoyingly slow. For
2447 another, this would fail to take advantage of Emacs's ability to visit
2448 more than one file in a single editing session. And it would lose the
2449 other accumulated context, such as registers, undo history, and the mark
2452 The recommended way to use XEmacs is to start it only once, just
2453 after you log in, and do all your editing in the same Emacs session.
2454 Each time you want to edit a different file, you visit it with the
2455 existing Emacs, which eventually comes to have many files in it ready
2456 for editing. Usually you do not kill the Emacs until you are about to
2457 log out. *Note Files::, for more information on visiting more than one
2461 File: xemacs.info, Node: Exiting, Next: Command Switches, Prev: Entering Emacs, Up: Top
2466 There are two commands for exiting Emacs because there are two kinds of
2467 exiting: "suspending" Emacs and "killing" Emacs.
2469 "Suspending" means stopping Emacs temporarily and returning control
2470 to its parent process (usually a shell), allowing you to resume editing
2471 later in the same Emacs job, with the same buffers, same kill ring,
2472 same undo history, and so on. This is the usual way to exit.
2474 "Killing" Emacs means destroying the Emacs job. You can run Emacs
2475 again later, but you will get a fresh Emacs; there is no way to resume
2476 the same editing session after it has been killed.
2479 Suspend Emacs or iconify a frame
2480 (`suspend-emacs-or-iconify-frame'). If used under the X window
2481 system, shrink the X window containing the Emacs frame to an icon
2485 Kill Emacs (`save-buffers-kill-emacs').
2487 If you use XEmacs under the X window system, `C-z' shrinks the X
2488 window containing the Emacs frame to an icon. The Emacs process is
2489 stopped temporarily, and control is returned to the window manager. If
2490 more than one frame is associated with the Emacs process, only the
2491 frame from which you used `C-z' is iconified.
2493 To activate the "suspended" Emacs, use the appropriate window manager
2494 mouse gestures. Usually left-clicking on the icon reactivates and
2495 reopens the X window containing the Emacs frame, but the window manager
2496 you use determines what exactly happens. To actually kill the Emacs
2497 process, use `C-x C-c' or the Exit XEmacs item on the File menu.
2499 To suspend Emacs, type `C-z' (`suspend-emacs'). This takes you back
2500 to the shell from which you invoked Emacs. You can resume Emacs with
2501 the shell command `%xemacs' in most common shells.
2503 On systems that do not support suspending programs, `C-z' starts an
2504 inferior shell that communicates directly with the terminal. Emacs
2505 waits until you exit the subshell. (The way to do that is probably
2506 with `C-d' or `exit', but it depends on which shell you use.) The only
2507 way on these systems to get back to the shell from which Emacs was run
2508 (to log out, for example) is to kill Emacs.
2510 Suspending also fails if you run Emacs under a shell that doesn't
2511 support suspending programs, even if the system itself does support it.
2512 In such a case, you can set the variable `cannot-suspend' to a
2513 non-`nil' value to force `C-z' to start an inferior shell. (One might
2514 also describe Emacs's parent shell as "inferior" for failing to support
2515 job control properly, but that is a matter of taste.)
2517 When Emacs communicates directly with an X server and creates its own
2518 dedicated X windows, `C-z' has a different meaning. Suspending an
2519 applications that uses its own X windows is not meaningful or useful.
2520 Instead, `C-z' runs the command `iconify-or-deiconify-frame', which
2521 temporarily closes up the selected Emacs frame. The way to get back to
2522 a shell window is with the window manager.
2524 To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs'). A
2525 two-character key is used for this to make it harder to type. Selecting
2526 the Exit XEmacs option of the File menu is an alternate way of issuing
2529 Unless a numeric argument is used, this command first offers to save
2530 any modified file-visiting buffers. If you do not save all buffers,
2531 you are asked for reconfirmation with `yes' before killing Emacs, since
2532 any changes not saved will be lost forever. If any subprocesses are
2533 still running, `C-x C-c' asks you to confirm killing them, since killing
2534 Emacs will kill the subprocesses immediately.
2536 There is no way to restart an Emacs session once you have killed it.
2537 You can, however, arrange for Emacs to record certain session
2538 information, such as which files are visited, when you kill it, so that
2539 the next time you restart Emacs it will try to visit the same files and
2542 The operating system usually listens for certain special characters
2543 whose meaning is to kill or suspend the program you are running. This
2544 operating system feature is turned off while you are in Emacs. The
2545 meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the
2546 use of `C-z' and `C-c' on several operating systems as the characters
2547 for stopping or killing a program, but that is their only relationship
2548 with the operating system. You can customize these keys to run any
2549 commands of your choice (*note Keymaps::).
2552 File: xemacs.info, Node: Command Switches, Next: Startup Paths, Prev: Exiting, Up: Top
2554 Command Line Switches and Arguments
2555 ===================================
2557 XEmacs supports command line arguments you can use to request various
2558 actions when invoking Emacs. The commands are for compatibility with
2559 other editors and for sophisticated activities. If you are using
2560 XEmacs under the X window system, you can also use a number of standard
2561 Xt command line arguments. Command line arguments are not usually
2562 needed for editing with Emacs; new users can skip this section.
2564 Many editors are designed to be started afresh each time you want to
2565 edit. You start the editor to edit one file; then exit the editor. The
2566 next time you want to edit either another file or the same one, you
2567 start the editor again. Under these circumstances, it makes sense to
2568 use a command line argument to say which file to edit.
2570 The recommended way to use XEmacs is to start it only once, just
2571 after you log in, and do all your editing in the same Emacs process.
2572 Each time you want to edit a file, you visit it using the existing
2573 Emacs. Emacs creates a new buffer for each file, and (unless you kill
2574 some of the buffers) Emacs eventually has many files in it ready for
2575 editing. Usually you do not kill the Emacs process until you are about
2576 to log out. Since you usually read files by typing commands to Emacs,
2577 command line arguments for specifying a file when Emacs is started are
2580 Emacs accepts command-line arguments that specify files to visit,
2581 functions to call, and other activities and operating modes. If you
2582 are running XEmacs under the X window system, a number of standard Xt
2583 command line arguments are available, as well as a few X parameters
2584 that are XEmacs-specific.
2586 Options with long names with a single initial hyphen are also
2587 recognized with the GNU double initial hyphen syntax. (The reverse is
2590 The following subsections list:
2591 * Command line arguments that you can always use
2593 * Command line arguments that have to appear at the beginning of the
2596 * Command line arguments that are only relevant if you are running
2599 Command Line Arguments for Any Position
2600 ---------------------------------------
2602 Command line arguments are processed in the order they appear on the
2603 command line; however, certain arguments (the ones in the second table)
2604 must be at the front of the list if they are used.
2606 Here are the arguments allowed:
2609 Visit FILE using `find-file'. *Note Visiting::.
2612 Visit FILE using `find-file', then go to line number LINENUM in it.
2616 Load a file FILE of Lisp code with the function `load'. *Note
2621 Call Lisp function FUNCTION with no arguments.
2624 Interpret the next argument as a Lisp expression, and evaluate it.
2625 You must be very careful of the shell quoting here.
2629 Insert the contents of FILE into the current buffer. This is like
2630 what `M-x insert-buffer' does; *Note Misc File Ops::.
2633 Exit from Emacs without asking for confirmation. Always the last
2634 argument processed, no matter where it appears in the command line.
2638 Prints version information. This implies `-batch'.
2641 XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs]
2644 Prints a summary of command-line options and then exits.
2646 Command Line Arguments (Beginning of Line Only)
2647 -----------------------------------------------
2649 The following arguments are recognized only at the beginning of the
2650 command line. If more than one of them appears, they must appear in the
2651 order in which they appear in this table.
2655 Print the ID for the new portable dumper's dump file on the
2656 terminal and exit. (Prints an error message and exits if XEmacs
2657 was not configured `--pdump'.)
2661 Don't load the dump file. Roughly equivalent to old temacs.
2662 (Ignored if XEmacs was not configured `--pdump'.)
2666 Use FILE instead of the terminal for input and output. This
2667 implies the `-nw' option, documented below.
2670 Run Emacs in "batch mode", which means that the text being edited
2671 is not displayed and the standard Unix interrupt characters such as
2672 `C-z' and `C-c' continue to have their normal effect. Emacs in
2673 batch mode outputs to `stderr' only what would normally be printed
2674 in the echo area under program control.
2676 Batch mode is used for running programs written in Emacs Lisp from
2677 shell scripts, makefiles, and so on. Normally the `-l' switch or
2678 `-f' switch will be used as well, to invoke a Lisp program to do
2679 the batch processing.
2681 `-batch' implies `-q' (do not load an init file). It also causes
2682 Emacs to kill itself after all command switches have been
2683 processed. In addition, auto-saving is not done except in buffers
2684 for which it has been explicitly requested.
2688 Start up XEmacs in TTY mode (using the TTY XEmacs was started
2689 from), rather than trying to connect to an X display. Note that
2690 this happens automatically if the `DISPLAY' environment variable
2694 Enter the debugger if an error in the init file occurs.
2697 Displays information on how XEmacs constructs the various paths
2698 into its hierarchy on startup. (See also *note Startup Paths::.)
2701 Do not map the initial frame. This is useful if you want to start
2702 up XEmacs as a server (e.g. for gnuserv screens or external client
2707 Do not load your Emacs init file. *Note Init File::.
2710 Do not load the site-specific init file `lisp/site-start.el'.
2713 Do not load global symbol files (`auto-autoloads') at startup.
2714 This implies `-vanilla'.
2716 `-no-early-packages'
2717 Do not process early packages. (For more information on startup
2718 issues concerning the package system, *Note Startup Paths::.)
2721 This is equivalent to `-q -no-site-file -no-early-packages'.
2723 `-user-init-file FILE'
2724 Load FILE as your Emacs init file instead of
2725 `~/.xemacs/init.el'/`~/.emacs'.
2727 `-user-init-directory DIRECTORY'
2728 Use DIRECTORY as the location of your early package hierarchies
2729 and the various user-specific initialization files.
2733 Equivalent to `-user-init-file ~USER/.xemacs/init.el
2734 -user-init-directory ~USER/.xemacs', or `-user-init-file
2735 ~USER/.emacs -user-init-directory ~USER/.xemacs', whichever init
2736 file comes first. *Note Init File::.
2739 Note that the init file can get access to the command line argument
2740 values as the elements of a list in the variable `command-line-args'.
2741 (The arguments in the second table above will already have been
2742 processed and will not be in the list.) The init file can override the
2743 normal processing of the other arguments by setting this variable.
2745 One way to use command switches is to visit many files automatically:
2749 passes each `.c' file as a separate argument to Emacs, so that Emacs
2750 visits each file (*note Visiting::).
2752 Here is an advanced example that assumes you have a Lisp program file
2753 called `hack-c-program.el' which, when loaded, performs some useful
2754 operation on the current buffer, expected to be a C program.
2756 xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
2758 Here Emacs is told to visit `foo.c', load `hack-c-program.el' (which
2759 makes changes in the visited file), save `foo.c' (note that
2760 `save-buffer' is the function that `C-x C-s' is bound to), and then
2761 exit to the shell from which the command was executed. `-batch'
2762 guarantees there will be no problem redirecting output to `log',
2763 because Emacs will not assume that it has a display terminal to work
2766 Command Line Arguments (for XEmacs Under X)
2767 -------------------------------------------
2769 If you are running XEmacs under X, a number of options are available to
2770 control color, border, and window title and icon name:
2775 Use TITLE as the window title. This sets the `frame-title-format'
2776 variable, which controls the title of the X window corresponding
2777 to the selected frame. This is the same format as
2782 Use TITLE as the icon name. This sets the
2783 `frame-icon-title-format' variable, which controls the title of
2784 the icon corresponding to the selected frame.
2787 Use COLOR as the mouse color.
2790 Use COLOR as the text-cursor foreground color.
2793 Install a private colormap for XEmacs.
2795 In addition, XEmacs allows you to use a number of standard Xt
2796 command line arguments.
2800 Use COLOR as the background color.
2802 `-bordercolor COLOR'
2804 Use COLOR as the border color.
2806 `-borderwidth WIDTH'
2808 Use WIDTH as the border width.
2812 When running under the X window system, create the window
2813 containing the Emacs frame on the display named DISPLAY.
2817 Use COLOR as the foreground color.
2821 Use NAME as the default font.
2826 Use the geometry (window size and/or position) specified by SPEC.
2832 Bring up Emacs in reverse video.
2835 Use the resource manager resources specified by NAME. The default
2836 is to use the name of the program (`argv[0]') as the resource
2840 Read something into the resource database for this invocation of
2845 File: xemacs.info, Node: Startup Paths, Next: Packages, Prev: Command Switches, Up: Top
2847 How XEmacs finds Directories and Files
2848 ======================================
2850 XEmacs deals with a multitude of files during operation. These files
2851 are spread over many directories, and XEmacs determines the location of
2852 most of these directories at startup and organizes them into various
2853 paths. (A "path", for the purposes of this section, is simply a list
2854 of directories which XEmacs searches successively in order to locate a
2857 XEmacs Directory Hierarchies
2858 ----------------------------
2860 Many of the files XEmacs looks for are located within the XEmacs
2861 installation itself. However, there are several views of what actually
2862 constitutes the "XEmacs installation": XEmacs may be run from the
2863 compilation directory, it may be installed into arbitrary directories,
2864 spread over several directories unrelated to each other. Moreover, it
2865 may subsequently be moved to a different place. (This last case is not
2866 as uncommon as it sounds. Binary kits work this way.) Consequently,
2867 XEmacs has quite complex procedures in place to find directories, no
2868 matter where they may be hidden.
2870 XEmacs will always respect directory options passed to `configure'.
2871 However, if it cannot locate a directory at the configured place, it
2872 will initiate a search for the directory in any of a number of
2873 "hierarchies" rooted under a directory which XEmacs assumes contain
2874 parts of the XEmacs installation; it may locate several such hierarchies
2875 and search across them. (Typically, there are just one or two
2876 hierarchies: the hierarchy where XEmacs was or will be installed, and
2877 the one where it is being built.) Such a directory containing a
2878 hierarchy is called a "root". Whenever this section refers to a
2879 directory using the shorthand `<root>', it means that XEmacs searches
2880 for it under all hierarchies XEmacs was able to scrounge up. In a
2881 running XEmacs, the hierarchy roots are stored in the variable
2887 Many relevant directories and files XEmacs uses are actually not part of
2888 the core installation. They are part of any of the many packages
2889 usually installed on top of an XEmacs installation. (*Note Packages::.)
2890 Hence, they play a prominent role in the various paths XEmacs sets up.
2892 XEmacs locates packages in any of a number of package hierarchies.
2893 Package hierarchies fall into three groups: "early", "late", and "last",
2894 according to the relative location at which they show up in the various
2895 XEmacs paths. Early package hierarchies are at the very front, late
2896 ones somewhere in the middle, and last hierarchies are (you guessed it)
2899 By default, XEmacs expects an early package hierarchy in the
2900 subdirectory `.xemacs/xemacs-packages' of the user's home directory.
2902 Moreover, XEmacs expects late hierarchies in the subdirectories
2903 `site-packages', `mule-packages', and `xemacs-packages' (in that order)
2904 of the `<root>/lib/xemacs' subdirectory of one of the installation
2905 hierarchies. (If you run in-place, these are direct subdirectories of
2906 the build directory.) Furthermore, XEmacs will also search these
2907 subdirectories in the `<root>/lib/xemacs-<VERSION>' subdirectory and
2908 prefer directories found there.
2910 By default, XEmacs does not have a pre-configured last package
2911 hierarchy. Last hierarchies are primarily for using package hierarchies
2912 of outdated versions of XEmacs as a fallback option. For example, it is
2913 possible to run XEmacs 21 with the 20.4 package hierarchy as a last
2916 It is possible to specify at configure-time the location of the
2917 various package hierarchies with the `--package-path' option to
2918 configure. The early, late, and last components of the package path
2919 are separated by double instead of single colons. If all three
2920 components are present, they locate the early, late, and last package
2921 hierarchies respectively. If two components are present, they locate
2922 the early and late hierarchies. If only one component is present, it
2923 locates the late hierarchy. At run time, the package path may also be
2924 specified via the `EMACSPACKAGEPATH' environment variable.
2926 An XEmacs package is laid out just like a normal installed XEmacs
2927 lisp directory. It may have `lisp', `etc', `info', and `lib-src'
2928 subdirectories. XEmacs adds these at appropriate places within the
2929 various system-wide paths.
2931 There may be any number of package hierarchy directories.
2933 Directories and Paths
2934 ---------------------
2936 Here is a list of the various directories and paths XEmacs tries to
2937 locate during startup. XEmacs distinguishes between directories and
2938 paths specific to "version", "site", and "architecture" when looking
2942 directories are specific to the version of XEmacs they belong to
2943 and typically reside under `<root>/lib/xemacs-<VERSION>'.
2946 directories are independent of the version of XEmacs they belong
2947 to and typically reside under `<root>/lib/xemacs'
2949 `architecture-specific'
2950 directories are specific both to the version of XEmacs and the
2951 architecture it runs on and typically reside under
2952 `<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>'.
2954 During installation, all of these directories may also reside
2955 directly under `<root>', because that is where they are in the XEmacs
2958 If XEmacs runs with the `-debug-paths' option (*note Command
2959 Switches::), it will print the values of these variables, hopefully
2960 aiding in debugging any problems which come up.
2963 Contains the version-specific location of the Lisp files that come
2964 with the core distribution of XEmacs. XEmacs will search it
2965 recursively to a depth of 1 when setting up `load-path'.
2968 Is where XEmacs searches for XEmacs Lisp files with commands like
2969 `load-library'. It contains the package lisp directories (see
2970 further down) and the version-specific core Lisp directories. If
2971 the environment variable `EMACSLOADPATH' is set at startup, its
2972 directories are prepended to `load-path'.
2974 `Info-directory-list'
2975 Contains the location of info files. (See *Note (info)::.) It
2976 contains the package info directories and the version-specific core
2977 documentation. Moreover, XEmacs will add `/usr/info',
2978 `/usr/local/info' as well as the directories of the environment
2979 variable `INFOPATH' to `Info-directory-list'.
2982 Is the directory of architecture-dependent files that come with
2983 XEmacs, especially executable programs intended for XEmacs to
2987 Is the path for executables which XEmacs may want to start. It
2988 contains the package executable paths as well as `exec-directory',
2989 and the directories of the environment variables `PATH' and
2993 Is the directory containing the architecture-specific `DOC' file
2994 that contains documentation for XEmacs' commands.
2997 Is the version-specific directory that contains core data files
2998 XEmacs uses. It may be initialized from the `EMACSDATA'
2999 environment variable.
3001 `data-directory-list'
3002 Is the path where XEmacs looks for data files. It contains
3003 package data directories as well as `data-directory'.
3007 File: xemacs.info, Node: Basic, Next: Undo, Prev: Packages, Up: Top
3009 Basic Editing Commands
3010 **********************
3012 We now give the basics of how to enter text, make corrections, and save
3013 the text in a file. If this material is new to you, you might learn it
3014 more easily by running the Emacs learn-by-doing tutorial. To use the
3015 tutorial, run Emacs and type `Control-h t' (`help-with-tutorial'). You
3016 can also use Tutorials item from the Help menu.
3018 XEmacs comes with many translations of tutorial. If your XEmacs is
3019 with MULE and you set up language environment correctly, XEmacs chooses
3020 right tutorial when available (*note Language Environments::). If you
3021 want specific translation, give `C-h t' a prefix argument, like `C-u
3024 To clear the screen and redisplay, type `C-l' (`recenter').
3029 * Inserting Text:: Inserting text by simply typing it.
3030 * Moving Point:: How to move the cursor to the place where you want to
3032 * Erasing:: Deleting and killing text.
3033 * Files: Basic Files. Visiting, creating, and saving files.
3034 * Help: Basic Help. Asking what a character does.
3035 * Blank Lines:: Commands to make or delete blank lines.
3036 * Continuation Lines:: Lines too wide for the screen.
3037 * Position Info:: What page, line, row, or column is point on?
3038 * Arguments:: Numeric arguments for repeating a command.
3041 File: xemacs.info, Node: Inserting Text, Next: Moving Point, Up: Basic
3046 To insert printing characters into the text you are editing, just type
3047 them. This inserts the characters you type into the buffer at the
3048 cursor (that is, at "point"; *note Point::). The cursor moves forward,
3049 and any text after the cursor moves forward too. If the text in the
3050 buffer is `FOOBAR', with the cursor before the `B', then if you type
3051 `XX', you get `FOOXXBAR', with the cursor still before the `B'.
3053 To "delete" text you have just inserted, use <BS>. <BS> deletes the
3054 character _before_ the cursor (not the one that the cursor is on top of
3055 or under; that is the character AFTER the cursor). The cursor and all
3056 characters after it move backwards. Therefore, if you type a printing
3057 character and then type <BS>, they cancel out.
3059 To end a line and start typing a new one, type <RET>. This inserts
3060 a newline character in the buffer. If point is in the middle of a
3061 line, <RET> splits the line. Typing <DEL> when the cursor is at the
3062 beginning of a line deletes the preceding newline, thus joining the
3063 line with the preceding line.
3065 Emacs can split lines automatically when they become too long, if you
3066 turn on a special minor mode called "Auto Fill" mode. *Note Filling::,
3067 for how to use Auto Fill mode.
3069 If you prefer to have text characters replace (overwrite) existing
3070 text rather than shove it to the right, you can enable Overwrite mode,
3071 a minor mode. *Note Minor Modes::.
3073 Direct insertion works for printing characters and <SPC>, but other
3074 characters act as editing commands and do not insert themselves. If you
3075 need to insert a control character or a character whose code is above
3076 200 octal, you must "quote" it by typing the character `Control-q'
3077 (`quoted-insert') first. (This character's name is normally written
3078 `C-q' for short.) There are two ways to use `C-q':
3080 * `C-q' followed by any non-graphic character (even `C-g') inserts
3083 * `C-q' followed by a sequence of octal digits inserts the character
3084 with the specified octal character code. You can use any number of
3085 octal digits; any non-digit terminates the sequence. If the
3086 terminating character is <RET>, it serves only to terminate the
3087 sequence; any other non-digit is itself used as input after
3088 terminating the sequence. (The use of octal sequences is disabled
3089 in ordinary non-binary Overwrite mode, to give you a convenient
3090 way to insert a digit instead of overwriting with it.)
3092 A numeric argument to `C-q' specifies how many copies of the quoted
3093 character should be inserted (*note Arguments::).
3095 Customization information: <DEL>, in most modes, runs the command
3096 `backward-or-forward-delete-char'; <RET> runs the command `newline',
3097 and self-inserting printing characters run the command `self-insert',
3098 which inserts whatever character was typed to invoke it. Some major
3099 modes rebind <DEL> to other commands.
3102 File: xemacs.info, Node: Moving Point, Next: Erasing, Prev: Inserting Text, Up: Basic
3104 Changing the Location of Point
3105 ==============================
3107 To do more than insert characters, you have to know how to move point
3108 (*note Point::). The simplest way to do this is with arrow keys, or by
3109 clicking the left mouse button where you want to move to.
3111 NOTE: Many of the following commands have two versions, one that uses
3112 the function keys (e.g. <LEFT> or <END>) and one that doesn't. The
3113 former versions may only be available on X terminals (i.e. not on
3114 TTY's), but the latter are available on all terminals.
3118 Move to the beginning of the line (`beginning-of-line').
3122 Move to the end of the line (`end-of-line').
3126 Move forward one character (`forward-char').
3130 Move backward one character (`backward-char').
3134 Move forward one word (`forward-word').
3138 Move backward one word (`backward-word').
3142 Move down one line, vertically (`next-line'). This command
3143 attempts to keep the horizontal position unchanged, so if you
3144 start in the middle of one line, you end in the middle of the
3145 next. When on the last line of text, `C-n' creates a new line and
3150 Move up one line, vertically (`previous-line').
3154 Move down one page, vertically (`scroll-up').
3158 Move up one page, vertically (`scroll-down').
3161 Clear the frame and reprint everything (`recenter'). Text moves
3162 on the frame to bring point to the center of the window.
3165 Move point to left margin, vertically centered in the window
3166 (`move-to-window-line'). Text does not move on the screen.
3168 A numeric argument says which screen line to place point on. It
3169 counts screen lines down from the top of the window (zero for the
3170 top line). A negative argument counts lines from the bottom (-1
3171 for the bottom line).
3174 Transpose two characters, the ones before and after the cursor
3175 (`transpose-chars').
3179 Move to the top of the buffer (`beginning-of-buffer'). With
3180 numeric argument N, move to N/10 of the way from the top. *Note
3181 Arguments::, for more information on numeric arguments.
3185 Move to the end of the buffer (`end-of-buffer').
3188 Read a number N and move point to buffer position N. Position 1
3189 is the beginning of the buffer.
3192 Read a number N and move point to line number N (`goto-line').
3193 Line 1 is the beginning of the buffer.
3195 `M-x set-goal-column'
3196 Use the current column of point as the "semi-permanent goal
3197 column" for `C-n' and `C-p' (`set-goal-column'). Henceforth, those
3198 commands always move to this column in each line moved into, or as
3199 close as possible given the contents of the line. This goal
3200 column remains in effect until canceled.
3202 `C-u M-x set-goal-column'
3203 Cancel the goal column. Henceforth, `C-n' and `C-p' once again
3204 try to avoid changing the horizontal position, as usual.
3206 If you set the variable `track-eol' to a non-`nil' value, then `C-n'
3207 and `C-p' when at the end of the starting line move to the end of
3208 another line. Normally, `track-eol' is `nil'. *Note Variables::, for
3209 how to set variables such as `track-eol'.
3211 Normally, `C-n' on the last line of a buffer appends a newline to
3212 it. If the variable `next-line-add-newlines' is `nil', then `C-n' gets
3213 an error instead (like `C-p' on the first line).
3216 File: xemacs.info, Node: Erasing, Next: Basic Files, Prev: Moving Point, Up: Basic
3222 Delete the character before or after point
3223 (`backward-or-forward-delete-char'). You can customize this
3224 behavior by setting the variable `delete-key-deletes-forward'.
3227 Delete the character after point (`delete-char').
3230 Kill to the end of the line (`kill-line').
3233 Kill forward to the end of the next word (`kill-word').
3236 Kill back to the beginning of the previous word
3237 (`backward-kill-word').
3239 You already know about the <DEL> key which deletes the character
3240 before point (that is, before the cursor). Another key, `Control-d'
3241 (`C-d' for short), deletes the character after point (that is, the
3242 character that the cursor is on). This shifts the rest of the text on
3243 the line to the left. If you type `C-d' at the end of a line, it joins
3244 together that line and the next line.
3246 To erase a larger amount of text, use the `C-k' key, which kills a
3247 line at a time. If you type `C-k' at the beginning or middle of a
3248 line, it kills all the text up to the end of the line. If you type
3249 `C-k' at the end of a line, it joins that line and the next line.
3251 *Note Killing::, for more flexible ways of killing text.
3254 File: xemacs.info, Node: Basic Files, Next: Basic Help, Prev: Erasing, Up: Basic
3259 The commands described above are sufficient for creating and altering
3260 text in an Emacs buffer; the more advanced Emacs commands just make
3261 things easier. But to keep any text permanently you must put it in a
3262 "file". Files are named units of text which are stored by the
3263 operating system for you to retrieve later by name. To look at or use
3264 the contents of a file in any way, including editing the file with
3265 Emacs, you must specify the file name.
3267 Consider a file named `/usr/rms/foo.c'. To begin editing this file
3270 C-x C-f /usr/rms/foo.c <RET>
3272 Here the file name is given as an "argument" to the command `C-x C-f'
3273 (`find-file'). That command uses the "minibuffer" to read the
3274 argument, and you type <RET> to terminate the argument (*note
3277 You can also use the Open... menu item from the File menu, then type
3278 the name of the file to the prompt.
3280 Emacs obeys the command by "visiting" the file: creating a buffer,
3281 copying the contents of the file into the buffer, and then displaying
3282 the buffer for you to edit. If you alter the text, you can "save" the
3283 new text in the file by typing `C-x C-s' (`save-buffer') or choosing
3284 Save Buffer from the File menu. This makes the changes permanent by
3285 copying the altered buffer contents back into the file
3286 `/usr/rms/foo.c'. Until you save, the changes exist only inside Emacs,
3287 and the file `foo.c' is unaltered.
3289 To create a file, visit the file with `C-x C-f' as if it already
3290 existed or choose Open... from the File menu and provide the name for
3291 the new file. Emacs will create an empty buffer in which you can
3292 insert the text you want to put in the file. When you save the buffer
3293 with `C-x C-s', or by choosing Save Buffer from the File menu, the file
3296 To learn more about using files, *Note Files::.
3299 File: xemacs.info, Node: Basic Help, Next: Blank Lines, Prev: Basic Files, Up: Basic
3304 If you forget what a key does, you can find out with the Help
3305 character, which is `C-h' (or <F1>, which is an alias for `C-h'). Type
3306 `C-h k' followed by the key you want to know about; for example, `C-h k
3307 C-n' tells you all about what `C-n' does. `C-h' is a prefix key; `C-h
3308 k' is just one of its subcommands (the command `describe-key'). The
3309 other subcommands of `C-h' provide different kinds of help. Type `C-h'
3310 twice to get a description of all the help facilities. *Note Help::.
3313 File: xemacs.info, Node: Blank Lines, Next: Continuation Lines, Prev: Basic Help, Up: Basic
3318 Here are special commands and techniques for putting in and taking out
3322 Insert one or more blank lines after the cursor (`open-line').
3325 Delete all but one of many consecutive blank lines
3326 (`delete-blank-lines').
3328 When you want to insert a new line of text before an existing line,
3329 you can do it by typing the new line of text, followed by <RET>.
3330 However, it may be easier to see what you are doing if you first make a
3331 blank line and then insert the desired text into it. This is easy to do
3332 using the key `C-o' (`open-line'), which inserts a newline after point
3333 but leaves point in front of the newline. After `C-o', type the text
3334 for the new line. `C-o F O O' has the same effect as `F O O <RET>',
3335 except for the final location of point.
3337 You can make several blank lines by typing `C-o' several times, or
3338 by giving it a numeric argument to tell it how many blank lines to make.
3339 *Note Arguments::, for how. If you have a fill prefix, then `C-o'
3340 command inserts the fill prefix on the new line, when you use it at the
3341 beginning of a line. *Note Fill Prefix::.
3343 The easy way to get rid of extra blank lines is with the command
3344 `C-x C-o' (`delete-blank-lines'). `C-x C-o' in a run of several blank
3345 lines deletes all but one of them. `C-x C-o' on a solitary blank line
3346 deletes that blank line. When point is on a nonblank line, `C-x C-o'
3347 deletes any blank lines following that nonblank line.
3350 File: xemacs.info, Node: Continuation Lines, Next: Position Info, Prev: Blank Lines, Up: Basic
3355 If you add too many characters to one line without breaking it with
3356 <RET>, the line will grow to occupy two (or more) lines on the screen,
3357 with a curved arrow at the extreme right margin of all but the last of
3358 them. The curved arrow says that the following screen line is not
3359 really a distinct line in the text, but just the "continuation" of a
3360 line too long to fit the screen. Continuation is also called "line
3363 Sometimes it is nice to have Emacs insert newlines automatically when
3364 a line gets too long. Continuation on the screen does not do that. Use
3365 Auto Fill mode (*note Filling::) if that's what you want.
3367 Instead of continuation, long lines can be displayed by "truncation".
3368 This means that all the characters that do not fit in the width of the
3369 frame or window do not appear at all. They remain in the buffer,
3370 temporarily invisible. Right arrow in the last column (instead of the
3371 curved arrow) inform you that truncation is in effect.
3373 Truncation instead of continuation happens whenever horizontal
3374 scrolling is in use, and optionally in all side-by-side windows (*note
3375 Windows::). You can enable truncation for a particular buffer by
3376 setting the variable `truncate-lines' to non-`nil' in that buffer.
3377 (*Note Variables::.) Altering the value of `truncate-lines' makes it
3378 local to the current buffer; until that time, the default value is in
3379 effect. The default is initially `nil'. *Note Locals::.
3381 *Note Display Vars::, for additional variables that affect how text
3385 File: xemacs.info, Node: Position Info, Next: Arguments, Prev: Continuation Lines, Up: Basic
3387 Cursor Position Information
3388 ===========================
3390 If you are accustomed to other display editors, you may be surprised
3391 that Emacs does not always display the page number or line number of
3392 point in the mode line. In Emacs, this information is only rarely
3393 needed, and a number of commands are available to compute and print it.
3394 Since text is stored in a way that makes it difficult to compute the
3395 information, it is not displayed all the time.
3398 Print page number of point, and line number within page.
3401 Print line number of point in the buffer.
3403 `M-x line-number-mode'
3404 Toggle automatic display of current line number.
3407 Print number of lines and characters in the current region
3408 (`count-lines-region'). *Note Mark::, for information about the
3412 Print character code of character after point, character position
3413 of point, and column of point (`what-cursor-position').
3415 There are several commands for printing line numbers:
3417 * `M-x what-line' counts lines from the beginning of the file and
3418 prints the line number point is on. The first line of the file is
3419 line number 1. You can use these numbers as arguments to `M-x
3422 * `M-x what-page' counts pages from the beginning of the file, and
3423 counts lines within the page, printing both of them. *Note
3424 Pages::, for the command `C-x l', which counts the lines in the
3427 * `M-=' (`count-lines-region') prints the number of lines in the
3428 region (*note Mark::). *Note Pages::, for the command `C-x l'
3429 which counts the lines in the
3431 The command `C-x =' (`what-cursor-position') can be used to find out
3432 the column that the cursor is in, and other miscellaneous information
3433 about point. It prints a line in the echo area that looks like this:
3435 Char: c (0143, 99, 0x63) point=18862 of 24800(76%) column 53
3437 (In fact, this is the output produced when point is before `column 53'
3440 The four values after `Char:' describe the character that follows
3441 point, first by showing it and then by giving its character code in
3442 octal, decimal and hex.
3444 `point=' is followed by the position of point expressed as a
3445 character count. The front of the buffer counts as position 1, one
3446 character later as 2, and so on. The next, larger number is the total
3447 number of characters in the buffer. Afterward in parentheses comes the
3448 position expressed as a percentage of the total size.
3450 `column' is followed by the horizontal position of point, in columns
3451 from the left edge of the window.
3453 If the buffer has been narrowed, making some of the text at the
3454 beginning and the end temporarily invisible, `C-x =' prints additional
3455 text describing the current visible range. For example, it might say:
3457 Char: c (0143, 99, 0x63) point=19674 of 24575(80%) <19591 - 19703> column 69
3459 where the two extra numbers give the smallest and largest character
3460 position that point is allowed to assume. The characters between those
3461 two positions are the visible ones. *Note Narrowing::.
3463 If point is at the end of the buffer (or the end of the visible
3464 part), `C-x =' omits any description of the character after point. The
3467 point=563026 of 563025(100%) column 0
3470 File: xemacs.info, Node: Arguments, Prev: Position Info, Up: Basic
3475 In mathematics and computer usage, the word "argument" means "data
3476 provided to a function or operation." Any Emacs command can be given a
3477 "numeric argument" (also called a "prefix argument"). Some commands
3478 interpret the argument as a repetition count. For example, giving an
3479 argument of ten to the key `C-f' (the command `forward-char', move
3480 forward one character) moves forward ten characters. With these
3481 commands, no argument is equivalent to an argument of one. Negative
3482 arguments are allowed. Often they tell a command to move or act in
3483 the opposite direction.
3485 If your keyboard has a <META> key (labelled with a diamond on
3486 Sun-type keyboards and labelled `Alt' on some other keyboards), the
3487 easiest way to specify a numeric argument is to type digits and/or a
3488 minus sign while holding down the <META> key. For example,
3491 would move down five lines. The characters `Meta-1', `Meta-2', and so
3492 on, as well as `Meta--', do this because they are keys bound to
3493 commands (`digit-argument' and `negative-argument') that are defined to
3494 contribute to an argument for the next command. Digits and `-'
3495 modified with Control, or Control and Meta, also specify numeric
3498 Another way of specifying an argument is to use the `C-u'
3499 (`universal-argument') command followed by the digits of the argument.
3500 With `C-u', you can type the argument digits without holding down
3501 modifier keys; `C-u' works on all terminals. To type a negative
3502 argument, type a minus sign after `C-u'. Just a minus sign without
3503 digits normally means -1.
3505 `C-u' followed by a character which is neither a digit nor a minus
3506 sign has the special meaning of "multiply by four". It multiplies the
3507 argument for the next command by four. `C-u' twice multiplies it by
3508 sixteen. Thus, `C-u C-u C-f' moves forward sixteen characters. This
3509 is a good way to move forward "fast", since it moves about 1/5 of a line
3510 in the usual size frame. Other useful combinations are `C-u C-n', `C-u
3511 C-u C-n' (move down a good fraction of a frame), `C-u C-u C-o' (make "a
3512 lot" of blank lines), and `C-u C-k' (kill four lines).
3514 Some commands care only about whether there is an argument and not
3515 about its value. For example, the command `M-q' (`fill-paragraph') with
3516 no argument fills text; with an argument, it justifies the text as well.
3517 (*Note Filling::, for more information on `M-q'.) Just `C-u' is a
3518 handy way of providing an argument for such commands.
3520 Some commands use the value of the argument as a repeat count, but do
3521 something peculiar when there is no argument. For example, the command
3522 `C-k' (`kill-line') with argument N kills N lines, including their
3523 terminating newlines. But `C-k' with no argument is special: it kills
3524 the text up to the next newline, or, if point is right at the end of
3525 the line, it kills the newline itself. Thus, two `C-k' commands with
3526 no arguments can kill a non-blank line, just like `C-k' with an
3527 argument of one. (*Note Killing::, for more information on `C-k'.)
3529 A few commands treat a plain `C-u' differently from an ordinary
3530 argument. A few others may treat an argument of just a minus sign
3531 differently from an argument of -1. These unusual cases are described
3532 when they come up; they are always for reasons of convenience of use of
3533 the individual command.
3535 You can use a numeric argument to insert multiple copies of a
3536 character. This is straightforward unless the character is a digit; for
3537 example, `C-u 6 4 a' inserts 64 copies of the character `a'. But this
3538 does not work for inserting digits; `C-u 6 4 1' specifies an argument
3539 of 641, rather than inserting anything. To separate the digit to
3540 insert from the argument, type another `C-u'; for example, `C-u 6 4 C-u
3541 1' does insert 64 copies of the character `1'.
3543 We use the term "prefix argument" as well as "numeric argument" to
3544 emphasize that you type the argument before the command, and to
3545 distinguish these arguments from minibuffer arguments that come after
3549 File: xemacs.info, Node: Undo, Next: Minibuffer, Prev: Basic, Up: Top
3554 Emacs allows you to undo all changes you make to the text of a buffer,
3555 up to a certain amount of change (8000 characters). Each buffer records
3556 changes individually, and the undo command always applies to the
3557 current buffer. Usually each editing command makes a separate entry in
3558 the undo records, but some commands such as `query-replace' make many
3559 entries, and very simple commands such as self-inserting characters are
3560 often grouped to make undoing less tedious.
3563 Undo one batch of changes (usually, one command's worth) (`undo').
3568 The command `C-x u' or `C-_' allows you to undo changes. The first
3569 time you give this command, it undoes the last change. Point moves to
3570 the text affected by the undo, so you can see what was undone.
3572 Consecutive repetitions of the `C-_' or `C-x u' commands undo
3573 earlier and earlier changes, back to the limit of what has been
3574 recorded. If all recorded changes have already been undone, the undo
3575 command prints an error message and does nothing.
3577 Any command other than an undo command breaks the sequence of undo
3578 commands. Starting at this moment, the previous undo commands are
3579 considered ordinary changes that can themselves be undone. Thus, you
3580 can redo changes you have undone by typing `C-f' or any other command
3581 that have no important effect, and then using more undo commands.
3583 If you notice that a buffer has been modified accidentally, the
3584 easiest way to recover is to type `C-_' repeatedly until the stars
3585 disappear from the front of the mode line. When that happens, all the
3586 modifications you made have been canceled. If you do not remember
3587 whether you changed the buffer deliberately, type `C-_' once. When you
3588 see Emacs undo the last change you made, you probably remember why you
3589 made it. If the change was an accident, leave it undone. If it was
3590 deliberate, redo the change as described in the preceding paragraph.
3592 Whenever an undo command makes the stars disappear from the mode
3593 line, the buffer contents is the same as it was when the file was last
3596 Not all buffers record undo information. Buffers whose names start
3597 with spaces don't; these buffers are used internally by Emacs and its
3598 extensions to hold text that users don't normally look at or edit.
3599 Minibuffers, help buffers, and documentation buffers also don't record
3602 Emacs can remember at most 8000 or so characters of deleted or
3603 modified text in any one buffer for reinsertion by the undo command.
3604 There is also a limit on the number of individual insert, delete, or
3605 change actions that Emacs can remember.
3607 There are two keys to run the `undo' command, `C-x u' and `C-_',
3608 because on some keyboards, it is not obvious how to type `C-_'. `C-x u'
3609 is an alternative you can type in the same fashion on any terminal.
3612 File: xemacs.info, Node: Minibuffer, Next: M-x, Prev: Undo, Up: Top
3617 The "minibuffer" is the facility used by XEmacs commands to read
3618 arguments more complicated than a single number. Minibuffer arguments
3619 can be file names, buffer names, Lisp function names, XEmacs command
3620 names, Lisp expressions, and many other things, depending on the command
3621 reading the argument. You can use the usual XEmacs editing commands in
3622 the minibuffer to edit the argument text.
3624 When the minibuffer is in use, it appears in the echo area, and the
3625 cursor moves there. The beginning of the minibuffer line displays a
3626 "prompt" which says what kind of input you should supply and how it
3627 will be used. Often this prompt is derived from the name of the command
3628 that the argument is for. The prompt normally ends with a colon.
3630 Sometimes a "default argument" appears in parentheses after the
3631 colon; it, too, is part of the prompt. The default is used as the
3632 argument value if you enter an empty argument (e.g., by just typing
3633 <RET>). For example, commands that read buffer names always show a
3634 default, which is the name of the buffer that will be used if you type
3637 The simplest way to enter a minibuffer argument is to type the text
3638 you want, terminated by <RET> which exits the minibuffer. You can
3639 cancel the command that wants the argument, and get out of the
3640 minibuffer, by typing `C-g'.
3642 Since the minibuffer uses the screen space of the echo area, it can
3643 conflict with other ways XEmacs customarily uses the echo area. Here is
3644 how XEmacs handles such conflicts:
3646 * If a command gets an error while you are in the minibuffer, this
3647 does not cancel the minibuffer. However, the echo area is needed
3648 for the error message and therefore the minibuffer itself is
3649 hidden for a while. It comes back after a few seconds, or as soon
3650 as you type anything.
3652 * If in the minibuffer you use a command whose purpose is to print a
3653 message in the echo area, such as `C-x =', the message is printed
3654 normally, and the minibuffer is hidden for a while. It comes back
3655 after a few seconds, or as soon as you type anything.
3657 * Echoing of keystrokes does not take place while the minibuffer is
3662 * File: Minibuffer File. Entering file names with the minibuffer.
3663 * Edit: Minibuffer Edit. How to edit in the minibuffer.
3664 * Completion:: An abbreviation facility for minibuffer input.
3665 * Minibuffer History:: Reusing recent minibuffer arguments.
3666 * Repetition:: Re-executing commands that used the minibuffer.
3669 File: xemacs.info, Node: Minibuffer File, Next: Minibuffer Edit, Prev: Minibuffer, Up: Minibuffer
3671 Minibuffers for File Names
3672 ==========================
3674 Sometimes the minibuffer starts out with text in it. For example, when
3675 you are supposed to give a file name, the minibuffer starts out
3676 containing the "default directory", which ends with a slash. This is
3677 to inform you which directory the file will be found in if you do not
3678 specify a directory.
3680 For example, the minibuffer might start out with these contents:
3682 Find File: /u2/emacs/src/
3684 where `Find File: ' is the prompt. Typing `buffer.c' specifies the
3685 file `/u2/emacs/src/buffer.c'. To find files in nearby directories,
3686 use `..'; thus, if you type `../lisp/simple.el', you will get the file
3687 named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with
3688 `M-<DEL>' the directory names you don't want (*note Words::).
3690 If you don't want any of the default, you can kill it with `C-a
3691 C-k'. But you don't need to kill the default; you can simply ignore it.
3692 Insert an absolute file name, one starting with a slash or a tilde,
3693 after the default directory. For example, to specify the file
3694 `/etc/termcap', just insert that name, giving these minibuffer contents:
3696 Find File: /u2/emacs/src//etc/termcap
3698 XEmacs gives a special meaning to a double slash (which is not normally
3699 a useful thing to write): it means, "ignore everything before the
3700 second slash in the pair." Thus, `/u2/emacs/src/' is ignored in the
3701 example above, and you get the file `/etc/termcap'.
3703 If you set `insert-default-directory' to `nil', the default
3704 directory is not inserted in the minibuffer. This way, the minibuffer
3705 starts out empty. But the name you type, if relative, is still
3706 interpreted with respect to the same default directory.
3709 File: xemacs.info, Node: Minibuffer Edit, Next: Completion, Prev: Minibuffer File, Up: Minibuffer
3711 Editing in the Minibuffer
3712 =========================
3714 The minibuffer is an XEmacs buffer (albeit a peculiar one), and the
3715 usual XEmacs commands are available for editing the text of an argument
3718 Since <RET> in the minibuffer is defined to exit the minibuffer, you
3719 can't use it to insert a newline in the minibuffer. To do that, type
3720 `C-o' or `C-q C-j'. (Recall that a newline is really the character
3723 The minibuffer has its own window which always has space on the
3724 screen but acts as if it were not there when the minibuffer is not in
3725 use. When the minibuffer is in use, its window is just like the
3726 others; you can switch to another window with `C-x o', edit text in
3727 other windows and perhaps even visit more files, before returning to the
3728 minibuffer to submit the argument. You can kill text in another window,
3729 return to the minibuffer window, and then yank the text to use it in the
3730 argument. *Note Windows::.
3732 There are some restrictions on the use of the minibuffer window,
3733 however. You cannot switch buffers in it--the minibuffer and its
3734 window are permanently attached. Also, you cannot split or kill the
3735 minibuffer window. But you can make it taller in the normal fashion with
3736 `C-x ^'. If you enable Resize-Minibuffer mode, then the minibuffer
3737 window expands vertically as necessary to hold the text that you put in
3738 the minibuffer. Use `M-x resize-minibuffer-mode' to enable or disable
3739 this minor mode (*note Minor Modes::).
3741 If while in the minibuffer you issue a command that displays help
3742 text of any sort in another window, you can use the `C-M-v' command
3743 while in the minibuffer to scroll the help text. This lasts until you
3744 exit the minibuffer. This feature is especially useful if a completing
3745 minibuffer gives you a list of possible completions. *Note Other
3748 If the variable `minibuffer-confirm-incomplete' is `t', you are
3749 asked for confirmation if there is no known completion for the text you
3750 typed. For example, if you attempted to visit a non-existent file, the
3751 minibuffer might read:
3752 Find File: chocolate_bar.c [no completions, confirm]
3753 If you press `Return' again, that confirms the filename. Otherwise,
3754 you can continue editing it.
3756 XEmacs supports recursive use of the minibuffer. However, it is easy
3757 to do this by accident (because of autorepeating keyboards, for example)
3758 and get confused. Therefore, most XEmacs commands that use the
3759 minibuffer refuse to operate if the minibuffer window is selected. If
3760 the minibuffer is active but you have switched to a different window,
3761 recursive use of the minibuffer is allowed--if you know enough to try
3762 to do this, you probably will not get confused.
3764 If you set the variable `enable-recursive-minibuffers' to a
3765 non-`nil', recursive use of the minibuffer is always allowed.
3768 File: xemacs.info, Node: Completion, Next: Minibuffer History, Prev: Minibuffer Edit, Up: Minibuffer
3773 For certain kinds of arguments, you can use "completion" to enter the
3774 argument value. Completion means that you type part of the argument,
3775 then XEmacs visibly fills in the rest, or as much as can be determined
3776 from the part you have typed.
3778 When completion is available, certain keys--<TAB>, <RET>, and
3779 <SPC>--are rebound to complete the text present in the minibuffer into
3780 a longer string that it stands for, by matching it against a set of
3781 "completion alternatives" provided by the command reading the argument.
3782 `?' is defined to display a list of possible completions of what you
3785 For example, when `M-x' uses the minibuffer to read the name of a
3786 command, it provides a list of all available XEmacs command names to
3787 complete against. The completion keys match the text in the minibuffer
3788 against all the command names, find any additional name characters
3789 implied by the ones already present in the minibuffer, and add those
3790 characters to the ones you have given. This is what makes it possible
3791 to type `M-x inse <SPC> b <RET>' instead of `M-x insert-buffer <RET>'
3794 Case is normally significant in completion because it is significant
3795 in most of the names that you can complete (buffer names, file names and
3796 command names). Thus, `fo' does not complete to `Foo'. When you are
3797 completing a name in which case does not matter, case may be ignored
3798 for completion's sake if specified by program.
3800 When a completion list is displayed, the completions will highlight
3801 as you move the mouse over them. Clicking the middle mouse button on
3802 any highlighted completion will "select" it just as if you had typed it
3807 * Example: Completion Example.
3808 * Commands: Completion Commands.
3809 * Strict Completion::
3810 * Options: Completion Options.
3813 File: xemacs.info, Node: Completion Example, Next: Completion Commands, Prev: Completion, Up: Completion
3818 A concrete example may help here. If you type `M-x au <TAB>', the
3819 <TAB> looks for alternatives (in this case, command names) that start
3820 with `au'. There are several, including `auto-fill-mode' and
3821 `auto-save-mode'--but they are all the same as far as `auto', so the
3822 `au' in the minibuffer changes to `auto'.
3824 If you type <TAB> again immediately, there are multiple
3825 possibilities for the very next character--it could be any of `c-'--so
3826 no more characters are added; instead, <TAB> displays a list of all
3827 possible completions in another window.
3829 If you go on to type `-f <TAB>', this <TAB> sees `auto-f'. The only
3830 command name starting this way is `auto-fill-mode', so completion fills
3831 in the rest of that. You now have `auto-fill-mode' in the minibuffer
3832 after typing just `au <TAB> f <TAB>'. Note that <TAB> has this effect
3833 because in the minibuffer it is bound to the command
3834 `minibuffer-complete' when completion is available.
3837 File: xemacs.info, Node: Completion Commands, Next: Strict Completion, Prev: Completion Example, Up: Completion
3842 Here is a list of the completion commands defined in the minibuffer
3843 when completion is available.
3846 Complete the text in the minibuffer as much as possible
3847 (`minibuffer-complete').
3850 Complete the minibuffer text, but don't go beyond one word
3851 (`minibuffer-complete-word').
3854 Submit the text in the minibuffer as the argument, possibly
3855 completing first as described below
3856 (`minibuffer-complete-and-exit').
3859 Print a list of all possible completions of the text in the
3860 minibuffer (`minibuffer-list-completions').
3863 Select the highlighted text under the mouse as a minibuffer
3864 response. When the minibuffer is being used to prompt the user
3865 for a completion, any valid completions which are visible on the
3866 screen will be highlighted when the mouse moves over them.
3867 Clicking <button2> will select the highlighted completion and exit
3868 the minibuffer. (`minibuf-select-highlighted-completion').
3870 <SPC> completes much like <TAB>, but never goes beyond the next
3871 hyphen or space. If you have `auto-f' in the minibuffer and type
3872 <SPC>, it finds that the completion is `auto-fill-mode', but it stops
3873 completing after `fill-'. This gives `auto-fill-'. Another <SPC> at
3874 this point completes all the way to `auto-fill-mode'. <SPC> in the
3875 minibuffer when completion is available runs the command
3876 `minibuffer-complete-word'.
3878 Here are some commands you can use to choose a completion from a
3879 window that displays a list of completions:
3882 Clicking mouse button 2 on a completion in the list of possible
3883 completions chooses that completion (`mouse-choose-completion').
3884 You normally use this command while point is in the minibuffer;
3885 but you must click in the list of completions, not in the
3890 Typing <PRIOR> or `M-v', while in the minibuffer, selects the
3891 window showing the completion list buffer
3892 (`switch-to-completions'). This paves the way for using the
3893 commands below. (Selecting that window in the usual ways has the
3894 same effect, but this way is more convenient.)
3897 Typing <RET> _in the completion list buffer_ chooses the
3898 completion that point is in or next to (`choose-completion'). To
3899 use this command, you must first switch windows to the window that
3900 shows the list of completions.
3905 Typing the right-arrow key <RIGHT>, <TAB> or `C-f' _in the
3906 completion list buffer_ moves point to the following completion
3907 (`next-list-mode-item').
3911 Typing the left-arrow key <LEFT> or `C-b' _in the completion list
3912 buffer_ moves point toward the beginning of the buffer, to the
3913 previous completion (`previous-list-mode-item').
3916 File: xemacs.info, Node: Strict Completion, Next: Completion Options, Prev: Completion Commands, Up: Completion
3921 There are three different ways that <RET> can work in completing
3922 minibuffers, depending on how the argument will be used.
3924 * "Strict" completion is used when it is meaningless to give any
3925 argument except one of the known alternatives. For example, when
3926 `C-x k' reads the name of a buffer to kill, it is meaningless to
3927 give anything but the name of an existing buffer. In strict
3928 completion, <RET> refuses to exit if the text in the minibuffer
3929 does not complete to an exact match.
3931 * "Cautious" completion is similar to strict completion, except that
3932 <RET> exits only if the text was an exact match already, not
3933 needing completion. If the text is not an exact match, <RET> does
3934 not exit, but it does complete the text. If it completes to an
3935 exact match, a second <RET> will exit.
3937 Cautious completion is used for reading file names for files that
3940 * "Permissive" completion is used when any string whatever is
3941 meaningful, and the list of completion alternatives is just a
3942 guide. For example, when `C-x C-f' reads the name of a file to
3943 visit, any file name is allowed, in case you want to create a
3944 file. In permissive completion, <RET> takes the text in the
3945 minibuffer exactly as given, without completing it.
3947 The completion commands display a list of all possible completions in
3948 a window whenever there is more than one possibility for the very next
3949 character. Also, typing `?' explicitly requests such a list. If the
3950 list of completions is long, you can scroll it with `C-M-v' (*note
3954 File: xemacs.info, Node: Completion Options, Prev: Strict Completion, Up: Completion
3959 When completion is done on file names, certain file names are usually
3960 ignored. The variable `completion-ignored-extensions' contains a list
3961 of strings; a file whose name ends in any of those strings is ignored
3962 as a possible completion. The standard value of this variable has
3963 several elements including `".o"', `".elc"', `".dvi"' and `"~"'. The
3964 effect is that, for example, `foo' can complete to `foo.c' even though
3965 `foo.o' exists as well. However, if _all_ the possible completions end
3966 in "ignored" strings, then they are not ignored. Ignored extensions do
3967 not apply to lists of completions--those always mention all possible
3970 If a completion command finds the next character is undetermined, it
3971 automatically displays a list of all possible completions. If the
3972 variable `completion-auto-help' is set to `nil', this does not happen,
3973 and you must type `?' to display the possible completions.
3975 If the variable `minibuffer-confirm-incomplete' is set to `t', then
3976 in contexts where `completing-read' allows answers that are not valid
3977 completions, an extra <RET> must be typed to confirm the response.
3978 This is helpful for catching typos.
3980 Icomplete mode presents a constantly-updated display that tells you
3981 what completions are available for the text you've entered so far. The
3982 command to enable or disable this minor mode is `M-x icomplete-mode'.
3985 File: xemacs.info, Node: Minibuffer History, Next: Repetition, Prev: Completion, Up: Minibuffer
3990 Every argument that you enter with the minibuffer is saved on a
3991 "minibuffer history list" so that you can use it again later in another
3992 argument. Special commands load the text of an earlier argument in the
3993 minibuffer. They discard the old minibuffer contents, so you can think
3994 of them as moving through the history of previous arguments.
3998 Move to the next earlier argument string saved in the minibuffer
3999 history (`previous-history-element').
4003 Move to the next later argument string saved in the minibuffer
4004 history (`next-history-element').
4007 Move to an earlier saved argument in the minibuffer history that
4008 has a match for REGEXP (`previous-matching-history-element').
4011 Move to a later saved argument in the minibuffer history that has a
4012 match for REGEXP (`next-matching-history-element').
4014 The simplest way to reuse the saved arguments in the history list is
4015 to move through the history list one element at a time. While in the
4016 minibuffer, use `M-p' or up-arrow (`previous-history-element') to "move
4017 to" the next earlier minibuffer input, and use `M-n' or down-arrow
4018 (`next-history-element') to "move to" the next later input.
4020 The previous input that you fetch from the history entirely replaces
4021 the contents of the minibuffer. To use it as the argument, exit the
4022 minibuffer as usual with <RET>. You can also edit the text before you
4023 reuse it; this does not change the history element that you "moved" to,
4024 but your new argument does go at the end of the history list in its own
4027 For many minibuffer arguments there is a "default" value. In some
4028 cases, the minibuffer history commands know the default value. Then you
4029 can insert the default value into the minibuffer as text by using `M-n'
4030 to move "into the future" in the history.
4032 There are also commands to search forward or backward through the
4033 history; they search for history elements that match a regular
4034 expression that you specify with the minibuffer. `M-r'
4035 (`previous-matching-history-element') searches older elements in the
4036 history, while `M-s' (`next-matching-history-element') searches newer
4037 elements. By special dispensation, these commands can use the
4038 minibuffer to read their arguments even though you are already in the
4039 minibuffer when you issue them. As with incremental searching, an
4040 uppercase letter in the regular expression makes the search
4041 case-sensitive (*note Search Case::).
4043 All uses of the minibuffer record your input on a history list, but
4044 there are separate history lists for different kinds of arguments. For
4045 example, there is a list for file names, used by all the commands that
4048 There are several other very specific history lists, including one
4049 for command names read by `M-x', one for buffer names, one for arguments
4050 of commands like `query-replace', and one for compilation commands read
4051 by `compile'. Finally, there is one "miscellaneous" history list that
4052 most minibuffer arguments use.
4055 File: xemacs.info, Node: Repetition, Prev: Minibuffer History, Up: Minibuffer
4057 Repeating Minibuffer Commands
4058 =============================
4060 Every command that uses the minibuffer at least once is recorded on a
4061 special history list, together with the values of its arguments, so that
4062 you can repeat the entire command. In particular, every use of `M-x'
4063 is recorded there, since `M-x' uses the minibuffer to read the command
4067 Re-execute a recent minibuffer command (`repeat-complex-command').
4070 Within `C-x <ESC> <ESC>', move to previous recorded command
4071 (`previous-history-element').
4074 Within `C-x <ESC> <ESC>', move to the next (more recent) recorded
4075 command (`next-history-element').
4077 `M-x list-command-history'
4078 Display the entire command history, showing all the commands `C-x
4079 <ESC> <ESC>' can repeat, most recent first.
4081 `C-x <ESC> <ESC>' is used to re-execute a recent minibuffer-using
4082 command. With no argument, it repeats the last such command. A
4083 numeric argument specifies which command to repeat; one means the last
4084 one, and larger numbers specify earlier ones.
4086 `C-x <ESC> <ESC>' works by turning the previous command into a Lisp
4087 expression and then entering a minibuffer initialized with the text for
4088 that expression. If you type just <RET>, the command is repeated as
4089 before. You can also change the command by editing the Lisp
4090 expression. Whatever expression you finally submit is what will be
4091 executed. The repeated command is added to the front of the command
4092 history unless it is identical to the most recently executed command
4095 Even if you don't understand Lisp syntax, it will probably be obvious
4096 which command is displayed for repetition. If you do not change the
4097 text, you can be sure the command will repeat exactly as before.
4099 If you are in the minibuffer for `C-x <ESC> <ESC>' and the command
4100 shown to you is not the one you want to repeat, you can move around the
4101 list of previous commands using `M-n' and `M-p'. `M-p' replaces the
4102 contents of the minibuffer with the next earlier recorded command, and
4103 `M-n' replaces it with the next later command. After finding the
4104 desired previous command, you can edit its expression and then resubmit
4105 it by typing <RET>. Any editing you have done on the command to be
4106 repeated is lost if you use `M-n' or `M-p'.
4108 `M-n' and `M-p' are specially defined within `C-x <ESC> <ESC>' to
4109 run the commands `previous-history-element' and `next-history-element'.
4111 The list of previous commands using the minibuffer is stored as a
4112 Lisp list in the variable `command-history'. Each element of the list
4113 is a Lisp expression which describes one command and its arguments.
4114 Lisp programs can reexecute a command by feeding the corresponding
4115 `command-history' element to `eval'.
4118 File: xemacs.info, Node: M-x, Next: Help, Prev: Minibuffer, Up: Top
4120 Running Commands by Name
4121 ************************
4123 The Emacs commands that are used often or that must be quick to type are
4124 bound to keys--short sequences of characters--for convenient use. Other
4125 Emacs commands that are used more rarely are not bound to keys; to run
4126 them, you must refer to them by name.
4128 A command name consists, by convention, of one or more words,
4129 separated by hyphens: for example, `auto-fill-mode' or `manual-entry'.
4130 The use of English words makes the command name easier to remember than
4131 a key made up of obscure characters, even though it results in more
4132 characters to type. You can run any command by name, even if it can be
4133 run by keys as well.
4135 To run a command by name, start with `M-x', then type the command
4136 name, and finish with <RET>. `M-x' uses the minibuffer to read the
4137 command name. <RET> exits the minibuffer and runs the command.
4139 Emacs uses the minibuffer for reading input for many different
4140 purposes; on this occasion, the string `M-x' is displayed at the
4141 beginning of the minibuffer as a "prompt" to remind you that your input
4142 should be the name of a command to be run. *Note Minibuffer::, for
4143 full information on the features of the minibuffer.
4145 You can use completion to enter a command name. For example, to
4146 invoke the command `forward-char', type:
4148 M-x forward-char <RET>
4150 M-x fo <TAB> c <RET>
4152 After you type in `M-x fo TAB' emacs will give you a possible list of
4153 completions from which you can choose. Note that `forward-char' is the
4154 same command that you invoke with the key `C-f'. You can call any
4155 command (interactively callable function) defined in Emacs by its name
4156 using `M-x' regardless of whether or not any keys are bound to it.
4158 If you type `C-g' while Emacs reads the command name, you cancel the
4159 `M-x' command and get out of the minibuffer, ending up at top level.
4161 To pass a numeric argument to a command you are invoking with `M-x',
4162 specify the numeric argument before the `M-x'. `M-x' passes the
4163 argument along to the function that it calls. The argument value
4164 appears in the prompt while the command name is being read.
4166 You can use the command `M-x interactive' to specify a way of
4167 parsing arguments for interactive use of a function. For example,
4170 (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
4172 to make `arg' be the prefix argument when `foo' is called as a
4173 command. The call to `interactive' is actually a declaration rather
4174 than a function; it tells `call-interactively' how to read arguments to
4175 pass to the function. When actually called, `interactive' returns
4178 The argument of INTERACTIVE is usually a string containing a code
4179 letter followed by a prompt. Some code letters do not use I/O to get
4180 the argument and do not need prompts. To prompt for multiple arguments,
4181 you must provide a code letter, its prompt, a newline, and another code
4182 letter, and so forth. If the argument is not a string, it is evaluated
4183 to get a list of arguments to pass to the function. If you do not
4184 provide an argument to `interactive', no arguments are passed when
4185 calling interactively.
4187 Available code letters are:
4190 Function name: symbol with a function definition
4193 Name of existing buffer
4196 Name of buffer, possibly nonexistent
4202 Command name: symbol with interactive function definition
4205 Value of point as number (does not do I/O)
4217 Possibly nonexistent file name
4220 Key sequence (string)
4223 Value of mark as number (does not do I/O)
4226 Number read using minibuffer
4229 Prefix arg converted to number, or if none, do like code `n'
4232 Prefix arg converted to number (does not do I/O)
4235 Prefix arg in raw form (does not do I/O)
4238 Region: point and mark as two numeric arguments, smallest first
4248 Variable name: symbol that is `user-variable-p'
4251 Lisp expression read but not evaluated
4254 Lisp expression read and evaluated
4256 In addition, if the string begins with `*', an error is signaled if
4257 the buffer is read-only. This happens before reading any arguments.
4258 If the string begins with `@', the window the mouse is over is selected
4259 before anything else is done. You may use both `@' and `*'; they are
4260 processed in the order that they appear.
4262 Normally, when describing a command that is run by name, we omit the
4263 <RET> that is needed to terminate the name. Thus we may refer to `M-x
4264 auto-fill-mode' rather than `M-x auto-fill-mode' <RET>. We mention the
4265 <RET> only when it is necessary to emphasize its presence, for example,
4266 when describing a sequence of input that contains a command name and
4267 arguments that follow it.
4269 `M-x' is defined to run the command `execute-extended-command',
4270 which is responsible for reading the name of another command and
4274 File: xemacs.info, Node: Help, Next: Mark, Prev: M-x, Up: Top
4279 XEmacs provides extensive help features accessible through a single
4280 character, `C-h'. `C-h' is a prefix key that is used only for
4281 documentation-printing commands. The characters that you can type after
4282 `C-h' are called "help options". One help option is `C-h'; that is how
4283 you ask for help about using `C-h'. To cancel, type `C-g'. The
4284 function key <F1> is equivalent to `C-h'.
4286 `C-h C-h' (`help-for-help') displays a list of the possible help
4287 options, and then asks you to type the desired option. It prompts with
4290 A B C F I K L M N P S T V W C-c C-d C-f C-i C-k C-n C-w; ? for more help:
4292 You should type one of those characters.
4294 Typing a third `C-h' displays a description of what the options mean;
4295 Emacs still waits for you to type an option. To cancel, type `C-g'.
4297 Most help buffers use a special major mode, Help mode, which lets you
4298 scroll conveniently with <SPC> and <DEL> or <BS>.
4302 * Help Summary:: Brief list of all Help commands.
4303 * Key Help:: Asking what a key does in XEmacs.
4304 * Name Help:: Asking about a command, variable or function name.
4305 * Apropos:: Asking what pertains to a given topic.
4306 * Library Keywords:: Finding Lisp libraries by keywords (topics).
4307 * Help Mode:: Special features of Help mode and Help buffers.
4308 * Misc Help:: Other help commands.
4311 File: xemacs.info, Node: Help Summary, Next: Key Help, Prev: Help, Up: Help
4316 Here is a summary of the defined help commands.
4318 `C-h a REGEXP <RET>'
4319 Display a list of functions and variables whose names match REGEXP
4323 Show all commands whose names contain matches for REGEXP
4324 (`command-apropos').
4327 Display a table of all key bindings currently in effect, with local
4328 bindings of the current major mode first, followed by all global
4329 bindings (`describe-bindings').
4332 Print the name of the command that KEY runs
4333 (`describe-key-briefly'). Here `c' stands for `character'. For
4334 more extensive information on KEY, use `C-h k'.
4336 `C-h d FUNCTION <RET>'
4337 `C-h f FUNCTION <RET>'
4338 Display documentation on the Lisp function named FUNCTION
4339 (`describe-function'). Since commands are Lisp functions, a
4340 command name may be used.
4343 Run Info, the program for browsing documentation files (`info').
4344 The complete XEmacs manual is available online in Info.
4347 Display the name and documentation of the command that KEY runs
4351 Display a description of the last 100 characters you typed
4355 Display documentation of the current major mode (`describe-mode').
4359 Display documentation of XEmacs changes, most recent first
4360 (`view-emacs-news').
4363 Find packages by topic keyword (`finder-by-keyword').
4366 Display a table of all mouse bindings currently in effect now, with
4367 local bindings of the current major mode first, followed by all
4368 global bindings (`describe-pointer').
4371 Display current contents of the syntax table, plus an explanation
4372 of what they mean (`describe-syntax'). *Note Syntax::.
4375 Enter the XEmacs interactive tutorial (`help-with-tutorial').
4378 Display the documentation of the Lisp variable VAR
4379 (`describe-variable').
4381 `C-h w COMMAND <RET>'
4382 Print which keys run the command named COMMAND (`where-is').
4385 Display info on how to deal with Beta versions of XEmacs
4389 Select customization buffer for GROUP (`customize').
4392 View the local copy of the XEmacs FAQ (`xemacs-local-faq').
4394 `C-h C-i FILE <RET>'
4395 Read Info file FILE with Info browser (`Info-query').
4397 `C-h C-c COMMAND <RET>'
4398 Look up an Emacs command COMMAND in the Emacs manual in the Info
4399 system (`Info-goto-emacs-command-node').
4401 `C-h C-f FUNCTION <RET>'
4402 Look up an Emacs Lisp function FUNCTION in the Elisp manual in the
4403 Info system (`Info-elisp-ref').
4406 File: xemacs.info, Node: Key Help, Next: Name Help, Prev: Help Summary, Up: Help
4408 Documentation for a Key
4409 =======================
4411 The most basic `C-h' options are `C-h c' (`describe-key-briefly') and
4412 `C-h k' (`describe-key'). `C-h c KEY' prints in the echo area the name
4413 of the command that KEY is bound to. For example, `C-h c C-f' prints
4414 `forward-char'. Since command names are chosen to describe what the
4415 commands do, this is a good way to get a very brief description of what
4418 `C-h k KEY' is similar to `C-h c' but gives more information. It
4419 displays the documentation string of the function KEY is bound to as
4420 well as its name. KEY is a string or vector of events. When called
4421 interactively, KEY may also be a menu selection. This information does
4422 not usually fit into the echo area, so a window is used for the display.
4424 `C-h c' and `C-h k' work for any sort of key sequences, including
4425 function keys and mouse events.
4428 File: xemacs.info, Node: Name Help, Next: Apropos, Prev: Key Help, Up: Help
4430 Help by Command or Variable Name
4431 ================================
4433 `C-h f' (`describe-function') reads the name of a Lisp function using
4434 the minibuffer, then displays that function's documentation string in a
4435 window. Since commands are Lisp functions, you can use the argument
4436 FUNCTION to get the documentation of a command that you know by name.
4439 C-h f auto-fill-mode <RET>
4441 displays the documentation for `auto-fill-mode'. Using `C-h f' is the
4442 only way to see the documentation of a command that is not bound to any
4443 key, that is, a command you would normally call using `M-x'. If the
4444 variable `describe-function-show-arglist' is `t', `describe-function'
4445 shows its arglist if the FUNCTION is not an autoload function.
4447 `C-h f' is also useful for Lisp functions that you are planning to
4448 use in a Lisp program. For example, if you have just written the
4449 expression `(make-vector len)' and want to make sure you are using
4450 `make-vector' properly, type `C-h f make-vector <RET>'. Because `C-h
4451 f' allows all function names, not just command names, you may find that
4452 some of your favorite abbreviations that work in `M-x' don't work in
4453 `C-h f'. An abbreviation may be unique among command names, yet fail
4454 to be unique when other function names are allowed.
4456 The function name for `C-h f' to describe has a default which is
4457 used if you type <RET> leaving the minibuffer empty. The default is
4458 the function called by the innermost Lisp expression in the buffer
4459 around point, _provided_ that is a valid, defined Lisp function name.
4460 For example, if point is located following the text `(make-vector (car
4461 x)', the innermost list containing point is the one that starts with
4462 `(make-vector', so the default is to describe the function
4465 `C-h f' is often useful just to verify that you have the right
4466 spelling for the function name. If `C-h f' mentions a name from the
4467 buffer as the default, that name must be defined as a Lisp function. If
4468 that is all you want to know, just type `C-g' to cancel the `C-h f'
4469 command, then go on editing.
4471 `C-h w COMMAND <RET>' (`where-is') tells you what keys are bound to
4472 COMMAND. It prints a list of the keys in the echo area. Alternatively,
4473 it informs you that a command is not bound to any keys, which implies
4474 that you must use `M-x' to call the command.
4476 `C-h v' (`describe-variable') is like `C-h f' but describes Lisp
4477 variables instead of Lisp functions. Its default is the Lisp symbol
4478 around or before point, if that is the name of a known Lisp variable.
4482 File: xemacs.info, Node: Apropos, Next: Library Keywords, Prev: Name Help, Up: Help
4488 Show only symbols that are names of commands (`command-apropos').
4490 `M-x apropos REGEXP'
4491 Show all symbols whose names contain matches for REGEXP.
4493 A more sophisticated sort of question to ask is, "What are the
4494 commands for working with files?" To ask this question, type `C-h a
4495 file <RET>', which displays a list of all command names that contain
4496 `file', including `copy-file', `find-file', and so on. With each
4497 command name appears a brief description of how to use the command, and
4498 what keys you can currently invoke it with. For example, it would say
4499 that you can invoke `find-file' by typing `C-x C-f'. The `A' in `C-h
4500 A' stands for `Apropos'; `C-h A' runs the command `command-apropos'.
4501 This command normally checks only commands (interactive functions); if
4502 you specify a prefix argument, it checks noninteractive functions as
4505 Because `C-h A' looks only for functions whose names contain the
4506 string you specify, you must use ingenuity in choosing the string. If
4507 you are looking for commands for killing backwards and `C-h a
4508 kill-backwards <RET>' doesn't reveal any, don't give up. Try just
4509 `kill', or just `backwards', or just `back'. Be persistent. Pretend
4510 you are playing Adventure. Also note that you can use a regular
4511 expression as the argument, for more flexibility (*note Regexps::).
4513 Here is a set of arguments to give to `C-h a' that covers many
4514 classes of XEmacs commands, since there are strong conventions for
4515 naming the standard XEmacs commands. By giving you a feel for the
4516 naming conventions, this set should also serve to aid you in developing
4517 a technique for picking `apropos' strings.
4519 char, line, word, sentence, paragraph, region, page, sexp, list,
4520 defun, rect, buffer, frame, window, face, file, dir, register,
4521 mode, beginning, end, forward, backward, next, previous, up, down,
4522 search, goto, kill, delete, mark, insert, yank, fill, indent,
4523 case, change, set, what, list, find, view, describe, default.
4525 To list all Lisp symbols that contain a match for a regexp, not just
4526 the ones that are defined as commands, use the command `M-x apropos'
4527 instead of `C-h A'. This command does not check key bindings by
4528 default; specify a numeric argument if you want it to check them.
4530 The `apropos-documentation' command is like `apropos' except that it
4531 searches documentation strings for matches for the specified regular
4534 The `apropos-value' command is like `apropos' except that it
4535 searches symbols' values for matches for the specified regular
4536 expression. This command does not check function definitions or
4537 property lists by default; specify a numeric argument if you want it to
4540 If the variable `apropos-do-all' is non-`nil', the commands above
4541 all behave as if they had been given a prefix argument.
4543 If you want more information about a function definition, variable or
4544 symbol property listed in the Apropos buffer, you can click on it with
4545 `Mouse-2' or move there and type <RET>.
4548 File: xemacs.info, Node: Library Keywords, Next: Help Mode, Prev: Apropos, Up: Help
4550 Keyword Search for Lisp Libraries
4551 =================================
4553 The `C-h p' command lets you search the standard Emacs Lisp libraries
4554 by topic keywords. Here is a partial list of keywords you can use:
4556 abbrev abbreviation handling, typing shortcuts, macros
4557 bib code related to the `bib' bibliography processor
4558 c C, C++, and Objective-C language support
4559 calendar calendar and time management support
4560 comm communications, networking, remote access to files
4561 data support for editing files of data
4562 docs support for Emacs documentation
4563 dumped files preloaded into Emacs
4564 emulations emulations of other editors
4565 extensions Emacs Lisp language extensions
4566 faces support for multiple fonts
4567 frames support for Emacs frames and window systems
4568 games games, jokes and amusements
4569 hardware support for interfacing with exotic hardware
4570 help support for on-line help systems
4571 hypermedia support for links between text or other media types
4572 i18n internationalization and alternate character-set support
4573 internal code for Emacs internals, build process, defaults
4574 languages specialized modes for editing programming languages
4575 lisp Lisp support, including Emacs Lisp
4576 local code local to your site
4577 maint maintenance aids for the Emacs development group
4578 mail modes for electronic-mail handling
4579 matching various sorts of searching and matching
4581 mule multi-language extensions
4582 news support for netnews reading and posting
4583 oop support for object-oriented programming
4584 outlines support for hierarchical outlining
4585 processes process, subshell, compilation, and job control support
4586 terminals support for terminal types
4587 tex code related to the TeX formatter
4588 tools programming tools
4589 unix front-ends/assistants for, or emulators of, UNIX features
4590 vms support code for vms
4594 File: xemacs.info, Node: Help Mode, Next: Misc Help, Prev: Library Keywords, Up: Help
4599 Help buffers provide the commands of View mode (*note Misc File Ops::),
4600 plus a few special commands of their own.
4609 When a command name (*note Running Commands by Name: M-x.) or
4610 variable name (*note Variables::) appears in the documentation, it
4611 normally appears inside paired single-quotes.
4614 File: xemacs.info, Node: Misc Help, Prev: Help Mode, Up: Help
4619 `C-h i' (`info') runs the Info program, which is used for browsing
4620 through structured documentation files. The entire XEmacs manual is
4621 available within Info. Eventually all the documentation of the GNU
4622 system will be available. Type `h' after entering Info to run a
4623 tutorial on using Info.
4625 If you specify a numeric argument, `C-h i' prompts for the name of a
4626 documentation file. This way, you can browse a file which doesn't have
4627 an entry in the top-level Info menu. It is also handy when you need to
4628 get to the documentation quickly, and you know the exact name of the
4631 There are two special help commands for accessing XEmacs
4632 documentation through Info. `C-h C-f FUNCTION <RET>' enters Info and
4633 goes straight to the documentation of the XEmacs function FUNCTION.
4634 `C-h C-k KEY' enters Info and goes straight to the documentation of the
4635 key KEY. These two keys run the commands `Info-elisp-ref' and
4636 `Info-goto-emacs-key-command-node'.
4638 If something surprising happens, and you are not sure what commands
4639 you typed, use `C-h l' (`view-lossage'). `C-h l' prints the last 100
4640 command characters you typed in. If you see commands that you don't
4641 know, you can use `C-h c' to find out what they do.
4643 XEmacs has several major modes. Each mode redefines a few keys and
4644 makes a few other changes in how editing works. `C-h m'
4645 (`describe-mode') prints documentation on the current major mode, which
4646 normally describes all the commands that are changed in this mode.
4648 `C-h b' (`describe-bindings') and `C-h s' (`describe-syntax')
4649 present information about the current XEmacs mode that is not covered
4650 by `C-h m'. `C-h b' displays a list of all the key bindings currently
4651 in effect, with the local bindings of the current major mode first,
4652 followed by the global bindings (*note Key Bindings::). `C-h s'
4653 displays the contents of the syntax table with explanations of each
4654 character's syntax (*note Syntax::).
4656 You can get a similar list for a particular prefix key by typing
4657 `C-h' after the prefix key. (There are a few prefix keys for which
4658 this does not work--those that provide their own bindings for `C-h'.
4659 One of these is <ESC>, because `<ESC> C-h' is actually `C-M-h', which
4662 The other `C-h' options display various files of useful information.
4663 `C-h C-w' (`describe-no-warranty') displays the full details on the
4664 complete absence of warranty for XEmacs. `C-h n' (`view-emacs-news')
4665 displays the file `xemacs/etc/NEWS', which contains documentation on
4666 XEmacs changes arranged chronologically. `C-h F' (`xemacs-local-faq')
4667 displays local version of the XEmacs
4668 frequently-answered-questions-list. `C-h t' (`help-with-tutorial')
4669 displays the learn-by-doing XEmacs tutorial. `C-h C-c'
4670 (`describe-copying') displays the file `xemacs/etc/COPYING', which
4671 tells you the conditions you must obey in distributing copies of
4672 XEmacs. `C-h C-d' (`describe-distribution') displays another file named
4673 `xemacs/etc/DISTRIB', which tells you how you can order a copy of the
4674 latest version of XEmacs.
4677 File: xemacs.info, Node: Mark, Next: Mouse Selection, Prev: Help, Up: Top
4682 Many Emacs commands operate on an arbitrary contiguous part of the
4683 current buffer. You can select text in two ways:
4685 * You use special keys to select text by defining a region between
4688 * If you are running XEmacs under X, you can also select text with
4691 The Mark and the Region
4692 =======================
4694 To specify the text for a command to operate on, set "the mark" at one
4695 end of it, and move point to the other end. The text between point and
4696 the mark is called "the region". You can move point or the mark to
4697 adjust the boundaries of the region. It doesn't matter which one is
4698 set first chronologically, or which one comes earlier in the text.
4700 Once the mark has been set, it remains until it is set again at
4701 another place. The mark remains fixed with respect to the preceding
4702 character if text is inserted or deleted in a buffer. Each Emacs
4703 buffer has its own mark; when you return to a buffer that had been
4704 selected previously, it has the same mark it had before.
4706 Many commands that insert text, such as `C-y' (`yank') and `M-x
4707 insert-buffer', position the mark at one end of the inserted text--the
4708 opposite end from where point is positioned, so that the region
4709 contains the text just inserted.
4711 Aside from delimiting the region, the mark is useful for marking a
4712 spot that you may want to go back to. To make this feature more useful,
4713 Emacs remembers 16 previous locations of the mark in the `mark ring'.
4717 * Setting Mark:: Commands to set the mark.
4718 * Using Region:: Summary of ways to operate on contents of the region.
4719 * Marking Objects:: Commands to put region around textual units.
4720 * Mark Ring:: Previous mark positions saved so you can go back there.
4723 File: xemacs.info, Node: Setting Mark, Next: Using Region, Prev: Mark, Up: Mark
4728 Here are some commands for setting the mark:
4731 Set the mark where point is (`set-mark-command').
4737 Interchange mark and point (`exchange-point-and-mark').
4740 Pushes a mark at the beginning of the buffer.
4743 Pushes a mark at the end of the buffer.
4745 For example, to convert part of the buffer to all upper-case, you
4746 can use the `C-x C-u' (`upcase-region') command, which operates on the
4747 text in the region. First go to the beginning of the text you want to
4748 capitalize and type `C-<SPC>' to put the mark there, then move to the
4749 end, and then type `C-x C-u' to capitalize the selected region. You
4750 can also set the mark at the end of the text, move to the beginning,
4751 and then type `C-x C-u'. Most commands that operate on the text in the
4752 region have the word `region' in their names.
4754 The most common way to set the mark is with the `C-<SPC>' command
4755 (`set-mark-command'). This command sets the mark where point is. You
4756 can then move point away, leaving the mark behind. It is actually
4757 incorrect to speak of the character `C-<SPC>'; there is no such
4758 character. When you type <SPC> while holding down <CTRL>, you get the
4759 character `C-@' on most terminals. This character is actually bound to
4760 `set-mark-command'. But unless you are unlucky enough to have a
4761 terminal where typing `C-<SPC>' does not produce `C-@', you should
4762 think of this character as `C-<SPC>'.
4764 Since terminals have only one cursor, Emacs cannot show you where the
4765 mark is located. Most people use the mark soon after they set it, before
4766 they forget where it is. But you can see where the mark is with the
4767 command `C-x C-x' (`exchange-point-and-mark') which puts the mark where
4768 point was and point where the mark was. The extent of the region is
4769 unchanged, but the cursor and point are now at the previous location of
4772 Another way to set the mark is to push the mark to the beginning of a
4773 buffer while leaving point at its original location. If you supply an
4774 argument to `C-<' (`mark-beginning-of-buffer'), the mark is pushed N/10
4775 of the way from the true beginning of the buffer. You can also set the
4776 mark at the end of a buffer with `C->' (`mark-end-of-buffer'). It
4777 pushes the mark to the end of the buffer, leaving point alone.
4778 Supplying an argument to the command pushes the mark N/10 of the way
4779 from the true end of the buffer.
4781 If you are using XEmacs under the X window system, you can set the
4782 variable `zmacs-regions' to `t'. This makes the current region (defined
4783 by point and mark) highlight and makes it available as the X clipboard
4784 selection, which means you can use the menu bar items on it. *Note
4785 Active Regions::, for more information.
4787 `C-x C-x' is also useful when you are satisfied with the location of
4788 point but want to move the mark; do `C-x C-x' to put point there and
4789 then you can move it. A second use of `C-x C-x', if necessary, puts
4790 the mark at the new location with point back at its original location.
4793 File: xemacs.info, Node: Using Region, Next: Marking Objects, Prev: Setting Mark, Up: Mark
4795 Operating on the Region
4796 -----------------------
4798 Once you have created an active region, you can do many things to the
4800 * Kill it with `C-w' (*note Killing::).
4802 * Save it in a register with `C-x r s' (*note Registers::).
4804 * Save it in a buffer or a file (*note Accumulating Text::).
4806 * Convert case with `C-x C-l' or `C-x C-u'
4809 * Evaluate it as Lisp code with `M-x eval-region' (*note Lisp
4812 * Fill it as text with `M-q' (*note Filling::).
4814 * Print hardcopy with `M-x print-region' (*note Hardcopy::).
4816 * Indent it with `C-x <TAB>' or `C-M-\' (*note Indentation::).
4819 File: xemacs.info, Node: Marking Objects, Next: Mark Ring, Prev: Using Region, Up: Mark
4821 Commands to Mark Textual Objects
4822 --------------------------------
4824 There are commands for placing point and the mark around a textual
4825 object such as a word, list, paragraph or page.
4828 Set mark after end of next word (`mark-word'). This command and
4829 the following one do not move point.
4832 Set mark after end of next Lisp expression (`mark-sexp').
4835 Put region around current paragraph (`mark-paragraph').
4838 Put region around current Lisp defun (`mark-defun').
4841 Put region around entire buffer (`mark-whole-buffer').
4844 Put region around current page (`mark-page').
4846 `M-@' (`mark-word') puts the mark at the end of the next word, while
4847 `C-M-@' (`mark-sexp') puts it at the end of the next Lisp expression.
4848 These characters sometimes save you some typing.
4850 A number of commands are available that set both point and mark and
4851 thus delimit an object in the buffer. `M-h' (`mark-paragraph') moves
4852 point to the beginning of the paragraph that surrounds or follows
4853 point, and puts the mark at the end of that paragraph (*note
4854 Paragraphs::). You can then indent, case-convert, or kill the whole
4855 paragraph. In the same fashion, `C-M-h' (`mark-defun') puts point
4856 before and the mark after the current or following defun (*note
4857 Defuns::). `C-x C-p' (`mark-page') puts point before the current page
4858 (or the next or previous, depending on the argument), and mark at the
4859 end (*note Pages::). The mark goes after the terminating page
4860 delimiter (to include it), while point goes after the preceding page
4861 delimiter (to exclude it). Finally, `C-x h' (`mark-whole-buffer') sets
4862 up the entire buffer as the region by putting point at the beginning
4863 and the mark at the end.
4866 File: xemacs.info, Node: Mark Ring, Prev: Marking Objects, Up: Mark
4871 Aside from delimiting the region, the mark is also useful for marking a
4872 spot that you may want to go back to. To make this feature more
4873 useful, Emacs remembers 16 previous locations of the mark in the "mark
4874 ring". Most commands that set the mark push the old mark onto this
4875 ring. To return to a marked location, use `C-u C-<SPC>' (or `C-u
4876 C-@'); this is the command `set-mark-command' given a numeric argument.
4877 The command moves point to where the mark was, and restores the mark
4878 from the ring of former marks. Repeated use of this command moves point
4879 to all the old marks on the ring, one by one. The marks you have seen
4880 go to the end of the ring, so no marks are lost.
4882 Each buffer has its own mark ring. All editing commands use the
4883 current buffer's mark ring. In particular, `C-u C-<SPC>' always stays
4886 Many commands that can move long distances, such as `M-<'
4887 (`beginning-of-buffer'), start by setting the mark and saving the old
4888 mark on the mark ring. This makes it easier for you to move back
4889 later. Searches set the mark, unless they do not actually move point.
4890 When a command sets the mark, `Mark Set' is printed in the echo area.
4892 The variable `mark-ring-max' is the maximum number of entries to
4893 keep in the mark ring. If that many entries exist and another entry is
4894 added, the last entry in the list is discarded. Repeating `C-u
4895 C-<SPC>' circulates through the entries that are currently in the ring.
4897 The variable `mark-ring' holds the mark ring itself, as a list of
4898 marker objects in the order most recent first. This variable is local
4902 File: xemacs.info, Node: Mouse Selection, Next: Additional Mouse Operations, Prev: Mark, Up: Top
4904 Selecting Text with the Mouse
4905 =============================
4907 If you are using XEmacs under X, you can use the mouse pointer to
4908 select text. (The normal mouse pointer is an I-beam, the same pointer
4911 The glyph variable `text-pointer-glyph' controls the shape of the
4912 mouse pointer when over text. You can also control the shape of the
4913 mouse pointer when over nontext using `nontext-pointer-glyph', and the
4914 shape of the mouse pointer when over the modeline using
4915 `modeline-pointer-glyph'. (Remember, you should use `set-glyph-image',
4916 not `setq', to set one of these variables.)
4918 If you want to get fancy, you can set the foreground and background
4919 colors of the mouse pointer by setting the `pointer' face.
4921 There are two ways to select a region of text with the mouse:
4923 To select a word in text, double-click with the left mouse button
4924 while the mouse cursor is over the word. The word is highlighted when
4925 selected. On monochrome monitors, a stippled background indicates that a
4926 region of text has been highlighted. On color monitors, a color
4927 background indicates highlighted text. You can triple-click to select
4930 To select an arbitrary region of text:
4932 1. Move the mouse cursor over the character at the beginning of the
4933 region of text you want to select.
4935 2. Press and hold the left mouse button.
4937 3. While holding the left mouse button down, drag the cursor to the
4938 character at the end of the region of text you want to select.
4940 4. Release the left mouse button.
4941 The selected region of text is highlighted.
4943 Once a region of text is selected, it becomes the primary X selection
4944 (*note Using X Selections::) as well as the Emacs selected region. You
4945 can paste it into other X applications and use the options from the
4946 Edit pull-down menu on it. Since it is also the Emacs region, you can
4947 use Emacs region commands on it.
4950 File: xemacs.info, Node: Additional Mouse Operations, Next: Killing, Prev: Mouse Selection, Up: Top
4952 Additional Mouse Operations
4953 ===========================
4955 XEmacs also provides the following mouse functions. Most of these are
4956 not bound to mouse gestures by default, but they are provided for your
4957 customization pleasure. For example, if you wanted `shift-left' (that
4958 is, holding down the <Shift> key and clicking the left mouse button) to
4959 delete the character at which you are pointing, then you could do this:
4961 (global-set-key '(shift button1) 'mouse-del-char)
4964 Delete the character pointed to by the mouse.
4966 `mouse-delete-window'
4967 Delete the Emacs window that the mouse is on.
4969 `mouse-keep-one-window'
4970 Select the Emacs window that the mouse is on, then delete all other
4971 windows on this frame.
4974 Kill the line pointed to by the mouse.
4977 Print the length of the line indicated by the pointer.
4980 Scroll point to the mouse position.
4983 Select the Emacs window the mouse is on.
4985 `mouse-select-and-split'
4986 Select the Emacs window mouse is on, then split it vertically in
4990 Select the Emacs window the mouse is on and set the mark at the
4991 mouse position. Display the cursor at that position for a second.
4994 Select the Emacs window that the mouse is on and move point to the
4998 Make a selection with the mouse. This is the default binding of
4999 the left mouse button (<button1>).
5001 `mouse-track-adjust'
5002 Extend the existing selection. This is the default binding of
5005 `mouse-track-and-copy-to-cutbuffer'
5006 Make a selection like `mouse-track', but also copy it to the cut
5009 `mouse-track-delete-and-insert'
5010 Make a selection with the mouse and insert it at point. This is
5011 the default binding of <control-shift-button1>.
5013 `mouse-track-insert'
5014 Make a selection with the mouse and insert it at point. This is
5015 the default binding of <control-button1>.
5017 `mouse-window-to-region'
5018 Narrow a window to the region between the cursor and the mouse
5021 The `M-x mouse-track' command should be bound to a mouse button. If
5022 you click-and-drag, the selection is set to the region between the
5023 point of the initial click and the point at which you release the
5024 button. These positions do not need to be ordered.
5026 If you click-and-release without moving the mouse, the point is
5027 moved, and the selection is disowned (there will be no selection
5028 owner.) The mark will be set to the previous position of point.
5030 If you double-click, the selection will extend by symbols instead of
5031 by characters. If you triple-click, the selection will extend by lines.
5033 If you drag the mouse off the top or bottom of the window, you can
5034 select pieces of text that are larger than the visible part of the
5035 buffer; the buffer will scroll as necessary.
5037 The selected text becomes the current X selection, and is also
5038 copied to the top of the kill ring. Point will be left at the position
5039 at which you released the button and the mark will be left at the
5040 initial click position. Bind a mouse click to
5041 `mouse-track-and-copy-to-cutbuffer' to copy selections to the cut
5042 buffer. (See also the `mouse-track-adjust' command, on
5045 The `M-x mouse-track-adjust' command should be bound to a mouse
5046 button. The selection will be enlarged or shrunk so that the point of
5047 the mouse click is one of its endpoints. This is only meaningful after
5048 the `mouse-track' command (<button1>) has been executed.
5050 The `M-x mouse-track-delete-and-insert' command is exactly the same
5051 as the `mouse-track' command on <button1>, except that point is not
5052 moved; the selected text is immediately inserted after being selected;
5053 and the text of the selection is deleted.
5055 The `M-x mouse-track-insert' command is exactly the same as the
5056 `mouse-track' command on <button1>, except that point is not moved; the
5057 selected text is immediately inserted after being selected; and the
5058 selection is immediately disowned afterwards.
5061 File: xemacs.info, Node: Killing, Next: Yanking, Prev: Additional Mouse Operations, Up: Top
5063 Deletion and Killing
5064 ====================
5066 Most commands that erase text from the buffer save it. You can get the
5067 text back if you change your mind, or you can move or copy it to other
5068 parts of the buffer. Commands which erase text and save it in the kill
5069 ring are known as "kill" commands. Some other commands erase text but
5070 do not save it; they are known as "delete" commands. (This distinction
5071 is made only for erasing text in the buffer.)
5073 The commands' names and individual descriptions use the words `kill'
5074 and `delete' to indicate what they do. If you perform a kill or delete
5075 command by mistake, use the `C-x u' (`undo') command to undo it (*note
5076 Undo::). The delete commands include `C-d' (`delete-char') and <DEL>
5077 (`delete-backward-char'), which delete only one character at a time,
5078 and those commands that delete only spaces or newlines. Commands that
5079 can destroy significant amounts of nontrivial data usually kill.
5085 Delete next character (`delete-char').
5088 Delete previous character (`delete-backward-char').
5091 Delete spaces and tabs around point (`delete-horizontal-space').
5094 Delete spaces and tabs around point, leaving one space
5098 Delete blank lines around the current line (`delete-blank-lines').
5101 Join two lines by deleting the intervening newline, and any
5102 indentation following it (`delete-indentation').
5104 The most basic delete commands are `C-d' (`delete-char') and <DEL>
5105 (`delete-backward-char'). `C-d' deletes the character after point, the
5106 one the cursor is "on top of". Point doesn't move. <DEL> deletes the
5107 character before the cursor, and moves point back. You can delete
5108 newlines like any other characters in the buffer; deleting a newline
5109 joins two lines. Actually, `C-d' and <DEL> aren't always delete
5110 commands; if you give them an argument, they kill instead, since they
5111 can erase more than one character this way.
5113 The other delete commands delete only formatting characters: spaces,
5114 tabs and newlines. `M-\' (`delete-horizontal-space') deletes all
5115 spaces and tab characters before and after point. `M-<SPC>'
5116 (`just-one-space') does the same but leaves a single space after point,
5117 regardless of the number of spaces that existed previously (even zero).
5119 `C-x C-o' (`delete-blank-lines') deletes all blank lines after the
5120 current line. If the current line is blank, it deletes all blank lines
5121 preceding the current line as well as leaving one blank line, the
5122 current line. `M-^' (`delete-indentation') joins the current line and
5123 the previous line, or, if given an argument, joins the current line and
5124 the next line by deleting a newline and all surrounding spaces, possibly
5125 leaving a single space. *Note M-^: Indentation.
5131 Kill rest of line or one or more lines (`kill-line').
5133 The simplest kill command is `C-k'. If given at the beginning of a
5134 line, it kills all the text on the line, leaving the line blank. If
5135 given on a blank line, the blank line disappears. As a consequence, a
5136 line disappears completely if you go to the front of a non-blank line
5137 and type `C-k' twice.
5139 More generally, `C-k' kills from point up to the end of the line,
5140 unless it is at the end of a line. In that case, it kills the newline
5141 following the line, thus merging the next line into the current one.
5142 Emacs ignores invisible spaces and tabs at the end of the line when
5143 deciding which case applies: if point appears to be at the end of the
5144 line, you can be sure the newline will be killed.
5146 If you give `C-k' a positive argument, it kills that many lines and
5147 the newlines that follow them (however, text on the current line before
5148 point is not killed). With a negative argument, `C-k' kills back to a
5149 number of line beginnings. An argument of -2 means kill back to the
5150 second line beginning. If point is at the beginning of a line, that
5151 line beginning doesn't count, so `C-u - 2 C-k' with point at the front
5152 of a line kills the two previous lines.
5154 `C-k' with an argument of zero kills all the text before point on the
5161 Kill region (from point to the mark) (`kill-region'). *Note
5165 Kill word (`kill-word').
5168 Kill word backwards (`backward-kill-word').
5171 Kill back to beginning of sentence (`backward-kill-sentence').
5175 Kill to end of sentence (`kill-sentence').
5178 Kill sexp (`kill-sexp'). *Note Lists::.
5181 Kill up to next occurrence of CHAR (`zap-to-char').
5183 `C-w' (`kill-region') is a very general kill command; it kills
5184 everything between point and the mark. You can use this command to kill
5185 any contiguous sequence of characters by first setting the mark at one
5186 end of a sequence of characters, then going to the other end and typing
5189 A convenient way of killing is combined with searching: `M-z'
5190 (`zap-to-char') reads a character and kills from point up to (but not
5191 including) the next occurrence of that character in the buffer. If
5192 there is no next occurrence, killing goes to the end of the buffer. A
5193 numeric argument acts as a repeat count. A negative argument means to
5194 search backward and kill text before point.
5196 Other syntactic units can be killed: words, with `M-<DEL>' and `M-d'
5197 (*note Words::); sexps, with `C-M-k' (*note Lists::); and sentences,
5198 with `C-x <DEL>' and `M-k' (*note Sentences::).
5201 File: xemacs.info, Node: Yanking, Next: Using X Selections, Prev: Killing, Up: Top
5206 "Yanking" means getting back text which was killed. Some systems call
5207 this "pasting". The usual way to move or copy text is to kill it and
5208 then yank it one or more times.
5211 Yank last killed text (`yank').
5214 Replace re-inserted killed text with the previously killed text
5218 Save region as last killed text without actually killing it
5219 (`copy-region-as-kill').
5222 Append next kill to last batch of killed text (`append-next-kill').
5226 * Kill Ring:: Where killed text is stored. Basic yanking.
5227 * Appending Kills:: Several kills in a row all yank together.
5228 * Earlier Kills:: Yanking something killed some time ago.
5231 File: xemacs.info, Node: Kill Ring, Next: Appending Kills, Prev: Yanking, Up: Yanking
5236 All killed text is recorded in the "kill ring", a list of blocks of
5237 text that have been killed. There is only one kill ring, used in all
5238 buffers, so you can kill text in one buffer and yank it in another
5239 buffer. This is the usual way to move text from one file to another.
5240 (*Note Accumulating Text::, for some other ways.)
5242 If you have two separate Emacs processes, you cannot use the kill
5243 ring to move text. If you are using XEmacs under X, however, you can
5244 use the X selection mechanism to move text from one to another.
5246 If you are using XEmacs under X and have one Emacs process with
5247 multiple frames, they do share the same kill ring. You can kill or
5248 copy text in one Emacs frame, then yank it in the other frame belonging
5249 to the same process.
5251 The command `C-y' (`yank') reinserts the text of the most recent
5252 kill. It leaves the cursor at the end of the text and sets the mark at
5253 the beginning of the text. *Note Mark::.
5255 `C-u C-y' yanks the text, leaves the cursor in front of the text,
5256 and sets the mark after it, if the argument is with just a `C-u'. Any
5257 other argument, including `C-u' and digits, has different results,
5258 described below, under "Yanking Earlier Kills".
5260 To copy a block of text, you can also use `M-w'
5261 (`copy-region-as-kill'), which copies the region into the kill ring
5262 without removing it from the buffer. `M-w' is similar to `C-w' followed
5263 by `C-y' but does not mark the buffer as "modified" and does not
5264 actually cut anything.
5267 File: xemacs.info, Node: Appending Kills, Next: Earlier Kills, Prev: Kill Ring, Up: Yanking
5272 Normally, each kill command pushes a new block onto the kill ring.
5273 However, two or more kill commands in a row combine their text into a
5274 single entry, so that a single `C-y' yanks it all back. This means you
5275 don't have to kill all the text you want to yank in one command; you
5276 can kill line after line, or word after word, until you have killed what
5277 you want, then get it all back at once using `C-y'. (Thus we join
5278 television in leading people to kill thoughtlessly.)
5280 Commands that kill forward from point add onto the end of the
5281 previous killed text. Commands that kill backward from point add onto
5282 the beginning. This way, any sequence of mixed forward and backward
5283 kill commands puts all the killed text into one entry without
5284 rearrangement. Numeric arguments do not break the sequence of
5285 appending kills. For example, suppose the buffer contains:
5289 and here is the third.
5291 with point at the beginning of the second line. If you type `C-k C-u 2
5292 M-<DEL> C-k', the first `C-k' kills the text `line of sample text',
5293 `C-u 2 M-<DEL>' kills `the first' with the newline that followed it,
5294 and the second `C-k' kills the newline after the second line. The
5295 result is that the buffer contains `This is and here is the third.' and
5296 a single kill entry contains `the first<RET>line of sample
5297 text<RET>'--all the killed text, in its original order.
5299 If a kill command is separated from the last kill command by other
5300 commands (not just numeric arguments), it starts a new entry on the kill
5301 ring. To force a kill command to append, first type the command `C-M-w'
5302 (`append-next-kill'). `C-M-w' tells the following command, if it is a
5303 kill command, to append the text it kills to the last killed text,
5304 instead of starting a new entry. With `C-M-w', you can kill several
5305 separated pieces of text and accumulate them to be yanked back in one
5309 File: xemacs.info, Node: Earlier Kills, Prev: Appending Kills, Up: Yanking
5311 Yanking Earlier Kills
5312 ---------------------
5314 To recover killed text that is no longer the most recent kill, you need
5315 the `Meta-y' (`yank-pop') command. You can use `M-y' only after a
5316 `C-y' or another `M-y'. It takes the text previously yanked and
5317 replaces it with the text from an earlier kill. To recover the text of
5318 the next-to-the-last kill, first use `C-y' to recover the last kill,
5319 then `M-y' to replace it with the previous kill.
5321 You can think in terms of a "last yank" pointer which points at an
5322 item in the kill ring. Each time you kill, the "last yank" pointer
5323 moves to the new item at the front of the ring. `C-y' yanks the item
5324 which the "last yank" pointer points to. `M-y' moves the "last yank"
5325 pointer to a different item, and the text in the buffer changes to
5326 match. Enough `M-y' commands can move the pointer to any item in the
5327 ring, so you can get any item into the buffer. Eventually the pointer
5328 reaches the end of the ring; the next `M-y' moves it to the first item
5331 Yanking moves the "last yank" pointer around the ring, but does not
5332 change the order of the entries in the ring, which always runs from the
5333 most recent kill at the front to the oldest one still remembered.
5335 Use `M-y' with a numeric argument to advance the "last yank" pointer
5336 by the specified number of items. A negative argument moves the
5337 pointer toward the front of the ring; from the front of the ring, it
5338 moves to the last entry and starts moving forward from there.
5340 Once the text you are looking for is brought into the buffer, you can
5341 stop doing `M-y' commands and the text will stay there. Since the text
5342 is just a copy of the kill ring item, editing it in the buffer does not
5343 change what's in the ring. As long you don't kill additional text, the
5344 "last yank" pointer remains at the same place in the kill ring:
5345 repeating `C-y' will yank another copy of the same old kill.
5347 If you know how many `M-y' commands it would take to find the text
5348 you want, you can yank that text in one step using `C-y' with a numeric
5349 argument. `C-y' with an argument greater than one restores the text
5350 the specified number of entries back in the kill ring. Thus, `C-u 2
5351 C-y' gets the next to the last block of killed text. It is equivalent
5352 to `C-y M-y'. `C-y' with a numeric argument starts counting from the
5353 "last yank" pointer, and sets the "last yank" pointer to the entry that
5356 The variable `kill-ring-max' controls the length of the kill ring;
5357 no more than that many blocks of killed text are saved.
5360 File: xemacs.info, Node: Using X Selections, Next: Accumulating Text, Prev: Yanking, Up: Top
5365 In the X window system, mouse selections provide a simple mechanism for
5366 text transfer between different applications. In a typical X
5367 application, you can select text by pressing the left mouse button and
5368 dragging the cursor over the text you want to copy. The text becomes
5369 the primary X selection and is highlighted. The highlighted region is
5370 also the Emacs selected region.
5372 * Since the region is the primary X selection, you can go to a
5373 different X application and click the middle mouse button: the
5374 text that you selected in the previous application is pasted into
5375 the current application.
5377 * Since the region is the Emacs selected region, you can use all
5378 region commands (`C-w, M-w' etc.) as well as the options of the
5379 Edit menu to manipulate the selected text.
5383 * X Clipboard Selection:: Pasting to the X clipboard.
5384 * X Selection Commands:: Other operations on the selection.
5385 * X Cut Buffers:: X cut buffers are available for compatibility.
5386 * Active Regions:: Using zmacs-style highlighting of the
5390 File: xemacs.info, Node: X Clipboard Selection, Next: X Selection Commands, Prev: Using X Selections, Up: Using X Selections
5392 The Clipboard Selection
5393 -----------------------
5395 There are other kinds of X selections besides the Primary selection; one
5396 common one is the Clipboard selection. Some applications prefer to
5397 transfer data using this selection in preference to the Primary. One
5398 can transfer text from the Primary selection to the Clipboard
5399 selection with the Copy command under the Edit menu in the menubar.
5401 Usually, the clipboard selection is not visible. However, if you
5402 run the `xclipboard' application, the text most recently copied to the
5403 clipboard (with the Copy command) is displayed in a window. Any time
5404 new text is thus copied, the `xclipboard' application makes a copy of
5405 it and displays it in its window. The value of the clipboard can
5406 survive the lifetime of the running Emacs process. The `xclipboard'
5407 man page provides more details.
5409 Warning: If you use the `xclipboard' application, remember that it
5410 maintains a list of all things that have been pasted to the clipboard
5411 (that is, copied with the Copy command). If you don't manually delete
5412 elements from this list by clicking on the Delete button in the
5413 `xclipboard' window, the clipboard will eventually consume a lot of
5416 In summary, some X applications (such as `xterm') allow one to paste
5417 text in them from XEmacs in the following way:
5419 * Drag out a region of text in Emacs with the left mouse button,
5420 making that text be the Primary selection.
5422 * Click the middle button in the other application, pasting the
5425 With some other applications (notably, the OpenWindows and Motif
5426 tools) you must use this method instead:
5428 * Drag out a region of text in Emacs with the left mouse button,
5429 making that text be the Primary selection.
5431 * Copy the selected text to the Clipboard selection by selecting the
5432 Copy menu item from the Edit menu, or by hitting the Copy key on
5435 * Paste the text in the other application by selecting Paste from its
5436 menu, or by hitting the Paste key on your keyboard.
5439 File: xemacs.info, Node: X Selection Commands, Next: X Cut Buffers, Prev: X Clipboard Selection, Up: Using X Selections
5441 Miscellaneous X Selection Commands
5442 ----------------------------------
5444 `M-x x-copy-primary-selection'
5445 Copy the primary selection to both the kill ring and the Clipboard.
5447 `M-x x-insert-selection'
5448 Insert the current selection into the buffer at point.
5450 `M-x x-delete-primary-selection'
5451 Deletes the text in the primary selection without copying it to
5452 the kill ring or the Clipboard.
5454 `M-x x-kill-primary-selection'
5455 Deletes the text in the primary selection and copies it to both
5456 the kill ring and the Clipboard.
5459 Kill the text between point and the mouse and copy it to the
5460 clipboard and to the cut buffer.
5462 `M-x x-own-secondary-selection'
5463 Make a secondary X selection of the given argument.
5465 `M-x x-own-selection'
5466 Make a primary X selection of the given argument.
5468 `M-x x-set-point-and-insert-selection'
5469 Set point where clicked and insert the primary selection or the
5473 File: xemacs.info, Node: X Cut Buffers, Next: Active Regions, Prev: X Selection Commands, Up: Using X Selections
5478 X cut buffers are a different, older way of transferring text between
5479 applications. XEmacs supports cut buffers for compatibility with older
5480 programs, even though selections are now the preferred way of
5483 X has a concept of applications "owning" selections. When you select
5484 text by clicking and dragging inside an application, the application
5485 tells the X server that it owns the selection. When another
5486 application asks the X server for the value of the selection, the X
5487 server requests the information from the owner. When you use
5488 selections, the selection data is not actually transferred unless
5489 someone wants it; the act of making a selection doesn't transfer data.
5490 Cut buffers are different: when you "own" a cut buffer, the data is
5491 actually transferred to the X server immediately, and survives the
5492 lifetime of the application.
5494 Any time a region of text becomes the primary selection in Emacs,
5495 Emacs also copies that text to the cut buffer. This makes it possible
5496 to copy text from an XEmacs buffer and paste it into an older,
5497 non-selection-based application (such as Emacs 18).
5499 Note: Older versions of Emacs could not access the X selections, only
5503 File: xemacs.info, Node: Active Regions, Prev: X Cut Buffers, Up: Using X Selections
5508 By default, both the text you select in an Emacs buffer using the
5509 click-and-drag mechanism and text you select by setting point and the
5510 mark is highlighted. You can use Emacs region commands as well as the
5511 Cut and Copy commands on the highlighted region you selected with the
5514 If you prefer, you can make a distinction between text selected with
5515 the mouse and text selected with point and the mark by setting the
5516 variable `zmacs-regions' to `nil'. In that case:
5518 * The text selected with the mouse becomes both the X selection and
5519 the Emacs selected region. You can use menu-bar commands as well
5520 as Emacs region commands on it.
5522 * The text selected with point and the mark is not highlighted. You
5523 can only use Emacs region commands on it, not the menu-bar items.
5525 Active regions originally come from Zmacs, the Lisp Machine editor.
5526 The idea behind them is that commands can only operate on a region when
5527 the region is in an "active" state. Put simply, you can only operate on
5528 a region that is highlighted.
5530 The variable `zmacs-regions' checks whether LISPM-style active
5531 regions should be used. This means that commands that operate on the
5532 region (the area between point and the mark) only work while the region
5533 is in the active state, which is indicated by highlighting. Most
5534 commands causes the region to not be in the active state; for example,
5535 `C-w' only works immediately after activating the region.
5538 * Commands that operate on the region only work if the region is
5541 * Only a very small set of commands causes the region to become
5542 active-- those commands whose semantics are to mark an area, such
5545 * The region is deactivated after each command that is executed,
5546 except that motion commands do not change whether the region is
5549 `set-mark-command' (`C-SPC') pushes a mark and activates the region.
5550 Moving the cursor with normal motion commands (`C-n', `C-p', etc.)
5551 will cause the region between point and the recently-pushed mark to be
5552 highlighted. It will remain highlighted until some non-motion command
5555 `exchange-point-and-mark' (`C-x C-x') activates the region. So if
5556 you mark a region and execute a command that operates on it, you can
5557 reactivate the same region with `C-x C-x' (or perhaps `C-x C-x C-x
5558 C-x') to operate on it again.
5560 Generally, commands that push marks as a means of navigation, such as
5561 `beginning-of-buffer' (`M-<') and `end-of-buffer' (`M->'), do not
5562 activate the region. However, commands that push marks as a means of
5563 marking an area of text, such as `mark-defun' (`M-C-h'), `mark-word'
5564 (`M-@'), and `mark-whole-buffer' (`C-x h'), do activate the region.
5566 When `zmacs-regions' is `t', there is no distinction between the
5567 primary X selection and the active region selected by point and the
5568 mark. To see this, set the mark (<C-SPC>) and move the cursor with any
5569 cursor-motion command: the region between point and mark is
5570 highlighted, and you can watch it grow and shrink as you move the
5573 Any other commands besides cursor-motion commands (such as inserting
5574 or deleting text) will cause the region to no longer be active; it will
5575 no longer be highlighted, and will no longer be the primary selection.
5576 Region can be explicitly deactivated with `C-g'.
5578 Commands that require a region (such as `C-w') signal an error if
5579 the region is not active. Certain commands cause the region to be in
5580 its active state. The most common ones are `push-mark' (<C-SPC>) and
5581 `exchange-point-and-mark' (`C-x C-x').
5583 When `zmacs-regions' is `t', programs can be non-intrusive on the
5584 state of the region by setting the variable `zmacs-region-stays' to a
5585 non-`nil' value. If you are writing a new Emacs command that is
5586 conceptually a "motion" command and should not interfere with the
5587 current highlightedness of the region, then you may set this variable.
5588 It is reset to `nil' after each user command is executed.
5590 When `zmacs-regions' is `t', programs can make the region between
5591 point and mark go into the active (highlighted) state by using the
5592 function `zmacs-activate-region'. Only a small number of commands
5593 should ever do this.
5595 When `zmacs-regions' is `t', programs can deactivate the region
5596 between point and the mark by using `zmacs-deactivate-region'. Note:
5597 you should not have to call this function; the command loop calls it
5601 File: xemacs.info, Node: Accumulating Text, Next: Rectangles, Prev: Using X Selections, Up: Top
5606 Usually you copy or move text by killing it and yanking it, but there
5607 are other ways that are useful for copying one block of text in many
5608 places, or for copying many scattered blocks of text into one place.
5610 If you like, you can accumulate blocks of text from scattered
5611 locations either into a buffer or into a file. The relevant commands
5612 are described here. You can also use Emacs registers for storing and
5613 accumulating text. *Note Registers::.
5615 `M-x append-to-buffer'
5616 Append region to contents of specified buffer (`append-to-buffer').
5618 `M-x prepend-to-buffer'
5619 Prepend region to contents of specified buffer.
5621 `M-x copy-to-buffer'
5622 Copy region into specified buffer, deleting that buffer's old
5626 Insert contents of specified buffer into current buffer at point.
5628 `M-x append-to-file'
5629 Append region to the end of the contents of specified file.
5631 To accumulate text into a buffer, use the command `M-x
5632 append-to-buffer', which inserts a copy of the region into the buffer
5633 BUFFERNAME, at the location of point in that buffer. If there is no
5634 buffer with the given name, one is created.
5636 If you append text to a buffer that has been used for editing, the
5637 copied text goes to the place where point is. Point in that buffer is
5638 left at the end of the copied text, so successive uses of
5639 `append-to-buffer' accumulate the text in the specified buffer in the
5640 same order as they were copied. Strictly speaking, this command does
5641 not always append to the text already in the buffer; but if this command
5642 is the only command used to alter a buffer, it does always append to the
5643 existing text because point is always at the end.
5645 `M-x prepend-to-buffer' is similar to `append-to-buffer', but point
5646 in the other buffer is left before the copied text, so successive
5647 prependings add text in reverse order. `M-x copy-to-buffer' is
5648 similar, except that any existing text in the other buffer is deleted,
5649 so the buffer is left containing just the text newly copied into it.
5651 You can retrieve the accumulated text from that buffer with `M-x
5652 insert-buffer', which takes BUFFERNAME as an argument. It inserts a
5653 copy of the text in buffer BUFFERNAME into the selected buffer. You
5654 could alternatively select the other buffer for editing, perhaps moving
5655 text from it by killing or with `append-to-buffer'. *Note Buffers::,
5656 for background information on buffers.
5658 Instead of accumulating text within Emacs in a buffer, you can append
5659 text directly into a file with `M-x append-to-file', which takes
5660 FILE-NAME as an argument. It adds the text of the region to the end of
5661 the specified file. The file is changed immediately on disk. This
5662 command is normally used with files that are not being visited in
5663 Emacs. Using it on a file that Emacs is visiting can produce confusing
5664 results, because the file's text inside Emacs does not change while the
5665 file itself changes.
5668 File: xemacs.info, Node: Rectangles, Next: Registers, Prev: Accumulating Text, Up: Top
5673 The rectangle commands affect rectangular areas of text: all characters
5674 between a certain pair of columns, in a certain range of lines.
5675 Commands are provided to kill rectangles, yank killed rectangles, clear
5676 them out, or delete them. Rectangle commands are useful with text in
5677 multicolumnar formats, like code with comments at the right, or for
5678 changing text into or out of such formats.
5680 To specify the rectangle a command should work on, put the mark at
5681 one corner and point at the opposite corner. The specified rectangle is
5682 called the "region-rectangle" because it is controlled about the same
5683 way the region is controlled. Remember that a given combination of
5684 point and mark values can be interpreted either as specifying a region
5685 or as specifying a rectangle; it is up to the command that uses them to
5686 choose the interpretation.
5688 `M-x delete-rectangle'
5689 Delete the text of the region-rectangle, moving any following text
5690 on each line leftward to the left edge of the region-rectangle.
5692 `M-x kill-rectangle'
5693 Similar, but also save the contents of the region-rectangle as the
5694 "last killed rectangle".
5696 `M-x yank-rectangle'
5697 Yank the last killed rectangle with its upper left corner at point.
5699 `M-x open-rectangle'
5700 Insert blank space to fill the space of the region-rectangle. The
5701 previous contents of the region-rectangle are pushed rightward.
5703 `M-x clear-rectangle'
5704 Clear the region-rectangle by replacing its contents with spaces.
5706 The rectangle operations fall into two classes: commands deleting and
5707 moving rectangles, and commands for blank rectangles.
5709 There are two ways to get rid of the text in a rectangle: you can
5710 discard the text (delete it) or save it as the "last killed" rectangle.
5711 The commands for these two ways are `M-x delete-rectangle' and `M-x
5712 kill-rectangle'. In either case, the portion of each line that falls
5713 inside the rectangle's boundaries is deleted, causing following text
5714 (if any) on the line to move left.
5716 Note that "killing" a rectangle is not killing in the usual sense;
5717 the rectangle is not stored in the kill ring, but in a special place
5718 that only records the most recently killed rectangle (that is, does not
5719 append to a killed rectangle). Different yank commands have to be used
5720 and only one rectangle is stored, because yanking a rectangle is quite
5721 different from yanking linear text and yank-popping commands are
5722 difficult to make sense of.
5724 Inserting a rectangle is the opposite of deleting one. You specify
5725 where to put the upper left corner by putting point there. The
5726 rectangle's first line is inserted at point, the rectangle's second line
5727 is inserted at a point one line vertically down, and so on. The number
5728 of lines affected is determined by the height of the saved rectangle.
5730 To insert the last killed rectangle, type `M-x yank-rectangle'.
5731 This can be used to convert single-column lists into double-column
5732 lists; kill the second half of the list as a rectangle and then yank it
5733 beside the first line of the list.
5735 There are two commands for working with blank rectangles: `M-x
5736 clear-rectangle' erases existing text, and `M-x open-rectangle' inserts
5737 a blank rectangle. Clearing a rectangle is equivalent to deleting it
5738 and then inserting a blank rectangle of the same size.
5740 Rectangles can also be copied into and out of registers. *Note
5741 Rectangle Registers: RegRect.
5744 File: xemacs.info, Node: Registers, Next: Display, Prev: Rectangles, Up: Top
5749 XEmacs "registers" are places in which you can save text or positions
5750 for later use. Once you save text or a rectangle in a register, you
5751 can copy it into the buffer once or many times; a position saved in a
5752 register is used by moving point to that position. Rectangles can also
5753 be copied into and out of registers (*note Rectangles::).
5755 Each register has a name which is a single character. A register can
5756 store a piece of text, a rectangle, a position, a window configuration,
5757 or a file name, but only one thing at any given time. Whatever you
5758 store in a register remains there until you store something else in that
5759 register. To see what a register R contains, use `M-x view-register'.
5761 `M-x view-register <RET> R'
5762 Display a description of what register R contains.
5764 `M-x view-register' reads a register name as an argument and then
5765 displays the contents of the specified register.
5769 * Position: RegPos. Saving positions in registers.
5770 * Text: RegText. Saving text in registers.
5771 * Rectangle: RegRect. Saving rectangles in registers.
5772 * Configurations: RegConfig. Saving window configurations in registers.
5773 * Files: RegFiles. File names in registers.
5774 * Numbers: RegNumbers. Numbers in registers.
5775 * Bookmarks:: Bookmarks are like registers, but persistent.
5778 File: xemacs.info, Node: RegPos, Next: RegText, Prev: Registers, Up: Registers
5780 Saving Positions in Registers
5781 =============================
5783 Saving a position records a place in a buffer so that you can move back
5784 there later. Moving to a saved position switches to that buffer and
5785 moves point to that place in it.
5788 Save position of point in register R (`point-to-register').
5791 Jump to the position saved in register R (`jump-to-register').
5793 To save the current position of point in a register, choose a name R
5794 and type `C-x r <SPC> R'. The register R retains the position thus
5795 saved until you store something else in that register.
5797 The command `C-x r j R' moves point to the position recorded in
5798 register R. The register is not affected; it continues to record the
5799 same location. You can jump to the same position using the same
5800 register as often as you want.
5802 If you use `C-x r j' to go to a saved position, but the buffer it
5803 was saved from has been killed, `C-x r j' tries to create the buffer
5804 again by visiting the same file. Of course, this works only for buffers
5805 that were visiting files.
5808 File: xemacs.info, Node: RegText, Next: RegRect, Prev: RegPos, Up: Registers
5810 Saving Text in Registers
5811 ========================
5813 When you want to insert a copy of the same piece of text many times, it
5814 can be impractical to use the kill ring, since each subsequent kill
5815 moves the piece of text further down on the ring. It becomes hard to
5816 keep track of the argument needed to retrieve the same text with `C-y'.
5817 An alternative is to store the text in a register with `C-x r s'
5818 (`copy-to-register') and then retrieve it with `C-x r i'
5819 (`insert-register').
5822 Copy region into register R (`copy-to-register').
5826 Insert text contents of register R (`insert-register').
5828 `C-x r s R' stores a copy of the text of the region into the
5829 register named R. Given a numeric argument, `C-x r s R' deletes the
5830 text from the buffer as well.
5832 `C-x r i R' inserts the text from register R in the buffer. By
5833 default it leaves point before the text and places the mark after it.
5834 With a numeric argument (`C-u'), it puts point after the text and the
5838 File: xemacs.info, Node: RegRect, Next: RegConfig, Prev: RegText, Up: Registers
5840 Saving Rectangles in Registers
5841 ==============================
5843 A register can contain a rectangle instead of lines of text. The
5844 rectangle is represented as a list of strings. *Note Rectangles::, for
5845 basic information on rectangles and how to specify rectangles in a
5849 Copy the region-rectangle into register R
5850 (`copy-rectangle-to-register'). With a numeric argument, delete it
5855 Insert the rectangle stored in register R (if it contains a
5856 rectangle) (`insert-register').
5858 The `C-x r i R' command inserts linear text if the register
5859 contains that, or inserts a rectangle if the register contains one.
5861 See also the command `sort-columns', which you can think of as
5862 sorting a rectangle. *Note Sorting::.
5865 File: xemacs.info, Node: RegConfig, Next: RegNumbers, Prev: RegRect, Up: Registers
5867 Saving Window Configurations in Registers
5868 =========================================
5870 You can save the window configuration of the selected frame in a
5871 register, or even the configuration of all windows in all frames, and
5872 restore the configuration later.
5875 Save the state of the selected frame's windows in register R
5876 (`window-configuration-to-register').
5878 `M-x frame-configuration-to-register <RET> R'
5879 Save the state of all frames, including all their windows, in
5880 register R (`frame-configuration-to-register').
5882 Use `C-x r j R' to restore a window or frame configuration. This is
5883 the same command used to restore a cursor position. When you restore a
5884 frame configuration, any existing frames not included in the
5885 configuration become invisible. If you wish to delete these frames
5886 instead, use `C-u C-x r j R'.
5889 File: xemacs.info, Node: RegNumbers, Next: RegFiles, Prev: RegConfig, Up: Registers
5891 Keeping Numbers in Registers
5892 ============================
5894 There are commands to store a number in a register, to insert the
5895 number in the buffer in decimal, and to increment it. These commands
5896 can be useful in keyboard macros (*note Keyboard Macros::).
5898 `C-u NUMBER C-x r n REG'
5899 Store NUMBER into register REG (`number-to-register').
5901 `C-u NUMBER C-x r + REG'
5902 Increment the number in register REG by NUMBER
5903 (`increment-register').
5906 Insert the number from register REG into the buffer.
5908 `C-x r g' is the same command used to insert any other sort of
5909 register contents into the buffer.
5912 File: xemacs.info, Node: RegFiles, Next: Bookmarks, Prev: RegNumbers, Up: Registers
5914 Keeping File Names in Registers
5915 ===============================
5917 If you visit certain file names frequently, you can visit them more
5918 conveniently if you put their names in registers. Here's the Lisp code
5919 used to put a file name in a register:
5921 (set-register ?R '(file . NAME))
5925 (set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog"))
5927 puts the file name shown in register `z'.
5929 To visit the file whose name is in register R, type `C-x r j R'.
5930 (This is the same command used to jump to a position or restore a frame
5934 File: xemacs.info, Node: Bookmarks, Prev: RegFiles, Up: Registers
5939 "Bookmarks" are somewhat like registers in that they record positions
5940 you can jump to. Unlike registers, they have long names, and they
5941 persist automatically from one Emacs session to the next. The
5942 prototypical use of bookmarks is to record "where you were reading" in
5945 Note: bookmark.el is distributed in edit-utils package. You need to
5946 install that to use bookmark facility (*note Packages::).
5949 Set the bookmark for the visited file, at point.
5951 `C-x r m BOOKMARK <RET>'
5952 Set the bookmark named BOOKMARK at point (`bookmark-set').
5954 `C-x r b BOOKMARK <RET>'
5955 Jump to the bookmark named BOOKMARK (`bookmark-jump').
5958 List all bookmarks (`list-bookmarks').
5961 Save all the current bookmark values in the default bookmark file.
5963 The prototypical use for bookmarks is to record one current position
5964 in each of several files. So the command `C-x r m', which sets a
5965 bookmark, uses the visited file name as the default for the bookmark
5966 name. If you name each bookmark after the file it points to, then you
5967 can conveniently revisit any of those files with `C-x r b', and move to
5968 the position of the bookmark at the same time.
5970 To display a list of all your bookmarks in a separate buffer, type
5971 `C-x r l' (`list-bookmarks'). If you switch to that buffer, you can
5972 use it to edit your bookmark definitions or annotate the bookmarks.
5973 Type `C-h m' in that buffer for more information about its special
5976 When you kill XEmacs, XEmacs offers to save your bookmark values in
5977 your default bookmark file, `~/.emacs.bmk', if you have changed any
5978 bookmark values. You can also save the bookmarks at any time with the
5979 `M-x bookmark-save' command. The bookmark commands load your default
5980 bookmark file automatically. This saving and loading is how bookmarks
5981 persist from one XEmacs session to the next.
5983 If you set the variable `bookmark-save-flag' to 1, then each command
5984 that sets a bookmark will also save your bookmarks; this way, you don't
5985 lose any bookmark values even if XEmacs crashes. (The value, if a
5986 number, says how many bookmark modifications should go by between
5989 Bookmark position values are saved with surrounding context, so that
5990 `bookmark-jump' can find the proper position even if the file is
5991 modified slightly. The variable `bookmark-search-size' says how many
5992 characters of context to record, on each side of the bookmark's
5995 Here are some additional commands for working with bookmarks:
5997 `M-x bookmark-load <RET> FILENAME <RET>'
5998 Load a file named FILENAME that contains a list of bookmark
5999 values. You can use this command, as well as `bookmark-write', to
6000 work with other files of bookmark values in addition to your
6001 default bookmark file.
6003 `M-x bookmark-write <RET> FILENAME <RET>'
6004 Save all the current bookmark values in the file FILENAME.
6006 `M-x bookmark-delete <RET> BOOKMARK <RET>'
6007 Delete the bookmark named BOOKMARK.
6009 `M-x bookmark-insert-location <RET> BOOKMARK <RET>'
6010 Insert in the buffer the name of the file that bookmark BOOKMARK
6013 `M-x bookmark-insert <RET> BOOKMARK <RET>'
6014 Insert in the buffer the _contents_ of the file that bookmark
6018 File: xemacs.info, Node: Display, Next: Search, Prev: Registers, Up: Top
6020 Controlling the Display
6021 ***********************
6023 Since only part of a large buffer fits in the window, XEmacs tries to
6024 show the part that is likely to be interesting. The display control
6025 commands allow you to specify which part of the text you want to see.
6028 Clear frame and redisplay, scrolling the selected window to center
6029 point vertically within it (`recenter').
6034 Scroll forward (a windowful or a specified number of lines)
6035 (`scroll-up'). On most X keyboards, you can get this
6036 functionality using the key labelled `Page Down', which generates
6037 either `next' or `pgdn'.
6042 Scroll backward (`scroll-down'). On most X keyboards, you can get
6043 this functionality using the key labelled `Page Up', which
6044 generates either `prior' or `pgup'.
6047 Scroll so point is on line ARG (`recenter').
6052 Scroll text in current window to the left (`scroll-left').
6057 Scroll to the right (`scroll-right').
6060 Make deeply indented lines invisible (`set-selective-display').
6064 * Scrolling:: Moving text up and down in a window.
6065 * Horizontal Scrolling:: Moving text left and right in a window.
6066 * Selective Display:: Hiding lines with lots of indentation.
6067 * Display Vars:: Information on variables for customizing display.
6070 File: xemacs.info, Node: Scrolling, Next: Horizontal Scrolling, Prev: Display, Up: Display
6075 If a buffer contains text that is too large to fit entirely within the
6076 window that is displaying the buffer, XEmacs shows a contiguous section
6077 of the text. The section shown always contains point.
6079 "Scrolling" means moving text up or down in the window so that
6080 different parts of the text are visible. Scrolling forward means that
6081 text moves up, and new text appears at the bottom. Scrolling backward
6082 moves text down and new text appears at the top.
6084 Scrolling happens automatically if you move point past the bottom or
6085 top of the window. You can also explicitly request scrolling with the
6086 commands in this section.
6089 Clear frame and redisplay, scrolling the selected window to center
6090 point vertically within it (`recenter').
6095 Scroll forward (a windowful or a specified number of lines)
6101 Scroll backward (`scroll-down').
6104 Scroll so point is on line ARG (`recenter').
6106 The most basic scrolling command is `C-l' (`recenter') with no
6107 argument. It clears the entire frame and redisplays all windows. In
6108 addition, it scrolls the selected window so that point is halfway down
6109 from the top of the window.
6111 The scrolling commands `C-v' and `M-v' let you move all the text in
6112 the window up or down a few lines. `C-v' (`scroll-up') with an
6113 argument shows you that many more lines at the bottom of the window,
6114 moving the text and point up together as `C-l' might. `C-v' with a
6115 negative argument shows you more lines at the top of the window.
6116 `Meta-v' (`scroll-down') is like `C-v', but moves in the opposite
6119 To read the buffer a windowful at a time, use `C-v' with no
6120 argument. `C-v' takes the last two lines at the bottom of the window
6121 and puts them at the top, followed by nearly a whole windowful of lines
6122 not previously visible. Point moves to the new top of the window if it
6123 was in the text scrolled off the top. `M-v' with no argument moves
6124 backward with similar overlap. The number of lines of overlap across a
6125 `C-v' or `M-v' is controlled by the variable
6126 `next-screen-context-lines'; by default, it is two.
6128 Another way to scroll is using `C-l' with a numeric argument. `C-l'
6129 does not clear the frame when given an argument; it only scrolls the
6130 selected window. With a positive argument N, `C-l' repositions text to
6131 put point N lines down from the top. An argument of zero puts point on
6132 the very top line. Point does not move with respect to the text;
6133 rather, the text and point move rigidly on the frame. `C-l' with a
6134 negative argument puts point that many lines from the bottom of the
6135 window. For example, `C-u - 1 C-l' puts point on the bottom line, and
6136 `C-u - 5 C-l' puts it five lines from the bottom. Just `C-u' as
6137 argument, as in `C-u C-l', scrolls point to the center of the frame.
6139 Scrolling happens automatically if point has moved out of the visible
6140 portion of the text when it is time to display. Usually scrolling is
6141 done to put point vertically centered within the window. However, if
6142 the variable `scroll-step' has a non-zero value, an attempt is made to
6143 scroll the buffer by that many lines; if that is enough to bring point
6144 back into visibility, that is what happens.
6146 Scrolling happens automatically if point has moved out of the visible
6147 portion of the text when it is time to display. Usually scrolling is
6148 done to put point vertically centered within the window. However, if
6149 the variable `scroll-step' has a non-zero value, an attempt is made to
6150 scroll the buffer by that many lines; if that is enough to bring point
6151 back into visibility, that is what happens.
6153 If you set `scroll-step' to a small value because you want to use
6154 arrow keys to scroll the screen without recentering, the redisplay
6155 preemption will likely make XEmacs keep recentering the screen when
6156 scrolling fast, regardless of `scroll-step'. To prevent this, set
6157 `scroll-conservatively' to a small value, which will have the result of
6158 overriding the redisplay preemption.
6161 File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display
6163 Horizontal Scrolling
6164 ====================
6167 Scroll text in current window to the left (`scroll-left').
6170 Scroll to the right (`scroll-right').
6172 The text in a window can also be scrolled horizontally. This means that
6173 each line of text is shifted sideways in the window, and one or more
6174 characters at the beginning of each line are not displayed at all.
6175 When a window has been scrolled horizontally in this way, text lines
6176 are truncated rather than continued (*note Continuation Lines::), with
6177 a `$' appearing in the first column when there is text truncated to the
6178 left, and in the last column when there is text truncated to the right.
6180 The command `C-x <' (`scroll-left') scrolls the selected window to
6181 the left by N columns with argument N. With no argument, it scrolls by
6182 almost the full width of the window (two columns less, to be precise).
6183 `C-x >' (`scroll-right') scrolls similarly to the right. The window
6184 cannot be scrolled any farther to the right once it is displaying
6185 normally (with each line starting at the window's left margin);
6186 attempting to do so has no effect.
6189 File: xemacs.info, Node: Selective Display, Next: Display Vars, Prev: Display, Up: Display
6194 XEmacs can hide lines indented more than a certain number of columns
6195 (you specify how many columns). This allows you to get an overview of
6196 a part of a program.
6198 To hide lines, type `C-x $' (`set-selective-display') with a numeric
6199 argument N. (*Note Arguments::, for information on giving the
6200 argument.) Lines with at least N columns of indentation disappear from
6201 the screen. The only indication of their presence are three dots
6202 (`...'), which appear at the end of each visible line that is followed
6203 by one or more invisible ones.
6205 The invisible lines are still present in the buffer, and most editing
6206 commands see them as usual, so it is very easy to put point in the
6207 middle of invisible text. When this happens, the cursor appears at the
6208 end of the previous line, after the three dots. If point is at the end
6209 of the visible line, before the newline that ends it, the cursor
6210 appears before the three dots.
6212 The commands `C-n' and `C-p' move across the invisible lines as if
6213 they were not there.
6215 To make everything visible again, type `C-x $' with no argument.
6218 File: xemacs.info, Node: Display Vars, Prev: Selective Display, Up: Display
6220 Variables Controlling Display
6221 =============================
6223 This section contains information for customization only. Beginning
6224 users should skip it.
6226 When you reenter XEmacs after suspending, XEmacs normally clears the
6227 screen and redraws the entire display. On some terminals with more than
6228 one page of memory, it is possible to arrange the termcap entry so that
6229 the `ti' and `te' strings (output to the terminal when XEmacs is
6230 entered and exited, respectively) switch between pages of memory so as
6231 to use one page for XEmacs and another page for other output. In that
6232 case, you might want to set the variable `no-redraw-on-reenter' to
6233 non-`nil' so that XEmacs will assume, when resumed, that the screen
6234 page it is using still contains what XEmacs last wrote there.
6236 The variable `echo-keystrokes' controls the echoing of
6237 multi-character keys; its value is the number of seconds of pause
6238 required to cause echoing to start, or zero, meaning don't echo at all.
6241 If the variable `ctl-arrow' is `nil', control characters in the
6242 buffer are displayed with octal escape sequences, all except newline and
6243 tab. If its value is `t', then control characters will be printed with
6244 an up-arrow, for example `^A'.
6246 If its value is not `t' and not `nil', then characters whose code is
6247 greater than 160 (that is, the space character (32) with its high bit
6248 set) will be assumed to be printable, and will be displayed without
6249 alteration. This is the default when running under X Windows, since
6250 XEmacs assumes an ISO/8859-1 character set (also known as "Latin1").
6251 The `ctl-arrow' variable may also be set to an integer, in which case
6252 all characters whose codes are greater than or equal to that value will
6253 be assumed to be printable.
6255 Altering the value of `ctl-arrow' makes it local to the current
6256 buffer; until that time, the default value is in effect. *Note
6259 Normally, a tab character in the buffer is displayed as whitespace
6260 which extends to the next display tab stop position, and display tab
6261 stops come at intervals equal to eight spaces. The number of spaces
6262 per tab is controlled by the variable `tab-width', which is made local
6263 by changing it, just like `ctl-arrow'. Note that how the tab character
6264 in the buffer is displayed has nothing to do with the definition of
6267 If you set the variable `selective-display-ellipses' to `nil', the
6268 three dots at the end of a line that precedes invisible lines do not
6269 appear. There is no visible indication of the invisible lines. This
6270 variable becomes local automatically when set.
6273 File: xemacs.info, Node: Search, Next: Fixit, Prev: Display, Up: Top
6275 Searching and Replacement
6276 *************************
6278 Like other editors, Emacs has commands for searching for occurrences of
6279 a string. The principal search command is unusual in that it is
6280 "incremental": it begins to search before you have finished typing the
6281 search string. There are also non-incremental search commands more like
6282 those of other editors.
6284 Besides the usual `replace-string' command that finds all
6285 occurrences of one string and replaces them with another, Emacs has a
6286 fancy replacement command called `query-replace' which asks
6287 interactively which occurrences to replace.
6291 * Incremental Search:: Search happens as you type the string.
6292 * Non-Incremental Search:: Specify entire string and then search.
6293 * Word Search:: Search for sequence of words.
6294 * Regexp Search:: Search for match for a regexp.
6295 * Regexps:: Syntax of regular expressions.
6296 * Search Case:: To ignore case while searching, or not.
6297 * Replace:: Search, and replace some or all matches.
6298 * Other Repeating Search:: Operating on all matches for some regexp.
6301 File: xemacs.info, Node: Incremental Search, Next: Non-Incremental Search, Prev: Search, Up: Search
6306 An incremental search begins searching as soon as you type the first
6307 character of the search string. As you type in the search string, Emacs
6308 shows you where the string (as you have typed it so far) is found.
6309 When you have typed enough characters to identify the place you want,
6310 you can stop. Depending on what you do next, you may or may not need to
6311 terminate the search explicitly with a <RET>.
6314 Incremental search forward (`isearch-forward').
6317 Incremental search backward (`isearch-backward').
6319 `C-s' starts an incremental search. `C-s' reads characters from the
6320 keyboard and positions the cursor at the first occurrence of the
6321 characters that you have typed. If you type `C-s' and then `F', the
6322 cursor moves right after the first `F'. Type an `O', and see the
6323 cursor move to after the first `FO'. After another `O', the cursor is
6324 after the first `FOO' after the place where you started the search.
6325 Meanwhile, the search string `FOO' has been echoed in the echo area.
6327 The echo area display ends with three dots when actual searching is
6328 going on. When search is waiting for more input, the three dots are
6329 removed. (On slow terminals, the three dots are not displayed.)
6331 If you make a mistake in typing the search string, you can erase
6332 characters with <DEL>. Each <DEL> cancels the last character of the
6333 search string. This does not happen until Emacs is ready to read
6334 another input character; first it must either find, or fail to find,
6335 the character you want to erase. If you do not want to wait for this
6336 to happen, use `C-g' as described below.
6338 When you are satisfied with the place you have reached, you can type
6339 <RET> (or <C-m>), which stops searching, leaving the cursor where the
6340 search brought it. Any command not specially meaningful in searches
6341 also stops the search and is then executed. Thus, typing `C-a' exits
6342 the search and then moves to the beginning of the line. <RET> is
6343 necessary only if the next command you want to type is a printing
6344 character, <DEL>, <ESC>, or another control character that is special
6345 within searches (`C-q', `C-w', `C-r', `C-s', or `C-y').
6347 Sometimes you search for `FOO' and find it, but were actually
6348 looking for a different occurrence of it. To move to the next
6349 occurrence of the search string, type another `C-s'. Do this as often
6350 as necessary. If you overshoot, you can cancel some `C-s' characters
6353 After you exit a search, you can search for the same string again by
6354 typing just `C-s C-s': the first `C-s' is the key that invokes
6355 incremental search, and the second `C-s' means "search again".
6357 If the specified string is not found at all, the echo area displays
6358 the text `Failing I-Search'. The cursor is after the place where Emacs
6359 found as much of your string as it could. Thus, if you search for
6360 `FOOT', and there is no `FOOT', the cursor may be after the `FOO' in
6361 `FOOL'. At this point there are several things you can do. If you
6362 mistyped the search string, correct it. If you like the place you have
6363 found, you can type <RET> or some other Emacs command to "accept what
6364 the search offered". Or you can type `C-g', which removes from the
6365 search string the characters that could not be found (the `T' in
6366 `FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second
6367 `C-g' at that point cancels the search entirely, returning point to
6368 where it was when the search started.
6370 If a search is failing and you ask to repeat it by typing another
6371 `C-s', it starts again from the beginning of the buffer. Repeating a
6372 failing backward search with `C-r' starts again from the end. This is
6373 called "wrapping around". `Wrapped' appears in the search prompt once
6376 The `C-g' "quit" character does special things during searches; just
6377 what it does depends on the status of the search. If the search has
6378 found what you specified and is waiting for input, `C-g' cancels the
6379 entire search. The cursor moves back to where you started the search.
6380 If `C-g' is typed when there are characters in the search string that
6381 have not been found--because Emacs is still searching for them, or
6382 because it has failed to find them--then the search string characters
6383 which have not been found are discarded from the search string. The
6384 search is now successful and waiting for more input, so a second `C-g'
6385 cancels the entire search.
6387 To search for a control character such as `C-s' or <DEL> or <ESC>,
6388 you must quote it by typing `C-q' first. This function of `C-q' is
6389 analogous to its meaning as an Emacs command: it causes the following
6390 character to be treated the way a graphic character would normally be
6391 treated in the same context.
6393 To search backwards, you can use `C-r' instead of `C-s' to start the
6394 search; `C-r' is the key that runs the command (`isearch-backward') to
6395 search backward. You can also use `C-r' to change from searching
6396 forward to searching backwards. Do this if a search fails because the
6397 place you started was too far down in the file. Repeated `C-r' keeps
6398 looking for more occurrences backwards. `C-s' starts going forward
6399 again. You can cancel `C-r' in a search with <DEL>.
6401 The characters `C-y' and `C-w' can be used in incremental search to
6402 grab text from the buffer into the search string. This makes it
6403 convenient to search for another occurrence of text at point. `C-w'
6404 copies the word after point as part of the search string, advancing
6405 point over that word. Another `C-s' to repeat the search will then
6406 search for a string including that word. `C-y' is similar to `C-w' but
6407 copies the rest of the current line into the search string.
6409 The characters `M-p' and `M-n' can be used in an incremental search
6410 to recall things which you have searched for in the past. A list of
6411 the last 16 things you have searched for is retained, and `M-p' and
6412 `M-n' let you cycle through that ring.
6414 The character `M-<TAB>' does completion on the elements in the
6415 search history ring. For example, if you know that you have recently
6416 searched for the string `POTATOE', you could type `C-s P O M-<TAB>'.
6417 If you had searched for other strings beginning with `PO' then you
6418 would be shown a list of them, and would need to type more to select
6421 You can change any of the special characters in incremental search
6422 via the normal keybinding mechanism: simply add a binding to the
6423 `isearch-mode-map'. For example, to make the character `C-b' mean
6424 "search backwards" while in isearch-mode, do this:
6426 (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
6428 These are the default bindings of isearch-mode:
6431 Delete a character from the incremental search string
6432 (`isearch-delete-char').
6435 Exit incremental search (`isearch-exit').
6438 Quote special characters for incremental search
6439 (`isearch-quote-char').
6442 Repeat incremental search forward (`isearch-repeat-forward').
6445 Repeat incremental search backward (`isearch-repeat-backward').
6448 Pull rest of line from buffer into search string
6449 (`isearch-yank-line').
6452 Pull next word from buffer into search string
6453 (`isearch-yank-word').
6456 Cancels input back to what has been found successfully, or aborts
6457 the isearch (`isearch-abort').
6460 Recall the previous element in the isearch history ring
6461 (`isearch-ring-retreat').
6464 Recall the next element in the isearch history ring
6465 (`isearch-ring-advance').
6468 Do completion on the elements in the isearch history ring
6469 (`isearch-complete').
6472 Any other character which is normally inserted into a buffer when
6473 typed is automatically added to the search string in isearch-mode.
6475 Slow Terminal Incremental Search
6476 --------------------------------
6478 Incremental search on a slow terminal uses a modified style of display
6479 that is designed to take less time. Instead of redisplaying the buffer
6480 at each place the search gets to, it creates a new single-line window
6481 and uses that to display the line the search has found. The
6482 single-line window appears as soon as point gets outside of the text
6483 that is already on the screen.
6485 When the search is terminated, the single-line window is removed.
6486 Only at this time the window in which the search was done is
6487 redisplayed to show its new value of point.
6489 The three dots at the end of the search string, normally used to
6490 indicate that searching is going on, are not displayed in slow style
6493 The slow terminal style of display is used when the terminal baud
6494 rate is less than or equal to the value of the variable
6495 `search-slow-speed', initially 1200.
6497 The number of lines to use in slow terminal search display is
6498 controlled by the variable `search-slow-window-lines'. Its normal
6502 File: xemacs.info, Node: Non-Incremental Search, Next: Word Search, Prev: Incremental Search, Up: Search
6504 Non-Incremental Search
6505 ======================
6507 Emacs also has conventional non-incremental search commands, which
6508 require you type the entire search string before searching begins.
6510 `C-s <RET> STRING <RET>'
6513 `C-r <RET> STRING <RET>'
6514 Search backward for STRING.
6516 To do a non-incremental search, first type `C-s <RET>' (or `C-s
6517 C-m'). This enters the minibuffer to read the search string.
6518 Terminate the string with <RET> to start the search. If the string is
6519 not found, the search command gets an error.
6521 By default, `C-s' invokes incremental search, but if you give it an
6522 empty argument, which would otherwise be useless, it invokes
6523 non-incremental search. Therefore, `C-s <RET>' invokes non-incremental
6524 search. `C-r <RET>' also works this way.
6526 Forward and backward non-incremental searches are implemented by the
6527 commands `search-forward' and `search-backward'. You can bind these
6528 commands to keys. The reason that incremental search is programmed to
6529 invoke them as well is that `C-s <RET>' is the traditional sequence of
6530 characters used in Emacs to invoke non-incremental search.
6532 Non-incremental searches performed using `C-s <RET>' do not call
6533 `search-forward' right away. They first check if the next character is
6534 `C-w', which requests a word search. *Note Word Search::.
6537 File: xemacs.info, Node: Word Search, Next: Regexp Search, Prev: Non-Incremental Search, Up: Search
6542 Word search looks for a sequence of words without regard to how the
6543 words are separated. More precisely, you type a string of many words,
6544 using single spaces to separate them, and the string is found even if
6545 there are multiple spaces, newlines or other punctuation between the
6548 Word search is useful in editing documents formatted by text
6549 formatters. If you edit while looking at the printed, formatted
6550 version, you can't tell where the line breaks are in the source file.
6551 Word search, allows you to search without having to know the line
6554 `C-s <RET> C-w WORDS <RET>'
6555 Search for WORDS, ignoring differences in punctuation.
6557 `C-r <RET> C-w WORDS <RET>'
6558 Search backward for WORDS, ignoring differences in punctuation.
6560 Word search is a special case of non-incremental search. It is
6561 invoked with `C-s <RET> C-w' followed by the search string, which must
6562 always be terminated with another <RET>. Being non-incremental, this
6563 search does not start until the argument is terminated. It works by
6564 constructing a regular expression and searching for that. *Note Regexp
6567 You can do a backward word search with `C-r <RET> C-w'.
6569 Forward and backward word searches are implemented by the commands
6570 `word-search-forward' and `word-search-backward'. You can bind these
6571 commands to keys. The reason that incremental search is programmed to
6572 invoke them as well is that `C-s <RET> C-w' is the traditional Emacs
6573 sequence of keys for word search.
6576 File: xemacs.info, Node: Regexp Search, Next: Regexps, Prev: Word Search, Up: Search
6578 Regular Expression Search
6579 =========================
6581 A "regular expression" ("regexp", for short) is a pattern that denotes
6582 a (possibly infinite) set of strings. Searching for matches for a
6583 regexp is a powerful operation that editors on Unix systems have
6584 traditionally offered.
6586 To gain a thorough understanding of regular expressions and how to
6587 use them to best advantage, we recommend that you study `Mastering
6588 Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
6589 1997'. (It's known as the "Hip Owls" book, because of the picture on its
6590 cover.) You might also read the manuals to *Note (gawk)Top::, *Note
6591 (ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
6592 (rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
6593 regular expressions.
6595 The XEmacs regular expression syntax most closely resembles that of
6596 `ed', or `grep', the GNU versions of which all utilize the GNU `regex'
6597 library. XEmacs' version of `regex' has recently been extended with
6598 some Perl-like capabilities, described in the next section.
6600 In XEmacs, you can search for the next match for a regexp either
6601 incrementally or not.
6603 Incremental search for a regexp is done by typing `M-C-s'
6604 (`isearch-forward-regexp'). This command reads a search string
6605 incrementally just like `C-s', but it treats the search string as a
6606 regexp rather than looking for an exact match against the text in the
6607 buffer. Each time you add text to the search string, you make the
6608 regexp longer, and the new regexp is searched for. A reverse regexp
6609 search command `isearch-backward-regexp' also exists, bound to `M-C-r'.
6611 All of the control characters that do special things within an
6612 ordinary incremental search have the same functionality in incremental
6613 regexp search. Typing `C-s' or `C-r' immediately after starting a
6614 search retrieves the last incremental search regexp used: incremental
6615 regexp and non-regexp searches have independent defaults.
6617 Non-incremental search for a regexp is done by the functions
6618 `re-search-forward' and `re-search-backward'. You can invoke them with
6619 `M-x' or bind them to keys. You can also call `re-search-forward' by
6620 way of incremental regexp search with `M-C-s <RET>'; similarly for
6621 `re-search-backward' with `M-C-r <RET>'.
6624 File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search
6626 Syntax of Regular Expressions
6627 =============================
6629 Regular expressions have a syntax in which a few characters are special
6630 constructs and the rest are "ordinary". An ordinary character is a
6631 simple regular expression that matches that character and nothing else.
6632 The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and
6633 `\'; no new special characters will be defined in the future. Any
6634 other character appearing in a regular expression is ordinary, unless a
6637 For example, `f' is not a special character, so it is ordinary, and
6638 therefore `f' is a regular expression that matches the string `f' and
6639 no other string. (It does _not_ match the string `ff'.) Likewise, `o'
6640 is a regular expression that matches only `o'.
6642 Any two regular expressions A and B can be concatenated. The result
6643 is a regular expression that matches a string if A matches some amount
6644 of the beginning of that string and B matches the rest of the string.
6646 As a simple example, we can concatenate the regular expressions `f'
6647 and `o' to get the regular expression `fo', which matches only the
6648 string `fo'. Still trivial. To do something more powerful, you need
6649 to use one of the special characters. Here is a list of them:
6652 is a special character that matches any single character except a
6653 newline. Using concatenation, we can make regular expressions
6654 like `a.b', which matches any three-character string that begins
6655 with `a' and ends with `b'.
6658 is not a construct by itself; it is a quantifying suffix operator
6659 that means to repeat the preceding regular expression as many
6660 times as possible. In `fo*', the `*' applies to the `o', so `fo*'
6661 matches one `f' followed by any number of `o's. The case of zero
6662 `o's is allowed: `fo*' does match `f'.
6664 `*' always applies to the _smallest_ possible preceding
6665 expression. Thus, `fo*' has a repeating `o', not a repeating `fo'.
6667 The matcher processes a `*' construct by matching, immediately, as
6668 many repetitions as can be found; it is "greedy". Then it
6669 continues with the rest of the pattern. If that fails,
6670 backtracking occurs, discarding some of the matches of the
6671 `*'-modified construct in case that makes it possible to match the
6672 rest of the pattern. For example, in matching `ca*ar' against the
6673 string `caaar', the `a*' first tries to match all three `a's; but
6674 the rest of the pattern is `ar' and there is only `r' left to
6675 match, so this try fails. The next alternative is for `a*' to
6676 match only two `a's. With this choice, the rest of the regexp
6677 matches successfully.
6679 Nested repetition operators can be extremely slow if they specify
6680 backtracking loops. For example, it could take hours for the
6681 regular expression `\(x+y*\)*a' to match the sequence
6682 `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because
6683 Emacs must try each imaginable way of grouping the 35 `x''s before
6684 concluding that none of them can work. To make sure your regular
6685 expressions run fast, check nested repetitions carefully.
6688 is a quantifying suffix operator similar to `*' except that the
6689 preceding expression must match at least once. It is also
6690 "greedy". So, for example, `ca+r' matches the strings `car' and
6691 `caaaar' but not the string `cr', whereas `ca*r' matches all three
6695 is a quantifying suffix operator similar to `*', except that the
6696 preceding expression can match either once or not at all. For
6697 example, `ca?r' matches `car' or `cr', but does not match anything
6701 works just like `*', except that rather than matching the longest
6702 match, it matches the shortest match. `*?' is known as a
6703 "non-greedy" quantifier, a regexp construct borrowed from Perl.
6705 This construct is very useful for when you want to match the text
6706 inside a pair of delimiters. For instance, `/\*.*?\*/' will match
6707 C comments in a string. This could not easily be achieved without
6708 the use of a non-greedy quantifier.
6710 This construct has not been available prior to XEmacs 20.4. It is
6711 not available in FSF Emacs.
6714 is the non-greedy version of `+'.
6717 is the non-greedy version of `?'.
6720 serves as an interval quantifier, analogous to `*' or `+', but
6721 specifies that the expression must match at least N times, but no
6722 more than M times. This syntax is supported by most Unix regexp
6723 utilities, and has been introduced to XEmacs for the version 20.3.
6725 Unfortunately, the non-greedy version of this quantifier does not
6726 exist currently, although it does in Perl.
6729 `[' begins a "character set", which is terminated by a `]'. In
6730 the simplest case, the characters between the two brackets form
6731 the set. Thus, `[ad]' matches either one `a' or one `d', and
6732 `[ad]*' matches any string composed of just `a's and `d's
6733 (including the empty string), from which it follows that `c[ad]*r'
6734 matches `cr', `car', `cdr', `caddaar', etc.
6736 The usual regular expression special characters are not special
6737 inside a character set. A completely different set of special
6738 characters exists inside character sets: `]', `-' and `^'.
6740 `-' is used for ranges of characters. To write a range, write two
6741 characters with a `-' between them. Thus, `[a-z]' matches any
6742 lower case letter. Ranges may be intermixed freely with individual
6743 characters, as in `[a-z$%.]', which matches any lower case letter
6744 or `$', `%', or a period.
6746 To include a `]' in a character set, make it the first character.
6747 For example, `[]a]' matches `]' or `a'. To include a `-', write
6748 `-' as the first character in the set, or put it immediately after
6749 a range. (You can replace one individual character C with the
6750 range `C-C' to make a place to put the `-'.) There is no way to
6751 write a set containing just `-' and `]'.
6753 To include `^' in a set, put it anywhere but at the beginning of
6757 `[^' begins a "complement character set", which matches any
6758 character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
6759 all characters _except_ letters and digits.
6761 `^' is not special in a character set unless it is the first
6762 character. The character following the `^' is treated as if it
6763 were first (thus, `-' and `]' are not special there).
6765 Note that a complement character set can match a newline, unless
6766 newline is mentioned as one of the characters not to match.
6769 is a special character that matches the empty string, but only at
6770 the beginning of a line in the text being matched. Otherwise it
6771 fails to match anything. Thus, `^foo' matches a `foo' that occurs
6772 at the beginning of a line.
6774 When matching a string instead of a buffer, `^' matches at the
6775 beginning of the string or after a newline character `\n'.
6778 is similar to `^' but matches only at the end of a line. Thus,
6779 `x+$' matches a string of one `x' or more at the end of a line.
6781 When matching a string instead of a buffer, `$' matches at the end
6782 of the string or before a newline character `\n'.
6785 has two functions: it quotes the special characters (including
6786 `\'), and it introduces additional special constructs.
6788 Because `\' quotes special characters, `\$' is a regular
6789 expression that matches only `$', and `\[' is a regular expression
6790 that matches only `[', and so on.
6793 *Please note:* For historical compatibility, special characters are
6794 treated as ordinary ones if they are in contexts where their special
6795 meanings make no sense. For example, `*foo' treats `*' as ordinary
6796 since there is no preceding expression on which the `*' can act. It is
6797 poor practice to depend on this behavior; quote the special character
6798 anyway, regardless of where it appears.
6800 For the most part, `\' followed by any character matches only that
6801 character. However, there are several exceptions: characters that,
6802 when preceded by `\', are special constructs. Such characters are
6803 always ordinary when encountered on their own. Here is a table of `\'
6807 specifies an alternative. Two regular expressions A and B with
6808 `\|' in between form an expression that matches anything that
6809 either A or B matches.
6811 Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
6813 `\|' applies to the largest possible surrounding expressions.
6814 Only a surrounding `\( ... \)' grouping can limit the grouping
6817 Full backtracking capability exists to handle multiple uses of
6821 is a grouping construct that serves three purposes:
6823 1. To enclose a set of `\|' alternatives for other operations.
6824 Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
6826 2. To enclose an expression for a suffix operator such as `*' to
6827 act on. Thus, `ba\(na\)*' matches `bananana', etc., with any
6828 (zero or more) number of `na' strings.
6830 3. To record a matched substring for future reference.
6832 This last application is not a consequence of the idea of a
6833 parenthetical grouping; it is a separate feature that happens to be
6834 assigned as a second meaning to the same `\( ... \)' construct
6835 because there is no conflict in practice between the two meanings.
6836 Here is an explanation of this feature:
6839 matches the same text that matched the DIGITth occurrence of a `\(
6842 In other words, after the end of a `\( ... \)' construct. the
6843 matcher remembers the beginning and end of the text matched by that
6844 construct. Then, later on in the regular expression, you can use
6845 `\' followed by DIGIT to match that same text, whatever it may
6848 The strings matching the first nine `\( ... \)' constructs
6849 appearing in a regular expression are assigned numbers 1 through 9
6850 in the order that the open parentheses appear in the regular
6851 expression. So you can use `\1' through `\9' to refer to the text
6852 matched by the corresponding `\( ... \)' constructs.
6854 For example, `\(.*\)\1' matches any newline-free string that is
6855 composed of two identical halves. The `\(.*\)' matches the first
6856 half, which may be anything, but the `\1' that follows must match
6857 the same exact text.
6860 is called a "shy" grouping operator, and it is used just like `\(
6861 ... \)', except that it does not cause the matched substring to be
6862 recorded for future reference.
6864 This is useful when you need a lot of grouping `\( ... \)'
6865 constructs, but only want to remember one or two - or if you have
6866 more than nine groupings and need to use backreferences to refer to
6867 the groupings at the end.
6869 Using `\(?: ... \)' rather than `\( ... \)' when you don't need
6870 the captured substrings ought to speed up your programs some,
6871 since it shortens the code path followed by the regular expression
6872 engine, as well as the amount of memory allocation and string
6873 copying it must do. The actual performance gain to be observed
6874 has not been measured or quantified as of this writing.
6876 The shy grouping operator has been borrowed from Perl, and has not
6877 been available prior to XEmacs 20.3, nor is it available in FSF
6881 matches any word-constituent character. The editor syntax table
6882 determines which characters these are. *Note Syntax::.
6885 matches any character that is not a word constituent.
6888 matches any character whose syntax is CODE. Here CODE is a
6889 character that represents a syntax code: thus, `w' for word
6890 constituent, `-' for whitespace, `(' for open parenthesis, etc.
6891 *Note Syntax::, for a list of syntax codes and the characters that
6895 matches any character whose syntax is not CODE.
6897 The following regular expression constructs match the empty
6898 string--that is, they don't use up any characters--but whether they
6899 match depends on the context.
6902 matches the empty string, but only at the beginning of the buffer
6903 or string being matched against.
6906 matches the empty string, but only at the end of the buffer or
6907 string being matched against.
6910 matches the empty string, but only at point. (This construct is
6911 not defined when matching against a string.)
6914 matches the empty string, but only at the beginning or end of a
6915 word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
6916 separate word. `\bballs?\b' matches `ball' or `balls' as a
6920 matches the empty string, but _not_ at the beginning or end of a
6924 matches the empty string, but only at the beginning of a word.
6927 matches the empty string, but only at the end of a word.
6929 Here is a complicated regexp used by Emacs to recognize the end of a
6930 sentence together with any whitespace that follows. It is given in Lisp
6931 syntax to enable you to distinguish the spaces from the tab characters.
6932 In Lisp syntax, the string constant begins and ends with a
6933 double-quote. `\"' stands for a double-quote as part of the regexp,
6934 `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for
6937 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
6939 This regexp contains four parts: a character set matching period, `?'
6940 or `!'; a character set matching close-brackets, quotes or parentheses,
6941 repeated any number of times; an alternative in backslash-parentheses
6942 that matches end-of-line, a tab or two spaces; and a character set
6943 matching whitespace characters, repeated any number of times.
6946 File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search
6951 All searches in Emacs normally ignore the case of the text they are
6952 searching through; if you specify searching for `FOO', `Foo' and `foo'
6953 are also considered a match. Regexps, and in particular character
6954 sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
6956 If you want a case-sensitive search, set the variable
6957 `case-fold-search' to `nil'. Then all letters must match exactly,
6958 including case. `case-fold-search' is a per-buffer variable; altering
6959 it affects only the current buffer, but there is a default value which
6960 you can change as well. *Note Locals::. You can also use Case
6961 Sensitive Search from the Options menu on your screen.
6964 File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search
6966 Replacement Commands
6967 ====================
6969 Global search-and-replace operations are not needed as often in Emacs as
6970 they are in other editors, but they are available. In addition to the
6971 simple `replace-string' command which is like that found in most
6972 editors, there is a `query-replace' command which asks you, for each
6973 occurrence of a pattern, whether to replace it.
6975 The replace commands all replace one string (or regexp) with one
6976 replacement string. It is possible to perform several replacements in
6977 parallel using the command `expand-region-abbrevs'. *Note Expanding
6982 * Unconditional Replace:: Replacing all matches for a string.
6983 * Regexp Replace:: Replacing all matches for a regexp.
6984 * Replacement and Case:: How replacements preserve case of letters.
6985 * Query Replace:: How to use querying.
6988 File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace
6990 Unconditional Replacement
6991 -------------------------
6993 `M-x replace-string <RET> STRING <RET> NEWSTRING <RET>'
6994 Replace every occurrence of STRING with NEWSTRING.
6996 `M-x replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
6997 Replace every match for REGEXP with NEWSTRING.
6999 To replace every instance of `foo' after point with `bar', use the
7000 command `M-x replace-string' with the two arguments `foo' and `bar'.
7001 Replacement occurs only after point: if you want to cover the whole
7002 buffer you must go to the beginning first. By default, all occurrences
7003 up to the end of the buffer are replaced. To limit replacement to part
7004 of the buffer, narrow to that part of the buffer before doing the
7005 replacement (*note Narrowing::).
7007 When `replace-string' exits, point is left at the last occurrence
7008 replaced. The value of point when the `replace-string' command was
7009 issued is remembered on the mark ring; `C-u C-<SPC>' moves back there.
7011 A numeric argument restricts replacement to matches that are
7012 surrounded by word boundaries.
7015 File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace
7020 `replace-string' replaces exact matches for a single string. The
7021 similar command `replace-regexp' replaces any match for a specified
7024 In `replace-regexp', the NEWSTRING need not be constant. It can
7025 refer to all or part of what is matched by the REGEXP. `\&' in
7026 NEWSTRING stands for the entire text being replaced. `\D' in
7027 NEWSTRING, where D is a digit, stands for whatever matched the D'th
7028 parenthesized grouping in REGEXP. For example,
7030 M-x replace-regexp <RET> c[ad]+r <RET> \&-safe <RET>
7032 would replace (for example) `cadr' with `cadr-safe' and `cddr' with
7035 M-x replace-regexp <RET> \(c[ad]+r\)-safe <RET> \1 <RET>
7037 would perform exactly the opposite replacements. To include a `\' in
7038 the text to replace with, you must give `\\'.