1 This is ../info/xemacs.info, produced by makeinfo version 4.8 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 * CC Mode:: Modes for C, C++, Java and similar languages
405 * Fortran:: Fortran mode and its special features.
406 * Asm Mode:: Asm mode and its special features.
408 Indentation for Programs
411 * Multi-line Indent:: Commands to reindent many lines at once.
412 * Lisp Indent:: Specifying how each Lisp function should be indented.
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
554 Copyright (C) 1989 Free Software Foundation, Inc.
555 675 Mass Ave, Cambridge, MA 02139, USA
557 Everyone is permitted to copy and distribute verbatim copies
558 of this license document, but changing it is not allowed.
563 The license agreements of most software companies try to keep users at
564 the mercy of those companies. By contrast, our General Public License
565 is intended to guarantee your freedom to share and change free
566 software--to make sure the software is free for all its users. The
567 General Public License applies to the Free Software Foundation's
568 software and to any other program whose authors commit to using it.
569 You can use it for your programs, too.
571 When we speak of free software, we are referring to freedom, not
572 price. Specifically, the General Public License is designed to make
573 sure that you have the freedom to give away or sell copies of free
574 software, that you receive source code or can get it if you want it,
575 that you can change the software or use pieces of it in new free
576 programs; and that you know you can do these things.
578 To protect your rights, we need to make restrictions that forbid
579 anyone to deny you these rights or to ask you to surrender the rights.
580 These restrictions translate to certain responsibilities for you if you
581 distribute copies of the software, or if you modify it.
583 For example, if you distribute copies of a such a program, whether
584 gratis or for a fee, you must give the recipients all the rights that
585 you have. You must make sure that they, too, receive or can get the
586 source code. And you must tell them their rights.
588 We protect your rights with two steps: (1) copyright the software,
589 and (2) offer you this license which gives you legal permission to copy,
590 distribute and/or modify the software.
592 Also, for each author's protection and ours, we want to make certain
593 that everyone understands that there is no warranty for this free
594 software. If the software is modified by someone else and passed on, we
595 want its recipients to know that what they have is not the original, so
596 that any problems introduced by others will not reflect on the original
597 authors' reputations.
599 The precise terms and conditions for copying, distribution and
603 1. This License Agreement applies to any program or other work which
604 contains a notice placed by the copyright holder saying it may be
605 distributed under the terms of this General Public License. The
606 "Program", below, refers to any such program or work, and a "work
607 based on the Program" means either the Program or any work
608 containing the Program or a portion of it, either verbatim or with
609 modifications. Each licensee is addressed as "you".
611 2. You may copy and distribute verbatim copies of the Program's source
612 code as you receive it, in any medium, provided that you
613 conspicuously and appropriately publish on each copy an
614 appropriate copyright notice and disclaimer of warranty; keep
615 intact all the notices that refer to this General Public License
616 and to the absence of any warranty; and give any other recipients
617 of the Program a copy of this General Public License along with
618 the Program. You may charge a fee for the physical act of
621 3. You may modify your copy or copies of the Program or any portion of
622 it, and copy and distribute such modifications under the terms of
623 Paragraph 1 above, provided that you also do the following:
625 * cause the modified files to carry prominent notices stating
626 that you changed the files and the date of any change; and
628 * cause the whole of any work that you distribute or publish,
629 that in whole or in part contains the Program or any part
630 thereof, either with or without modifications, to be licensed
631 at no charge to all third parties under the terms of this
632 General Public License (except that you may choose to grant
633 warranty protection to some or all third parties, at your
636 * If the modified program normally reads commands interactively
637 when run, you must cause it, when started running for such
638 interactive use in the simplest and most usual way, to print
639 or display an announcement including an appropriate copyright
640 notice and a notice that there is no warranty (or else,
641 saying that you provide a warranty) and that users may
642 redistribute the program under these conditions, and telling
643 the user how to view a copy of this General Public License.
645 * You may charge a fee for the physical act of transferring a
646 copy, and you may at your option offer warranty protection in
649 Mere aggregation of another independent work with the Program (or
650 its derivative) on a volume of a storage or distribution medium
651 does not bring the other work under the scope of these terms.
653 4. You may copy and distribute the Program (or a portion or
654 derivative of it, under Paragraph 2) in object code or executable
655 form under the terms of Paragraphs 1 and 2 above provided that you
656 also do one of the following:
658 * accompany it with the complete corresponding machine-readable
659 source code, which must be distributed under the terms of
660 Paragraphs 1 and 2 above; or,
662 * accompany it with a written offer, valid for at least three
663 years, to give any third party free (except for a nominal
664 charge for the cost of distribution) a complete
665 machine-readable copy of the corresponding source code, to be
666 distributed under the terms of Paragraphs 1 and 2 above; or,
668 * accompany it with the information you received as to where the
669 corresponding source code may be obtained. (This alternative
670 is allowed only for noncommercial distribution and only if you
671 received the program in object code or executable form alone.)
673 Source code for a work means the preferred form of the work for
674 making modifications to it. For an executable file, complete
675 source code means all the source code for all modules it contains;
676 but, as a special exception, it need not include source code for
677 modules which are standard libraries that accompany the operating
678 system on which the executable file runs, or for standard header
679 files or definitions files that accompany that operating system.
681 5. You may not copy, modify, sublicense, distribute or transfer the
682 Program except as expressly provided under this General Public
683 License. Any attempt otherwise to copy, modify, sublicense,
684 distribute or transfer the Program is void, and will automatically
685 terminate your rights to use the Program under this License.
686 However, parties who have received copies, or rights to use
687 copies, from you under this General Public License will not have
688 their licenses terminated so long as such parties remain in full
691 6. By copying, distributing or modifying the Program (or any work
692 based on the Program) you indicate your acceptance of this license
693 to do so, and all its terms and conditions.
695 7. Each time you redistribute the Program (or any work based on the
696 Program), the recipient automatically receives a license from the
697 original licensor to copy, distribute or modify the Program
698 subject to these terms and conditions. You may not impose any
699 further restrictions on the recipients' exercise of the rights
702 8. The Free Software Foundation may publish revised and/or new
703 versions of the General Public License from time to time. Such
704 new versions will be similar in spirit to the present version, but
705 may differ in detail to address new problems or concerns.
707 Each version is given a distinguishing version number. If the
708 Program specifies a version number of the license which applies to
709 it and "any later version", you have the option of following the
710 terms and conditions either of that version or of any later
711 version published by the Free Software Foundation. If the Program
712 does not specify a version number of the license, you may choose
713 any version ever published by the Free Software Foundation.
715 9. If you wish to incorporate parts of the Program into other free
716 programs whose distribution conditions are different, write to the
717 author to ask for permission. For software which is copyrighted
718 by the Free Software Foundation, write to the Free Software
719 Foundation; we sometimes make exceptions for this. Our decision
720 will be guided by the two goals of preserving the free status of
721 all derivatives of our free software and of promoting the sharing
722 and reuse of software generally.
725 10. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
726 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
727 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
728 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
729 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
730 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
731 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
732 QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
733 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
734 SERVICING, REPAIR OR CORRECTION.
736 11. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
737 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
738 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
739 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
740 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
741 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
742 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
743 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
744 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
745 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
747 END OF TERMS AND CONDITIONS
748 Appendix: How to Apply These Terms to Your New Programs
749 =======================================================
751 If you develop a new program, and you want it to be of the greatest
752 possible use to humanity, the best way to achieve this is to make it
753 free software which everyone can redistribute and change under these
756 To do so, attach the following notices to the program. It is safest
757 to attach them to the start of each source file to most effectively
758 convey the exclusion of warranty; and each file should have at least the
759 "copyright" line and a pointer to where the full notice is found.
761 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
762 Copyright (C) 19YY NAME OF AUTHOR
764 This program is free software; you can redistribute it and/or modify
765 it under the terms of the GNU General Public License as published by
766 the Free Software Foundation; either version 1, or (at your option)
769 This program is distributed in the hope that it will be useful,
770 but WITHOUT ANY WARRANTY; without even the implied warranty of
771 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
772 GNU General Public License for more details.
774 You should have received a copy of the GNU General Public License
775 along with this program; if not, write to the Free Software
776 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
778 Also add information on how to contact you by electronic and paper
781 If the program is interactive, make it output a short notice like
782 this when it starts in an interactive mode:
784 Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
785 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
786 This is free software, and you are welcome to redistribute it
787 under certain conditions; type `show c' for details.
789 The hypothetical commands `show w' and `show c' should show the
790 appropriate parts of the General Public License. Of course, the
791 commands you use may be called something other than `show w' and `show
792 c'; they could even be mouse-clicks or menu items--whatever suits your
795 You should also get your employer (if you work as a programmer) or
796 your school, if any, to sign a "copyright disclaimer" for the program,
797 if necessary. Here a sample; alter the names:
799 Yoyodyne, Inc., hereby disclaims all copyright interest in the
800 program `Gnomovision' (a program to direct compilers to make passes
801 at assemblers) written by James Hacker.
803 SIGNATURE OF TY COON, 1 April 1989
804 Ty Coon, President of Vice
806 That's all there is to it!
809 File: xemacs.info, Node: Distrib, Next: Intro, Prev: License, Up: Top
814 XEmacs is "free"; this means that everyone is free to use it and free
815 to redistribute it on a free basis. XEmacs is not in the public
816 domain; it is copyrighted and there are restrictions on its
817 distribution, but these restrictions are designed to permit everything
818 that a good cooperating citizen would want to do. What is not allowed
819 is to try to prevent others from further sharing any version of XEmacs
820 that they might get from you. The precise conditions are found in the
821 GNU General Public License that comes with XEmacs and also appears
822 following this section.
824 The easiest way to get a copy of XEmacs is from someone else who has
825 it. You need not ask for permission to do so, or tell any one else;
828 If you have access to the Internet, you can get the latest version of
829 XEmacs from the anonymous FTP server `ftp.xemacs.org' in the directory
830 `/pub/xemacs'. It can also be found at numerous other archive sites
831 around the world; check the file `etc/DISTRIB' in an XEmacs
832 distribution for the latest known list.
834 Getting Other Versions of Emacs
835 ===============================
837 The Free Software Foundation's version of Emacs (called "FSF Emacs" in
838 this manual and often referred to as "GNU Emacs") is available by
839 anonymous FTP from `prep.ai.mit.edu'.
841 Win-Emacs, an older version of XEmacs that runs on Microsoft Windows
842 and Windows NT, is available by anonymous FTP from `ftp.netcom.com' in
843 the directory `/pub/pe/pearl', or from `ftp.cica.indiana.edu' as the
844 files `wemdemo*.zip' in the directory `/pub/pc/win3/demo'.
847 File: xemacs.info, Node: Intro, Next: Glossary, Prev: Distrib, Up: Top
852 You are reading about XEmacs, an incarnation of the advanced,
853 self-documenting, customizable, extensible real-time display editor
854 Emacs. XEmacs provides many powerful display and user-interface
855 capabilities not found in other Emacsen and is mostly upwardly
856 compatible with GNU Emacs from the Free Software Foundation (referred
857 to as "FSF Emacs" in this manual). XEmacs also comes standard with a
858 great number of useful packages.
860 We say that XEmacs is a "display" editor because normally the text
861 being edited is visible on the screen and is updated automatically as
862 you type. *Note Display: Frame.
864 We call XEmacs a "real-time" editor because the display is updated
865 very frequently, usually after each character or pair of characters you
866 type. This minimizes the amount of information you must keep in your
867 head as you edit. *Note Real-time: Basic.
869 We call XEmacs advanced because it provides facilities that go beyond
870 simple insertion and deletion: filling of text; automatic indentation of
871 programs; viewing two or more files at once; and dealing in terms of
872 characters, words, lines, sentences, paragraphs, and pages, as well as
873 expressions and comments in several different programming languages.
874 It is much easier to type one command meaning "go to the end of the
875 paragraph" than to find that spot with simple cursor keys.
877 "Self-documenting" means that at any time you can type a special
878 character, `Control-h', to find out what your options are. You can
879 also use `C-h' to find out what a command does, or to find all the
880 commands relevant to a topic. *Note Help::.
882 "Customizable" means you can change the definitions of XEmacs
883 commands. For example, if you use a programming language in which
884 comments start with `<**' and end with `**>', you can tell the XEmacs
885 comment manipulation commands to use those strings (*note Comments::).
886 Another sort of customization is rearrangement of the command set. For
887 example, you can set up the four basic cursor motion commands (up,
888 down, left and right) on keys in a diamond pattern on the keyboard if
889 you prefer. *Note Customization::.
891 "Extensible" means you can go beyond simple customization and write
892 entirely new commands, programs in the Lisp language to be run by
893 XEmacs's own Lisp interpreter. XEmacs is an "on-line extensible"
894 system: it is divided into many functions that call each other. You can
895 redefine any function in the middle of an editing session and replace
896 any part of XEmacs without making a separate copy of all of XEmacs.
897 Most of the editing commands of XEmacs are written in Lisp; the few
898 exceptions could have been written in Lisp but are written in C for
899 efficiency. Only a programmer can write an extension to XEmacs, but
900 anybody can use it afterward.
903 File: xemacs.info, Node: Frame, Next: Keystrokes, Prev: Concept Index, Up: Top
909 In many environments, such as a tty terminal, an XEmacs frame
910 literally takes up the whole screen. If you are running XEmacs in
911 a multi-window system like the X Window System, the XEmacs frame
912 takes up one X window. *Note XEmacs under X::, for more
916 No matter what environment you are running in, XEmacs allows you
917 to look at several buffers at the same time by having several
918 windows be part of the frame. Often, the whole frame is taken up
919 by just one window, but you can split the frame into two or more
920 subwindows. If you are running XEmacs under the X window system,
921 that means you can have several "XEmacs windows" inside the X
922 window that contains the XEmacs frame. You can even have multiple
923 frames in different X windows, each with their own set of
927 Each XEmacs frame displays a variety of information:
928 * The biggest area usually displays the text you are editing. It may
929 consist of one window or of two or more windows if you need to
930 look at two buffers a the same time.
932 * Below each text window's last line is a "mode line" (*note Mode
933 Line::), which describes what is going on in that window. The
934 mode line is in inverse video if the terminal supports that. If
935 there are several XEmacs windows in one frame, each window has its
938 * At the bottom of each XEmacs frame is the "echo area" or
939 "minibuffer window"(*note Echo Area::). It is used by XEmacs to
940 exchange information with the user. There is only one echo area
943 * If you are running XEmacs under a graphical windowing system, a
944 menu bar at the top of the frame makes shortcuts to several of the
945 commands available (*note Pull-down Menus::).
947 * Under a graphical windowing system, a toolbar at the top of the
948 frame, just under the menu bar if it exists, provides "one-touch"
949 shortcuts to several commands. (Not yet documented.)
951 * Under a graphical windowing system, a gutter at the top (under the
952 toolbar) and/or bottom of the frame provides advanced GUI
953 facilities like tab controls for rapid switching among related
954 windows and progress bars for time-consuming operations like
955 downloads across the Internet. Gutters are an experimental feature
956 introduced in XEmacs version 21.2. (Not yet documented.)
958 You can subdivide the XEmacs frame into multiple text windows, and
959 use each window for a different file (*note Windows::). Multiple XEmacs
960 windows are tiled vertically on the XEmacs frame. The upper XEmacs
961 window is separated from the lower window by its mode line.
963 When there are multiple, tiled XEmacs windows on a single XEmacs
964 frame, the XEmacs window receiving input from the keyboard has the
965 "keyboard focus" and is called the "selected window". The selected
966 window contains the cursor, which indicates the insertion point. If
967 you are working in an environment that permits multiple XEmacs frames,
968 and you move the focus from one XEmacs frame into another, the selected
969 window is the one that was last selected in that frame.
971 The same text can be displayed simultaneously in several XEmacs
972 windows, which can be in different XEmacs frames. If you alter the text
973 in an XEmacs buffer by editing it in one XEmacs window, the changes are
974 visible in all XEmacs windows containing that buffer.
978 * Point:: The place in the text where editing commands operate.
979 * Echo Area:: Short messages appear at the bottom of the frame.
980 * Mode Line:: Interpreting the mode line.
981 * GUI Components:: Menubar, toolbars, gutters.
982 * XEmacs under X:: Some information on using XEmacs under the X
984 * XEmacs under MS Windows:: Some information on using XEmacs under
988 File: xemacs.info, Node: Point, Next: Echo Area, Prev: Frame, Up: Frame
993 When XEmacs is running, the cursor shows the location at which editing
994 commands will take effect. This location is called "point". You can
995 use keystrokes or the mouse cursor to move point through the text and
996 edit the text at different places.
998 While the cursor appears to point AT a character, you should think
999 of point as BETWEEN two characters: it points BEFORE the character on
1000 which the cursor appears. The exception is at the end of the line,
1001 where the cursor appears after the last character of the line. Where
1002 the display is capable, the cursor at the end of the line will appear
1003 differently from a cursor over whitespace at the end of the line. (In
1004 an X Windows frame, the end-of-line cursor is half the width of a
1005 within-line cursor.) Sometimes people speak of "the cursor" when they
1006 mean "point," or speak of commands that move point as "cursor motion"
1009 Each XEmacs frame has only one cursor. When output is in progress,
1010 the cursor must appear where the typing is being done. This does not
1011 mean that point is moving. It is only that XEmacs has no way to show
1012 you the location of point except when the terminal is idle.
1014 If you are editing several files in XEmacs, each file has its own
1015 point location. A file that is not being displayed remembers where
1016 point is. Point becomes visible at the correct location when you look
1019 When there are multiple text windows, each window has its own point
1020 location. The cursor shows the location of point in the selected
1021 window. The visible cursor also shows you which window is selected. If
1022 the same buffer appears in more than one window, point can be moved in
1023 each window independently.
1025 The term `point' comes from the character `.', which was the command
1026 in TECO (the language in which the original Emacs was written) for
1027 accessing the value now called `point'.
1030 File: xemacs.info, Node: Echo Area, Next: Mode Line, Prev: Point, Up: Frame
1035 The line at the bottom of the frame (below the mode line) is the "echo
1036 area". XEmacs uses this area to communicate with the user:
1038 * "Echoing" means printing out the characters that the user types.
1039 XEmacs never echoes single-character commands. Multi-character
1040 commands are echoed only if you pause while typing them: As soon
1041 as you pause for more than one second in the middle of a command,
1042 all the characters of the command so far are echoed. This is
1043 intended to "prompt" you for the rest of the command. Once
1044 echoing has started, the rest of the command is echoed immediately
1045 as you type it. This behavior is designed to give confident users
1046 fast response, while giving hesitant users maximum feedback. You
1047 can change this behavior by setting a variable (*note Display
1050 * If you issue a command that cannot be executed, XEmacs may print
1051 an "error message" in the echo area. Error messages are
1052 accompanied by a beep or by flashing the frame. Any input you
1053 have typed ahead is thrown away when an error happens.
1055 * Some commands print informative messages in the echo area. These
1056 messages look similar to error messages, but are not announced
1057 with a beep and do not throw away input. Sometimes a message
1058 tells you what the command has done, when this is not obvious from
1059 looking at the text being edited. Sometimes the sole purpose of a
1060 command is to print a message giving you specific information.
1061 For example, the command `C-x =' is used to print a message
1062 describing the character position of point in the text and its
1063 current column in the window. Commands that take a long time
1064 often display messages ending in `...' while they are working, and
1065 add `done' at the end when they are finished.
1067 * The echo area is also used to display the "minibuffer", a window
1068 that is used for reading arguments to commands, such as the name
1069 of a file to be edited. When the minibuffer is in use, the echo
1070 area displays with a prompt string that usually ends with a colon.
1071 The cursor appears after the prompt. You can always get out of
1072 the minibuffer by typing `C-g'. *Note Minibuffer::.
1075 File: xemacs.info, Node: Mode Line, Next: GUI Components, Prev: Echo Area, Up: Frame
1080 Each text window's last line is a "mode line" which describes what is
1081 going on in that window. When there is only one text window, the mode
1082 line appears right above the echo area. The mode line is in inverse
1083 video if the terminal supports that, starts and ends with dashes, and
1084 contains text like `XEmacs: SOMETHING'.
1086 If a mode line has something else in place of `XEmacs: SOMETHING',
1087 the window above it is in a special subsystem such as Dired. The mode
1088 line then indicates the status of the subsystem.
1090 Normally, the mode line has the following appearance:
1092 --CH-XEmacs: BUF (MAJOR MINOR)----POS------
1094 This gives information about the buffer being displayed in the window:
1095 the buffer's name, what major and minor modes are in use, whether the
1096 buffer's text has been changed, and how far down the buffer you are
1099 CH contains two stars (`**') if the text in the buffer has been
1100 edited (the buffer is "modified"), or two dashes (`--') if the buffer
1101 has not been edited. Exception: for a read-only buffer, it is `%%'.
1103 BUF is the name of the window's chosen "buffer". The chosen buffer
1104 in the selected window (the window that the cursor is in) is also
1105 XEmacs's selected buffer, the buffer in which editing takes place. When
1106 we speak of what some command does to "the buffer", we mean the
1107 currently selected buffer. *Note Buffers::.
1109 POS tells you whether there is additional text above the top of the
1110 screen or below the bottom. If your file is small and it is completely
1111 visible on the screen, POS is `All'. Otherwise, POS is `Top' if you
1112 are looking at the beginning of the file, `Bot' if you are looking at
1113 the end of the file, or `NN%', where NN is the percentage of the file
1114 above the top of the screen.
1116 MAJOR is the name of the "major mode" in effect in the buffer. At
1117 any time, each buffer is in one and only one major mode. The available
1118 major modes include Fundamental mode (the least specialized), Text
1119 mode, Lisp mode, and C mode. *Note Major Modes::, for details on how
1120 the modes differ and how you select one.
1122 MINOR is a list of some of the "minor modes" that are turned on in
1123 the window's chosen buffer. For example, `Fill' means that Auto Fill
1124 mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means
1125 that Overwrite mode is on. *Note Minor Modes::, for more information.
1126 `Narrow' means that the buffer being displayed has editing restricted
1127 to only a portion of its text. This is not really a minor mode, but is
1128 like one. *Note Narrowing::. `Def' means that a keyboard macro is
1129 being defined. *Note Keyboard Macros::.
1131 Some buffers display additional information after the minor modes.
1132 For example, Rmail buffers display the current message number and the
1133 total number of messages. Compilation buffers and Shell mode display
1134 the status of the subprocess.
1136 If XEmacs is currently inside a recursive editing level, square
1137 brackets (`[...]') appear around the parentheses that surround the
1138 modes. If XEmacs is in one recursive editing level within another,
1139 double square brackets appear, and so on. Since information on
1140 recursive editing applies to XEmacs in general and not to any one
1141 buffer, the square brackets appear in every mode line on the screen or
1142 not in any of them. *Note Recursive Edit::.
1144 XEmacs can optionally display the time and system load in all mode
1145 lines. To enable this feature, type `M-x display-time'. The
1146 information added to the mode line usually appears after the file name,
1147 before the mode names and their parentheses. It looks like this:
1151 (Some fields may be missing if your operating system cannot support
1152 them.) HH and MM are the hour and minute, followed always by `am' or
1153 `pm'. L.LL is the average number of running processes in the whole
1154 system recently. D is an approximate index of the ratio of disk
1155 activity to CPU activity for all users.
1157 The word `Mail' appears after the load level if there is mail for
1158 you that you have not read yet.
1160 Customization note: the variable `mode-line-inverse-video' controls
1161 whether the mode line is displayed in inverse video (assuming the
1162 terminal supports it); `nil' means no inverse video. The default is
1163 `t'. For X frames, simply set the foreground and background colors
1167 File: xemacs.info, Node: GUI Components, Next: XEmacs under X, Prev: Mode Line, Up: Frame
1172 When executed in a graphical windowing environment such as the X Window
1173 System or Microsoft Windows, XEmacs displays several graphical user
1174 interface components such as scrollbars, menubars, toolbars, and
1175 gutters. By default there is a vertical scrollbar at the right of each
1176 frame, and at the top of the frame there is a menubar, a toolbar, and a
1177 gutter, in that order. Gutters can contain any of several widgets, but
1178 the default configuration puts a set of "notebook tabs" which you can
1179 use as a shortcut for selecting any of several related buffers in a
1180 given frame. Operating the GUI components is "obvious": click on the
1181 menubar to pull down a menu, on a button in the toolbar to invoke a
1182 function, and on a tab in the gutter to switch buffers.
1186 * Menubar Basics:: How XEmacs uses the menubar.
1187 * Scrollbar Basics:: How XEmacs uses scrollbars.
1188 * Mode Line Basics:: How XEmacs uses modelines.
1189 * Toolbar Basics:: How XEmacs uses toolbars.
1190 * Gutter Basics:: How XEmacs uses gutters.
1191 * Inhibiting:: What if you don't like GUI?
1192 * Customizing:: Position, orientation, and appearance of GUI objects.
1195 File: xemacs.info, Node: Menubar Basics, Next: Scrollbar Basics, Up: GUI Components
1197 1.5 The XEmacs Menubar
1198 ======================
1200 The XEmacs menubar is intended to be conformant to the usual conventions
1201 for menubars, although conformance is not yet perfect. The menu at the
1202 extreme right is the `Help' menu, which should always be available. It
1203 provides access to all the XEmacs help facilities available through
1204 `C-h', as well as samples of various configuration files like
1205 `~/.Xdefaults' and `~/.emacs'. At the extreme left is the `Files'
1206 menu, which provides the usual file reading, writing, and printing
1207 operations, as well as operations like revert buffer from most recent
1208 save. The next menu from the left is the `Edit' menu, which provides
1209 the `Undo' operation as well as cutting and pasting, searching, and
1210 keyboard macro definition and execution.
1212 XEmacs provides a very dynamic environment, and the Lisp language
1213 makes for highly flexible applications. The menubar reflects this:
1214 many menus (eg, the `Buffers' menu, *note Buffers Menu::) contain items
1215 determined by the current state of XEmacs, and most major modes and many
1216 minor modes add items to menus and even whole menus to the menubar. In
1217 fact, some applications like w3.el and VM provide so many menus that
1218 they define a whole new menubar and add a button that allows convenient
1219 switching between the "XEmacs menubar" and the "application menubar".
1220 Such applications normally bind themselves to a particular frame, and
1221 this switching only takes place on frames where such an application is
1222 active (ie, the current window of the frame is displaying a buffer in
1223 the appropriate major mode).
1225 Other menus which are typically available are the `Options',
1226 `Tools', `Buffers', `Apps', and `Mule' menus. For detailed
1227 descriptions of these menus, *Note Pull-down Menus::. (In 21.2
1228 XEmacsen, the `Mule' menu will be moved under `Options'.)
1231 File: xemacs.info, Node: Scrollbar Basics, Next: Mode Line Basics, Prev: Menubar Basics, Up: GUI Components
1233 1.6 XEmacs Scrollbars
1234 =====================
1236 XEmacs scrollbars provide the usual interface. Arrow buttons at either
1237 end allow for line by line scrolling, including autorepeat. Clicking in
1238 the scrollbar itself provides scrolling by windowsfull, depending on
1239 which side of the slider is clicked. The slider itself may be dragged
1240 for smooth scrolling.
1242 The position of the slider corresponds to the position of the window
1243 in the buffer. In particular, the length of the slider is proportional
1244 to the fraction of the buffer which appears in the window.
1246 The presence of the scrollbars is under control of the application or
1247 may be customized by the user. By default a vertical scrollbar is
1248 present in all windows (except the minibuffer), and there is no
1249 horizontal scrollbar.
1252 File: xemacs.info, Node: Mode Line Basics, Next: Toolbar Basics, Prev: Scrollbar Basics, Up: GUI Components
1254 1.7 XEmacs Mode Lines
1255 =====================
1257 When used in a windowing system, the XEmacs modelines can be dragged
1258 vertically. The effect is to resize the windows above and below the
1259 modeline (this includes the minibuffer window).
1261 Additionally, a modeline can be dragged horizontally, in which case
1262 it scrolls its own text. This behavior is not enabled by default
1263 because it could be considered as disturbing when dragging vertically.
1264 When this behavior is enabled, the modeline's text can be dragged
1265 either in the same direction as the mouse, or in the opposite sense,
1266 making the modeline act as a scrollbar for its own text.
1268 You can select the behavior you want from the `Display' submenu of
1272 File: xemacs.info, Node: Toolbar Basics, Next: Gutter Basics, Prev: Mode Line Basics, Up: GUI Components
1277 XEmacs has a default toolbar which provides shortcuts for some of the
1278 commonly used operations (such as opening files) and applications (such
1279 as the Info manual reader). Operations which require arguments will pop
1280 up dialogs to get them.
1282 The position of the default toolbar can be customized. Also, several
1283 toolbars may be present simultaneously (in different positions). VM,
1284 for example, provides an application toolbar which shortcuts for
1285 mail-specific operations like sending, saving, and deleting messages.
1288 File: xemacs.info, Node: Gutter Basics, Next: Inhibiting, Prev: Toolbar Basics, Up: GUI Components
1293 Gutters are the most flexible of the GUI components described in this
1294 section. In theory, the other GUI components could be implemented by
1295 customizing a gutter, but in practice the other components were
1296 introduced earlier and have their own special implementations. Gutters
1297 tend to be more transient than the other components. Buffer tabs, for
1298 example, change every time the selected buffer in the frame changes.
1299 And for progress gauges a gutter to contain the gauge is typically
1300 created on the fly when needed, then destroyed when the operation whose
1301 staus is being displayed is completed.
1303 Buffer tabs, having somewhat complex behavior, deserve a closer look.
1304 By default, a row of buffer tabs is displayed at the top of every frame.
1305 (The tabs could be placed in the bottom gutter, but would be oriented
1306 the same way and look rather odd. The horizontal orientation makes
1307 putting them in a side gutter utterly impractical.) The buffer
1308 displayed in the current window of a frame can be changed to a specific
1309 buffer by clicking [mouse-1] on the corresponding tab in the gutter.
1311 Each tab contains the name of its buffer. The tab for the current
1312 buffer in each frame is displayed in raised relief. The list of buffers
1313 chosen for display in the buffer tab row is derived by filtering the
1314 buffer list (like the `Buffers' menu). The list starts out with all
1315 existing buffers, with more recently selected buffers coming earlier in
1318 Then "uninteresting" buffers, like internal XEmacs buffers, the
1319 `*Message Log*' buffer, and so on are deleted from the list. Next, the
1320 frame's selected buffer is determined. Buffers with a different major
1321 mode from the selected buffer are removed from the list. Finally, if
1322 the list is too long, the least recently used buffers are deleted from
1323 the list. By default up to 6 most recently used buffers with the same
1324 mode are displayed on tabs in the gutter.
1326 This behavior can be altered by customizing
1327 `buffers-tab-filter-functions'. Setting this variable to `nil' forces
1328 display of all buffers, up to `buffers-tab-max-size' (also
1329 customizable). More complex behavior may be available in 3rd party
1330 libraries. These, and some more rarely customized options, are in the
1331 `buffers-tab' Customize group.
1334 File: xemacs.info, Node: Inhibiting, Next: Customizing, Prev: Gutter Basics, Up: GUI Components
1336 1.10 Inhibiting Display of GUI Components
1337 =========================================
1339 Use of GUI facilities is a personal thing. Almost everyone agrees that
1340 drawing via keyboard-based "turtle graphics" is acceptable to hardly
1341 anyone if a mouse is available, but conversely emulating a keyboard with
1342 a screenful of buttons is a painful experience. But between those
1343 extremes the complete novice will require a fair amount of time before
1344 toolbars and menus become dispensable, but many an "Ancien Haquer" sees
1345 them as a complete waste of precious frame space that could be filled
1348 Display of all of the GUI components created by XEmacs can be
1349 inhibited through the use of Customize. Customize can be accessed
1350 through `Options | Customize' in the menu bar, or via `M-x customize'.
1351 Then navigate through the Customize tree to `Emacs | Environment'.
1352 Scrollbar and toolbar visibility is controlled via the `Display' group,
1353 options `Scrollbars visible' and `Toolbar visible' respectively.
1354 Gutter visibility is controlled by group `Gutter', option `Visible'.
1356 Or they can be controlled directly by `M-x customize-variable', by
1357 changing the values of the variables `menubar-visible-p',
1358 `scrollbars-visible-p', `toolbar-visible-p', or
1359 `gutter-buffers-tab-visible-p' respectively. (The strange form of the
1360 last variable is due to the fact that gutters are often used to display
1361 transient widgets like progress gauges, which you probably don't want
1362 to inhibit. It is more likely that you want to inhibit the default
1363 display of the buffers tab widget, which is what that variable controls.
1364 This interface is subject to change depending on developer experience
1367 Control of frame configuration can controlled automatically
1368 according to various parameters such as buffer or frame because these
1369 are "specifiers" *Note Specifiers: (lispref)Specifiers. Using these
1370 features requires programming in Lisp; Customize is not yet that
1371 sophisticated. Also, components that appear in various positions and
1372 orientations can have display suppressed according to position. `C-h a
1373 visible-p' gives a list of variables which can be customized. E.g., to
1374 control the visibility of specifically the left-side toolbar only,
1375 customize `left-toolbar-visible-p'.
1378 File: xemacs.info, Node: Customizing, Prev: Inhibiting, Up: GUI Components
1380 1.11 Changing the Position, Orientation, and Appearance of GUI Components
1381 =========================================================================
1383 #### Not documented yet.
1386 File: xemacs.info, Node: XEmacs under X, Next: XEmacs under MS Windows, Prev: GUI Components, Up: Frame
1388 1.12 Using XEmacs Under the X Window System
1389 ===========================================
1391 XEmacs can be used with the X Window System and a window manager like
1392 MWM or TWM. In that case, the X window manager opens, closes, and
1393 resizes XEmacs frames. You use the window manager's mouse gestures to
1394 perform the operations. Consult your window manager guide or reference
1395 manual for information on manipulating X windows.
1397 When you are working under X, each X window (that is, each XEmacs
1398 frame) has a menu bar for mouse-controlled operations (*note Pull-down
1401 XEmacs under X is also a multi-frame XEmacs. You can use the New
1402 Frame menu item from the File menu to create a new XEmacs frame in a
1403 new X window from the same process. The different frames will share the
1404 same buffer list, but you can look at different buffers in the different
1407 The function `find-file-other-frame' is just like `find-file', but
1408 creates a new frame to display the buffer in first. This is normally
1409 bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
1412 The function `switch-to-buffer-other-frame' is just like
1413 `switch-to-buffer', but creates a new frame to display the buffer in
1414 first. This is normally bound to `C-x 5 b'.
1416 You can specify a different default frame size other than the one
1417 provided. Use the variable `default-frame-plist', which is a plist of
1418 default values for frame creation other than the first one. These may
1419 be set in your init file, like this:
1421 (setq default-frame-plist '(width 80 height 55))
1423 This variable has replaced `default-frame-alist', which is
1424 considered obsolete.
1426 For values specific to the first XEmacs frame, you must use X
1427 resources. The variable `x-frame-defaults' takes an alist of default
1428 frame creation parameters for X window frames. These override what is
1429 specified in `~/.Xdefaults' but are overridden by the arguments to the
1430 particular call to `x-create-frame'.
1432 When you create a new frame, the variable `create-frame-hook' is
1433 called with one argument, the frame just created.
1435 If you want to close one or more of the X windows you created using
1436 New Frame, use the Delete Frame menu item from the File menu.
1438 If you are working with multiple frames, some special information
1440 * Two variables, `frame-title-format' and `frame-icon-title-format'
1441 determine the title of the frame and the title of the icon that
1442 results if you shrink the frame.
1444 * The variables `auto-lower-frame' and `auto-raise-frame' position a
1445 frame. If true, `auto-lower-frame' lowers a frame to the bottom
1446 when it is no longer selected. If true, `auto-raise-frame' raises
1447 a frame to the top when it is selected. Under X, most
1448 ICCCM-compliant window managers will have options to do this for
1449 you, but these variables are provided in case you are using a
1450 broken window manager.
1452 * There is a new frame/modeline format directive, %S, which expands
1453 to the name of the current frame (a frame's name is distinct from
1454 its title; the name is used for resource lookup, among other
1455 things, and the title is simply what appears above the window.)
1458 File: xemacs.info, Node: XEmacs under MS Windows, Prev: XEmacs under X, Up: Frame
1460 1.13 Using XEmacs Under Microsoft Windows
1461 =========================================
1463 Use of XEmacs under MS Windows is not separately documented here, but
1464 most operations available under the X Window System are also available
1467 Where possible, native MS Windows GUI components and capabilities are
1471 File: xemacs.info, Node: Keystrokes, Next: Pull-down Menus, Prev: Frame, Up: Top
1473 2 Keystrokes, Key Sequences, and Key Bindings
1474 *********************************************
1478 * Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
1479 * Representing Keystrokes:: Using lists of modifiers and keysyms to
1480 represent keystrokes.
1481 * Key Sequences:: Combine key strokes into key sequences you can
1483 * String Key Sequences:: Available for upward compatibility.
1484 * Meta Key:: Using <ESC> to represent <Meta>
1485 * Super and Hyper Keys:: Adding modifier keys on certain keyboards.
1486 * Character Representation:: How characters appear in Emacs buffers.
1487 * Commands:: How commands are bound to key sequences.
1490 File: xemacs.info, Node: Intro to Keystrokes, Next: Representing Keystrokes, Prev: Keystrokes, Up: Keystrokes
1492 2.1 Keystrokes as Building Blocks of Key Sequences
1493 ==================================================
1495 Earlier versions of Emacs used only the ASCII character set, which
1496 defines 128 different character codes. Some of these codes are
1497 assigned graphic symbols like `a' and `='; the rest are control
1498 characters, such as `Control-a' (also called `C-a'). `C-a' means you
1499 hold down the <CTRL> key and then press `a'.
1501 Keybindings in XEmacs are not restricted to the set of keystrokes
1502 that can be represented in ASCII. XEmacs can tell the difference
1503 between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
1505 A keystroke is like a piano chord: you get it by simultaneously
1506 striking several keys. To be more precise, a keystroke consists of a
1507 possibly empty set of modifiers followed by a single "keysym". The set
1508 of modifiers is small; it consists of `Control', `Meta', `Super',
1509 `Hyper', and `Shift'.
1511 The rest of the keys on your keyboard, along with the mouse buttons,
1512 make up the set of keysyms. A keysym is usually what is printed on the
1513 keys on your keyboard. Here is a table of some of the symbolic names
1531 upstroke on the left mouse button
1534 upstroke on the middle mouse button
1537 upstroke on the right mouse button
1542 Use the variable `keyboard-translate-table' only if you are on a
1543 dumb tty, as it cannot handle input that cannot be represented as ASCII.
1544 The value of this variable is a string used as a translate table for
1545 keyboard input or `nil'. Each character is looked up in this string
1546 and the contents used instead. If the string is of length `n',
1547 character codes `N' and up are untranslated. If you are running Emacs
1548 under X, you should do the translations with the `xmodmap' program
1552 File: xemacs.info, Node: Representing Keystrokes, Next: Key Sequences, Prev: Intro to Keystrokes, Up: Keystrokes
1554 2.1.1 Representing Keystrokes
1555 -----------------------------
1557 XEmacs represents keystrokes as lists. Each list consists of an
1558 arbitrary combination of modifiers followed by a single keysym at the
1559 end of the list. If the keysym corresponds to an ASCII character, you
1560 can use its character code. (A keystroke may also be represented by an
1561 event object, as returned by the `read-key-sequence' function;
1562 non-programmers need not worry about this.)
1564 The following table gives some examples of how to list
1565 representations for keystrokes. Each list consists of sets of
1566 modifiers followed by keysyms:
1569 Pressing <CTRL> and `a' simultaneously.
1572 Another way of writing the keystroke `C-a'.
1575 Yet another way of writing the keystroke `C-a'.
1578 Pressing the <BREAK> key.
1580 `(control meta button2up)'
1581 Release the middle mouse button, while pressing <CTRL> and <META>.
1582 Note: As you define keystrokes, you can use the `shift' key only
1583 as a modifier with characters that do not have a second keysym on the
1584 same key, such as `backspace' and `tab'. It is an error to define a
1585 keystroke using the <shift> modifier with keysyms such as `a' and `='.
1586 The correct forms are `A' and `+'.
1589 File: xemacs.info, Node: Key Sequences, Next: String Key Sequences, Prev: Representing Keystrokes, Up: Keystrokes
1591 2.1.2 Representing Key Sequences
1592 --------------------------------
1594 A "complete key sequence" is a sequence of keystrokes that Emacs
1595 understands as a unit. Key sequences are significant because you can
1596 bind them to commands. Note that not all sequences of keystrokes are
1597 possible key sequences. In particular, the initial keystrokes in a key
1598 sequence must make up a "prefix key sequence".
1600 Emacs represents a key sequence as a vector of keystrokes. Thus, the
1601 schematic representation of a complete key sequence is as follows:
1603 [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]
1605 Here are some examples of complete key sequences:
1607 `[(control c) (control a)]'
1608 Typing `C-c' followed by `C-a'
1610 `[(control c) (control 65)]'
1611 Typing `C-c' followed by `C-a'. (Using the ASCII code for the
1614 `[(control c) (break)]'
1615 Typing `C-c' followed by the `break' character.
1617 A "prefix key sequence" is the beginning of a series of longer
1618 sequences that are valid key sequences; adding any single keystroke to
1619 the end of a prefix results in a valid key sequence. For example,
1620 `control-x' is standardly defined as a prefix. Thus there is a
1621 two-character key sequence starting with `C-x' for each valid
1622 keystroke, giving numerous possibilities. Here are some samples:
1624 * `[(control x) (c)]'
1626 * `[(control x) (control c)]'
1628 Adding one character to a prefix key does not have to form a complete
1629 key. It could make another, longer prefix. For example, `[(control x)
1630 (\4)]' is itself a prefix that leads to any number of different
1631 three-character keys, including `[(control x) (\4) (f)]', `[(control x)
1632 (\4) (b)]' and so on. It would be possible to define one of those
1633 three-character sequences as a prefix, creating a series of
1634 four-character keys, but we did not define any of them this way.
1636 By contrast, the two-character sequence `[(control f) (control k)]'
1637 is not a key, because the `(control f)' is a complete key sequence in
1638 itself. You cannot give `[(control f (control k)]' an independent
1639 meaning as a command while `(control f)' is a complete sequence,
1640 because Emacs would understand <C-f C-k> as two commands.
1642 The predefined prefix key sequences in Emacs are `(control c)',
1643 `(control x)', `(control h)', `[(control x) (\4)]', and `escape'. You
1644 can customize Emacs and could make new prefix keys or eliminate the
1645 default key sequences. *Note Key Bindings::. For example, if you
1646 redefine `(control f)' as a prefix, `[(control f) (control k)]'
1647 automatically becomes a valid key sequence (complete, unless you define
1648 it as a prefix as well). Conversely, if you remove the prefix
1649 definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
1650 `[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
1652 Note that the above paragraphs uses \4 instead of simply 4, because
1653 \4 is the symbol whose name is "4", and plain 4 is the integer 4, which
1654 would have been interpreted as the ASCII value. Another way of
1655 representing the symbol whose name is "4" is to write ?4, which would be
1656 interpreted as the number 52, which is the ASCII code for the character
1657 "4". We could therefore actually have written 52 directly, but that is
1661 File: xemacs.info, Node: String Key Sequences, Next: Meta Key, Prev: Key Sequences, Up: Keystrokes
1663 2.1.3 String Key Sequences
1664 --------------------------
1666 For backward compatibility, you may also represent a key sequence using
1667 strings. For example, we have the following equivalent representations:
1670 `[(control c) (control c)]'
1673 `[(meta control c)]'
1676 File: xemacs.info, Node: Meta Key, Next: Super and Hyper Keys, Prev: String Key Sequences, Up: Keystrokes
1678 2.1.4 Assignment of the <META> Key
1679 ----------------------------------
1681 Not all terminals have the complete set of modifiers. Terminals that
1682 have a <Meta> key allow you to type Meta characters by just holding
1683 that key down. To type `Meta-a', hold down <META> and press `a'. On
1684 those terminals, the <META> key works like the <SHIFT> key. Such a key
1685 is not always labeled <META>, however, as this function is often a
1686 special option for a key with some other primary purpose.
1688 If there is no <META> key, you can still type Meta characters using
1689 two-character sequences starting with <ESC>. To enter `M-a', you could
1690 type `<ESC> a'. To enter `C-M-a', you would type `ESC C-a'. <ESC> is
1691 allowed on terminals with Meta keys, too, in case you have formed a
1694 If you are running under X and do not have a <META> key, it is
1695 possible to reconfigure some other key to be a <META> key. *Note Super
1698 Emacs believes the terminal has a <META> key if the variable
1699 `meta-flag' is non-`nil'. Normally this is set automatically according
1700 to the termcap entry for your terminal type. However, sometimes the
1701 termcap entry is wrong, and then it is useful to set this variable
1702 yourself. *Note Variables::, for how to do this.
1704 Note: If you are running under the X window system, the setting of
1705 the `meta-flag' variable is irrelevant.
1708 File: xemacs.info, Node: Super and Hyper Keys, Next: Character Representation, Prev: Meta Key, Up: Keystrokes
1710 2.1.5 Assignment of the <SUPER> and <HYPER> Keys
1711 ------------------------------------------------
1713 Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
1714 keys. Under X, you can simulate the <SUPER> or <HYPER> key if you want
1715 to bind keys to sequences using `super' and `hyper'. You can use the
1716 `xmodmap' program to do this.
1718 For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
1721 Create a file called `~/.xmodmap'. In this file, place the lines
1723 remove Lock = Caps_Lock
1724 keysym Caps_Lock = Super_L
1727 The first line says that the key that is currently called `Caps_Lock'
1728 should no longer behave as a "lock" key. The second line says that
1729 this should now be called `Super_L' instead. The third line says that
1730 the key called `Super_L' should be a modifier key, which produces the
1733 To create a <META> or <HYPER> key instead of a <SUPER> key, replace
1734 the word `Super' above with `Meta' or `Hyper'.
1736 Just after you start up X, execute the command `xmodmap /.xmodmap'.
1737 You can add this command to the appropriate initialization file to have
1738 the command executed automatically.
1740 If you have problems, see the documentation for the `xmodmap'
1741 program. The X keyboard model is quite complicated, and explaining it
1742 is beyond the scope of this manual. However, we reprint the following
1743 description from the X Protocol document for your convenience:
1745 A list of keysyms is associated with each keycode. If that list
1746 (ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
1747 list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
1748 the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
1749 `K1 K2', then the list is treated as if it were the list ```K1 K2 K1
1750 K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
1751 of keysyms `K1 K2 K3', then the list is treated as if it were the list
1752 ```K1 K2 K3 NoSymbol'''.
1754 The first four elements of the list are split into two groups of
1755 keysyms. Group 1 contains the first and second keysyms; Group 2 contains
1756 third and fourth keysyms. Within each group, if the second element of
1757 the group is NoSymbol, then the group should be treated as if the second
1758 element were the same as the first element, except when the first
1759 element is an alphabetic keysym `K' for which both lowercase and
1760 uppercase forms are defined. In that case, the group should be treated
1761 as if the first element were the lowercase form of `K' and the second
1762 element were the uppercase form of `K'.
1764 The standard rules for obtaining a keysym from a KeyPress event make
1765 use of only the Group 1 and Group 2 keysyms; no interpretation of other
1766 keysyms in the list is given here. (That is, the last four keysyms are
1769 Which group to use is determined by modifier state. Switching between
1770 groups is controlled by the keysym named `Mode_switch'. Attach that
1771 keysym to some keycode and attach that keycode to any one of the
1772 modifiers Mod1 through Mod5. This modifier is called the "group
1773 modifier". For any keycode, Group 1 is used when the group modifier is
1774 off, and Group 2 is used when the group modifier is on.
1776 Within a group, which keysym to use is also determined by modifier
1777 state. The first keysym is used when the `Shift' and `Lock' modifiers
1778 are off. The second keysym is used when the `Shift' modifier is on, or
1779 when the `Lock' modifier is on and the second keysym is uppercase
1780 alphabetic, or when the `Lock' modifier is on and is interpreted as
1781 `ShiftLock'. Otherwise, when the `Lock' modifier is on and is
1782 interpreted as `CapsLock', the state of the `Shift' modifier is applied
1783 first to select a keysym, but if that keysym is lower-case alphabetic,
1784 then the corresponding upper-case keysym is used instead.
1786 In addition to the above information on keysyms, we also provide the
1787 following description of modifier mapping from the InterClient
1788 Communications Conventions Manual:
1790 X11 supports 8 modifier bits, of which 3 are pre-assigned to
1791 `Shift', `Lock', and `Control'. Each modifier bit is controlled by the
1792 state of a set of keys, and these sets are specified in a table
1793 accessed by `GetModifierMapping()' and `SetModifierMapping()'.
1795 A client needing to use one of the pre-assigned modifiers should
1796 assume that the modifier table has been set up correctly to control
1797 these modifiers. The `Lock' modifier should be interpreted as `Caps
1798 Lock' or `Shift Lock' according to whether the keycodes in its
1799 controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
1801 Clients should determine the meaning of a modifier bit from the
1802 keysyms being used to control it.
1804 A client needing to use an extra modifier, for example `Meta',
1807 1. Scan the existing modifier mappings.
1809 1. If it finds a modifier that contains a keycode whose set of
1810 keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
1813 2. If there is no existing modifier controlled by `XK_Meta_L' or
1814 `XK_Meta_R', it should select an unused modifier bit (one with
1815 an empty controlling set) and:
1817 2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
1818 that keycode to the set for the chosen modifier, and then:
1820 1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
1821 add that keycode to the set for the chosen modifier, and then:
1823 2. If the controlling set is still empty, interact with the user
1824 to select one or more keys to be `Meta'.
1826 3. If there are no unused modifier bits, ask the user to take
1829 This means that the `Mod1' modifier does not necessarily mean
1830 `Meta', although some applications (such as twm and emacs 18) assume
1831 that. Any of the five unassigned modifier bits could mean `Meta'; what
1832 matters is that a modifier bit is generated by a keycode which is bound
1833 to the keysym `Meta_L' or `Meta_R'.
1835 Therefore, if you want to make a <META> key, the right way is to
1836 make the keycode in question generate both a `Meta' keysym and some
1837 previously-unassigned modifier bit.
1840 File: xemacs.info, Node: Character Representation, Next: Commands, Prev: Super and Hyper Keys, Up: Keystrokes
1842 2.2 Representation of Characters
1843 ================================
1845 This section briefly discusses how characters are represented in Emacs
1846 buffers. *Note Key Sequences::, for information on representing key
1847 sequences to create key bindings.
1849 ASCII graphic characters in Emacs buffers are displayed with their
1850 graphics. <LFD> is the same as a newline character; it is displayed by
1851 starting a new line. <TAB> is displayed by moving to the next tab stop
1852 column (usually every 8 spaces). Other control characters are
1853 displayed as a caret (`^') followed by the non-control version of the
1854 character; thus, `C-a' is displayed as `^A'. Non-ASCII characters 128
1855 and up are displayed with octal escape sequences; thus, character code
1856 243 (octal), also called `M-#' when used as an input character, is
1857 displayed as `\243'.
1859 The variable `ctl-arrow' may be used to alter this behavior. *Note
1863 File: xemacs.info, Node: Commands, Prev: Character Representation, Up: Keystrokes
1865 2.3 Keys and Commands
1866 =====================
1868 This manual is full of passages that tell you what particular keys do.
1869 But Emacs does not assign meanings to keys directly. Instead, Emacs
1870 assigns meanings to "functions", and then gives keys their meanings by
1871 "binding" them to functions.
1873 A function is a Lisp object that can be executed as a program.
1874 Usually it is a Lisp symbol that has been given a function definition;
1875 every symbol has a name, usually made of a few English words separated
1876 by dashes, such as `next-line' or `forward-word'. It also has a
1877 "definition", which is a Lisp program. Only some functions can be the
1878 bindings of keys; these are functions whose definitions use
1879 `interactive' to specify how to call them interactively. Such
1880 functions are called "commands", and their names are "command names".
1881 More information on this subject will appear in the XEmacs Lisp
1884 The bindings between keys and functions are recorded in various
1885 tables called "keymaps". *Note Key Bindings::, for more information on
1886 key sequences you can bind commands to. *Note Keymaps::, for
1887 information on creating keymaps.
1889 When we say "`C-n' moves down vertically one line" we are glossing
1890 over a distinction that is irrelevant in ordinary use but is vital in
1891 understanding how to customize Emacs. The function `next-line' is
1892 programmed to move down vertically. `C-n' has this effect because it
1893 is bound to that function. If you rebind `C-n' to the function
1894 `forward-word' then `C-n' will move forward by words instead.
1895 Rebinding keys is a common method of customization.
1897 The rest of this manual usually ignores this subtlety to keep things
1898 simple. To give the customizer the information needed, we often state
1899 the name of the command that really does the work in parentheses after
1900 mentioning the key that runs it. For example, we will say that "The
1901 command `C-n' (`next-line') moves point vertically down," meaning that
1902 `next-line' is a command that moves vertically down and `C-n' is a key
1903 that is standardly bound to it.
1905 While we are on the subject of information for customization only,
1906 it's a good time to tell you about "variables". Often the description
1907 of a command will say, "To change this, set the variable `mumble-foo'."
1908 A variable is a name used to remember a value. Most of the variables
1909 documented in this manual exist just to facilitate customization: some
1910 command or other part of Emacs uses the variable and behaves
1911 differently depending on its setting. Until you are interested in
1912 customizing, you can ignore the information about variables. When you
1913 are ready to be interested, read the basic information on variables, and
1914 then the information on individual variables will make sense. *Note
1918 File: xemacs.info, Node: Pull-down Menus, Next: Entering Emacs, Prev: Keystrokes, Up: Top
1920 2.4 XEmacs Pull-down Menus
1921 ==========================
1923 If you are running XEmacs under X, a menu bar on top of the Emacs frame
1924 provides access to pull-down menus of file, edit, and help-related
1925 commands. The menus provide convenient shortcuts and an easy interface
1926 for novice users. They do not provide additions to the functionality
1927 available via key commands; you can still invoke commands from the
1928 keyboard as in previous versions of Emacs.
1931 Perform file and buffer-related operations, such as opening and
1932 closing files, saving and printing buffers, as well as exiting
1936 Perform standard editing operations, such as cutting, copying,
1937 pasting, and killing selected text.
1940 Access to sub-applications implemented within XEmacs, such as the
1941 mail reader, the World Wide Web browser, the spell-checker, and
1942 the calendar program.
1945 Control various options regarding the way XEmacs works, such as
1946 controlling which elements of the frame are visible, selecting the
1947 fonts to be used for text, specifying whether searches are
1948 case-sensitive, etc.
1951 Present a menu of buffers for selection as well as the option to
1952 display a buffer list.
1955 Perform various actions designed to automate software development
1956 and similar technical work, such as searching through many files,
1957 compiling a program, and comparing or merging two or three files.
1960 Access to Emacs Info.
1962 There are two ways of selecting an item from a pull-down menu:
1964 * Select an item in the menu bar by moving the cursor over it and
1965 click the left mouse-button. Then move the cursor over the menu
1966 item you want to choose and click left again.
1968 * Select an item in the menu bar by moving the cursor over it and
1969 click and hold the left mouse-button. With the mouse-button
1970 depressed, move the cursor over the menu item you want, then
1971 release it to make your selection.
1973 If a command in the pull-down menu is not applicable in a given
1974 situation, the command is disabled and its name appears faded. You
1975 cannot invoke items that are faded. For example, many commands on the
1976 Edit menu appear faded until you select text on which they are to
1977 operate; after you select a block of text, edit commands are enabled.
1978 *Note Mouse Selection::, for information on using the mouse to select
1979 text. *Note Using X Selections::, for related information.
1981 There are also `M-x' equivalents for each menu item. To find the
1982 equivalent for any left-button menu item, do the following:
1984 1. Type `C-h k' to get the `Describe Key' prompt.
1986 2. Select the menu item and click.
1988 Emacs displays the function associated with the menu item in a
1989 separate window, usually together with some documentation.
1993 * File Menu:: Items on the File menu.
1994 * Edit Menu:: Items on the Edit menu.
1995 * Apps Menu:: Items on the Apps menu.
1996 * Options Menu:: Items on the Options menu.
1997 * Buffers Menu:: Information about the Buffers menu.
1998 * Tools Menu:: Items on the Tools menu.
1999 * Help Menu:: Items on the Help menu.
2000 * Menu Customization:: Adding and removing menu items and related
2004 File: xemacs.info, Node: File Menu, Next: Edit Menu, Up: Pull-down Menus
2009 The File menu bar item contains the items New Frame, Open File..., Save
2010 Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete Frame,
2011 Kill Buffer and Exit Emacs on the pull-down menu. If you select a menu
2012 item, Emacs executes the equivalent command.
2014 Open File, New Frame...
2015 Prompts you for a filename and loads that file into a new buffer
2016 in a new Emacs frame, that is, a new X window running under the
2017 same Emacs process. You can remove the frame using the Delete
2018 Frame menu item. When you remove the last frame, you exit Emacs
2019 and are prompted for confirmation.
2022 Prompts you for a filename and loads that file into a new buffer.
2023 Open File... is equivalent to the Emacs command `find-file' (`C-x
2027 Prompts you for a filename and inserts the contents of that file
2028 into the current buffer. The file associated with the current
2029 buffer is not changed by this command. This is equivalent to the
2030 Emacs command `insert-file' (`C-x i').
2033 Writes and saves the current Emacs buffer as the latest version of
2034 the current visited file. Save Buffer is equivalent to the Emacs
2035 command `save-buffer' (`C-x C-s').
2038 Writes and saves the current Emacs buffer to the filename you
2039 specify. Save Buffer As... is equivalent to the Emacs command
2040 `write-file' (`C-x C-w').
2043 Restores the last saved version of the file to the current buffer.
2044 When you edit a buffer containing a text file, you must save the
2045 buffer before your changes become effective. Use Revert Buffer if
2046 you do not want to keep the changes you have made in the buffer.
2047 Revert Buffer is equivalent to the Emacs command `revert-file'
2048 (`M-x revert-buffer').
2051 Kills the current buffer, prompting you first if there are unsaved
2052 changes. This is roughly equivalent to the Emacs command
2053 `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
2054 name of a buffer to kill.
2057 Prints a hardcopy of the current buffer. Equivalent to the Emacs
2058 command `print-buffer' (`M-x print-buffer').
2061 Creates a new Emacs frame displaying the `*scratch*' buffer. This
2062 is like the Open File, New Frame... menu item, except that it does
2063 not prompt for or load a file.
2066 Allows you to close all but one of the frames created by New Frame.
2067 If you created several Emacs frames belonging to the same Emacs
2068 process, you can close all but one of them. When you attempt to
2069 close the last frame, Emacs informs you that you are attempting to
2070 delete the last frame. You have to choose Exit Emacs for that.
2073 Divides the current window on the current frame into two
2074 equal-sized windows, both displaying the same buffer. Equivalent
2075 to the Emacs command `split-window-vertically' (`C-x 2').
2077 Un-split (Keep This)
2078 If the frame is divided into multiple windows, this removes all
2079 windows other than the selected one. Equivalent to the Emacs
2080 command `delete-other-windows' (`C-x 1').
2082 Un-split (Keep Others)
2083 If the frame is divided into multiple windows, this removes the
2084 selected window from the frame, giving the space back to one of the
2085 other windows. Equivalent to the Emacs command `delete-window'
2089 Shuts down (kills) the Emacs process. Equivalent to the Emacs
2090 command `save-buffers-kill-emacs' (`C-x C-c'). Before killing the
2091 Emacs process, the system asks which unsaved buffers to save by
2092 going through the list of all buffers in that Emacs process.
2095 File: xemacs.info, Node: Edit Menu, Next: Apps Menu, Prev: File Menu, Up: Pull-down Menus
2100 The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and Clear
2101 menu items. When you select a menu item, Emacs executes the equivalent
2102 command. Most commands on the Edit menu work on a block of text, the X
2103 selection. They appear faded until you select a block of text
2104 (activate a region) with the mouse. *Note Using X Selections::, *note
2105 Killing::, and *note Yanking:: for more information.
2108 Undoes the previous command. Undo is equivalent to the Emacs
2109 command `undo' (`C-x u').
2112 Removes the selected text block from the current buffer, makes it
2113 the X clipboard selection, and places it in the kill ring. Before
2114 executing this command, you have to select a region using Emacs
2115 region selection commands or with the mouse.
2118 Makes a selected text block the X clipboard selection, and places
2119 it in the kill ring. You can select text using one of the Emacs
2120 region selection commands or by selecting a text region with the
2124 Inserts the current value of the X clipboard selection in the
2125 current buffer. Note that this is not necessarily the same as the
2126 Emacs `yank' command, because the Emacs kill ring and the X
2127 clipboard selection are not the same thing. You can paste in text
2128 you have placed in the clipboard using Copy or Cut. You can also
2129 use Paste to insert text that was pasted into the clipboard from
2133 Removes the selected text block from the current buffer but does
2134 not place it in the kill ring or the X clipboard selection.
2136 Start Macro Recording
2137 After selecting this, Emacs will remember every keystroke you type
2138 until End Macro Recording is selected. This is the same as the
2139 Emacs command `start-kbd-macro' (`C-x (').
2142 Selecting this tells emacs to stop remembering your keystrokes.
2143 This is the same as the Emacs command `end-kbd-macro' (`C-x )').
2146 Selecting this item will cause emacs to re-interpret all of the
2147 keystrokes which were saved between selections of the Start Macro
2148 Recording and End Macro Recording menu items. This is the same as
2149 the Emacs command `call-last-kbd-macro' (`C-x e').
2152 File: xemacs.info, Node: Apps Menu, Next: Options Menu, Prev: Edit Menu, Up: Pull-down Menus
2157 The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
2158 (MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
2159 Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
2160 When you select a menu item, Emacs executes the equivalent command.
2161 For some of the menu items, there are sub-menus which you will need to
2165 File: xemacs.info, Node: Options Menu, Next: Buffers Menu, Prev: Apps Menu, Up: Pull-down Menus
2167 2.4.4 The Options Menu
2168 ----------------------
2170 The Options pull-down menu contains the Read Only, Case Sensitive
2171 Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
2172 Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
2173 Menu Length..., Buffers Sub-Menus and Save Options menu items. When
2174 you select a menu item, Emacs executes the equivalent command. For
2175 some of the menu items, there are sub-menus which you will need to
2179 Selecting this item will cause the buffer to visit the file in a
2180 read-only mode. Changes to the file will not be allowed. This is
2181 equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
2183 Case Sensitive Search
2184 Selecting this item will cause searches to be case-sensitive. If
2185 its not selected then searches will ignore case. This option is
2186 local to the buffer.
2189 After selecting this item, when you type letters they will replace
2190 existing text on a one-to-one basis, rather than pushing it to the
2191 right. At the end of a line, such characters extend the line.
2192 Before a tab, such characters insert until the tab is filled in.
2193 This is the same as Emacs command `quoted-insert' (`C-q').
2195 Auto Delete Selection
2196 Selecting this item will cause automatic deletion of the selected
2197 region. The typed text will replace the selection if the selection
2198 is active (i.e. if its highlighted). If the option is not selected
2199 then the typed text is just inserted at the point.
2201 Teach Extended Commands
2202 After you select this item, any time you execute a command with
2203 `M-x'which has a shorter keybinding, you will be shown the
2204 alternate binding before the command executes.
2207 You can customize your init file to include the font-lock mode so
2208 that when you select this item, the comments will be displayed in
2209 one face, strings in another, reserved words in another, and so
2210 on. *Note Init File::. When Fonts is selected, different parts of
2211 the program will appear in different Fonts. When Colors is
2212 selected, then the program will be displayed in different colors.
2213 Selecting None causes the program to appear in just one Font and
2214 Color. Selecting Less resets the Fonts and Colors to a fast,
2215 minimal set of decorations. Selecting More resets the Fonts and
2216 Colors to a larger set of decorations. For example, if Less is
2217 selected (which is the default setting) then you might have all
2218 comments in green color. Whereas, if More is selected then a
2219 function name in the comments themselves might appear in a
2220 different Color or Font.
2223 After selecting Blink from this item, if you place the cursor on a
2224 parenthesis, the matching parenthesis will blink. If you select
2225 Highlight and place the cursor on a parenthesis, the whole
2226 expression of the parenthesis under the cursor will be highlighted.
2227 Selecting None will turn off the options (regarding Paren
2228 Highlighting) which you had selected earlier.
2231 You can select any Font for your program by choosing from one of
2232 the available Fonts.
2235 You can select any size ranging from 2 to 24 by selecting the
2239 You can choose either Bold or Medium for the weight.
2241 Buffers Menu Length...
2242 Prompts you for the number of buffers to display. Then it will
2243 display that number of most recently selected buffers.
2246 After selection of this item the Buffers menu will contain several
2247 commands, as submenus of each buffer line. If this item is
2248 unselected, then there are no submenus for each buffer line, the
2249 only command available will be selecting that buffer.
2252 Selecting this item will save the current settings of your Options
2253 menu to your init file. *Note Init File::.
2256 File: xemacs.info, Node: Buffers Menu, Next: Tools Menu, Prev: Options Menu, Up: Pull-down Menus
2258 2.4.5 The Buffers Menu
2259 ----------------------
2261 The Buffers menu provides a selection of up to ten buffers and the item
2262 List All Buffers, which provides a Buffer List. *Note List Buffers::,
2263 for more information.
2266 File: xemacs.info, Node: Tools Menu, Next: Help Menu, Prev: Buffers Menu, Up: Pull-down Menus
2268 2.4.6 The Tools Menu
2269 --------------------
2271 The Tools pull-down menu contains the Grep..., Compile..., Shell
2272 Command..., Shell Command on Region..., Debug(GDB)... and
2273 Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
2274 sub-menus. When you select a menu item, Emacs executes the equivalent
2275 command. For some of the menu items, there are sub-menus which you
2276 will need to select.
2279 File: xemacs.info, Node: Help Menu, Next: Menu Customization, Prev: Tools Menu, Up: Pull-down Menus
2284 The Help Menu gives you access to Emacs Info and provides a menu
2285 equivalent for each of the choices you have when using `C-h'. *Note
2286 Help::, for more information.
2288 The Help menu also gives access to UNIX online manual pages via the
2289 UNIX Manual Page option.
2292 File: xemacs.info, Node: Menu Customization, Prev: Help Menu, Up: Pull-down Menus
2294 2.4.8 Customizing XEmacs Menus
2295 ------------------------------
2297 You can customize any of the pull-down menus by adding or removing menu
2298 items and disabling or enabling existing menu items.
2300 The following functions are available:
2301 `add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)'
2302 Add a menu to the menu bar or one of its submenus.
2304 `add-menu-item: (MENU-PATH ITEM-NAME FUNCTION'
2305 ENABLED-P &optional BEFORE) Add a menu item to a menu, creating
2306 the menu first if necessary.
2308 `delete-menu-item: (PATH)'
2309 Remove the menu item defined by PATH from the menu hierarchy.
2311 `disable-menu-item: (PATH)'
2312 Disable the specified menu item.
2314 `enable-menu-item: (PATH)'
2315 Enable the specified previously disabled menu item.
2317 `relabel-menu-item: (PATH NEW-NAME)'
2318 Change the string of the menu item specified by PATH to NEW-NAME.
2321 Use the function `add-menu' to add a new menu or submenu. If a menu
2322 or submenu of the given name exists already, it is changed.
2324 MENU-PATH identifies the menu under which the new menu should be
2325 inserted. It is a list of strings; for example, `("File")' names the
2326 top-level File menu. `("File" "Foo")' names a hypothetical submenu of
2327 File. If MENU-PATH is `nil', the menu is added to the menu bar itself.
2329 MENU-NAME is the string naming the menu to be added.
2331 MENU-ITEMS is a list of menu item descriptions. Each menu item
2332 should be a vector of three elements:
2334 * A string, which is the name of the menu item
2336 * A symbol naming a command, or a form to evaluate
2338 * `t' or `nil' to indicate whether the item is selectable
2340 The optional argument BEFORE is the name of the menu before which
2341 the new menu or submenu should be added. If the menu is already
2342 present, it is not moved.
2344 The function `add-menu-item' adds a menu item to the specified menu,
2345 creating the menu first if necessary. If the named item already
2346 exists, the menu remains unchanged.
2348 MENU-PATH identifies the menu into which the new menu item should be
2349 inserted. It is a list of strings; for example, `("File")' names the
2350 top-level File menu. `("File" "Foo")' names a hypothetical submenu of
2353 ITEM-NAME is the string naming the menu item to add.
2355 FUNCTION is the command to invoke when this menu item is selected.
2356 If it is a symbol, it is invoked with `call-interactively', in the same
2357 way that functions bound to keys are invoked. If it is a list, the
2358 list is simply evaluated.
2360 ENABLED-P controls whether the item is selectable or not. It should
2361 be `t', `nil', or a form to evaluate to decide. This form will be
2362 evaluated just before the menu is displayed, and the menu item will be
2363 selectable if that form returns non-`nil'.
2365 For example, to make the `rename-file' command available from the
2366 File menu, use the following code:
2368 (add-menu-item '("File") "Rename File" 'rename-file t)
2370 To add a submenu of file management commands using a File Management
2371 item, use the following code:
2373 (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
2374 (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
2375 (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
2377 The optional BEFORE argument is the name of a menu item before which
2378 the new item should be added. If the item is already present, it is
2381 To remove a specified menu item from the menu hierarchy, use
2384 PATH is a list of strings that identify the position of the menu
2385 item in the menu hierarchy. `("File" "Save")' means the menu item
2386 called Save under the top level File menu. `("Menu" "Foo" "Item")'
2387 means the menu item called Item under the Foo submenu of Menu.
2389 To disable a menu item, use `disable-menu-item'. The disabled menu
2390 item is grayed and can no longer be selected. To make the item
2391 selectable again, use `enable-menu-item'. `disable-menu-item' and
2392 `enable-menu-item' both have the argument PATH.
2394 To change the string of the specified menu item, use
2395 `relabel-menu-item'. This function also takes the argument PATH.
2397 NEW-NAME is the string to which the menu item will be changed.
2400 File: xemacs.info, Node: Entering Emacs, Next: Exiting, Prev: Pull-down Menus, Up: Top
2402 3 Entering and Exiting Emacs
2403 ****************************
2405 The usual way to invoke XEmacs is to type `xemacs <RET>' at the shell.
2406 XEmacs clears the screen and then displays an initial advisory message
2407 and copyright notice. You can begin typing XEmacs commands immediately
2410 Some operating systems insist on discarding all type-ahead when
2411 XEmacs starts up; they give XEmacs no way to prevent this. Therefore,
2412 it is advisable to wait until XEmacs clears the screen before typing
2413 your first editing command.
2415 If you run XEmacs from a shell window under the X Window System, run
2416 it in the background with `xemacs&'. This way, XEmacs does not tie up
2417 the shell window, so you can use that to run other shell commands while
2418 XEmacs operates its own X windows. You can begin typing XEmacs commands
2419 as soon as you direct your keyboard input to the XEmacs frame.
2421 Before Emacs reads the first command, you have not had a chance to
2422 give a command to specify a file to edit. Since Emacs must always have
2423 a current buffer for editing, it presents a buffer, by default, a buffer
2424 named `*scratch*'. The buffer is in Lisp Interaction mode; you can use
2425 it to type Lisp expressions and evaluate them, or you can ignore that
2426 capability and simply doodle. (You can specify a different major mode
2427 for this buffer by setting the variable `initial-major-mode' in your
2428 init file. *Note Init File::.)
2430 It is possible to specify files to be visited, Lisp files to be
2431 loaded, and functions to be called, by giving Emacs arguments in the
2432 shell command line. *Note Command Switches::. But we don't recommend
2433 doing this. The feature exists mainly for compatibility with other
2436 Many other editors are designed to be started afresh each time you
2437 want to edit. You edit one file and then exit the editor. The next
2438 time you want to edit either another file or the same one, you must run
2439 the editor again. With these editors, it makes sense to use a
2440 command-line argument to say which file to edit.
2442 But starting a new Emacs each time you want to edit a different file
2443 does not make sense. For one thing, this would be annoyingly slow. For
2444 another, this would fail to take advantage of Emacs's ability to visit
2445 more than one file in a single editing session. And it would lose the
2446 other accumulated context, such as registers, undo history, and the mark
2449 The recommended way to use XEmacs is to start it only once, just
2450 after you log in, and do all your editing in the same Emacs session.
2451 Each time you want to edit a different file, you visit it with the
2452 existing Emacs, which eventually comes to have many files in it ready
2453 for editing. Usually you do not kill the Emacs until you are about to
2454 log out. *Note Files::, for more information on visiting more than one
2458 File: xemacs.info, Node: Exiting, Next: Command Switches, Prev: Entering Emacs, Up: Top
2463 There are two commands for exiting Emacs because there are two kinds of
2464 exiting: "suspending" Emacs and "killing" Emacs.
2466 "Suspending" means stopping Emacs temporarily and returning control
2467 to its parent process (usually a shell), allowing you to resume editing
2468 later in the same Emacs job, with the same buffers, same kill ring,
2469 same undo history, and so on. This is the usual way to exit.
2471 "Killing" Emacs means destroying the Emacs job. You can run Emacs
2472 again later, but you will get a fresh Emacs; there is no way to resume
2473 the same editing session after it has been killed.
2476 Suspend Emacs or iconify a frame
2477 (`suspend-emacs-or-iconify-frame'). If used under the X window
2478 system, shrink the X window containing the Emacs frame to an icon
2482 Kill Emacs (`save-buffers-kill-emacs').
2484 If you use XEmacs under the X window system, `C-z' shrinks the X
2485 window containing the Emacs frame to an icon. The Emacs process is
2486 stopped temporarily, and control is returned to the window manager. If
2487 more than one frame is associated with the Emacs process, only the
2488 frame from which you used `C-z' is iconified.
2490 To activate the "suspended" Emacs, use the appropriate window manager
2491 mouse gestures. Usually left-clicking on the icon reactivates and
2492 reopens the X window containing the Emacs frame, but the window manager
2493 you use determines what exactly happens. To actually kill the Emacs
2494 process, use `C-x C-c' or the Exit XEmacs item on the File menu.
2496 To suspend Emacs, type `C-z' (`suspend-emacs'). This takes you back
2497 to the shell from which you invoked Emacs. You can resume Emacs with
2498 the shell command `%xemacs' in most common shells.
2500 On systems that do not support suspending programs, `C-z' starts an
2501 inferior shell that communicates directly with the terminal. Emacs
2502 waits until you exit the subshell. (The way to do that is probably
2503 with `C-d' or `exit', but it depends on which shell you use.) The only
2504 way on these systems to get back to the shell from which Emacs was run
2505 (to log out, for example) is to kill Emacs.
2507 Suspending also fails if you run Emacs under a shell that doesn't
2508 support suspending programs, even if the system itself does support it.
2509 In such a case, you can set the variable `cannot-suspend' to a
2510 non-`nil' value to force `C-z' to start an inferior shell. (One might
2511 also describe Emacs's parent shell as "inferior" for failing to support
2512 job control properly, but that is a matter of taste.)
2514 When Emacs communicates directly with an X server and creates its own
2515 dedicated X windows, `C-z' has a different meaning. Suspending an
2516 applications that uses its own X windows is not meaningful or useful.
2517 Instead, `C-z' runs the command `iconify-or-deiconify-frame', which
2518 temporarily closes up the selected Emacs frame. The way to get back to
2519 a shell window is with the window manager.
2521 To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs'). A
2522 two-character key is used for this to make it harder to type. Selecting
2523 the Exit XEmacs option of the File menu is an alternate way of issuing
2526 Unless a numeric argument is used, this command first offers to save
2527 any modified file-visiting buffers. If you do not save all buffers,
2528 you are asked for reconfirmation with `yes' before killing Emacs, since
2529 any changes not saved will be lost forever. If any subprocesses are
2530 still running, `C-x C-c' asks you to confirm killing them, since killing
2531 Emacs will kill the subprocesses immediately.
2533 There is no way to restart an Emacs session once you have killed it.
2534 You can, however, arrange for Emacs to record certain session
2535 information, such as which files are visited, when you kill it, so that
2536 the next time you restart Emacs it will try to visit the same files and
2539 The operating system usually listens for certain special characters
2540 whose meaning is to kill or suspend the program you are running. This
2541 operating system feature is turned off while you are in Emacs. The
2542 meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the
2543 use of `C-z' and `C-c' on several operating systems as the characters
2544 for stopping or killing a program, but that is their only relationship
2545 with the operating system. You can customize these keys to run any
2546 commands of your choice (*note Keymaps::).
2549 File: xemacs.info, Node: Command Switches, Next: Startup Paths, Prev: Exiting, Up: Top
2551 3.2 Command Line Switches and Arguments
2552 =======================================
2554 XEmacs supports command line arguments you can use to request various
2555 actions when invoking Emacs. The commands are for compatibility with
2556 other editors and for sophisticated activities. If you are using
2557 XEmacs under the X window system, you can also use a number of standard
2558 Xt command line arguments. Command line arguments are not usually
2559 needed for editing with Emacs; new users can skip this section.
2561 Many editors are designed to be started afresh each time you want to
2562 edit. You start the editor to edit one file; then exit the editor. The
2563 next time you want to edit either another file or the same one, you
2564 start the editor again. Under these circumstances, it makes sense to
2565 use a command line argument to say which file to edit.
2567 The recommended way to use XEmacs is to start it only once, just
2568 after you log in, and do all your editing in the same Emacs process.
2569 Each time you want to edit a file, you visit it using the existing
2570 Emacs. Emacs creates a new buffer for each file, and (unless you kill
2571 some of the buffers) Emacs eventually has many files in it ready for
2572 editing. Usually you do not kill the Emacs process until you are about
2573 to log out. Since you usually read files by typing commands to Emacs,
2574 command line arguments for specifying a file when Emacs is started are
2577 Emacs accepts command-line arguments that specify files to visit,
2578 functions to call, and other activities and operating modes. If you
2579 are running XEmacs under the X window system, a number of standard Xt
2580 command line arguments are available, as well as a few X parameters
2581 that are XEmacs-specific.
2583 Options with long names with a single initial hyphen are also
2584 recognized with the GNU double initial hyphen syntax. (The reverse is
2587 The following subsections list:
2588 * Command line arguments that you can always use
2590 * Command line arguments that have to appear at the beginning of the
2593 * Command line arguments that are only relevant if you are running
2596 3.2.1 Command Line Arguments for Any Position
2597 ---------------------------------------------
2599 Command line arguments are processed in the order they appear on the
2600 command line; however, certain arguments (the ones in the second table)
2601 must be at the front of the list if they are used.
2603 Here are the arguments allowed:
2606 Visit FILE using `find-file'. *Note Visiting::.
2609 Visit FILE using `find-file', then go to line number LINENUM in it.
2613 Load a file FILE of Lisp code with the function `load'. *Note
2618 Call Lisp function FUNCTION with no arguments.
2621 Interpret the next argument as a Lisp expression, and evaluate it.
2622 You must be very careful of the shell quoting here.
2626 Insert the contents of FILE into the current buffer. This is like
2627 what `M-x insert-buffer' does; *Note Misc File Ops::.
2630 Exit from Emacs without asking for confirmation. Always the last
2631 argument processed, no matter where it appears in the command line.
2635 Prints version information. This implies `-batch'.
2638 XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs]
2641 Prints a summary of command-line options and then exits.
2643 3.2.2 Command Line Arguments (Beginning of Line Only)
2644 -----------------------------------------------------
2646 The following arguments are recognized only at the beginning of the
2647 command line. If more than one of them appears, they must appear in the
2648 order in which they appear in this table.
2652 Print the ID for the new portable dumper's dump file on the
2653 terminal and exit. (Prints an error message and exits if XEmacs
2654 was not configured `--pdump'.)
2658 Don't load the dump file. Roughly equivalent to old temacs.
2659 (Ignored if XEmacs was not configured `--pdump'.)
2663 Use FILE instead of the terminal for input and output. This
2664 implies the `-nw' option, documented below.
2667 Run Emacs in "batch mode", which means that the text being edited
2668 is not displayed and the standard Unix interrupt characters such as
2669 `C-z' and `C-c' continue to have their normal effect. Emacs in
2670 batch mode outputs to `stderr' only what would normally be printed
2671 in the echo area under program control.
2673 Batch mode is used for running programs written in Emacs Lisp from
2674 shell scripts, makefiles, and so on. Normally the `-l' switch or
2675 `-f' switch will be used as well, to invoke a Lisp program to do
2676 the batch processing.
2678 `-batch' implies `-q' (do not load an init file). It also causes
2679 Emacs to kill itself after all command switches have been
2680 processed. In addition, auto-saving is not done except in buffers
2681 for which it has been explicitly requested.
2685 Start up XEmacs in TTY mode (using the TTY XEmacs was started
2686 from), rather than trying to connect to an X display. Note that
2687 this happens automatically if the `DISPLAY' environment variable
2691 Enter the debugger if an error in the init file occurs.
2694 Displays information on how XEmacs constructs the various paths
2695 into its hierarchy on startup. (See also *note Startup Paths::.)
2698 Do not map the initial frame. This is useful if you want to start
2699 up XEmacs as a server (e.g. for gnuserv screens or external client
2704 Do not load your Emacs init file. *Note Init File::.
2707 Do not load the site-specific init file `lisp/site-start.el'.
2710 Do not load global symbol files (`auto-autoloads') at startup.
2711 This implies `-vanilla'.
2713 `-no-early-packages'
2714 Do not process early packages. (For more information on startup
2715 issues concerning the package system, *Note Startup Paths::.)
2718 This is equivalent to `-q -no-site-file -no-early-packages'.
2720 `-user-init-file FILE'
2721 Load FILE as your Emacs init file instead of
2722 `~/.xemacs/init.el'/`~/.emacs'.
2724 `-user-init-directory DIRECTORY'
2725 Use DIRECTORY as the location of your early package hierarchies
2726 and the various user-specific initialization files.
2730 Equivalent to `-user-init-file ~USER/.xemacs/init.el
2731 -user-init-directory ~USER/.xemacs', or `-user-init-file
2732 ~USER/.emacs -user-init-directory ~USER/.xemacs', whichever init
2733 file comes first. *Note Init File::.
2736 Note that the init file can get access to the command line argument
2737 values as the elements of a list in the variable `command-line-args'.
2738 (The arguments in the second table above will already have been
2739 processed and will not be in the list.) The init file can override the
2740 normal processing of the other arguments by setting this variable.
2742 One way to use command switches is to visit many files automatically:
2746 passes each `.c' file as a separate argument to Emacs, so that Emacs
2747 visits each file (*note Visiting::).
2749 Here is an advanced example that assumes you have a Lisp program file
2750 called `hack-c-program.el' which, when loaded, performs some useful
2751 operation on the current buffer, expected to be a C program.
2753 xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
2755 Here Emacs is told to visit `foo.c', load `hack-c-program.el' (which
2756 makes changes in the visited file), save `foo.c' (note that
2757 `save-buffer' is the function that `C-x C-s' is bound to), and then
2758 exit to the shell from which the command was executed. `-batch'
2759 guarantees there will be no problem redirecting output to `log',
2760 because Emacs will not assume that it has a display terminal to work
2763 3.2.3 Command Line Arguments (for XEmacs Under X)
2764 -------------------------------------------------
2766 If you are running XEmacs under X, a number of options are available to
2767 control color, border, and window title and icon name:
2772 Use TITLE as the window title. This sets the `frame-title-format'
2773 variable, which controls the title of the X window corresponding
2774 to the selected frame. This is the same format as
2779 Use TITLE as the icon name. This sets the
2780 `frame-icon-title-format' variable, which controls the title of
2781 the icon corresponding to the selected frame.
2784 Use COLOR as the mouse color.
2787 Use COLOR as the text-cursor foreground color.
2790 Install a private colormap for XEmacs.
2792 In addition, XEmacs allows you to use a number of standard Xt
2793 command line arguments.
2797 Use COLOR as the background color.
2799 `-bordercolor COLOR'
2801 Use COLOR as the border color.
2803 `-borderwidth WIDTH'
2805 Use WIDTH as the border width.
2809 When running under the X window system, create the window
2810 containing the Emacs frame on the display named DISPLAY.
2814 Use COLOR as the foreground color.
2818 Use NAME as the default font.
2823 Use the geometry (window size and/or position) specified by SPEC.
2829 Bring up Emacs in reverse video.
2832 Use the resource manager resources specified by NAME. The default
2833 is to use the name of the program (`argv[0]') as the resource
2837 Read something into the resource database for this invocation of
2842 File: xemacs.info, Node: Startup Paths, Next: Packages, Prev: Command Switches, Up: Top
2844 3.3 How XEmacs finds Directories and Files
2845 ==========================================
2847 XEmacs deals with a multitude of files during operation. These files
2848 are spread over many directories, and XEmacs determines the location of
2849 most of these directories at startup and organizes them into various
2850 paths. (A "path", for the purposes of this section, is simply a list
2851 of directories which XEmacs searches successively in order to locate a
2854 3.3.1 XEmacs Directory Hierarchies
2855 ----------------------------------
2857 Many of the files XEmacs looks for are located within the XEmacs
2858 installation itself. However, there are several views of what actually
2859 constitutes the "XEmacs installation": XEmacs may be run from the
2860 compilation directory, it may be installed into arbitrary directories,
2861 spread over several directories unrelated to each other. Moreover, it
2862 may subsequently be moved to a different place. (This last case is not
2863 as uncommon as it sounds. Binary kits work this way.) Consequently,
2864 XEmacs has quite complex procedures in place to find directories, no
2865 matter where they may be hidden.
2867 XEmacs will always respect directory options passed to `configure'.
2868 However, if it cannot locate a directory at the configured place, it
2869 will initiate a search for the directory in any of a number of
2870 "hierarchies" rooted under a directory which XEmacs assumes contain
2871 parts of the XEmacs installation; it may locate several such hierarchies
2872 and search across them. (Typically, there are just one or two
2873 hierarchies: the hierarchy where XEmacs was or will be installed, and
2874 the one where it is being built.) Such a directory containing a
2875 hierarchy is called a "root". Whenever this section refers to a
2876 directory using the shorthand `<root>', it means that XEmacs searches
2877 for it under all hierarchies XEmacs was able to scrounge up. In a
2878 running XEmacs, the hierarchy roots are stored in the variable
2881 3.3.2 Package Hierarchies
2882 -------------------------
2884 Many relevant directories and files XEmacs uses are actually not part of
2885 the core installation. They are part of any of the many packages
2886 usually installed on top of an XEmacs installation. (*Note Packages::.)
2887 Hence, they play a prominent role in the various paths XEmacs sets up.
2889 XEmacs locates packages in any of a number of package hierarchies.
2890 Package hierarchies fall into three groups: "early", "late", and "last", according
2891 to the relative location at which they show up in the various XEmacs
2892 paths. Early package hierarchies are at the very front, late ones
2893 somewhere in the middle, and last hierarchies are (you guessed it) last.
2895 By default, XEmacs expects an early package hierarchy in the
2896 subdirectory `.xemacs/xemacs-packages' of the user's home directory.
2898 Moreover, XEmacs expects late hierarchies in the subdirectories
2899 `site-packages', `mule-packages', and `xemacs-packages' (in that order)
2900 of the `<root>/lib/xemacs' subdirectory of one of the installation
2901 hierarchies. (If you run in-place, these are direct subdirectories of
2902 the build directory.) Furthermore, XEmacs will also search these
2903 subdirectories in the `<root>/lib/xemacs-<VERSION>' subdirectory and
2904 prefer directories found there.
2906 By default, XEmacs does not have a pre-configured last package
2907 hierarchy. Last hierarchies are primarily for using package hierarchies
2908 of outdated versions of XEmacs as a fallback option. For example, it is
2909 possible to run XEmacs 21 with the 20.4 package hierarchy as a last
2912 It is possible to specify at configure-time the location of the
2913 various package hierarchies with the `--package-path' option to
2914 configure. The early, late, and last components of the package path
2915 are separated by double instead of single colons. If all three
2916 components are present, they locate the early, late, and last package
2917 hierarchies respectively. If two components are present, they locate
2918 the early and late hierarchies. If only one component is present, it
2919 locates the late hierarchy. At run time, the package path may also be
2920 specified via the `EMACSPACKAGEPATH' environment variable.
2922 An XEmacs package is laid out just like a normal installed XEmacs
2923 lisp directory. It may have `lisp', `etc', `info', and `lib-src'
2924 subdirectories. XEmacs adds these at appropriate places within the
2925 various system-wide paths.
2927 There may be any number of package hierarchy directories.
2929 3.3.3 Directories and Paths
2930 ---------------------------
2932 Here is a list of the various directories and paths XEmacs tries to
2933 locate during startup. XEmacs distinguishes between directories and
2934 paths specific to "version", "site", and "architecture" when looking
2938 directories are specific to the version of XEmacs they belong to
2939 and typically reside under `<root>/lib/xemacs-<VERSION>'.
2942 directories are independent of the version of XEmacs they belong
2943 to and typically reside under `<root>/lib/xemacs'
2945 `architecture-specific'
2946 directories are specific both to the version of XEmacs and the
2947 architecture it runs on and typically reside under
2948 `<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>'.
2950 During installation, all of these directories may also reside
2951 directly under `<root>', because that is where they are in the XEmacs
2954 If XEmacs runs with the `-debug-paths' option (*note Command
2955 Switches::), it will print the values of these variables, hopefully
2956 aiding in debugging any problems which come up.
2959 Contains the version-specific location of the Lisp files that come
2960 with the core distribution of XEmacs. XEmacs will search it
2961 recursively to a depth of 1 when setting up `load-path'.
2964 Is where XEmacs searches for XEmacs Lisp files with commands like
2965 `load-library'. It contains the package lisp directories (see
2966 further down) and the version-specific core Lisp directories. If
2967 the environment variable `EMACSLOADPATH' is set at startup, its
2968 directories are prepended to `load-path'.
2970 `Info-directory-list'
2971 Contains the location of info files. (See *Note (info)::.) It
2972 contains the package info directories and the version-specific core
2973 documentation. Moreover, XEmacs will add `/usr/info',
2974 `/usr/local/info' as well as the directories of the environment
2975 variable `INFOPATH' to `Info-directory-list'.
2978 Is the directory of architecture-dependent files that come with
2979 XEmacs, especially executable programs intended for XEmacs to
2983 Is the path for executables which XEmacs may want to start. It
2984 contains the package executable paths as well as `exec-directory',
2985 and the directories of the environment variables `PATH' and
2989 Is the directory containing the architecture-specific `DOC' file
2990 that contains documentation for XEmacs' commands.
2993 Is the version-specific directory that contains core data files
2994 XEmacs uses. It may be initialized from the `EMACSDATA' environment
2997 `data-directory-list'
2998 Is the path where XEmacs looks for data files. It contains
2999 package data directories as well as `data-directory'.
3003 File: xemacs.info, Node: Basic, Next: Undo, Prev: Packages, Up: Top
3005 4 Basic Editing Commands
3006 ************************
3008 We now give the basics of how to enter text, make corrections, and save
3009 the text in a file. If this material is new to you, you might learn it
3010 more easily by running the Emacs learn-by-doing tutorial. To use the
3011 tutorial, run Emacs and type `Control-h t' (`help-with-tutorial'). You
3012 can also use Tutorials item from the Help menu.
3014 XEmacs comes with many translations of tutorial. If your XEmacs is
3015 with MULE and you set up language environment correctly, XEmacs chooses
3016 right tutorial when available (*note Language Environments::). If you
3017 want specific translation, give `C-h t' a prefix argument, like `C-u
3020 To clear the screen and redisplay, type `C-l' (`recenter').
3025 * Inserting Text:: Inserting text by simply typing it.
3026 * Moving Point:: How to move the cursor to the place where you want to
3028 * Erasing:: Deleting and killing text.
3029 * Files: Basic Files. Visiting, creating, and saving files.
3030 * Help: Basic Help. Asking what a character does.
3031 * Blank Lines:: Commands to make or delete blank lines.
3032 * Continuation Lines:: Lines too wide for the screen.
3033 * Position Info:: What page, line, row, or column is point on?
3034 * Arguments:: Numeric arguments for repeating a command.
3037 File: xemacs.info, Node: Inserting Text, Next: Moving Point, Up: Basic
3042 To insert printing characters into the text you are editing, just type
3043 them. This inserts the characters you type into the buffer at the
3044 cursor (that is, at "point"; *note Point::). The cursor moves forward,
3045 and any text after the cursor moves forward too. If the text in the
3046 buffer is `FOOBAR', with the cursor before the `B', then if you type
3047 `XX', you get `FOOXXBAR', with the cursor still before the `B'.
3049 To "delete" text you have just inserted, use <BS>. <BS> deletes the
3050 character _before_ the cursor (not the one that the cursor is on top of
3051 or under; that is the character AFTER the cursor). The cursor and all
3052 characters after it move backwards. Therefore, if you type a printing
3053 character and then type <BS>, they cancel out.
3055 To end a line and start typing a new one, type <RET>. This inserts
3056 a newline character in the buffer. If point is in the middle of a
3057 line, <RET> splits the line. Typing <DEL> when the cursor is at the
3058 beginning of a line deletes the preceding newline, thus joining the
3059 line with the preceding line.
3061 Emacs can split lines automatically when they become too long, if you
3062 turn on a special minor mode called "Auto Fill" mode. *Note Filling::,
3063 for how to use Auto Fill mode.
3065 If you prefer to have text characters replace (overwrite) existing
3066 text rather than shove it to the right, you can enable Overwrite mode,
3067 a minor mode. *Note Minor Modes::.
3069 Direct insertion works for printing characters and <SPC>, but other
3070 characters act as editing commands and do not insert themselves. If you
3071 need to insert a control character or a character whose code is above
3072 200 octal, you must "quote" it by typing the character `Control-q'
3073 (`quoted-insert') first. (This character's name is normally written
3074 `C-q' for short.) There are two ways to use `C-q':
3076 * `C-q' followed by any non-graphic character (even `C-g') inserts
3079 * `C-q' followed by a sequence of octal digits inserts the character
3080 with the specified octal character code. You can use any number of
3081 octal digits; any non-digit terminates the sequence. If the
3082 terminating character is <RET>, it serves only to terminate the
3083 sequence; any other non-digit is itself used as input after
3084 terminating the sequence. (The use of octal sequences is disabled
3085 in ordinary non-binary Overwrite mode, to give you a convenient
3086 way to insert a digit instead of overwriting with it.)
3088 A numeric argument to `C-q' specifies how many copies of the quoted
3089 character should be inserted (*note Arguments::).
3091 Customization information: <DEL>, in most modes, runs the command
3092 `backward-or-forward-delete-char'; <RET> runs the command `newline',
3093 and self-inserting printing characters run the command `self-insert',
3094 which inserts whatever character was typed to invoke it. Some major
3095 modes rebind <DEL> to other commands.
3098 File: xemacs.info, Node: Moving Point, Next: Erasing, Prev: Inserting Text, Up: Basic
3100 4.2 Changing the Location of Point
3101 ==================================
3103 To do more than insert characters, you have to know how to move point
3104 (*note Point::). The simplest way to do this is with arrow keys, or by
3105 clicking the left mouse button where you want to move to.
3107 NOTE: Many of the following commands have two versions, one that uses
3108 the function keys (e.g. <LEFT> or <END>) and one that doesn't. The
3109 former versions may only be available on X terminals (i.e. not on
3110 TTY's), but the latter are available on all terminals.
3114 Move to the beginning of the line (`beginning-of-line').
3118 Move to the end of the line (`end-of-line').
3122 Move forward one character (`forward-char').
3126 Move backward one character (`backward-char').
3130 Move forward one word (`forward-word').
3134 Move backward one word (`backward-word').
3138 Move down one line, vertically (`next-line'). This command
3139 attempts to keep the horizontal position unchanged, so if you
3140 start in the middle of one line, you end in the middle of the
3141 next. When on the last line of text, `C-n' creates a new line and
3146 Move up one line, vertically (`previous-line').
3150 Move down one page, vertically (`scroll-up').
3154 Move up one page, vertically (`scroll-down').
3157 Clear the frame and reprint everything (`recenter'). Text moves
3158 on the frame to bring point to the center of the window.
3161 Move point to left margin, vertically centered in the window
3162 (`move-to-window-line'). Text does not move on the screen.
3164 A numeric argument says which screen line to place point on. It
3165 counts screen lines down from the top of the window (zero for the
3166 top line). A negative argument counts lines from the bottom (-1
3167 for the bottom line).
3170 Transpose two characters, the ones before and after the cursor
3171 (`transpose-chars').
3175 Move to the top of the buffer (`beginning-of-buffer'). With
3176 numeric argument N, move to N/10 of the way from the top. *Note
3177 Arguments::, for more information on numeric arguments.
3181 Move to the end of the buffer (`end-of-buffer').
3184 Read a number N and move point to buffer position N. Position 1
3185 is the beginning of the buffer.
3188 Read a number N and move point to line number N (`goto-line').
3189 Line 1 is the beginning of the buffer.
3191 `M-x set-goal-column'
3192 Use the current column of point as the "semi-permanent goal
3193 column" for `C-n' and `C-p' (`set-goal-column'). Henceforth, those
3194 commands always move to this column in each line moved into, or as
3195 close as possible given the contents of the line. This goal
3196 column remains in effect until canceled.
3198 `C-u M-x set-goal-column'
3199 Cancel the goal column. Henceforth, `C-n' and `C-p' once again
3200 try to avoid changing the horizontal position, as usual.
3202 If you set the variable `track-eol' to a non-`nil' value, then `C-n'
3203 and `C-p' when at the end of the starting line move to the end of
3204 another line. Normally, `track-eol' is `nil'. *Note Variables::, for
3205 how to set variables such as `track-eol'.
3207 Normally, `C-n' on the last line of a buffer appends a newline to
3208 it. If the variable `next-line-add-newlines' is `nil', then `C-n' gets
3209 an error instead (like `C-p' on the first line).
3212 File: xemacs.info, Node: Erasing, Next: Basic Files, Prev: Moving Point, Up: Basic
3218 Delete the character before or after point
3219 (`backward-or-forward-delete-char'). You can customize this
3220 behavior by setting the variable `delete-key-deletes-forward'.
3223 Delete the character after point (`delete-char').
3226 Kill to the end of the line (`kill-line').
3229 Kill forward to the end of the next word (`kill-word').
3232 Kill back to the beginning of the previous word
3233 (`backward-kill-word').
3235 You already know about the <DEL> key which deletes the character
3236 before point (that is, before the cursor). Another key, `Control-d'
3237 (`C-d' for short), deletes the character after point (that is, the
3238 character that the cursor is on). This shifts the rest of the text on
3239 the line to the left. If you type `C-d' at the end of a line, it joins
3240 together that line and the next line.
3242 To erase a larger amount of text, use the `C-k' key, which kills a
3243 line at a time. If you type `C-k' at the beginning or middle of a
3244 line, it kills all the text up to the end of the line. If you type
3245 `C-k' at the end of a line, it joins that line and the next line.
3247 *Note Killing::, for more flexible ways of killing text.
3250 File: xemacs.info, Node: Basic Files, Next: Basic Help, Prev: Erasing, Up: Basic
3255 The commands described above are sufficient for creating and altering
3256 text in an Emacs buffer; the more advanced Emacs commands just make
3257 things easier. But to keep any text permanently you must put it in a
3258 "file". Files are named units of text which are stored by the
3259 operating system for you to retrieve later by name. To look at or use
3260 the contents of a file in any way, including editing the file with
3261 Emacs, you must specify the file name.
3263 Consider a file named `/usr/rms/foo.c'. To begin editing this file
3266 C-x C-f /usr/rms/foo.c <RET>
3268 Here the file name is given as an "argument" to the command `C-x C-f'
3269 (`find-file'). That command uses the "minibuffer" to read the
3270 argument, and you type <RET> to terminate the argument (*note
3273 You can also use the Open... menu item from the File menu, then type
3274 the name of the file to the prompt.
3276 Emacs obeys the command by "visiting" the file: creating a buffer,
3277 copying the contents of the file into the buffer, and then displaying
3278 the buffer for you to edit. If you alter the text, you can "save" the
3279 new text in the file by typing `C-x C-s' (`save-buffer') or choosing
3280 Save Buffer from the File menu. This makes the changes permanent by
3281 copying the altered buffer contents back into the file
3282 `/usr/rms/foo.c'. Until you save, the changes exist only inside Emacs,
3283 and the file `foo.c' is unaltered.
3285 To create a file, visit the file with `C-x C-f' as if it already
3286 existed or choose Open... from the File menu and provide the name for
3287 the new file. Emacs will create an empty buffer in which you can
3288 insert the text you want to put in the file. When you save the buffer
3289 with `C-x C-s', or by choosing Save Buffer from the File menu, the file
3292 To learn more about using files, *Note Files::.
3295 File: xemacs.info, Node: Basic Help, Next: Blank Lines, Prev: Basic Files, Up: Basic
3300 If you forget what a key does, you can find out with the Help
3301 character, which is `C-h' (or <F1>, which is an alias for `C-h'). Type
3302 `C-h k' followed by the key you want to know about; for example, `C-h k
3303 C-n' tells you all about what `C-n' does. `C-h' is a prefix key; `C-h
3304 k' is just one of its subcommands (the command `describe-key'). The
3305 other subcommands of `C-h' provide different kinds of help. Type `C-h'
3306 twice to get a description of all the help facilities. *Note Help::.
3309 File: xemacs.info, Node: Blank Lines, Next: Continuation Lines, Prev: Basic Help, Up: Basic
3314 Here are special commands and techniques for putting in and taking out
3318 Insert one or more blank lines after the cursor (`open-line').
3321 Delete all but one of many consecutive blank lines
3322 (`delete-blank-lines').
3324 When you want to insert a new line of text before an existing line,
3325 you can do it by typing the new line of text, followed by <RET>.
3326 However, it may be easier to see what you are doing if you first make a
3327 blank line and then insert the desired text into it. This is easy to do
3328 using the key `C-o' (`open-line'), which inserts a newline after point
3329 but leaves point in front of the newline. After `C-o', type the text
3330 for the new line. `C-o F O O' has the same effect as `F O O <RET>',
3331 except for the final location of point.
3333 You can make several blank lines by typing `C-o' several times, or
3334 by giving it a numeric argument to tell it how many blank lines to make.
3335 *Note Arguments::, for how. If you have a fill prefix, then `C-o'
3336 command inserts the fill prefix on the new line, when you use it at the
3337 beginning of a line. *Note Fill Prefix::.
3339 The easy way to get rid of extra blank lines is with the command
3340 `C-x C-o' (`delete-blank-lines'). `C-x C-o' in a run of several blank
3341 lines deletes all but one of them. `C-x C-o' on a solitary blank line
3342 deletes that blank line. When point is on a nonblank line, `C-x C-o'
3343 deletes any blank lines following that nonblank line.
3346 File: xemacs.info, Node: Continuation Lines, Next: Position Info, Prev: Blank Lines, Up: Basic
3348 4.7 Continuation Lines
3349 ======================
3351 If you add too many characters to one line without breaking it with
3352 <RET>, the line will grow to occupy two (or more) lines on the screen,
3353 with a curved arrow at the extreme right margin of all but the last of
3354 them. The curved arrow says that the following screen line is not
3355 really a distinct line in the text, but just the "continuation" of a
3356 line too long to fit the screen. Continuation is also called "line
3359 Sometimes it is nice to have Emacs insert newlines automatically when
3360 a line gets too long. Continuation on the screen does not do that. Use
3361 Auto Fill mode (*note Filling::) if that's what you want.
3363 Instead of continuation, long lines can be displayed by "truncation".
3364 This means that all the characters that do not fit in the width of the
3365 frame or window do not appear at all. They remain in the buffer,
3366 temporarily invisible. Right arrow in the last column (instead of the
3367 curved arrow) inform you that truncation is in effect.
3369 Truncation instead of continuation happens whenever horizontal
3370 scrolling is in use, and optionally in all side-by-side windows (*note
3371 Windows::). You can enable truncation for a particular buffer by
3372 setting the variable `truncate-lines' to non-`nil' in that buffer.
3373 (*Note Variables::.) Altering the value of `truncate-lines' makes it
3374 local to the current buffer; until that time, the default value is in
3375 effect. The default is initially `nil'. *Note Locals::.
3377 *Note Display Vars::, for additional variables that affect how text
3381 File: xemacs.info, Node: Position Info, Next: Arguments, Prev: Continuation Lines, Up: Basic
3383 4.8 Cursor Position Information
3384 ===============================
3386 If you are accustomed to other display editors, you may be surprised
3387 that Emacs does not always display the page number or line number of
3388 point in the mode line. In Emacs, this information is only rarely
3389 needed, and a number of commands are available to compute and print it.
3390 Since text is stored in a way that makes it difficult to compute the
3391 information, it is not displayed all the time.
3394 Print page number of point, and line number within page.
3397 Print line number of point in the buffer.
3399 `M-x line-number-mode'
3400 Toggle automatic display of current line number.
3403 Print number of lines and characters in the current region
3404 (`count-lines-region'). *Note Mark::, for information about the
3408 Print character code of character after point, character position
3409 of point, and column of point (`what-cursor-position').
3411 There are several commands for printing line numbers:
3413 * `M-x what-line' counts lines from the beginning of the file and
3414 prints the line number point is on. The first line of the file is
3415 line number 1. You can use these numbers as arguments to `M-x
3418 * `M-x what-page' counts pages from the beginning of the file, and
3419 counts lines within the page, printing both of them. *Note
3420 Pages::, for the command `C-x l', which counts the lines in the
3423 * `M-=' (`count-lines-region') prints the number of lines in the
3424 region (*note Mark::). *Note Pages::, for the command `C-x l'
3425 which counts the lines in the
3427 The command `C-x =' (`what-cursor-position') can be used to find out
3428 the column that the cursor is in, and other miscellaneous information
3429 about point. It prints a line in the echo area that looks like this:
3431 Char: c (0143, 99, 0x63) point=18862 of 24800(76%) column 53
3433 (In fact, this is the output produced when point is before `column 53'
3436 The four values after `Char:' describe the character that follows
3437 point, first by showing it and then by giving its character code in
3438 octal, decimal and hex.
3440 `point=' is followed by the position of point expressed as a
3441 character count. The front of the buffer counts as position 1, one
3442 character later as 2, and so on. The next, larger number is the total
3443 number of characters in the buffer. Afterward in parentheses comes the
3444 position expressed as a percentage of the total size.
3446 `column' is followed by the horizontal position of point, in columns
3447 from the left edge of the window.
3449 If the buffer has been narrowed, making some of the text at the
3450 beginning and the end temporarily invisible, `C-x =' prints additional
3451 text describing the current visible range. For example, it might say:
3453 Char: c (0143, 99, 0x63) point=19674 of 24575(80%) <19591 - 19703> column 69
3455 where the two extra numbers give the smallest and largest character
3456 position that point is allowed to assume. The characters between those
3457 two positions are the visible ones. *Note Narrowing::.
3459 If point is at the end of the buffer (or the end of the visible
3460 part), `C-x =' omits any description of the character after point. The
3463 point=563026 of 563025(100%) column 0
3466 File: xemacs.info, Node: Arguments, Prev: Position Info, Up: Basic
3468 4.9 Numeric Arguments
3469 =====================
3471 In mathematics and computer usage, the word "argument" means "data
3472 provided to a function or operation." Any Emacs command can be given a
3473 "numeric argument" (also called a "prefix argument"). Some commands
3474 interpret the argument as a repetition count. For example, giving an
3475 argument of ten to the key `C-f' (the command `forward-char', move
3476 forward one character) moves forward ten characters. With these
3477 commands, no argument is equivalent to an argument of one. Negative
3478 arguments are allowed. Often they tell a command to move or act in
3479 the opposite direction.
3481 If your keyboard has a <META> key (labelled with a diamond on
3482 Sun-type keyboards and labelled `Alt' on some other keyboards), the
3483 easiest way to specify a numeric argument is to type digits and/or a
3484 minus sign while holding down the <META> key. For example,
3486 would move down five lines. The characters `Meta-1', `Meta-2', and
3487 so on, as well as `Meta--', do this because they are keys bound to
3488 commands (`digit-argument' and `negative-argument') that are defined to
3489 contribute to an argument for the next command. Digits and `-'
3490 modified with Control, or Control and Meta, also specify numeric
3493 Another way of specifying an argument is to use the `C-u'
3494 (`universal-argument') command followed by the digits of the argument.
3495 With `C-u', you can type the argument digits without holding down
3496 modifier keys; `C-u' works on all terminals. To type a negative
3497 argument, type a minus sign after `C-u'. Just a minus sign without
3498 digits normally means -1.
3500 `C-u' followed by a character which is neither a digit nor a minus
3501 sign has the special meaning of "multiply by four". It multiplies the
3502 argument for the next command by four. `C-u' twice multiplies it by
3503 sixteen. Thus, `C-u C-u C-f' moves forward sixteen characters. This
3504 is a good way to move forward "fast", since it moves about 1/5 of a line
3505 in the usual size frame. Other useful combinations are `C-u C-n', `C-u
3506 C-u C-n' (move down a good fraction of a frame), `C-u C-u C-o' (make "a
3507 lot" of blank lines), and `C-u C-k' (kill four lines).
3509 Some commands care only about whether there is an argument and not
3510 about its value. For example, the command `M-q' (`fill-paragraph') with
3511 no argument fills text; with an argument, it justifies the text as well.
3512 (*Note Filling::, for more information on `M-q'.) Just `C-u' is a
3513 handy way of providing an argument for such commands.
3515 Some commands use the value of the argument as a repeat count, but do
3516 something peculiar when there is no argument. For example, the command
3517 `C-k' (`kill-line') with argument N kills N lines, including their
3518 terminating newlines. But `C-k' with no argument is special: it kills
3519 the text up to the next newline, or, if point is right at the end of
3520 the line, it kills the newline itself. Thus, two `C-k' commands with
3521 no arguments can kill a non-blank line, just like `C-k' with an
3522 argument of one. (*Note Killing::, for more information on `C-k'.)
3524 A few commands treat a plain `C-u' differently from an ordinary
3525 argument. A few others may treat an argument of just a minus sign
3526 differently from an argument of -1. These unusual cases are described
3527 when they come up; they are always for reasons of convenience of use of
3528 the individual command.
3530 You can use a numeric argument to insert multiple copies of a
3531 character. This is straightforward unless the character is a digit; for
3532 example, `C-u 6 4 a' inserts 64 copies of the character `a'. But this
3533 does not work for inserting digits; `C-u 6 4 1' specifies an argument
3534 of 641, rather than inserting anything. To separate the digit to
3535 insert from the argument, type another `C-u'; for example, `C-u 6 4 C-u
3536 1' does insert 64 copies of the character `1'.
3538 We use the term "prefix argument" as well as "numeric argument" to
3539 emphasize that you type the argument before the command, and to
3540 distinguish these arguments from minibuffer arguments that come after
3544 File: xemacs.info, Node: Undo, Next: Minibuffer, Prev: Basic, Up: Top
3549 Emacs allows you to undo all changes you make to the text of a buffer,
3550 up to a certain amount of change (8000 characters). Each buffer records
3551 changes individually, and the undo command always applies to the
3552 current buffer. Usually each editing command makes a separate entry in
3553 the undo records, but some commands such as `query-replace' make many
3554 entries, and very simple commands such as self-inserting characters are
3555 often grouped to make undoing less tedious.
3558 Undo one batch of changes (usually, one command's worth) (`undo').
3563 The command `C-x u' or `C-_' allows you to undo changes. The first
3564 time you give this command, it undoes the last change. Point moves to
3565 the text affected by the undo, so you can see what was undone.
3567 Consecutive repetitions of the `C-_' or `C-x u' commands undo
3568 earlier and earlier changes, back to the limit of what has been
3569 recorded. If all recorded changes have already been undone, the undo
3570 command prints an error message and does nothing.
3572 Any command other than an undo command breaks the sequence of undo
3573 commands. Starting at this moment, the previous undo commands are
3574 considered ordinary changes that can themselves be undone. Thus, you
3575 can redo changes you have undone by typing `C-f' or any other command
3576 that have no important effect, and then using more undo commands.
3578 If you notice that a buffer has been modified accidentally, the
3579 easiest way to recover is to type `C-_' repeatedly until the stars
3580 disappear from the front of the mode line. When that happens, all the
3581 modifications you made have been canceled. If you do not remember
3582 whether you changed the buffer deliberately, type `C-_' once. When you
3583 see Emacs undo the last change you made, you probably remember why you
3584 made it. If the change was an accident, leave it undone. If it was
3585 deliberate, redo the change as described in the preceding paragraph.
3587 Whenever an undo command makes the stars disappear from the mode
3588 line, the buffer contents is the same as it was when the file was last
3591 Not all buffers record undo information. Buffers whose names start
3592 with spaces don't; these buffers are used internally by Emacs and its
3593 extensions to hold text that users don't normally look at or edit.
3594 Minibuffers, help buffers, and documentation buffers also don't record
3597 Emacs can remember at most 8000 or so characters of deleted or
3598 modified text in any one buffer for reinsertion by the undo command.
3599 There is also a limit on the number of individual insert, delete, or
3600 change actions that Emacs can remember.
3602 There are two keys to run the `undo' command, `C-x u' and `C-_',
3603 because on some keyboards, it is not obvious how to type `C-_'. `C-x u'
3604 is an alternative you can type in the same fashion on any terminal.
3607 File: xemacs.info, Node: Minibuffer, Next: M-x, Prev: Undo, Up: Top
3612 The "minibuffer" is the facility used by XEmacs commands to read
3613 arguments more complicated than a single number. Minibuffer arguments
3614 can be file names, buffer names, Lisp function names, XEmacs command
3615 names, Lisp expressions, and many other things, depending on the command
3616 reading the argument. You can use the usual XEmacs editing commands in
3617 the minibuffer to edit the argument text.
3619 When the minibuffer is in use, it appears in the echo area, and the
3620 cursor moves there. The beginning of the minibuffer line displays a
3621 "prompt" which says what kind of input you should supply and how it
3622 will be used. Often this prompt is derived from the name of the command
3623 that the argument is for. The prompt normally ends with a colon.
3625 Sometimes a "default argument" appears in parentheses after the
3626 colon; it, too, is part of the prompt. The default is used as the
3627 argument value if you enter an empty argument (e.g., by just typing
3628 <RET>). For example, commands that read buffer names always show a
3629 default, which is the name of the buffer that will be used if you type
3632 The simplest way to enter a minibuffer argument is to type the text
3633 you want, terminated by <RET> which exits the minibuffer. You can
3634 cancel the command that wants the argument, and get out of the
3635 minibuffer, by typing `C-g'.
3637 Since the minibuffer uses the screen space of the echo area, it can
3638 conflict with other ways XEmacs customarily uses the echo area. Here is
3639 how XEmacs handles such conflicts:
3641 * If a command gets an error while you are in the minibuffer, this
3642 does not cancel the minibuffer. However, the echo area is needed
3643 for the error message and therefore the minibuffer itself is
3644 hidden for a while. It comes back after a few seconds, or as soon
3645 as you type anything.
3647 * If in the minibuffer you use a command whose purpose is to print a
3648 message in the echo area, such as `C-x =', the message is printed
3649 normally, and the minibuffer is hidden for a while. It comes back
3650 after a few seconds, or as soon as you type anything.
3652 * Echoing of keystrokes does not take place while the minibuffer is
3657 * File: Minibuffer File. Entering file names with the minibuffer.
3658 * Edit: Minibuffer Edit. How to edit in the minibuffer.
3659 * Completion:: An abbreviation facility for minibuffer input.
3660 * Minibuffer History:: Reusing recent minibuffer arguments.
3661 * Repetition:: Re-executing commands that used the minibuffer.
3664 File: xemacs.info, Node: Minibuffer File, Next: Minibuffer Edit, Prev: Minibuffer, Up: Minibuffer
3666 6.1 Minibuffers for File Names
3667 ==============================
3669 Sometimes the minibuffer starts out with text in it. For example, when
3670 you are supposed to give a file name, the minibuffer starts out
3671 containing the "default directory", which ends with a slash. This is
3672 to inform you which directory the file will be found in if you do not
3673 specify a directory.
3675 For example, the minibuffer might start out with these contents:
3677 Find File: /u2/emacs/src/
3679 where `Find File: ' is the prompt. Typing `buffer.c' specifies the
3680 file `/u2/emacs/src/buffer.c'. To find files in nearby directories,
3681 use `..'; thus, if you type `../lisp/simple.el', you will get the file
3682 named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with
3683 `M-<DEL>' the directory names you don't want (*note Words::).
3685 If you don't want any of the default, you can kill it with `C-a
3686 C-k'. But you don't need to kill the default; you can simply ignore it.
3687 Insert an absolute file name, one starting with a slash or a tilde,
3688 after the default directory. For example, to specify the file
3689 `/etc/termcap', just insert that name, giving these minibuffer contents:
3691 Find File: /u2/emacs/src//etc/termcap
3693 XEmacs gives a special meaning to a double slash (which is not normally
3694 a useful thing to write): it means, "ignore everything before the
3695 second slash in the pair." Thus, `/u2/emacs/src/' is ignored in the
3696 example above, and you get the file `/etc/termcap'.
3698 If you set `insert-default-directory' to `nil', the default
3699 directory is not inserted in the minibuffer. This way, the minibuffer
3700 starts out empty. But the name you type, if relative, is still
3701 interpreted with respect to the same default directory.
3704 File: xemacs.info, Node: Minibuffer Edit, Next: Completion, Prev: Minibuffer File, Up: Minibuffer
3706 6.2 Editing in the Minibuffer
3707 =============================
3709 The minibuffer is an XEmacs buffer (albeit a peculiar one), and the
3710 usual XEmacs commands are available for editing the text of an argument
3713 Since <RET> in the minibuffer is defined to exit the minibuffer, you
3714 can't use it to insert a newline in the minibuffer. To do that, type
3715 `C-o' or `C-q C-j'. (Recall that a newline is really the character
3718 The minibuffer has its own window which always has space on the
3719 screen but acts as if it were not there when the minibuffer is not in
3720 use. When the minibuffer is in use, its window is just like the
3721 others; you can switch to another window with `C-x o', edit text in
3722 other windows and perhaps even visit more files, before returning to the
3723 minibuffer to submit the argument. You can kill text in another window,
3724 return to the minibuffer window, and then yank the text to use it in the
3725 argument. *Note Windows::.
3727 There are some restrictions on the use of the minibuffer window,
3728 however. You cannot switch buffers in it--the minibuffer and its
3729 window are permanently attached. Also, you cannot split or kill the
3730 minibuffer window. But you can make it taller in the normal fashion with
3731 `C-x ^'. If you enable Resize-Minibuffer mode, then the minibuffer
3732 window expands vertically as necessary to hold the text that you put in
3733 the minibuffer. Use `M-x resize-minibuffer-mode' to enable or disable
3734 this minor mode (*note Minor Modes::).
3736 If while in the minibuffer you issue a command that displays help
3737 text of any sort in another window, you can use the `C-M-v' command
3738 while in the minibuffer to scroll the help text. This lasts until you
3739 exit the minibuffer. This feature is especially useful if a completing
3740 minibuffer gives you a list of possible completions. *Note Other
3743 If the variable `minibuffer-confirm-incomplete' is `t', you are
3744 asked for confirmation if there is no known completion for the text you
3745 typed. For example, if you attempted to visit a non-existent file, the
3746 minibuffer might read:
3747 Find File: chocolate_bar.c [no completions, confirm]
3748 If you press `Return' again, that confirms the filename. Otherwise,
3749 you can continue editing it.
3751 XEmacs supports recursive use of the minibuffer. However, it is easy
3752 to do this by accident (because of autorepeating keyboards, for example)
3753 and get confused. Therefore, most XEmacs commands that use the
3754 minibuffer refuse to operate if the minibuffer window is selected. If
3755 the minibuffer is active but you have switched to a different window,
3756 recursive use of the minibuffer is allowed--if you know enough to try
3757 to do this, you probably will not get confused.
3759 If you set the variable `enable-recursive-minibuffers' to a
3760 non-`nil', recursive use of the minibuffer is always allowed.
3763 File: xemacs.info, Node: Completion, Next: Minibuffer History, Prev: Minibuffer Edit, Up: Minibuffer
3768 For certain kinds of arguments, you can use "completion" to enter the
3769 argument value. Completion means that you type part of the argument,
3770 then XEmacs visibly fills in the rest, or as much as can be determined
3771 from the part you have typed.
3773 When completion is available, certain keys--<TAB>, <RET>, and
3774 <SPC>--are rebound to complete the text present in the minibuffer into
3775 a longer string that it stands for, by matching it against a set of
3776 "completion alternatives" provided by the command reading the argument.
3777 `?' is defined to display a list of possible completions of what you
3780 For example, when `M-x' uses the minibuffer to read the name of a
3781 command, it provides a list of all available XEmacs command names to
3782 complete against. The completion keys match the text in the minibuffer
3783 against all the command names, find any additional name characters
3784 implied by the ones already present in the minibuffer, and add those
3785 characters to the ones you have given. This is what makes it possible
3786 to type `M-x inse <SPC> b <RET>' instead of `M-x insert-buffer <RET>'
3789 Case is normally significant in completion because it is significant
3790 in most of the names that you can complete (buffer names, file names and
3791 command names). Thus, `fo' does not complete to `Foo'. When you are
3792 completing a name in which case does not matter, case may be ignored
3793 for completion's sake if specified by program.
3795 When a completion list is displayed, the completions will highlight
3796 as you move the mouse over them. Clicking the middle mouse button on
3797 any highlighted completion will "select" it just as if you had typed it
3802 * Example: Completion Example.
3803 * Commands: Completion Commands.
3804 * Strict Completion::
3805 * Options: Completion Options.
3808 File: xemacs.info, Node: Completion Example, Next: Completion Commands, Prev: Completion, Up: Completion
3810 6.3.1 Completion Example
3811 ------------------------
3813 A concrete example may help here. If you type `M-x au <TAB>', the
3814 <TAB> looks for alternatives (in this case, command names) that start
3815 with `au'. There are several, including `auto-fill-mode' and
3816 `auto-save-mode'--but they are all the same as far as `auto', so the
3817 `au' in the minibuffer changes to `auto'.
3819 If you type <TAB> again immediately, there are multiple
3820 possibilities for the very next character--it could be any of `c-'--so
3821 no more characters are added; instead, <TAB> displays a list of all
3822 possible completions in another window.
3824 If you go on to type `-f <TAB>', this <TAB> sees `auto-f'. The only
3825 command name starting this way is `auto-fill-mode', so completion fills
3826 in the rest of that. You now have `auto-fill-mode' in the minibuffer
3827 after typing just `au <TAB> f <TAB>'. Note that <TAB> has this effect
3828 because in the minibuffer it is bound to the command
3829 `minibuffer-complete' when completion is available.
3832 File: xemacs.info, Node: Completion Commands, Next: Strict Completion, Prev: Completion Example, Up: Completion
3834 6.3.2 Completion Commands
3835 -------------------------
3837 Here is a list of the completion commands defined in the minibuffer
3838 when completion is available.
3841 Complete the text in the minibuffer as much as possible
3842 (`minibuffer-complete').
3845 Complete the minibuffer text, but don't go beyond one word
3846 (`minibuffer-complete-word').
3849 Submit the text in the minibuffer as the argument, possibly
3850 completing first as described below
3851 (`minibuffer-complete-and-exit').
3854 Print a list of all possible completions of the text in the
3855 minibuffer (`minibuffer-list-completions').
3858 Select the highlighted text under the mouse as a minibuffer
3859 response. When the minibuffer is being used to prompt the user
3860 for a completion, any valid completions which are visible on the
3861 screen will be highlighted when the mouse moves over them.
3862 Clicking <button2> will select the highlighted completion and exit
3863 the minibuffer. (`minibuf-select-highlighted-completion').
3865 <SPC> completes much like <TAB>, but never goes beyond the next
3866 hyphen or space. If you have `auto-f' in the minibuffer and type
3867 <SPC>, it finds that the completion is `auto-fill-mode', but it stops
3868 completing after `fill-'. This gives `auto-fill-'. Another <SPC> at
3869 this point completes all the way to `auto-fill-mode'. <SPC> in the
3870 minibuffer when completion is available runs the command
3871 `minibuffer-complete-word'.
3873 Here are some commands you can use to choose a completion from a
3874 window that displays a list of completions:
3877 Clicking mouse button 2 on a completion in the list of possible
3878 completions chooses that completion (`mouse-choose-completion').
3879 You normally use this command while point is in the minibuffer;
3880 but you must click in the list of completions, not in the
3885 Typing <PRIOR> or `M-v', while in the minibuffer, selects the
3886 window showing the completion list buffer
3887 (`switch-to-completions'). This paves the way for using the
3888 commands below. (Selecting that window in the usual ways has the
3889 same effect, but this way is more convenient.)
3892 Typing <RET> _in the completion list buffer_ chooses the
3893 completion that point is in or next to (`choose-completion'). To
3894 use this command, you must first switch windows to the window that
3895 shows the list of completions.
3900 Typing the right-arrow key <RIGHT>, <TAB> or `C-f' _in the
3901 completion list buffer_ moves point to the following completion
3902 (`next-list-mode-item').
3906 Typing the left-arrow key <LEFT> or `C-b' _in the completion list
3907 buffer_ moves point toward the beginning of the buffer, to the
3908 previous completion (`previous-list-mode-item').
3911 File: xemacs.info, Node: Strict Completion, Next: Completion Options, Prev: Completion Commands, Up: Completion
3913 6.3.3 Strict Completion
3914 -----------------------
3916 There are three different ways that <RET> can work in completing
3917 minibuffers, depending on how the argument will be used.
3919 * "Strict" completion is used when it is meaningless to give any
3920 argument except one of the known alternatives. For example, when
3921 `C-x k' reads the name of a buffer to kill, it is meaningless to
3922 give anything but the name of an existing buffer. In strict
3923 completion, <RET> refuses to exit if the text in the minibuffer
3924 does not complete to an exact match.
3926 * "Cautious" completion is similar to strict completion, except that
3927 <RET> exits only if the text was an exact match already, not
3928 needing completion. If the text is not an exact match, <RET> does
3929 not exit, but it does complete the text. If it completes to an
3930 exact match, a second <RET> will exit.
3932 Cautious completion is used for reading file names for files that
3935 * "Permissive" completion is used when any string whatever is
3936 meaningful, and the list of completion alternatives is just a
3937 guide. For example, when `C-x C-f' reads the name of a file to
3938 visit, any file name is allowed, in case you want to create a
3939 file. In permissive completion, <RET> takes the text in the
3940 minibuffer exactly as given, without completing it.
3942 The completion commands display a list of all possible completions in
3943 a window whenever there is more than one possibility for the very next
3944 character. Also, typing `?' explicitly requests such a list. If the
3945 list of completions is long, you can scroll it with `C-M-v' (*note
3949 File: xemacs.info, Node: Completion Options, Prev: Strict Completion, Up: Completion
3951 6.3.4 Completion Options
3952 ------------------------
3954 When completion is done on file names, certain file names are usually
3955 ignored. The variable `completion-ignored-extensions' contains a list
3956 of strings; a file whose name ends in any of those strings is ignored
3957 as a possible completion. The standard value of this variable has
3958 several elements including `".o"', `".elc"', `".dvi"' and `"~"'. The
3959 effect is that, for example, `foo' can complete to `foo.c' even though
3960 `foo.o' exists as well. However, if _all_ the possible completions end
3961 in "ignored" strings, then they are not ignored. Ignored extensions do
3962 not apply to lists of completions--those always mention all possible
3965 If a completion command finds the next character is undetermined, it
3966 automatically displays a list of all possible completions. If the
3967 variable `completion-auto-help' is set to `nil', this does not happen,
3968 and you must type `?' to display the possible completions.
3970 If the variable `minibuffer-confirm-incomplete' is set to `t', then
3971 in contexts where `completing-read' allows answers that are not valid
3972 completions, an extra <RET> must be typed to confirm the response.
3973 This is helpful for catching typos.
3975 Icomplete mode presents a constantly-updated display that tells you
3976 what completions are available for the text you've entered so far. The
3977 command to enable or disable this minor mode is `M-x icomplete-mode'.
3980 File: xemacs.info, Node: Minibuffer History, Next: Repetition, Prev: Completion, Up: Minibuffer
3982 6.4 Minibuffer History
3983 ======================
3985 Every argument that you enter with the minibuffer is saved on a
3986 "minibuffer history list" so that you can use it again later in another
3987 argument. Special commands load the text of an earlier argument in the
3988 minibuffer. They discard the old minibuffer contents, so you can think
3989 of them as moving through the history of previous arguments.
3993 Move to the next earlier argument string saved in the minibuffer
3994 history (`previous-history-element').
3998 Move to the next later argument string saved in the minibuffer
3999 history (`next-history-element').
4002 Move to an earlier saved argument in the minibuffer history that
4003 has a match for REGEXP (`previous-matching-history-element').
4006 Move to a later saved argument in the minibuffer history that has a
4007 match for REGEXP (`next-matching-history-element').
4009 The simplest way to reuse the saved arguments in the history list is
4010 to move through the history list one element at a time. While in the
4011 minibuffer, use `M-p' or up-arrow (`previous-history-element') to "move
4012 to" the next earlier minibuffer input, and use `M-n' or down-arrow
4013 (`next-history-element') to "move to" the next later input.
4015 The previous input that you fetch from the history entirely replaces
4016 the contents of the minibuffer. To use it as the argument, exit the
4017 minibuffer as usual with <RET>. You can also edit the text before you
4018 reuse it; this does not change the history element that you "moved" to,
4019 but your new argument does go at the end of the history list in its own
4022 For many minibuffer arguments there is a "default" value. In some
4023 cases, the minibuffer history commands know the default value. Then you
4024 can insert the default value into the minibuffer as text by using `M-n'
4025 to move "into the future" in the history.
4027 There are also commands to search forward or backward through the
4028 history; they search for history elements that match a regular
4029 expression that you specify with the minibuffer. `M-r'
4030 (`previous-matching-history-element') searches older elements in the
4031 history, while `M-s' (`next-matching-history-element') searches newer
4032 elements. By special dispensation, these commands can use the
4033 minibuffer to read their arguments even though you are already in the
4034 minibuffer when you issue them. As with incremental searching, an
4035 uppercase letter in the regular expression makes the search
4036 case-sensitive (*note Search Case::).
4038 All uses of the minibuffer record your input on a history list, but
4039 there are separate history lists for different kinds of arguments. For
4040 example, there is a list for file names, used by all the commands that
4043 There are several other very specific history lists, including one
4044 for command names read by `M-x', one for buffer names, one for arguments
4045 of commands like `query-replace', and one for compilation commands read
4046 by `compile'. Finally, there is one "miscellaneous" history list that
4047 most minibuffer arguments use.
4050 File: xemacs.info, Node: Repetition, Prev: Minibuffer History, Up: Minibuffer
4052 6.5 Repeating Minibuffer Commands
4053 =================================
4055 Every command that uses the minibuffer at least once is recorded on a
4056 special history list, together with the values of its arguments, so that
4057 you can repeat the entire command. In particular, every use of `M-x'
4058 is recorded there, since `M-x' uses the minibuffer to read the command
4062 Re-execute a recent minibuffer command (`repeat-complex-command').
4065 Within `C-x <ESC> <ESC>', move to previous recorded command
4066 (`previous-history-element').
4069 Within `C-x <ESC> <ESC>', move to the next (more recent) recorded
4070 command (`next-history-element').
4072 `M-x list-command-history'
4073 Display the entire command history, showing all the commands `C-x
4074 <ESC> <ESC>' can repeat, most recent first.
4076 `C-x <ESC> <ESC>' is used to re-execute a recent minibuffer-using
4077 command. With no argument, it repeats the last such command. A
4078 numeric argument specifies which command to repeat; one means the last
4079 one, and larger numbers specify earlier ones.
4081 `C-x <ESC> <ESC>' works by turning the previous command into a Lisp
4082 expression and then entering a minibuffer initialized with the text for
4083 that expression. If you type just <RET>, the command is repeated as
4084 before. You can also change the command by editing the Lisp
4085 expression. Whatever expression you finally submit is what will be
4086 executed. The repeated command is added to the front of the command
4087 history unless it is identical to the most recently executed command
4090 Even if you don't understand Lisp syntax, it will probably be obvious
4091 which command is displayed for repetition. If you do not change the
4092 text, you can be sure the command will repeat exactly as before.
4094 If you are in the minibuffer for `C-x <ESC> <ESC>' and the command
4095 shown to you is not the one you want to repeat, you can move around the
4096 list of previous commands using `M-n' and `M-p'. `M-p' replaces the
4097 contents of the minibuffer with the next earlier recorded command, and
4098 `M-n' replaces it with the next later command. After finding the
4099 desired previous command, you can edit its expression and then resubmit
4100 it by typing <RET>. Any editing you have done on the command to be
4101 repeated is lost if you use `M-n' or `M-p'.
4103 `M-n' and `M-p' are specially defined within `C-x <ESC> <ESC>' to
4104 run the commands `previous-history-element' and `next-history-element'.
4106 The list of previous commands using the minibuffer is stored as a
4107 Lisp list in the variable `command-history'. Each element of the list
4108 is a Lisp expression which describes one command and its arguments.
4109 Lisp programs can reexecute a command by feeding the corresponding
4110 `command-history' element to `eval'.
4113 File: xemacs.info, Node: M-x, Next: Help, Prev: Minibuffer, Up: Top
4115 7 Running Commands by Name
4116 **************************
4118 The Emacs commands that are used often or that must be quick to type are
4119 bound to keys--short sequences of characters--for convenient use. Other
4120 Emacs commands that are used more rarely are not bound to keys; to run
4121 them, you must refer to them by name.
4123 A command name consists, by convention, of one or more words,
4124 separated by hyphens: for example, `auto-fill-mode' or `manual-entry'.
4125 The use of English words makes the command name easier to remember than
4126 a key made up of obscure characters, even though it results in more
4127 characters to type. You can run any command by name, even if it can be
4128 run by keys as well.
4130 To run a command by name, start with `M-x', then type the command
4131 name, and finish with <RET>. `M-x' uses the minibuffer to read the
4132 command name. <RET> exits the minibuffer and runs the command.
4134 Emacs uses the minibuffer for reading input for many different
4135 purposes; on this occasion, the string `M-x' is displayed at the
4136 beginning of the minibuffer as a "prompt" to remind you that your input
4137 should be the name of a command to be run. *Note Minibuffer::, for
4138 full information on the features of the minibuffer.
4140 You can use completion to enter a command name. For example, to
4141 invoke the command `forward-char', type:
4143 M-x forward-char <RET>
4145 M-x fo <TAB> c <RET>
4147 After you type in `M-x fo TAB' emacs will give you a possible list of
4148 completions from which you can choose. Note that `forward-char' is the
4149 same command that you invoke with the key `C-f'. You can call any
4150 command (interactively callable function) defined in Emacs by its name
4151 using `M-x' regardless of whether or not any keys are bound to it.
4153 If you type `C-g' while Emacs reads the command name, you cancel the
4154 `M-x' command and get out of the minibuffer, ending up at top level.
4156 To pass a numeric argument to a command you are invoking with `M-x',
4157 specify the numeric argument before the `M-x'. `M-x' passes the
4158 argument along to the function that it calls. The argument value
4159 appears in the prompt while the command name is being read.
4161 You can use the command `M-x interactive' to specify a way of
4162 parsing arguments for interactive use of a function. For example,
4165 (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
4167 to make `arg' be the prefix argument when `foo' is called as a
4168 command. The call to `interactive' is actually a declaration rather
4169 than a function; it tells `call-interactively' how to read arguments to
4170 pass to the function. When actually called, `interactive' returns
4173 The argument of INTERACTIVE is usually a string containing a code
4174 letter followed by a prompt. Some code letters do not use I/O to get
4175 the argument and do not need prompts. To prompt for multiple arguments,
4176 you must provide a code letter, its prompt, a newline, and another code
4177 letter, and so forth. If the argument is not a string, it is evaluated
4178 to get a list of arguments to pass to the function. If you do not
4179 provide an argument to `interactive', no arguments are passed when
4180 calling interactively.
4182 Available code letters are:
4185 Function name: symbol with a function definition
4188 Name of existing buffer
4191 Name of buffer, possibly nonexistent
4197 Command name: symbol with interactive function definition
4200 Value of point as number (does not do I/O)
4212 Possibly nonexistent file name
4215 Key sequence (string)
4218 Value of mark as number (does not do I/O)
4221 Number read using minibuffer
4224 Prefix arg converted to number, or if none, do like code `n'
4227 Prefix arg converted to number (does not do I/O)
4230 Prefix arg in raw form (does not do I/O)
4233 Region: point and mark as two numeric arguments, smallest first
4243 Variable name: symbol that is `user-variable-p'
4246 Lisp expression read but not evaluated
4249 Lisp expression read and evaluated
4251 In addition, if the string begins with `*', an error is signaled if
4252 the buffer is read-only. This happens before reading any arguments.
4253 If the string begins with `@', the window the mouse is over is selected
4254 before anything else is done. You may use both `@' and `*'; they are
4255 processed in the order that they appear.
4257 Normally, when describing a command that is run by name, we omit the
4258 <RET> that is needed to terminate the name. Thus we may refer to `M-x
4259 auto-fill-mode' rather than `M-x auto-fill-mode' <RET>. We mention the
4260 <RET> only when it is necessary to emphasize its presence, for example,
4261 when describing a sequence of input that contains a command name and
4262 arguments that follow it.
4264 `M-x' is defined to run the command `execute-extended-command',
4265 which is responsible for reading the name of another command and
4269 File: xemacs.info, Node: Help, Next: Mark, Prev: M-x, Up: Top
4274 XEmacs provides extensive help features accessible through a single
4275 character, `C-h'. `C-h' is a prefix key that is used only for
4276 documentation-printing commands. The characters that you can type after
4277 `C-h' are called "help options". One help option is `C-h'; that is how
4278 you ask for help about using `C-h'. To cancel, type `C-g'. The
4279 function key <F1> is equivalent to `C-h'.
4281 `C-h C-h' (`help-for-help') displays a list of the possible help
4282 options, and then asks you to type the desired option. It prompts with
4285 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:
4287 You should type one of those characters.
4289 Typing a third `C-h' displays a description of what the options mean;
4290 Emacs still waits for you to type an option. To cancel, type `C-g'.
4292 Most help buffers use a special major mode, Help mode, which lets you
4293 scroll conveniently with <SPC> and <DEL> or <BS>.
4297 * Help Summary:: Brief list of all Help commands.
4298 * Key Help:: Asking what a key does in XEmacs.
4299 * Name Help:: Asking about a command, variable or function name.
4300 * Apropos:: Asking what pertains to a given topic.
4301 * Library Keywords:: Finding Lisp libraries by keywords (topics).
4302 * Help Mode:: Special features of Help mode and Help buffers.
4303 * Misc Help:: Other help commands.
4306 File: xemacs.info, Node: Help Summary, Next: Key Help, Prev: Help, Up: Help
4311 Here is a summary of the defined help commands.
4313 `C-h a REGEXP <RET>'
4314 Display a list of functions and variables whose names match REGEXP
4318 Show all commands whose names contain matches for REGEXP
4319 (`command-apropos').
4322 Display a table of all key bindings currently in effect, with local
4323 bindings of the current major mode first, followed by all global
4324 bindings (`describe-bindings').
4327 Print the name of the command that KEY runs
4328 (`describe-key-briefly'). Here `c' stands for `character'. For
4329 more extensive information on KEY, use `C-h k'.
4331 `C-h d FUNCTION <RET>'
4332 `C-h f FUNCTION <RET>'
4333 Display documentation on the Lisp function named FUNCTION
4334 (`describe-function'). Since commands are Lisp functions, a
4335 command name may be used.
4338 Run Info, the program for browsing documentation files (`info').
4339 The complete XEmacs manual is available online in Info.
4342 Display the name and documentation of the command that KEY runs
4346 Display a description of the last 100 characters you typed
4350 Display documentation of the current major mode (`describe-mode').
4354 Display documentation of XEmacs changes, most recent first
4355 (`view-emacs-news').
4358 Find packages by topic keyword (`finder-by-keyword').
4361 Display a table of all mouse bindings currently in effect now, with
4362 local bindings of the current major mode first, followed by all
4363 global bindings (`describe-pointer').
4366 Display current contents of the syntax table, plus an explanation
4367 of what they mean (`describe-syntax'). *Note Syntax::.
4370 Enter the XEmacs interactive tutorial (`help-with-tutorial').
4373 Display the documentation of the Lisp variable VAR
4374 (`describe-variable').
4376 `C-h w COMMAND <RET>'
4377 Print which keys run the command named COMMAND (`where-is').
4380 Display info on how to deal with Beta versions of XEmacs
4384 Select customization buffer for GROUP (`customize').
4387 View the local copy of the XEmacs FAQ (`xemacs-local-faq').
4389 `C-h C-i FILE <RET>'
4390 Read Info file FILE with Info browser (`Info-query').
4392 `C-h C-c COMMAND <RET>'
4393 Look up an Emacs command COMMAND in the Emacs manual in the Info
4394 system (`Info-goto-emacs-command-node').
4396 `C-h C-f FUNCTION <RET>'
4397 Look up an Emacs Lisp function FUNCTION in the Elisp manual in the
4398 Info system (`Info-elisp-ref').
4401 File: xemacs.info, Node: Key Help, Next: Name Help, Prev: Help Summary, Up: Help
4403 8.2 Documentation for a Key
4404 ===========================
4406 The most basic `C-h' options are `C-h c' (`describe-key-briefly') and
4407 `C-h k' (`describe-key'). `C-h c KEY' prints in the echo area the name
4408 of the command that KEY is bound to. For example, `C-h c C-f' prints
4409 `forward-char'. Since command names are chosen to describe what the
4410 commands do, this is a good way to get a very brief description of what
4413 `C-h k KEY' is similar to `C-h c' but gives more information. It
4414 displays the documentation string of the function KEY is bound to as
4415 well as its name. KEY is a string or vector of events. When called
4416 interactively, KEY may also be a menu selection. This information does
4417 not usually fit into the echo area, so a window is used for the display.
4419 `C-h c' and `C-h k' work for any sort of key sequences, including
4420 function keys and mouse events.
4423 File: xemacs.info, Node: Name Help, Next: Apropos, Prev: Key Help, Up: Help
4425 8.3 Help by Command or Variable Name
4426 ====================================
4428 `C-h f' (`describe-function') reads the name of a Lisp function using
4429 the minibuffer, then displays that function's documentation string in a
4430 window. Since commands are Lisp functions, you can use the argument
4431 FUNCTION to get the documentation of a command that you know by name.
4434 C-h f auto-fill-mode <RET>
4436 displays the documentation for `auto-fill-mode'. Using `C-h f' is the
4437 only way to see the documentation of a command that is not bound to any
4438 key, that is, a command you would normally call using `M-x'. If the
4439 variable `describe-function-show-arglist' is `t', `describe-function'
4440 shows its arglist if the FUNCTION is not an autoload function.
4442 `C-h f' is also useful for Lisp functions that you are planning to
4443 use in a Lisp program. For example, if you have just written the
4444 expression `(make-vector len)' and want to make sure you are using
4445 `make-vector' properly, type `C-h f make-vector <RET>'. Because `C-h
4446 f' allows all function names, not just command names, you may find that
4447 some of your favorite abbreviations that work in `M-x' don't work in
4448 `C-h f'. An abbreviation may be unique among command names, yet fail
4449 to be unique when other function names are allowed.
4451 The function name for `C-h f' to describe has a default which is
4452 used if you type <RET> leaving the minibuffer empty. The default is
4453 the function called by the innermost Lisp expression in the buffer
4454 around point, _provided_ that is a valid, defined Lisp function name.
4455 For example, if point is located following the text `(make-vector (car
4456 x)', the innermost list containing point is the one that starts with
4457 `(make-vector', so the default is to describe the function
4460 `C-h f' is often useful just to verify that you have the right
4461 spelling for the function name. If `C-h f' mentions a name from the
4462 buffer as the default, that name must be defined as a Lisp function. If
4463 that is all you want to know, just type `C-g' to cancel the `C-h f'
4464 command, then go on editing.
4466 `C-h w COMMAND <RET>' (`where-is') tells you what keys are bound to
4467 COMMAND. It prints a list of the keys in the echo area. Alternatively,
4468 it informs you that a command is not bound to any keys, which implies
4469 that you must use `M-x' to call the command.
4471 `C-h v' (`describe-variable') is like `C-h f' but describes Lisp
4472 variables instead of Lisp functions. Its default is the Lisp symbol
4473 around or before point, if that is the name of a known Lisp variable.
4477 File: xemacs.info, Node: Apropos, Next: Library Keywords, Prev: Name Help, Up: Help
4483 Show only symbols that are names of commands (`command-apropos').
4485 `M-x apropos REGEXP'
4486 Show all symbols whose names contain matches for REGEXP.
4488 A more sophisticated sort of question to ask is, "What are the
4489 commands for working with files?" To ask this question, type `C-h a
4490 file <RET>', which displays a list of all command names that contain
4491 `file', including `copy-file', `find-file', and so on. With each
4492 command name appears a brief description of how to use the command, and
4493 what keys you can currently invoke it with. For example, it would say
4494 that you can invoke `find-file' by typing `C-x C-f'. The `A' in `C-h
4495 A' stands for `Apropos'; `C-h A' runs the command `command-apropos'.
4496 This command normally checks only commands (interactive functions); if
4497 you specify a prefix argument, it checks noninteractive functions as
4500 Because `C-h A' looks only for functions whose names contain the
4501 string you specify, you must use ingenuity in choosing the string. If
4502 you are looking for commands for killing backwards and `C-h a
4503 kill-backwards <RET>' doesn't reveal any, don't give up. Try just
4504 `kill', or just `backwards', or just `back'. Be persistent. Pretend
4505 you are playing Adventure. Also note that you can use a regular
4506 expression as the argument, for more flexibility (*note Regexps::).
4508 Here is a set of arguments to give to `C-h a' that covers many
4509 classes of XEmacs commands, since there are strong conventions for
4510 naming the standard XEmacs commands. By giving you a feel for the
4511 naming conventions, this set should also serve to aid you in developing
4512 a technique for picking `apropos' strings.
4514 char, line, word, sentence, paragraph, region, page, sexp, list,
4515 defun, rect, buffer, frame, window, face, file, dir, register,
4516 mode, beginning, end, forward, backward, next, previous, up, down,
4517 search, goto, kill, delete, mark, insert, yank, fill, indent,
4518 case, change, set, what, list, find, view, describe, default.
4520 To list all Lisp symbols that contain a match for a regexp, not just
4521 the ones that are defined as commands, use the command `M-x apropos'
4522 instead of `C-h A'. This command does not check key bindings by
4523 default; specify a numeric argument if you want it to check them.
4525 The `apropos-documentation' command is like `apropos' except that it
4526 searches documentation strings for matches for the specified regular
4529 The `apropos-value' command is like `apropos' except that it
4530 searches symbols' values for matches for the specified regular
4531 expression. This command does not check function definitions or
4532 property lists by default; specify a numeric argument if you want it to
4535 If the variable `apropos-do-all' is non-`nil', the commands above
4536 all behave as if they had been given a prefix argument.
4538 If you want more information about a function definition, variable or
4539 symbol property listed in the Apropos buffer, you can click on it with
4540 `Mouse-2' or move there and type <RET>.
4543 File: xemacs.info, Node: Library Keywords, Next: Help Mode, Prev: Apropos, Up: Help
4545 8.5 Keyword Search for Lisp Libraries
4546 =====================================
4548 The `C-h p' command lets you search the standard Emacs Lisp libraries
4549 by topic keywords. Here is a partial list of keywords you can use:
4551 abbrev abbreviation handling, typing shortcuts, macros
4552 bib code related to the `bib' bibliography processor
4553 c C, C++, and Objective-C language support
4554 calendar calendar and time management support
4555 comm communications, networking, remote access to files
4556 data support for editing files of data
4557 docs support for Emacs documentation
4558 dumped files preloaded into Emacs
4559 emulations emulations of other editors
4560 extensions Emacs Lisp language extensions
4561 faces support for multiple fonts
4562 frames support for Emacs frames and window systems
4563 games games, jokes and amusements
4564 hardware support for interfacing with exotic hardware
4565 help support for on-line help systems
4566 hypermedia support for links between text or other media types
4567 i18n internationalization and alternate character-set support
4568 internal code for Emacs internals, build process, defaults
4569 languages specialized modes for editing programming languages
4570 lisp Lisp support, including Emacs Lisp
4571 local code local to your site
4572 maint maintenance aids for the Emacs development group
4573 mail modes for electronic-mail handling
4574 matching various sorts of searching and matching
4576 mule multi-language extensions
4577 news support for netnews reading and posting
4578 oop support for object-oriented programming
4579 outlines support for hierarchical outlining
4580 processes process, subshell, compilation, and job control support
4581 terminals support for terminal types
4582 tex code related to the TeX formatter
4583 tools programming tools
4584 unix front-ends/assistants for, or emulators of, UNIX features
4585 vms support code for vms
4589 File: xemacs.info, Node: Help Mode, Next: Misc Help, Prev: Library Keywords, Up: Help
4591 8.6 Help Mode Commands
4592 ======================
4594 Help buffers provide the commands of View mode (*note Misc File Ops::),
4595 plus a few special commands of their own.
4604 When a command name (*note Running Commands by Name: M-x.) or
4605 variable name (*note Variables::) appears in the documentation, it
4606 normally appears inside paired single-quotes.
4609 File: xemacs.info, Node: Misc Help, Prev: Help Mode, Up: Help
4611 8.7 Other Help Commands
4612 =======================
4614 `C-h i' (`info') runs the Info program, which is used for browsing
4615 through structured documentation files. The entire XEmacs manual is
4616 available within Info. Eventually all the documentation of the GNU
4617 system will be available. Type `h' after entering Info to run a
4618 tutorial on using Info.
4620 If you specify a numeric argument, `C-h i' prompts for the name of a
4621 documentation file. This way, you can browse a file which doesn't have
4622 an entry in the top-level Info menu. It is also handy when you need to
4623 get to the documentation quickly, and you know the exact name of the
4626 There are two special help commands for accessing XEmacs
4627 documentation through Info. `C-h C-f FUNCTION <RET>' enters Info and
4628 goes straight to the documentation of the XEmacs function FUNCTION.
4629 `C-h C-k KEY' enters Info and goes straight to the documentation of the
4630 key KEY. These two keys run the commands `Info-elisp-ref' and
4631 `Info-goto-emacs-key-command-node'. (GNU Emacs binds `C-h C-f' to
4632 `Info-goto-emacs-command-node', but this is less helpful to
4635 If something surprising happens, and you are not sure what commands
4636 you typed, use `C-h l' (`view-lossage'). `C-h l' prints the last 100
4637 command characters you typed in. If you see commands that you don't
4638 know, you can use `C-h c' to find out what they do.
4640 XEmacs has several major modes. Each mode redefines a few keys and
4641 makes a few other changes in how editing works. `C-h m'
4642 (`describe-mode') prints documentation on the current major mode, which
4643 normally describes all the commands that are changed in this mode.
4645 `C-h b' (`describe-bindings') and `C-h s' (`describe-syntax')
4646 present information about the current XEmacs mode that is not covered
4647 by `C-h m'. `C-h b' displays a list of all the key bindings currently
4648 in effect, with the local bindings of the current major mode first,
4649 followed by the global bindings (*note Key Bindings::). `C-h s'
4650 displays the contents of the syntax table with explanations of each
4651 character's syntax (*note Syntax::).
4653 You can get a similar list for a particular prefix key by typing
4654 `C-h' after the prefix key. (There are a few prefix keys for which
4655 this does not work--those that provide their own bindings for `C-h'.
4656 One of these is <ESC>, because `<ESC> C-h' is actually `C-M-h', which
4659 The other `C-h' options display various files of useful information.
4660 `C-h C-w' (`describe-no-warranty') displays the full details on the
4661 complete absence of warranty for XEmacs. `C-h n' (`view-emacs-news')
4662 displays the file `xemacs/etc/NEWS', which contains documentation on
4663 XEmacs changes arranged chronologically. `C-h F' (`xemacs-local-faq')
4664 displays local version of the XEmacs
4665 frequently-answered-questions-list. `C-h t' (`help-with-tutorial')
4666 displays the learn-by-doing XEmacs tutorial. `C-h C-c'
4667 (`describe-copying') displays the file `xemacs/etc/COPYING', which
4668 tells you the conditions you must obey in distributing copies of
4669 XEmacs. `C-h C-d' (`describe-distribution') displays another file named
4670 `xemacs/etc/DISTRIB', which tells you how you can order a copy of the
4671 latest version of XEmacs.
4674 File: xemacs.info, Node: Mark, Next: Mouse Selection, Prev: Help, Up: Top
4679 Many Emacs commands operate on an arbitrary contiguous part of the
4680 current buffer. You can select text in two ways:
4682 * You use special keys to select text by defining a region between
4685 * If you are running XEmacs under X, you can also select text with
4688 9.1 The Mark and the Region
4689 ===========================
4691 To specify the text for a command to operate on, set "the mark" at one
4692 end of it, and move point to the other end. The text between point and
4693 the mark is called "the region". You can move point or the mark to
4694 adjust the boundaries of the region. It doesn't matter which one is
4695 set first chronologically, or which one comes earlier in the text.
4697 Once the mark has been set, it remains until it is set again at
4698 another place. The mark remains fixed with respect to the preceding
4699 character if text is inserted or deleted in a buffer. Each Emacs
4700 buffer has its own mark; when you return to a buffer that had been
4701 selected previously, it has the same mark it had before.
4703 Many commands that insert text, such as `C-y' (`yank') and `M-x
4704 insert-buffer', position the mark at one end of the inserted text--the
4705 opposite end from where point is positioned, so that the region
4706 contains the text just inserted.
4708 Aside from delimiting the region, the mark is useful for marking a
4709 spot that you may want to go back to. To make this feature more useful,
4710 Emacs remembers 16 previous locations of the mark in the `mark ring'.
4714 * Setting Mark:: Commands to set the mark.
4715 * Using Region:: Summary of ways to operate on contents of the region.
4716 * Marking Objects:: Commands to put region around textual units.
4717 * Mark Ring:: Previous mark positions saved so you can go back there.
4720 File: xemacs.info, Node: Setting Mark, Next: Using Region, Prev: Mark, Up: Mark
4722 9.1.1 Setting the Mark
4723 ----------------------
4725 Here are some commands for setting the mark:
4728 Set the mark where point is (`set-mark-command').
4734 Interchange mark and point (`exchange-point-and-mark').
4737 Pushes a mark at the beginning of the buffer.
4740 Pushes a mark at the end of the buffer.
4742 For example, to convert part of the buffer to all upper-case, you
4743 can use the `C-x C-u' (`upcase-region') command, which operates on the
4744 text in the region. First go to the beginning of the text you want to
4745 capitalize and type `C-<SPC>' to put the mark there, then move to the
4746 end, and then type `C-x C-u' to capitalize the selected region. You
4747 can also set the mark at the end of the text, move to the beginning,
4748 and then type `C-x C-u'. Most commands that operate on the text in the
4749 region have the word `region' in their names.
4751 The most common way to set the mark is with the `C-<SPC>' command
4752 (`set-mark-command'). This command sets the mark where point is. You
4753 can then move point away, leaving the mark behind. It is actually
4754 incorrect to speak of the character `C-<SPC>'; there is no such
4755 character. When you type <SPC> while holding down <CTRL>, you get the
4756 character `C-@' on most terminals. This character is actually bound to
4757 `set-mark-command'. But unless you are unlucky enough to have a
4758 terminal where typing `C-<SPC>' does not produce `C-@', you should
4759 think of this character as `C-<SPC>'.
4761 Since terminals have only one cursor, Emacs cannot show you where the
4762 mark is located. Most people use the mark soon after they set it, before
4763 they forget where it is. But you can see where the mark is with the
4764 command `C-x C-x' (`exchange-point-and-mark') which puts the mark where
4765 point was and point where the mark was. The extent of the region is
4766 unchanged, but the cursor and point are now at the previous location of
4769 Another way to set the mark is to push the mark to the beginning of a
4770 buffer while leaving point at its original location. If you supply an
4771 argument to `C-<' (`mark-beginning-of-buffer'), the mark is pushed N/10
4772 of the way from the true beginning of the buffer. You can also set the
4773 mark at the end of a buffer with `C->' (`mark-end-of-buffer'). It
4774 pushes the mark to the end of the buffer, leaving point alone.
4775 Supplying an argument to the command pushes the mark N/10 of the way
4776 from the true end of the buffer.
4778 If you are using XEmacs under the X window system, you can set the
4779 variable `zmacs-regions' to `t'. This makes the current region (defined
4780 by point and mark) highlight and makes it available as the X clipboard
4781 selection, which means you can use the menu bar items on it. *Note
4782 Active Regions::, for more information.
4784 `C-x C-x' is also useful when you are satisfied with the location of
4785 point but want to move the mark; do `C-x C-x' to put point there and
4786 then you can move it. A second use of `C-x C-x', if necessary, puts
4787 the mark at the new location with point back at its original location.
4790 File: xemacs.info, Node: Using Region, Next: Marking Objects, Prev: Setting Mark, Up: Mark
4792 9.1.2 Operating on the Region
4793 -----------------------------
4795 Once you have created an active region, you can do many things to the
4797 * Kill it with `C-w' (*note Killing::).
4799 * Save it in a register with `C-x r s' (*note Registers::).
4801 * Save it in a buffer or a file (*note Accumulating Text::).
4803 * Convert case with `C-x C-l' or `C-x C-u'
4806 * Evaluate it as Lisp code with `M-x eval-region' (*note Lisp
4809 * Fill it as text with `M-q' (*note Filling::).
4811 * Print hardcopy with `M-x print-region' (*note Hardcopy::).
4813 * Indent it with `C-x <TAB>' or `C-M-\' (*note Indentation::).
4816 File: xemacs.info, Node: Marking Objects, Next: Mark Ring, Prev: Using Region, Up: Mark
4818 9.1.3 Commands to Mark Textual Objects
4819 --------------------------------------
4821 There are commands for placing point and the mark around a textual
4822 object such as a word, list, paragraph or page.
4825 Set mark after end of next word (`mark-word'). This command and
4826 the following one do not move point.
4829 Set mark after end of next Lisp expression (`mark-sexp').
4832 Put region around current paragraph (`mark-paragraph').
4835 Put region around current Lisp defun (`mark-defun').
4838 Put region around entire buffer (`mark-whole-buffer').
4841 Put region around current page (`mark-page').
4843 `M-@' (`mark-word') puts the mark at the end of the next word, while
4844 `C-M-@' (`mark-sexp') puts it at the end of the next Lisp expression.
4845 These characters sometimes save you some typing.
4847 A number of commands are available that set both point and mark and
4848 thus delimit an object in the buffer. `M-h' (`mark-paragraph') moves
4849 point to the beginning of the paragraph that surrounds or follows
4850 point, and puts the mark at the end of that paragraph (*note
4851 Paragraphs::). You can then indent, case-convert, or kill the whole
4852 paragraph. In the same fashion, `C-M-h' (`mark-defun') puts point
4853 before and the mark after the current or following defun (*note
4854 Defuns::). `C-x C-p' (`mark-page') puts point before the current page
4855 (or the next or previous, depending on the argument), and mark at the
4856 end (*note Pages::). The mark goes after the terminating page
4857 delimiter (to include it), while point goes after the preceding page
4858 delimiter (to exclude it). Finally, `C-x h' (`mark-whole-buffer') sets
4859 up the entire buffer as the region by putting point at the beginning
4860 and the mark at the end.
4863 File: xemacs.info, Node: Mark Ring, Prev: Marking Objects, Up: Mark
4868 Aside from delimiting the region, the mark is also useful for marking a
4869 spot that you may want to go back to. To make this feature more
4870 useful, Emacs remembers 16 previous locations of the mark in the "mark
4871 ring". Most commands that set the mark push the old mark onto this
4872 ring. To return to a marked location, use `C-u C-<SPC>' (or `C-u
4873 C-@'); this is the command `set-mark-command' given a numeric argument.
4874 The command moves point to where the mark was, and restores the mark
4875 from the ring of former marks. Repeated use of this command moves point
4876 to all the old marks on the ring, one by one. The marks you have seen
4877 go to the end of the ring, so no marks are lost.
4879 Each buffer has its own mark ring. All editing commands use the
4880 current buffer's mark ring. In particular, `C-u C-<SPC>' always stays
4883 Many commands that can move long distances, such as `M-<'
4884 (`beginning-of-buffer'), start by setting the mark and saving the old
4885 mark on the mark ring. This makes it easier for you to move back
4886 later. Searches set the mark, unless they do not actually move point.
4887 When a command sets the mark, `Mark Set' is printed in the echo area.
4889 The variable `mark-ring-max' is the maximum number of entries to
4890 keep in the mark ring. If that many entries exist and another entry is
4891 added, the last entry in the list is discarded. Repeating `C-u
4892 C-<SPC>' circulates through the entries that are currently in the ring.
4894 The variable `mark-ring' holds the mark ring itself, as a list of
4895 marker objects in the order most recent first. This variable is local
4899 File: xemacs.info, Node: Mouse Selection, Next: Additional Mouse Operations, Prev: Mark, Up: Top
4901 9.2 Selecting Text with the Mouse
4902 =================================
4904 If you are using XEmacs under X, you can use the mouse pointer to
4905 select text. (The normal mouse pointer is an I-beam, the same pointer
4908 The glyph variable `text-pointer-glyph' controls the shape of the
4909 mouse pointer when over text. You can also control the shape of the
4910 mouse pointer when over nontext using `nontext-pointer-glyph', and the
4911 shape of the mouse pointer when over the modeline using
4912 `modeline-pointer-glyph'. (Remember, you should use `set-glyph-image',
4913 not `setq', to set one of these variables.)
4915 If you want to get fancy, you can set the foreground and background
4916 colors of the mouse pointer by setting the `pointer' face.
4918 There are two ways to select a region of text with the mouse:
4920 To select a word in text, double-click with the left mouse button
4921 while the mouse cursor is over the word. The word is highlighted when
4922 selected. On monochrome monitors, a stippled background indicates that a
4923 region of text has been highlighted. On color monitors, a color
4924 background indicates highlighted text. You can triple-click to select
4927 To select an arbitrary region of text:
4929 1. Move the mouse cursor over the character at the beginning of the
4930 region of text you want to select.
4932 2. Press and hold the left mouse button.
4934 3. While holding the left mouse button down, drag the cursor to the
4935 character at the end of the region of text you want to select.
4937 4. Release the left mouse button.
4938 The selected region of text is highlighted.
4940 Once a region of text is selected, it becomes the primary X selection
4941 (*note Using X Selections::) as well as the Emacs selected region. You
4942 can paste it into other X applications and use the options from the
4943 Edit pull-down menu on it. Since it is also the Emacs region, you can
4944 use Emacs region commands on it.
4947 File: xemacs.info, Node: Additional Mouse Operations, Next: Killing, Prev: Mouse Selection, Up: Top
4949 9.3 Additional Mouse Operations
4950 ===============================
4952 XEmacs also provides the following mouse functions. Most of these are
4953 not bound to mouse gestures by default, but they are provided for your
4954 customization pleasure. For example, if you wanted `shift-left' (that
4955 is, holding down the <Shift> key and clicking the left mouse button) to
4956 delete the character at which you are pointing, then you could do this:
4958 (global-set-key '(shift button1) 'mouse-del-char)
4961 Delete the character pointed to by the mouse.
4963 `mouse-delete-window'
4964 Delete the Emacs window that the mouse is on.
4966 `mouse-keep-one-window'
4967 Select the Emacs window that the mouse is on, then delete all other
4968 windows on this frame.
4971 Kill the line pointed to by the mouse.
4974 Print the length of the line indicated by the pointer.
4977 Scroll point to the mouse position.
4980 Select the Emacs window the mouse is on.
4982 `mouse-select-and-split'
4983 Select the Emacs window mouse is on, then split it vertically in
4987 Select the Emacs window the mouse is on and set the mark at the
4988 mouse position. Display the cursor at that position for a second.
4991 Select the Emacs window that the mouse is on and move point to the
4995 Make a selection with the mouse. This is the default binding of
4996 the left mouse button (<button1>).
4998 `mouse-track-adjust'
4999 Extend the existing selection. This is the default binding of
5002 `mouse-track-and-copy-to-cutbuffer'
5003 Make a selection like `mouse-track', but also copy it to the cut
5006 `mouse-track-delete-and-insert'
5007 Make a selection with the mouse and insert it at point. This is
5008 the default binding of <control-shift-button1>.
5010 `mouse-track-insert'
5011 Make a selection with the mouse and insert it at point. This is
5012 the default binding of <control-button1>.
5014 `mouse-window-to-region'
5015 Narrow a window to the region between the cursor and the mouse
5018 The `M-x mouse-track' command should be bound to a mouse button. If
5019 you click-and-drag, the selection is set to the region between the
5020 point of the initial click and the point at which you release the
5021 button. These positions do not need to be ordered.
5023 If you click-and-release without moving the mouse, the point is
5024 moved, and the selection is disowned (there will be no selection
5025 owner.) The mark will be set to the previous position of point.
5027 If you double-click, the selection will extend by symbols instead of
5028 by characters. If you triple-click, the selection will extend by lines.
5030 If you drag the mouse off the top or bottom of the window, you can
5031 select pieces of text that are larger than the visible part of the
5032 buffer; the buffer will scroll as necessary.
5034 The selected text becomes the current X selection, and is also
5035 copied to the top of the kill ring. Point will be left at the position
5036 at which you released the button and the mark will be left at the
5037 initial click position. Bind a mouse click to
5038 `mouse-track-and-copy-to-cutbuffer' to copy selections to the cut
5039 buffer. (See also the `mouse-track-adjust' command, on
5042 The `M-x mouse-track-adjust' command should be bound to a mouse
5043 button. The selection will be enlarged or shrunk so that the point of
5044 the mouse click is one of its endpoints. This is only meaningful after
5045 the `mouse-track' command (<button1>) has been executed.
5047 The `M-x mouse-track-delete-and-insert' command is exactly the same
5048 as the `mouse-track' command on <button1>, except that point is not
5049 moved; the selected text is immediately inserted after being selected;
5050 and the text of the selection is deleted.
5052 The `M-x mouse-track-insert' command is exactly the same as the
5053 `mouse-track' command on <button1>, except that point is not moved; the
5054 selected text is immediately inserted after being selected; and the
5055 selection is immediately disowned afterwards.
5058 File: xemacs.info, Node: Killing, Next: Yanking, Prev: Additional Mouse Operations, Up: Top
5060 9.4 Deletion and Killing
5061 ========================
5063 Most commands that erase text from the buffer save it. You can get the
5064 text back if you change your mind, or you can move or copy it to other
5065 parts of the buffer. Commands which erase text and save it in the kill
5066 ring are known as "kill" commands. Some other commands erase text but
5067 do not save it; they are known as "delete" commands. (This distinction
5068 is made only for erasing text in the buffer.)
5070 The commands' names and individual descriptions use the words `kill'
5071 and `delete' to indicate what they do. If you perform a kill or delete
5072 command by mistake, use the `C-x u' (`undo') command to undo it (*note
5073 Undo::). The delete commands include `C-d' (`delete-char') and <DEL>
5074 (`delete-backward-char'), which delete only one character at a time,
5075 and those commands that delete only spaces or newlines. Commands that
5076 can destroy significant amounts of nontrivial data usually kill.
5082 Delete next character (`delete-char').
5085 Delete previous character (`delete-backward-char').
5088 Delete spaces and tabs around point (`delete-horizontal-space').
5091 Delete spaces and tabs around point, leaving one space
5095 Delete blank lines around the current line (`delete-blank-lines').
5098 Join two lines by deleting the intervening newline, and any
5099 indentation following it (`delete-indentation').
5101 The most basic delete commands are `C-d' (`delete-char') and <DEL>
5102 (`delete-backward-char'). `C-d' deletes the character after point, the
5103 one the cursor is "on top of". Point doesn't move. <DEL> deletes the
5104 character before the cursor, and moves point back. You can delete
5105 newlines like any other characters in the buffer; deleting a newline
5106 joins two lines. Actually, `C-d' and <DEL> aren't always delete
5107 commands; if you give them an argument, they kill instead, since they
5108 can erase more than one character this way.
5110 The other delete commands delete only formatting characters: spaces,
5111 tabs and newlines. `M-\' (`delete-horizontal-space') deletes all
5112 spaces and tab characters before and after point. `M-<SPC>'
5113 (`just-one-space') does the same but leaves a single space after point,
5114 regardless of the number of spaces that existed previously (even zero).
5116 `C-x C-o' (`delete-blank-lines') deletes all blank lines after the
5117 current line. If the current line is blank, it deletes all blank lines
5118 preceding the current line as well as leaving one blank line, the
5119 current line. `M-^' (`delete-indentation') joins the current line and
5120 the previous line, or, if given an argument, joins the current line and
5121 the next line by deleting a newline and all surrounding spaces, possibly
5122 leaving a single space. *Note M-^: Indentation.
5124 9.4.2 Killing by Lines
5125 ----------------------
5128 Kill rest of line or one or more lines (`kill-line').
5130 The simplest kill command is `C-k'. If given at the beginning of a
5131 line, it kills all the text on the line, leaving the line blank. If
5132 given on a blank line, the blank line disappears. As a consequence, a
5133 line disappears completely if you go to the front of a non-blank line
5134 and type `C-k' twice.
5136 More generally, `C-k' kills from point up to the end of the line,
5137 unless it is at the end of a line. In that case, it kills the newline
5138 following the line, thus merging the next line into the current one.
5139 Emacs ignores invisible spaces and tabs at the end of the line when
5140 deciding which case applies: if point appears to be at the end of the
5141 line, you can be sure the newline will be killed.
5143 If you give `C-k' a positive argument, it kills that many lines and
5144 the newlines that follow them (however, text on the current line before
5145 point is not killed). With a negative argument, `C-k' kills back to a
5146 number of line beginnings. An argument of -2 means kill back to the
5147 second line beginning. If point is at the beginning of a line, that
5148 line beginning doesn't count, so `C-u - 2 C-k' with point at the front
5149 of a line kills the two previous lines.
5151 `C-k' with an argument of zero kills all the text before point on the
5154 9.4.3 Other Kill Commands
5155 -------------------------
5158 Kill region (from point to the mark) (`kill-region'). *Note
5162 Kill word (`kill-word').
5165 Kill word backwards (`backward-kill-word').
5168 Kill back to beginning of sentence (`backward-kill-sentence').
5172 Kill to end of sentence (`kill-sentence').
5175 Kill sexp (`kill-sexp'). *Note Lists::.
5178 Kill up to next occurrence of CHAR (`zap-to-char').
5180 `C-w' (`kill-region') is a very general kill command; it kills
5181 everything between point and the mark. You can use this command to kill
5182 any contiguous sequence of characters by first setting the mark at one
5183 end of a sequence of characters, then going to the other end and typing
5186 A convenient way of killing is combined with searching: `M-z'
5187 (`zap-to-char') reads a character and kills from point up to (but not
5188 including) the next occurrence of that character in the buffer. If
5189 there is no next occurrence, killing goes to the end of the buffer. A
5190 numeric argument acts as a repeat count. A negative argument means to
5191 search backward and kill text before point.
5193 Other syntactic units can be killed: words, with `M-<DEL>' and `M-d'
5194 (*note Words::); sexps, with `C-M-k' (*note Lists::); and sentences,
5195 with `C-x <DEL>' and `M-k' (*note Sentences::).
5198 File: xemacs.info, Node: Yanking, Next: Using X Selections, Prev: Killing, Up: Top
5203 "Yanking" means getting back text which was killed. Some systems call
5204 this "pasting". The usual way to move or copy text is to kill it and
5205 then yank it one or more times.
5208 Yank last killed text (`yank').
5211 Replace re-inserted killed text with the previously killed text
5215 Save region as last killed text without actually killing it
5216 (`copy-region-as-kill').
5219 Append next kill to last batch of killed text (`append-next-kill').
5223 * Kill Ring:: Where killed text is stored. Basic yanking.
5224 * Appending Kills:: Several kills in a row all yank together.
5225 * Earlier Kills:: Yanking something killed some time ago.
5228 File: xemacs.info, Node: Kill Ring, Next: Appending Kills, Prev: Yanking, Up: Yanking
5233 All killed text is recorded in the "kill ring", a list of blocks of
5234 text that have been killed. There is only one kill ring, used in all
5235 buffers, so you can kill text in one buffer and yank it in another
5236 buffer. This is the usual way to move text from one file to another.
5237 (*Note Accumulating Text::, for some other ways.)
5239 If you have two separate Emacs processes, you cannot use the kill
5240 ring to move text. If you are using XEmacs under X, however, you can
5241 use the X selection mechanism to move text from one to another.
5243 If you are using XEmacs under X and have one Emacs process with
5244 multiple frames, they do share the same kill ring. You can kill or
5245 copy text in one Emacs frame, then yank it in the other frame belonging
5246 to the same process.
5248 The command `C-y' (`yank') reinserts the text of the most recent
5249 kill. It leaves the cursor at the end of the text and sets the mark at
5250 the beginning of the text. *Note Mark::.
5252 `C-u C-y' yanks the text, leaves the cursor in front of the text,
5253 and sets the mark after it, if the argument is with just a `C-u'. Any
5254 other argument, including `C-u' and digits, has different results,
5255 described below, under "Yanking Earlier Kills".
5257 To copy a block of text, you can also use `M-w'
5258 (`copy-region-as-kill'), which copies the region into the kill ring
5259 without removing it from the buffer. `M-w' is similar to `C-w' followed
5260 by `C-y' but does not mark the buffer as "modified" and does not
5261 actually cut anything.
5264 File: xemacs.info, Node: Appending Kills, Next: Earlier Kills, Prev: Kill Ring, Up: Yanking
5266 9.5.2 Appending Kills
5267 ---------------------
5269 Normally, each kill command pushes a new block onto the kill ring.
5270 However, two or more kill commands in a row combine their text into a
5271 single entry, so that a single `C-y' yanks it all back. This means you
5272 don't have to kill all the text you want to yank in one command; you
5273 can kill line after line, or word after word, until you have killed what
5274 you want, then get it all back at once using `C-y'. (Thus we join
5275 television in leading people to kill thoughtlessly.)
5277 Commands that kill forward from point add onto the end of the
5278 previous killed text. Commands that kill backward from point add onto
5279 the beginning. This way, any sequence of mixed forward and backward
5280 kill commands puts all the killed text into one entry without
5281 rearrangement. Numeric arguments do not break the sequence of
5282 appending kills. For example, suppose the buffer contains:
5286 and here is the third.
5288 with point at the beginning of the second line. If you type `C-k C-u 2
5289 M-<DEL> C-k', the first `C-k' kills the text `line of sample text',
5290 `C-u 2 M-<DEL>' kills `the first' with the newline that followed it,
5291 and the second `C-k' kills the newline after the second line. The
5292 result is that the buffer contains `This is and here is the third.' and
5293 a single kill entry contains `the first<RET>line of sample
5294 text<RET>'--all the killed text, in its original order.
5296 If a kill command is separated from the last kill command by other
5297 commands (not just numeric arguments), it starts a new entry on the kill
5298 ring. To force a kill command to append, first type the command `C-M-w'
5299 (`append-next-kill'). `C-M-w' tells the following command, if it is a
5300 kill command, to append the text it kills to the last killed text,
5301 instead of starting a new entry. With `C-M-w', you can kill several
5302 separated pieces of text and accumulate them to be yanked back in one
5306 File: xemacs.info, Node: Earlier Kills, Prev: Appending Kills, Up: Yanking
5308 9.5.3 Yanking Earlier Kills
5309 ---------------------------
5311 To recover killed text that is no longer the most recent kill, you need
5312 the `Meta-y' (`yank-pop') command. You can use `M-y' only after a
5313 `C-y' or another `M-y'. It takes the text previously yanked and
5314 replaces it with the text from an earlier kill. To recover the text of
5315 the next-to-the-last kill, first use `C-y' to recover the last kill,
5316 then `M-y' to replace it with the previous kill.
5318 You can think in terms of a "last yank" pointer which points at an
5319 item in the kill ring. Each time you kill, the "last yank" pointer
5320 moves to the new item at the front of the ring. `C-y' yanks the item
5321 which the "last yank" pointer points to. `M-y' moves the "last yank"
5322 pointer to a different item, and the text in the buffer changes to
5323 match. Enough `M-y' commands can move the pointer to any item in the
5324 ring, so you can get any item into the buffer. Eventually the pointer
5325 reaches the end of the ring; the next `M-y' moves it to the first item
5328 Yanking moves the "last yank" pointer around the ring, but does not
5329 change the order of the entries in the ring, which always runs from the
5330 most recent kill at the front to the oldest one still remembered.
5332 Use `M-y' with a numeric argument to advance the "last yank" pointer
5333 by the specified number of items. A negative argument moves the
5334 pointer toward the front of the ring; from the front of the ring, it
5335 moves to the last entry and starts moving forward from there.
5337 Once the text you are looking for is brought into the buffer, you can
5338 stop doing `M-y' commands and the text will stay there. Since the text
5339 is just a copy of the kill ring item, editing it in the buffer does not
5340 change what's in the ring. As long you don't kill additional text, the
5341 "last yank" pointer remains at the same place in the kill ring:
5342 repeating `C-y' will yank another copy of the same old kill.
5344 If you know how many `M-y' commands it would take to find the text
5345 you want, you can yank that text in one step using `C-y' with a numeric
5346 argument. `C-y' with an argument greater than one restores the text
5347 the specified number of entries back in the kill ring. Thus, `C-u 2
5348 C-y' gets the next to the last block of killed text. It is equivalent
5349 to `C-y M-y'. `C-y' with a numeric argument starts counting from the
5350 "last yank" pointer, and sets the "last yank" pointer to the entry that
5353 The variable `kill-ring-max' controls the length of the kill ring;
5354 no more than that many blocks of killed text are saved.
5357 File: xemacs.info, Node: Using X Selections, Next: Accumulating Text, Prev: Yanking, Up: Top
5359 9.6 Using X Selections
5360 ======================
5362 In the X window system, mouse selections provide a simple mechanism for
5363 text transfer between different applications. In a typical X
5364 application, you can select text by pressing the left mouse button and
5365 dragging the cursor over the text you want to copy. The text becomes
5366 the primary X selection and is highlighted. The highlighted region is
5367 also the Emacs selected region.
5369 * Since the region is the primary X selection, you can go to a
5370 different X application and click the middle mouse button: the
5371 text that you selected in the previous application is pasted into
5372 the current application.
5374 * Since the region is the Emacs selected region, you can use all
5375 region commands (`C-w, M-w' etc.) as well as the options of the
5376 Edit menu to manipulate the selected text.
5380 * X Clipboard Selection:: Pasting to the X clipboard.
5381 * X Selection Commands:: Other operations on the selection.
5382 * X Cut Buffers:: X cut buffers are available for compatibility.
5383 * Active Regions:: Using zmacs-style highlighting of the
5387 File: xemacs.info, Node: X Clipboard Selection, Next: X Selection Commands, Prev: Using X Selections, Up: Using X Selections
5389 9.6.1 The Clipboard Selection
5390 -----------------------------
5392 There are other kinds of X selections besides the Primary selection; one
5393 common one is the Clipboard selection. Some applications prefer to
5394 transfer data using this selection in preference to the Primary. One
5395 can transfer text from the Primary selection to the Clipboard
5396 selection with the Copy command under the Edit menu in the menubar.
5398 Usually, the clipboard selection is not visible. However, if you
5399 run the `xclipboard' application, the text most recently copied to the
5400 clipboard (with the Copy command) is displayed in a window. Any time
5401 new text is thus copied, the `xclipboard' application makes a copy of
5402 it and displays it in its window. The value of the clipboard can
5403 survive the lifetime of the running Emacs process. The `xclipboard'
5404 man page provides more details.
5406 Warning: If you use the `xclipboard' application, remember that it
5407 maintains a list of all things that have been pasted to the clipboard
5408 (that is, copied with the Copy command). If you don't manually delete
5409 elements from this list by clicking on the Delete button in the
5410 `xclipboard' window, the clipboard will eventually consume a lot of
5413 In summary, some X applications (such as `xterm') allow one to paste
5414 text in them from XEmacs in the following way:
5416 * Drag out a region of text in Emacs with the left mouse button,
5417 making that text be the Primary selection.
5419 * Click the middle button in the other application, pasting the
5422 With some other applications (notably, the OpenWindows and Motif
5423 tools) you must use this method instead:
5425 * Drag out a region of text in Emacs with the left mouse button,
5426 making that text be the Primary selection.
5428 * Copy the selected text to the Clipboard selection by selecting the
5429 Copy menu item from the Edit menu, or by hitting the Copy key on
5432 * Paste the text in the other application by selecting Paste from its
5433 menu, or by hitting the Paste key on your keyboard.
5436 File: xemacs.info, Node: X Selection Commands, Next: X Cut Buffers, Prev: X Clipboard Selection, Up: Using X Selections
5438 9.6.2 Miscellaneous X Selection Commands
5439 ----------------------------------------
5441 `M-x x-copy-primary-selection'
5442 Copy the primary selection to both the kill ring and the Clipboard.
5444 `M-x x-insert-selection'
5445 Insert the current selection into the buffer at point.
5447 `M-x x-delete-primary-selection'
5448 Deletes the text in the primary selection without copying it to
5449 the kill ring or the Clipboard.
5451 `M-x x-kill-primary-selection'
5452 Deletes the text in the primary selection and copies it to both
5453 the kill ring and the Clipboard.
5456 Kill the text between point and the mouse and copy it to the
5457 clipboard and to the cut buffer.
5459 `M-x x-own-secondary-selection'
5460 Make a secondary X selection of the given argument.
5462 `M-x x-own-selection'
5463 Make a primary X selection of the given argument.
5465 `M-x x-set-point-and-insert-selection'
5466 Set point where clicked and insert the primary selection or the
5470 File: xemacs.info, Node: X Cut Buffers, Next: Active Regions, Prev: X Selection Commands, Up: Using X Selections
5475 X cut buffers are a different, older way of transferring text between
5476 applications. XEmacs supports cut buffers for compatibility with older
5477 programs, even though selections are now the preferred way of
5480 X has a concept of applications "owning" selections. When you select
5481 text by clicking and dragging inside an application, the application
5482 tells the X server that it owns the selection. When another
5483 application asks the X server for the value of the selection, the X
5484 server requests the information from the owner. When you use
5485 selections, the selection data is not actually transferred unless
5486 someone wants it; the act of making a selection doesn't transfer data.
5487 Cut buffers are different: when you "own" a cut buffer, the data is
5488 actually transferred to the X server immediately, and survives the
5489 lifetime of the application.
5491 Any time a region of text becomes the primary selection in Emacs,
5492 Emacs also copies that text to the cut buffer. This makes it possible
5493 to copy text from an XEmacs buffer and paste it into an older,
5494 non-selection-based application (such as Emacs 18).
5496 Note: Older versions of Emacs could not access the X selections, only
5500 File: xemacs.info, Node: Active Regions, Prev: X Cut Buffers, Up: Using X Selections
5502 9.6.4 Active Regions
5503 --------------------
5505 By default, both the text you select in an Emacs buffer using the
5506 click-and-drag mechanism and text you select by setting point and the
5507 mark is highlighted. You can use Emacs region commands as well as the
5508 Cut and Copy commands on the highlighted region you selected with the
5511 If you prefer, you can make a distinction between text selected with
5512 the mouse and text selected with point and the mark by setting the
5513 variable `zmacs-regions' to `nil'. In that case:
5515 * The text selected with the mouse becomes both the X selection and
5516 the Emacs selected region. You can use menu-bar commands as well
5517 as Emacs region commands on it.
5519 * The text selected with point and the mark is not highlighted. You
5520 can only use Emacs region commands on it, not the menu-bar items.
5522 Active regions originally come from Zmacs, the Lisp Machine editor.
5523 The idea behind them is that commands can only operate on a region when
5524 the region is in an "active" state. Put simply, you can only operate on
5525 a region that is highlighted.
5527 The variable `zmacs-regions' checks whether LISPM-style active
5528 regions should be used. This means that commands that operate on the
5529 region (the area between point and the mark) only work while the region
5530 is in the active state, which is indicated by highlighting. Most
5531 commands causes the region to not be in the active state; for example,
5532 `C-w' only works immediately after activating the region.
5535 * Commands that operate on the region only work if the region is
5538 * Only a very small set of commands causes the region to become
5539 active-- those commands whose semantics are to mark an area, such
5542 * The region is deactivated after each command that is executed,
5543 except that motion commands do not change whether the region is
5546 `set-mark-command' (`C-SPC') pushes a mark and activates the region.
5547 Moving the cursor with normal motion commands (`C-n', `C-p', etc.)
5548 will cause the region between point and the recently-pushed mark to be
5549 highlighted. It will remain highlighted until some non-motion command
5552 `exchange-point-and-mark' (`C-x C-x') activates the region. So if
5553 you mark a region and execute a command that operates on it, you can
5554 reactivate the same region with `C-x C-x' (or perhaps `C-x C-x C-x
5555 C-x') to operate on it again.
5557 Generally, commands that push marks as a means of navigation, such as
5558 `beginning-of-buffer' (`M-<') and `end-of-buffer' (`M->'), do not
5559 activate the region. However, commands that push marks as a means of
5560 marking an area of text, such as `mark-defun' (`M-C-h'), `mark-word'
5561 (`M-@'), and `mark-whole-buffer' (`C-x h'), do activate the region.
5563 When `zmacs-regions' is `t', there is no distinction between the
5564 primary X selection and the active region selected by point and the
5565 mark. To see this, set the mark (<C-SPC>) and move the cursor with any
5566 cursor-motion command: the region between point and mark is
5567 highlighted, and you can watch it grow and shrink as you move the
5570 Any other commands besides cursor-motion commands (such as inserting
5571 or deleting text) will cause the region to no longer be active; it will
5572 no longer be highlighted, and will no longer be the primary selection.
5573 Region can be explicitly deactivated with `C-g'.
5575 Commands that require a region (such as `C-w') signal an error if
5576 the region is not active. Certain commands cause the region to be in
5577 its active state. The most common ones are `push-mark' (<C-SPC>) and
5578 `exchange-point-and-mark' (`C-x C-x').
5580 When `zmacs-regions' is `t', programs can be non-intrusive on the
5581 state of the region by setting the variable `zmacs-region-stays' to a
5582 non-`nil' value. If you are writing a new Emacs command that is
5583 conceptually a "motion" command and should not interfere with the
5584 current highlightedness of the region, then you may set this variable.
5585 It is reset to `nil' after each user command is executed.
5587 When `zmacs-regions' is `t', programs can make the region between
5588 point and mark go into the active (highlighted) state by using the
5589 function `zmacs-activate-region'. Only a small number of commands
5590 should ever do this.
5592 When `zmacs-regions' is `t', programs can deactivate the region
5593 between point and the mark by using `zmacs-deactivate-region'. Note:
5594 you should not have to call this function; the command loop calls it
5598 File: xemacs.info, Node: Accumulating Text, Next: Rectangles, Prev: Using X Selections, Up: Top
5600 9.7 Accumulating Text
5601 =====================
5603 Usually you copy or move text by killing it and yanking it, but there
5604 are other ways that are useful for copying one block of text in many
5605 places, or for copying many scattered blocks of text into one place.
5607 If you like, you can accumulate blocks of text from scattered
5608 locations either into a buffer or into a file. The relevant commands
5609 are described here. You can also use Emacs registers for storing and
5610 accumulating text. *Note Registers::.
5612 `M-x append-to-buffer'
5613 Append region to contents of specified buffer (`append-to-buffer').
5615 `M-x prepend-to-buffer'
5616 Prepend region to contents of specified buffer.
5618 `M-x copy-to-buffer'
5619 Copy region into specified buffer, deleting that buffer's old
5623 Insert contents of specified buffer into current buffer at point.
5625 `M-x append-to-file'
5626 Append region to the end of the contents of specified file.
5628 To accumulate text into a buffer, use the command `M-x
5629 append-to-buffer', which inserts a copy of the region into the buffer
5630 BUFFERNAME, at the location of point in that buffer. If there is no
5631 buffer with the given name, one is created.
5633 If you append text to a buffer that has been used for editing, the
5634 copied text goes to the place where point is. Point in that buffer is
5635 left at the end of the copied text, so successive uses of
5636 `append-to-buffer' accumulate the text in the specified buffer in the
5637 same order as they were copied. Strictly speaking, this command does
5638 not always append to the text already in the buffer; but if this command
5639 is the only command used to alter a buffer, it does always append to the
5640 existing text because point is always at the end.
5642 `M-x prepend-to-buffer' is similar to `append-to-buffer', but point
5643 in the other buffer is left before the copied text, so successive
5644 prependings add text in reverse order. `M-x copy-to-buffer' is
5645 similar, except that any existing text in the other buffer is deleted,
5646 so the buffer is left containing just the text newly copied into it.
5648 You can retrieve the accumulated text from that buffer with `M-x
5649 insert-buffer', which takes BUFFERNAME as an argument. It inserts a
5650 copy of the text in buffer BUFFERNAME into the selected buffer. You
5651 could alternatively select the other buffer for editing, perhaps moving
5652 text from it by killing or with `append-to-buffer'. *Note Buffers::,
5653 for background information on buffers.
5655 Instead of accumulating text within Emacs in a buffer, you can append
5656 text directly into a file with `M-x append-to-file', which takes
5657 FILE-NAME as an argument. It adds the text of the region to the end of
5658 the specified file. The file is changed immediately on disk. This
5659 command is normally used with files that are not being visited in
5660 Emacs. Using it on a file that Emacs is visiting can produce confusing
5661 results, because the file's text inside Emacs does not change while the
5662 file itself changes.
5665 File: xemacs.info, Node: Rectangles, Next: Registers, Prev: Accumulating Text, Up: Top
5670 The rectangle commands affect rectangular areas of text: all characters
5671 between a certain pair of columns, in a certain range of lines.
5672 Commands are provided to kill rectangles, yank killed rectangles, clear
5673 them out, or delete them. Rectangle commands are useful with text in
5674 multicolumnar formats, like code with comments at the right, or for
5675 changing text into or out of such formats.
5677 To specify the rectangle a command should work on, put the mark at
5678 one corner and point at the opposite corner. The specified rectangle is
5679 called the "region-rectangle" because it is controlled about the same
5680 way the region is controlled. Remember that a given combination of
5681 point and mark values can be interpreted either as specifying a region
5682 or as specifying a rectangle; it is up to the command that uses them to
5683 choose the interpretation.
5685 `M-x delete-rectangle'
5686 Delete the text of the region-rectangle, moving any following text
5687 on each line leftward to the left edge of the region-rectangle.
5689 `M-x kill-rectangle'
5690 Similar, but also save the contents of the region-rectangle as the
5691 "last killed rectangle".
5693 `M-x yank-rectangle'
5694 Yank the last killed rectangle with its upper left corner at point.
5696 `M-x open-rectangle'
5697 Insert blank space to fill the space of the region-rectangle. The
5698 previous contents of the region-rectangle are pushed rightward.
5700 `M-x clear-rectangle'
5701 Clear the region-rectangle by replacing its contents with spaces.
5703 The rectangle operations fall into two classes: commands deleting and
5704 moving rectangles, and commands for blank rectangles.
5706 There are two ways to get rid of the text in a rectangle: you can
5707 discard the text (delete it) or save it as the "last killed" rectangle.
5708 The commands for these two ways are `M-x delete-rectangle' and `M-x
5709 kill-rectangle'. In either case, the portion of each line that falls
5710 inside the rectangle's boundaries is deleted, causing following text
5711 (if any) on the line to move left.
5713 Note that "killing" a rectangle is not killing in the usual sense;
5714 the rectangle is not stored in the kill ring, but in a special place
5715 that only records the most recently killed rectangle (that is, does not
5716 append to a killed rectangle). Different yank commands have to be used
5717 and only one rectangle is stored, because yanking a rectangle is quite
5718 different from yanking linear text and yank-popping commands are
5719 difficult to make sense of.
5721 Inserting a rectangle is the opposite of deleting one. You specify
5722 where to put the upper left corner by putting point there. The
5723 rectangle's first line is inserted at point, the rectangle's second line
5724 is inserted at a point one line vertically down, and so on. The number
5725 of lines affected is determined by the height of the saved rectangle.
5727 To insert the last killed rectangle, type `M-x yank-rectangle'.
5728 This can be used to convert single-column lists into double-column
5729 lists; kill the second half of the list as a rectangle and then yank it
5730 beside the first line of the list.
5732 There are two commands for working with blank rectangles: `M-x
5733 clear-rectangle' erases existing text, and `M-x open-rectangle' inserts
5734 a blank rectangle. Clearing a rectangle is equivalent to deleting it
5735 and then inserting a blank rectangle of the same size.
5737 Rectangles can also be copied into and out of registers. *Note
5738 Rectangle Registers: RegRect.
5741 File: xemacs.info, Node: Registers, Next: Display, Prev: Rectangles, Up: Top
5746 XEmacs "registers" are places in which you can save text or positions
5747 for later use. Once you save text or a rectangle in a register, you
5748 can copy it into the buffer once or many times; a position saved in a
5749 register is used by moving point to that position. Rectangles can also
5750 be copied into and out of registers (*note Rectangles::).
5752 Each register has a name which is a single character. A register can
5753 store a piece of text, a rectangle, a position, a window configuration,
5754 or a file name, but only one thing at any given time. Whatever you
5755 store in a register remains there until you store something else in that
5756 register. To see what a register R contains, use `M-x view-register'.
5758 `M-x view-register <RET> R'
5759 Display a description of what register R contains.
5761 `M-x view-register' reads a register name as an argument and then
5762 displays the contents of the specified register.
5766 * Position: RegPos. Saving positions in registers.
5767 * Text: RegText. Saving text in registers.
5768 * Rectangle: RegRect. Saving rectangles in registers.
5769 * Configurations: RegConfig. Saving window configurations in registers.
5770 * Files: RegFiles. File names in registers.
5771 * Numbers: RegNumbers. Numbers in registers.
5772 * Bookmarks:: Bookmarks are like registers, but persistent.
5775 File: xemacs.info, Node: RegPos, Next: RegText, Prev: Registers, Up: Registers
5777 10.1 Saving Positions in Registers
5778 ==================================
5780 Saving a position records a place in a buffer so that you can move back
5781 there later. Moving to a saved position switches to that buffer and
5782 moves point to that place in it.
5785 Save position of point in register R (`point-to-register').
5788 Jump to the position saved in register R (`jump-to-register').
5790 To save the current position of point in a register, choose a name R
5791 and type `C-x r <SPC> R'. The register R retains the position thus
5792 saved until you store something else in that register.
5794 The command `C-x r j R' moves point to the position recorded in
5795 register R. The register is not affected; it continues to record the
5796 same location. You can jump to the same position using the same
5797 register as often as you want.
5799 If you use `C-x r j' to go to a saved position, but the buffer it
5800 was saved from has been killed, `C-x r j' tries to create the buffer
5801 again by visiting the same file. Of course, this works only for buffers
5802 that were visiting files.
5805 File: xemacs.info, Node: RegText, Next: RegRect, Prev: RegPos, Up: Registers
5807 10.2 Saving Text in Registers
5808 =============================
5810 When you want to insert a copy of the same piece of text many times, it
5811 can be impractical to use the kill ring, since each subsequent kill
5812 moves the piece of text further down on the ring. It becomes hard to
5813 keep track of the argument needed to retrieve the same text with `C-y'.
5814 An alternative is to store the text in a register with `C-x r s'
5815 (`copy-to-register') and then retrieve it with `C-x r i'
5816 (`insert-register').
5819 Copy region into register R (`copy-to-register').
5823 Insert text contents of register R (`insert-register').
5825 `C-x r s R' stores a copy of the text of the region into the
5826 register named R. Given a numeric argument, `C-x r s R' deletes the
5827 text from the buffer as well.
5829 `C-x r i R' inserts the text from register R in the buffer. By
5830 default it leaves point before the text and places the mark after it.
5831 With a numeric argument (`C-u'), it puts point after the text and the
5835 File: xemacs.info, Node: RegRect, Next: RegConfig, Prev: RegText, Up: Registers
5837 10.3 Saving Rectangles in Registers
5838 ===================================
5840 A register can contain a rectangle instead of lines of text. The
5841 rectangle is represented as a list of strings. *Note Rectangles::, for
5842 basic information on rectangles and how to specify rectangles in a
5846 Copy the region-rectangle into register R
5847 (`copy-rectangle-to-register'). With a numeric argument, delete it
5852 Insert the rectangle stored in register R (if it contains a
5853 rectangle) (`insert-register').
5855 The `C-x r i R' command inserts linear text if the register
5856 contains that, or inserts a rectangle if the register contains one.
5858 See also the command `sort-columns', which you can think of as
5859 sorting a rectangle. *Note Sorting::.
5862 File: xemacs.info, Node: RegConfig, Next: RegNumbers, Prev: RegRect, Up: Registers
5864 10.4 Saving Window Configurations in Registers
5865 ==============================================
5867 You can save the window configuration of the selected frame in a
5868 register, or even the configuration of all windows in all frames, and
5869 restore the configuration later.
5872 Save the state of the selected frame's windows in register R
5873 (`window-configuration-to-register').
5875 `M-x frame-configuration-to-register <RET> R'
5876 Save the state of all frames, including all their windows, in
5877 register R (`frame-configuration-to-register').
5879 Use `C-x r j R' to restore a window or frame configuration. This is
5880 the same command used to restore a cursor position. When you restore a
5881 frame configuration, any existing frames not included in the
5882 configuration become invisible. If you wish to delete these frames
5883 instead, use `C-u C-x r j R'.
5886 File: xemacs.info, Node: RegNumbers, Next: RegFiles, Prev: RegConfig, Up: Registers
5888 10.5 Keeping Numbers in Registers
5889 =================================
5891 There are commands to store a number in a register, to insert the
5892 number in the buffer in decimal, and to increment it. These commands
5893 can be useful in keyboard macros (*note Keyboard Macros::).
5895 `C-u NUMBER C-x r n REG'
5896 Store NUMBER into register REG (`number-to-register').
5898 `C-u NUMBER C-x r + REG'
5899 Increment the number in register REG by NUMBER
5900 (`increment-register').
5903 Insert the number from register REG into the buffer.
5905 `C-x r g' is the same command used to insert any other sort of
5906 register contents into the buffer.
5909 File: xemacs.info, Node: RegFiles, Next: Bookmarks, Prev: RegNumbers, Up: Registers
5911 10.6 Keeping File Names in Registers
5912 ====================================
5914 If you visit certain file names frequently, you can visit them more
5915 conveniently if you put their names in registers. Here's the Lisp code
5916 used to put a file name in a register:
5918 (set-register ?R '(file . NAME))
5922 (set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog"))
5924 puts the file name shown in register `z'.
5926 To visit the file whose name is in register R, type `C-x r j R'.
5927 (This is the same command used to jump to a position or restore a frame
5931 File: xemacs.info, Node: Bookmarks, Prev: RegFiles, Up: Registers
5936 "Bookmarks" are somewhat like registers in that they record positions
5937 you can jump to. Unlike registers, they have long names, and they
5938 persist automatically from one Emacs session to the next. The
5939 prototypical use of bookmarks is to record "where you were reading" in
5942 Note: bookmark.el is distributed in edit-utils package. You need to
5943 install that to use bookmark facility (*note Packages::).
5946 Set the bookmark for the visited file, at point.
5948 `C-x r m BOOKMARK <RET>'
5949 Set the bookmark named BOOKMARK at point (`bookmark-set').
5951 `C-x r b BOOKMARK <RET>'
5952 Jump to the bookmark named BOOKMARK (`bookmark-jump').
5955 List all bookmarks (`list-bookmarks').
5958 Save all the current bookmark values in the default bookmark file.
5960 The prototypical use for bookmarks is to record one current position
5961 in each of several files. So the command `C-x r m', which sets a
5962 bookmark, uses the visited file name as the default for the bookmark
5963 name. If you name each bookmark after the file it points to, then you
5964 can conveniently revisit any of those files with `C-x r b', and move to
5965 the position of the bookmark at the same time.
5967 To display a list of all your bookmarks in a separate buffer, type
5968 `C-x r l' (`list-bookmarks'). If you switch to that buffer, you can
5969 use it to edit your bookmark definitions or annotate the bookmarks.
5970 Type `C-h m' in that buffer for more information about its special
5973 When you kill XEmacs, XEmacs offers to save your bookmark values in
5974 your default bookmark file, `~/.emacs.bmk', if you have changed any
5975 bookmark values. You can also save the bookmarks at any time with the
5976 `M-x bookmark-save' command. The bookmark commands load your default
5977 bookmark file automatically. This saving and loading is how bookmarks
5978 persist from one XEmacs session to the next.
5980 If you set the variable `bookmark-save-flag' to 1, then each command
5981 that sets a bookmark will also save your bookmarks; this way, you don't
5982 lose any bookmark values even if XEmacs crashes. (The value, if a
5983 number, says how many bookmark modifications should go by between
5986 Bookmark position values are saved with surrounding context, so that
5987 `bookmark-jump' can find the proper position even if the file is
5988 modified slightly. The variable `bookmark-search-size' says how many
5989 characters of context to record, on each side of the bookmark's
5992 Here are some additional commands for working with bookmarks:
5994 `M-x bookmark-load <RET> FILENAME <RET>'
5995 Load a file named FILENAME that contains a list of bookmark
5996 values. You can use this command, as well as `bookmark-write', to
5997 work with other files of bookmark values in addition to your
5998 default bookmark file.
6000 `M-x bookmark-write <RET> FILENAME <RET>'
6001 Save all the current bookmark values in the file FILENAME.
6003 `M-x bookmark-delete <RET> BOOKMARK <RET>'
6004 Delete the bookmark named BOOKMARK.
6006 `M-x bookmark-insert-location <RET> BOOKMARK <RET>'
6007 Insert in the buffer the name of the file that bookmark BOOKMARK
6010 `M-x bookmark-insert <RET> BOOKMARK <RET>'
6011 Insert in the buffer the _contents_ of the file that bookmark
6015 File: xemacs.info, Node: Display, Next: Search, Prev: Registers, Up: Top
6017 11 Controlling the Display
6018 **************************
6020 Since only part of a large buffer fits in the window, XEmacs tries to
6021 show the part that is likely to be interesting. The display control
6022 commands allow you to specify which part of the text you want to see.
6025 Clear frame and redisplay, scrolling the selected window to center
6026 point vertically within it (`recenter').
6031 Scroll forward (a windowful or a specified number of lines)
6032 (`scroll-up'). On most X keyboards, you can get this
6033 functionality using the key labelled `Page Down', which generates
6034 either `next' or `pgdn'.
6039 Scroll backward (`scroll-down'). On most X keyboards, you can get
6040 this functionality using the key labelled `Page Up', which
6041 generates either `prior' or `pgup'.
6044 Scroll so point is on line ARG (`recenter').
6049 Scroll text in current window to the left (`scroll-left').
6054 Scroll to the right (`scroll-right').
6057 Make deeply indented lines invisible (`set-selective-display').
6061 * Scrolling:: Moving text up and down in a window.
6062 * Horizontal Scrolling:: Moving text left and right in a window.
6063 * Selective Display:: Hiding lines with lots of indentation.
6064 * Display Vars:: Information on variables for customizing display.
6067 File: xemacs.info, Node: Scrolling, Next: Horizontal Scrolling, Prev: Display, Up: Display
6072 If a buffer contains text that is too large to fit entirely within the
6073 window that is displaying the buffer, XEmacs shows a contiguous section
6074 of the text. The section shown always contains point.
6076 "Scrolling" means moving text up or down in the window so that
6077 different parts of the text are visible. Scrolling forward means that
6078 text moves up, and new text appears at the bottom. Scrolling backward
6079 moves text down and new text appears at the top.
6081 Scrolling happens automatically if you move point past the bottom or
6082 top of the window. You can also explicitly request scrolling with the
6083 commands in this section.
6086 Clear frame and redisplay, scrolling the selected window to center
6087 point vertically within it (`recenter').
6092 Scroll forward (a windowful or a specified number of lines)
6098 Scroll backward (`scroll-down').
6101 Scroll so point is on line ARG (`recenter').
6103 The most basic scrolling command is `C-l' (`recenter') with no
6104 argument. It clears the entire frame and redisplays all windows. In
6105 addition, it scrolls the selected window so that point is halfway down
6106 from the top of the window.
6108 The scrolling commands `C-v' and `M-v' let you move all the text in
6109 the window up or down a few lines. `C-v' (`scroll-up') with an
6110 argument shows you that many more lines at the bottom of the window,
6111 moving the text and point up together as `C-l' might. `C-v' with a
6112 negative argument shows you more lines at the top of the window.
6113 `Meta-v' (`scroll-down') is like `C-v', but moves in the opposite
6116 To read the buffer a windowful at a time, use `C-v' with no
6117 argument. `C-v' takes the last two lines at the bottom of the window
6118 and puts them at the top, followed by nearly a whole windowful of lines
6119 not previously visible. Point moves to the new top of the window if it
6120 was in the text scrolled off the top. `M-v' with no argument moves
6121 backward with similar overlap. The number of lines of overlap across a
6122 `C-v' or `M-v' is controlled by the variable
6123 `next-screen-context-lines'; by default, it is two.
6125 Another way to scroll is using `C-l' with a numeric argument. `C-l'
6126 does not clear the frame when given an argument; it only scrolls the
6127 selected window. With a positive argument N, `C-l' repositions text to
6128 put point N lines down from the top. An argument of zero puts point on
6129 the very top line. Point does not move with respect to the text;
6130 rather, the text and point move rigidly on the frame. `C-l' with a
6131 negative argument puts point that many lines from the bottom of the
6132 window. For example, `C-u - 1 C-l' puts point on the bottom line, and
6133 `C-u - 5 C-l' puts it five lines from the bottom. Just `C-u' as
6134 argument, as in `C-u C-l', scrolls point to the center of the frame.
6136 Scrolling happens automatically if point has moved out of the visible
6137 portion of the text when it is time to display. Usually scrolling is
6138 done to put point vertically centered within the window. However, if
6139 the variable `scroll-step' has a non-zero value, an attempt is made to
6140 scroll the buffer by that many lines; if that is enough to bring point
6141 back into visibility, that is what happens.
6143 Scrolling happens automatically if point has moved out of the visible
6144 portion of the text when it is time to display. Usually scrolling is
6145 done to put point vertically centered within the window. However, if
6146 the variable `scroll-step' has a non-zero value, an attempt is made to
6147 scroll the buffer by that many lines; if that is enough to bring point
6148 back into visibility, that is what happens.
6150 If you set `scroll-step' to a small value because you want to use
6151 arrow keys to scroll the screen without recentering, the redisplay
6152 preemption will likely make XEmacs keep recentering the screen when
6153 scrolling fast, regardless of `scroll-step'. To prevent this, set
6154 `scroll-conservatively' to a small value, which will have the result of
6155 overriding the redisplay preemption.
6158 File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display
6160 11.2 Horizontal Scrolling
6161 =========================
6164 Scroll text in current window to the left (`scroll-left').
6167 Scroll to the right (`scroll-right').
6169 The text in a window can also be scrolled horizontally. This means that
6170 each line of text is shifted sideways in the window, and one or more
6171 characters at the beginning of each line are not displayed at all.
6172 When a window has been scrolled horizontally in this way, text lines
6173 are truncated rather than continued (*note Continuation Lines::), with
6174 a `$' appearing in the first column when there is text truncated to the
6175 left, and in the last column when there is text truncated to the right.
6177 The command `C-x <' (`scroll-left') scrolls the selected window to
6178 the left by N columns with argument N. With no argument, it scrolls by
6179 almost the full width of the window (two columns less, to be precise).
6180 `C-x >' (`scroll-right') scrolls similarly to the right. The window
6181 cannot be scrolled any farther to the right once it is displaying
6182 normally (with each line starting at the window's left margin);
6183 attempting to do so has no effect.
6186 File: xemacs.info, Node: Selective Display, Next: Display Vars, Prev: Display, Up: Display
6188 11.3 Selective Display
6189 ======================
6191 XEmacs can hide lines indented more than a certain number of columns
6192 (you specify how many columns). This allows you to get an overview of
6193 a part of a program.
6195 To hide lines, type `C-x $' (`set-selective-display') with a numeric
6196 argument N. (*Note Arguments::, for information on giving the
6197 argument.) Lines with at least N columns of indentation disappear from
6198 the screen. The only indication of their presence are three dots
6199 (`...'), which appear at the end of each visible line that is followed
6200 by one or more invisible ones.
6202 The invisible lines are still present in the buffer, and most editing
6203 commands see them as usual, so it is very easy to put point in the
6204 middle of invisible text. When this happens, the cursor appears at the
6205 end of the previous line, after the three dots. If point is at the end
6206 of the visible line, before the newline that ends it, the cursor
6207 appears before the three dots.
6209 The commands `C-n' and `C-p' move across the invisible lines as if
6210 they were not there.
6212 To make everything visible again, type `C-x $' with no argument.
6215 File: xemacs.info, Node: Display Vars, Prev: Selective Display, Up: Display
6217 11.4 Variables Controlling Display
6218 ==================================
6220 This section contains information for customization only. Beginning
6221 users should skip it.
6223 When you reenter XEmacs after suspending, XEmacs normally clears the
6224 screen and redraws the entire display. On some terminals with more than
6225 one page of memory, it is possible to arrange the termcap entry so that
6226 the `ti' and `te' strings (output to the terminal when XEmacs is
6227 entered and exited, respectively) switch between pages of memory so as
6228 to use one page for XEmacs and another page for other output. In that
6229 case, you might want to set the variable `no-redraw-on-reenter' to
6230 non-`nil' so that XEmacs will assume, when resumed, that the screen
6231 page it is using still contains what XEmacs last wrote there.
6233 The variable `echo-keystrokes' controls the echoing of
6234 multi-character keys; its value is the number of seconds of pause
6235 required to cause echoing to start, or zero, meaning don't echo at all.
6238 If the variable `ctl-arrow' is `nil', control characters in the
6239 buffer are displayed with octal escape sequences, all except newline and
6240 tab. If its value is `t', then control characters will be printed with
6241 an up-arrow, for example `^A'.
6243 If its value is not `t' and not `nil', then characters whose code is
6244 greater than 160 (that is, the space character (32) with its high bit
6245 set) will be assumed to be printable, and will be displayed without
6246 alteration. This is the default when running under X Windows, since
6247 XEmacs assumes an ISO/8859-1 character set (also known as "Latin1").
6248 The `ctl-arrow' variable may also be set to an integer, in which case
6249 all characters whose codes are greater than or equal to that value will
6250 be assumed to be printable.
6252 Altering the value of `ctl-arrow' makes it local to the current
6253 buffer; until that time, the default value is in effect. *Note
6256 Normally, a tab character in the buffer is displayed as whitespace
6257 which extends to the next display tab stop position, and display tab
6258 stops come at intervals equal to eight spaces. The number of spaces
6259 per tab is controlled by the variable `tab-width', which is made local
6260 by changing it, just like `ctl-arrow'. Note that how the tab character
6261 in the buffer is displayed has nothing to do with the definition of
6264 If you set the variable `selective-display-ellipses' to `nil', the
6265 three dots at the end of a line that precedes invisible lines do not
6266 appear. There is no visible indication of the invisible lines. This
6267 variable becomes local automatically when set.
6270 File: xemacs.info, Node: Search, Next: Fixit, Prev: Display, Up: Top
6272 12 Searching and Replacement
6273 ****************************
6275 Like other editors, Emacs has commands for searching for occurrences of
6276 a string. The principal search command is unusual in that it is
6277 "incremental": it begins to search before you have finished typing the
6278 search string. There are also non-incremental search commands more like
6279 those of other editors.
6281 Besides the usual `replace-string' command that finds all
6282 occurrences of one string and replaces them with another, Emacs has a
6283 fancy replacement command called `query-replace' which asks
6284 interactively which occurrences to replace.
6288 * Incremental Search:: Search happens as you type the string.
6289 * Non-Incremental Search:: Specify entire string and then search.
6290 * Word Search:: Search for sequence of words.
6291 * Regexp Search:: Search for match for a regexp.
6292 * Regexps:: Syntax of regular expressions.
6293 * Search Case:: To ignore case while searching, or not.
6294 * Replace:: Search, and replace some or all matches.
6295 * Other Repeating Search:: Operating on all matches for some regexp.
6298 File: xemacs.info, Node: Incremental Search, Next: Non-Incremental Search, Prev: Search, Up: Search
6300 12.1 Incremental Search
6301 =======================
6303 An incremental search begins searching as soon as you type the first
6304 character of the search string. As you type in the search string, Emacs
6305 shows you where the string (as you have typed it so far) is found.
6306 When you have typed enough characters to identify the place you want,
6307 you can stop. Depending on what you do next, you may or may not need to
6308 terminate the search explicitly with a <RET>.
6311 Incremental search forward (`isearch-forward').
6314 Incremental search backward (`isearch-backward').
6316 `C-s' starts an incremental search. `C-s' reads characters from the
6317 keyboard and positions the cursor at the first occurrence of the
6318 characters that you have typed. If you type `C-s' and then `F', the
6319 cursor moves right after the first `F'. Type an `O', and see the
6320 cursor move to after the first `FO'. After another `O', the cursor is
6321 after the first `FOO' after the place where you started the search.
6322 Meanwhile, the search string `FOO' has been echoed in the echo area.
6324 The echo area display ends with three dots when actual searching is
6325 going on. When search is waiting for more input, the three dots are
6326 removed. (On slow terminals, the three dots are not displayed.)
6328 If you make a mistake in typing the search string, you can erase
6329 characters with <DEL>. Each <DEL> cancels the last character of the
6330 search string. This does not happen until Emacs is ready to read
6331 another input character; first it must either find, or fail to find,
6332 the character you want to erase. If you do not want to wait for this
6333 to happen, use `C-g' as described below.
6335 When you are satisfied with the place you have reached, you can type
6336 <RET> (or <C-m>), which stops searching, leaving the cursor where the
6337 search brought it. Any command not specially meaningful in searches
6338 also stops the search and is then executed. Thus, typing `C-a' exits
6339 the search and then moves to the beginning of the line. <RET> is
6340 necessary only if the next command you want to type is a printing
6341 character, <DEL>, <ESC>, or another control character that is special
6342 within searches (`C-q', `C-w', `C-r', `C-s', or `C-y').
6344 Sometimes you search for `FOO' and find it, but were actually
6345 looking for a different occurrence of it. To move to the next
6346 occurrence of the search string, type another `C-s'. Do this as often
6347 as necessary. If you overshoot, you can cancel some `C-s' characters
6350 After you exit a search, you can search for the same string again by
6351 typing just `C-s C-s': the first `C-s' is the key that invokes
6352 incremental search, and the second `C-s' means "search again".
6354 If the specified string is not found at all, the echo area displays
6355 the text `Failing I-Search'. The cursor is after the place where Emacs
6356 found as much of your string as it could. Thus, if you search for
6357 `FOOT', and there is no `FOOT', the cursor may be after the `FOO' in
6358 `FOOL'. At this point there are several things you can do. If you
6359 mistyped the search string, correct it. If you like the place you have
6360 found, you can type <RET> or some other Emacs command to "accept what
6361 the search offered". Or you can type `C-g', which removes from the
6362 search string the characters that could not be found (the `T' in
6363 `FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second
6364 `C-g' at that point cancels the search entirely, returning point to
6365 where it was when the search started.
6367 If a search is failing and you ask to repeat it by typing another
6368 `C-s', it starts again from the beginning of the buffer. Repeating a
6369 failing backward search with `C-r' starts again from the end. This is
6370 called "wrapping around". `Wrapped' appears in the search prompt once
6373 The `C-g' "quit" character does special things during searches; just
6374 what it does depends on the status of the search. If the search has
6375 found what you specified and is waiting for input, `C-g' cancels the
6376 entire search. The cursor moves back to where you started the search.
6377 If `C-g' is typed when there are characters in the search string that
6378 have not been found--because Emacs is still searching for them, or
6379 because it has failed to find them--then the search string characters
6380 which have not been found are discarded from the search string. The
6381 search is now successful and waiting for more input, so a second `C-g'
6382 cancels the entire search.
6384 To search for a control character such as `C-s' or <DEL> or <ESC>,
6385 you must quote it by typing `C-q' first. This function of `C-q' is
6386 analogous to its meaning as an Emacs command: it causes the following
6387 character to be treated the way a graphic character would normally be
6388 treated in the same context.
6390 To search backwards, you can use `C-r' instead of `C-s' to start the
6391 search; `C-r' is the key that runs the command (`isearch-backward') to
6392 search backward. You can also use `C-r' to change from searching
6393 forward to searching backwards. Do this if a search fails because the
6394 place you started was too far down in the file. Repeated `C-r' keeps
6395 looking for more occurrences backwards. `C-s' starts going forward
6396 again. You can cancel `C-r' in a search with <DEL>.
6398 The characters `C-y' and `C-w' can be used in incremental search to
6399 grab text from the buffer into the search string. This makes it
6400 convenient to search for another occurrence of text at point. `C-w'
6401 copies the word after point as part of the search string, advancing
6402 point over that word. Another `C-s' to repeat the search will then
6403 search for a string including that word. `C-y' is similar to `C-w' but
6404 copies the rest of the current line into the search string.
6406 The characters `M-p' and `M-n' can be used in an incremental search
6407 to recall things which you have searched for in the past. A list of
6408 the last 16 things you have searched for is retained, and `M-p' and
6409 `M-n' let you cycle through that ring.
6411 The character `M-<TAB>' does completion on the elements in the
6412 search history ring. For example, if you know that you have recently
6413 searched for the string `POTATOE', you could type `C-s P O M-<TAB>'.
6414 If you had searched for other strings beginning with `PO' then you
6415 would be shown a list of them, and would need to type more to select
6418 You can change any of the special characters in incremental search
6419 via the normal keybinding mechanism: simply add a binding to the
6420 `isearch-mode-map'. For example, to make the character `C-b' mean
6421 "search backwards" while in isearch-mode, do this:
6423 (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
6425 These are the default bindings of isearch-mode:
6428 Delete a character from the incremental search string
6429 (`isearch-delete-char').
6432 Exit incremental search (`isearch-exit').
6435 Quote special characters for incremental search
6436 (`isearch-quote-char').
6439 Repeat incremental search forward (`isearch-repeat-forward').
6442 Repeat incremental search backward (`isearch-repeat-backward').
6445 Pull rest of line from buffer into search string
6446 (`isearch-yank-line').
6449 Pull next word from buffer into search string
6450 (`isearch-yank-word').
6453 Cancels input back to what has been found successfully, or aborts
6454 the isearch (`isearch-abort').
6457 Recall the previous element in the isearch history ring
6458 (`isearch-ring-retreat').
6461 Recall the next element in the isearch history ring
6462 (`isearch-ring-advance').
6465 Do completion on the elements in the isearch history ring
6466 (`isearch-complete').
6469 Any other character which is normally inserted into a buffer when
6470 typed is automatically added to the search string in isearch-mode.
6472 12.1.1 Slow Terminal Incremental Search
6473 ---------------------------------------
6475 Incremental search on a slow terminal uses a modified style of display
6476 that is designed to take less time. Instead of redisplaying the buffer
6477 at each place the search gets to, it creates a new single-line window
6478 and uses that to display the line the search has found. The
6479 single-line window appears as soon as point gets outside of the text
6480 that is already on the screen.
6482 When the search is terminated, the single-line window is removed.
6483 Only at this time the window in which the search was done is
6484 redisplayed to show its new value of point.
6486 The three dots at the end of the search string, normally used to
6487 indicate that searching is going on, are not displayed in slow style
6490 The slow terminal style of display is used when the terminal baud
6491 rate is less than or equal to the value of the variable
6492 `search-slow-speed', initially 1200.
6494 The number of lines to use in slow terminal search display is
6495 controlled by the variable `search-slow-window-lines'. Its normal
6499 File: xemacs.info, Node: Non-Incremental Search, Next: Word Search, Prev: Incremental Search, Up: Search
6501 12.2 Non-Incremental Search
6502 ===========================
6504 Emacs also has conventional non-incremental search commands, which
6505 require you type the entire search string before searching begins.
6507 `C-s <RET> STRING <RET>'
6510 `C-r <RET> STRING <RET>'
6511 Search backward for STRING.
6513 To do a non-incremental search, first type `C-s <RET>' (or `C-s
6514 C-m'). This enters the minibuffer to read the search string.
6515 Terminate the string with <RET> to start the search. If the string is
6516 not found, the search command gets an error.
6518 By default, `C-s' invokes incremental search, but if you give it an
6519 empty argument, which would otherwise be useless, it invokes
6520 non-incremental search. Therefore, `C-s <RET>' invokes non-incremental
6521 search. `C-r <RET>' also works this way.
6523 Forward and backward non-incremental searches are implemented by the
6524 commands `search-forward' and `search-backward'. You can bind these
6525 commands to keys. The reason that incremental search is programmed to
6526 invoke them as well is that `C-s <RET>' is the traditional sequence of
6527 characters used in Emacs to invoke non-incremental search.
6529 Non-incremental searches performed using `C-s <RET>' do not call
6530 `search-forward' right away. They first check if the next character is
6531 `C-w', which requests a word search. *Note Word Search::.
6534 File: xemacs.info, Node: Word Search, Next: Regexp Search, Prev: Non-Incremental Search, Up: Search
6539 Word search looks for a sequence of words without regard to how the
6540 words are separated. More precisely, you type a string of many words,
6541 using single spaces to separate them, and the string is found even if
6542 there are multiple spaces, newlines or other punctuation between the
6545 Word search is useful in editing documents formatted by text
6546 formatters. If you edit while looking at the printed, formatted
6547 version, you can't tell where the line breaks are in the source file.
6548 Word search, allows you to search without having to know the line
6551 `C-s <RET> C-w WORDS <RET>'
6552 Search for WORDS, ignoring differences in punctuation.
6554 `C-r <RET> C-w WORDS <RET>'
6555 Search backward for WORDS, ignoring differences in punctuation.
6557 Word search is a special case of non-incremental search. It is
6558 invoked with `C-s <RET> C-w' followed by the search string, which must
6559 always be terminated with another <RET>. Being non-incremental, this
6560 search does not start until the argument is terminated. It works by
6561 constructing a regular expression and searching for that. *Note Regexp
6564 You can do a backward word search with `C-r <RET> C-w'.
6566 Forward and backward word searches are implemented by the commands
6567 `word-search-forward' and `word-search-backward'. You can bind these
6568 commands to keys. The reason that incremental search is programmed to
6569 invoke them as well is that `C-s <RET> C-w' is the traditional Emacs
6570 sequence of keys for word search.
6573 File: xemacs.info, Node: Regexp Search, Next: Regexps, Prev: Word Search, Up: Search
6575 12.4 Regular Expression Search
6576 ==============================
6578 A "regular expression" ("regexp", for short) is a pattern that denotes
6579 a (possibly infinite) set of strings. Searching for matches for a
6580 regexp is a powerful operation that editors on Unix systems have
6581 traditionally offered.
6583 To gain a thorough understanding of regular expressions and how to
6584 use them to best advantage, we recommend that you study `Mastering
6585 Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
6586 1997'. (It's known as the "Hip Owls" book, because of the picture on its
6587 cover.) You might also read the manuals to *Note (gawk)Top::, *Note
6588 (ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
6589 (rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
6590 regular expressions.
6592 The XEmacs regular expression syntax most closely resembles that of
6593 `ed', or `grep', the GNU versions of which all utilize the GNU `regex'
6594 library. XEmacs' version of `regex' has recently been extended with
6595 some Perl-like capabilities, described in the next section.
6597 In XEmacs, you can search for the next match for a regexp either
6598 incrementally or not.
6600 Incremental search for a regexp is done by typing `M-C-s'
6601 (`isearch-forward-regexp'). This command reads a search string
6602 incrementally just like `C-s', but it treats the search string as a
6603 regexp rather than looking for an exact match against the text in the
6604 buffer. Each time you add text to the search string, you make the
6605 regexp longer, and the new regexp is searched for. A reverse regexp
6606 search command `isearch-backward-regexp' also exists, bound to `M-C-r'.
6608 All of the control characters that do special things within an
6609 ordinary incremental search have the same functionality in incremental
6610 regexp search. Typing `C-s' or `C-r' immediately after starting a
6611 search retrieves the last incremental search regexp used: incremental
6612 regexp and non-regexp searches have independent defaults.
6614 Non-incremental search for a regexp is done by the functions
6615 `re-search-forward' and `re-search-backward'. You can invoke them with
6616 `M-x' or bind them to keys. You can also call `re-search-forward' by
6617 way of incremental regexp search with `M-C-s <RET>'; similarly for
6618 `re-search-backward' with `M-C-r <RET>'.
6621 File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search
6623 12.5 Syntax of Regular Expressions
6624 ==================================
6626 Regular expressions have a syntax in which a few characters are special
6627 constructs and the rest are "ordinary". An ordinary character is a
6628 simple regular expression that matches that character and nothing else.
6629 The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and
6630 `\'; no new special characters will be defined in the future. Any
6631 other character appearing in a regular expression is ordinary, unless a
6634 For example, `f' is not a special character, so it is ordinary, and
6635 therefore `f' is a regular expression that matches the string `f' and
6636 no other string. (It does _not_ match the string `ff'.) Likewise, `o'
6637 is a regular expression that matches only `o'.
6639 Any two regular expressions A and B can be concatenated. The result
6640 is a regular expression that matches a string if A matches some amount
6641 of the beginning of that string and B matches the rest of the string.
6643 As a simple example, we can concatenate the regular expressions `f'
6644 and `o' to get the regular expression `fo', which matches only the
6645 string `fo'. Still trivial. To do something more powerful, you need
6646 to use one of the special characters. Here is a list of them:
6649 is a special character that matches any single character except a
6650 newline. Using concatenation, we can make regular expressions
6651 like `a.b', which matches any three-character string that begins
6652 with `a' and ends with `b'.
6655 is not a construct by itself; it is a quantifying suffix operator
6656 that means to repeat the preceding regular expression as many
6657 times as possible. In `fo*', the `*' applies to the `o', so `fo*'
6658 matches one `f' followed by any number of `o's. The case of zero
6659 `o's is allowed: `fo*' does match `f'.
6661 `*' always applies to the _smallest_ possible preceding
6662 expression. Thus, `fo*' has a repeating `o', not a repeating `fo'.
6664 The matcher processes a `*' construct by matching, immediately, as
6665 many repetitions as can be found; it is "greedy". Then it
6666 continues with the rest of the pattern. If that fails,
6667 backtracking occurs, discarding some of the matches of the
6668 `*'-modified construct in case that makes it possible to match the
6669 rest of the pattern. For example, in matching `ca*ar' against the
6670 string `caaar', the `a*' first tries to match all three `a's; but
6671 the rest of the pattern is `ar' and there is only `r' left to
6672 match, so this try fails. The next alternative is for `a*' to
6673 match only two `a's. With this choice, the rest of the regexp
6674 matches successfully.
6676 Nested repetition operators can be extremely slow if they specify
6677 backtracking loops. For example, it could take hours for the
6678 regular expression `\(x+y*\)*a' to match the sequence
6679 `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because
6680 Emacs must try each imaginable way of grouping the 35 `x''s before
6681 concluding that none of them can work. To make sure your regular
6682 expressions run fast, check nested repetitions carefully.
6685 is a quantifying suffix operator similar to `*' except that the
6686 preceding expression must match at least once. It is also
6687 "greedy". So, for example, `ca+r' matches the strings `car' and
6688 `caaaar' but not the string `cr', whereas `ca*r' matches all three
6692 is a quantifying suffix operator similar to `*', except that the
6693 preceding expression can match either once or not at all. For
6694 example, `ca?r' matches `car' or `cr', but does not match anything
6698 works just like `*', except that rather than matching the longest
6699 match, it matches the shortest match. `*?' is known as a
6700 "non-greedy" quantifier, a regexp construct borrowed from Perl.
6702 This construct is very useful for when you want to match the text
6703 inside a pair of delimiters. For instance, `/\*.*?\*/' will match
6704 C comments in a string. This could not easily be achieved without
6705 the use of a non-greedy quantifier.
6707 This construct has not been available prior to XEmacs 20.4. It is
6708 not available in FSF Emacs.
6711 is the non-greedy version of `+'.
6714 is the non-greedy version of `?'.
6717 serves as an interval quantifier, analogous to `*' or `+', but
6718 specifies that the expression must match at least N times, but no
6719 more than M times. This syntax is supported by most Unix regexp
6720 utilities, and has been introduced to XEmacs for the version 20.3.
6722 Unfortunately, the non-greedy version of this quantifier does not
6723 exist currently, although it does in Perl.
6726 `[' begins a "character set", which is terminated by a `]'. In
6727 the simplest case, the characters between the two brackets form
6728 the set. Thus, `[ad]' matches either one `a' or one `d', and
6729 `[ad]*' matches any string composed of just `a's and `d's
6730 (including the empty string), from which it follows that `c[ad]*r'
6731 matches `cr', `car', `cdr', `caddaar', etc.
6733 The usual regular expression special characters are not special
6734 inside a character set. A completely different set of special
6735 characters exists inside character sets: `]', `-' and `^'.
6737 `-' is used for ranges of characters. To write a range, write two
6738 characters with a `-' between them. Thus, `[a-z]' matches any
6739 lower case letter. Ranges may be intermixed freely with individual
6740 characters, as in `[a-z$%.]', which matches any lower case letter
6741 or `$', `%', or a period.
6743 To include a `]' in a character set, make it the first character.
6744 For example, `[]a]' matches `]' or `a'. To include a `-', write
6745 `-' as the first character in the set, or put it immediately after
6746 a range. (You can replace one individual character C with the
6747 range `C-C' to make a place to put the `-'.) There is no way to
6748 write a set containing just `-' and `]'.
6750 To include `^' in a set, put it anywhere but at the beginning of
6754 `[^' begins a "complement character set", which matches any
6755 character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
6756 all characters _except_ letters and digits.
6758 `^' is not special in a character set unless it is the first
6759 character. The character following the `^' is treated as if it
6760 were first (thus, `-' and `]' are not special there).
6762 Note that a complement character set can match a newline, unless
6763 newline is mentioned as one of the characters not to match.
6766 is a special character that matches the empty string, but only at
6767 the beginning of a line in the text being matched. Otherwise it
6768 fails to match anything. Thus, `^foo' matches a `foo' that occurs
6769 at the beginning of a line.
6771 When matching a string instead of a buffer, `^' matches at the
6772 beginning of the string or after a newline character `\n'.
6775 is similar to `^' but matches only at the end of a line. Thus,
6776 `x+$' matches a string of one `x' or more at the end of a line.
6778 When matching a string instead of a buffer, `$' matches at the end
6779 of the string or before a newline character `\n'.
6782 has two functions: it quotes the special characters (including
6783 `\'), and it introduces additional special constructs.
6785 Because `\' quotes special characters, `\$' is a regular
6786 expression that matches only `$', and `\[' is a regular expression
6787 that matches only `[', and so on.
6790 *Please note:* For historical compatibility, special characters are
6791 treated as ordinary ones if they are in contexts where their special
6792 meanings make no sense. For example, `*foo' treats `*' as ordinary
6793 since there is no preceding expression on which the `*' can act. It is
6794 poor practice to depend on this behavior; quote the special character
6795 anyway, regardless of where it appears.
6797 For the most part, `\' followed by any character matches only that
6798 character. However, there are several exceptions: characters that,
6799 when preceded by `\', are special constructs. Such characters are
6800 always ordinary when encountered on their own. Here is a table of `\'
6804 specifies an alternative. Two regular expressions A and B with
6805 `\|' in between form an expression that matches anything that
6806 either A or B matches.
6808 Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
6810 `\|' applies to the largest possible surrounding expressions.
6811 Only a surrounding `\( ... \)' grouping can limit the grouping
6814 Full backtracking capability exists to handle multiple uses of
6818 is a grouping construct that serves three purposes:
6820 1. To enclose a set of `\|' alternatives for other operations.
6821 Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
6823 2. To enclose an expression for a suffix operator such as `*' to
6824 act on. Thus, `ba\(na\)*' matches `bananana', etc., with any
6825 (zero or more) number of `na' strings.
6827 3. To record a matched substring for future reference.
6829 This last application is not a consequence of the idea of a
6830 parenthetical grouping; it is a separate feature that happens to be
6831 assigned as a second meaning to the same `\( ... \)' construct
6832 because there is no conflict in practice between the two meanings.
6833 Here is an explanation of this feature:
6836 matches the same text that matched the DIGITth occurrence of a `\(
6839 In other words, after the end of a `\( ... \)' construct. the
6840 matcher remembers the beginning and end of the text matched by that
6841 construct. Then, later on in the regular expression, you can use
6842 `\' followed by DIGIT to match that same text, whatever it may
6845 The strings matching the first nine `\( ... \)' constructs
6846 appearing in a regular expression are assigned numbers 1 through 9
6847 in the order that the open parentheses appear in the regular
6848 expression. So you can use `\1' through `\9' to refer to the text
6849 matched by the corresponding `\( ... \)' constructs.
6851 For example, `\(.*\)\1' matches any newline-free string that is
6852 composed of two identical halves. The `\(.*\)' matches the first
6853 half, which may be anything, but the `\1' that follows must match
6854 the same exact text.
6857 is called a "shy" grouping operator, and it is used just like `\(
6858 ... \)', except that it does not cause the matched substring to be
6859 recorded for future reference.
6861 This is useful when you need a lot of grouping `\( ... \)'
6862 constructs, but only want to remember one or two - or if you have
6863 more than nine groupings and need to use backreferences to refer to
6864 the groupings at the end.
6866 Using `\(?: ... \)' rather than `\( ... \)' when you don't need
6867 the captured substrings ought to speed up your programs some,
6868 since it shortens the code path followed by the regular expression
6869 engine, as well as the amount of memory allocation and string
6870 copying it must do. The actual performance gain to be observed
6871 has not been measured or quantified as of this writing.
6873 The shy grouping operator has been borrowed from Perl, and has not
6874 been available prior to XEmacs 20.3, nor is it available in FSF
6878 matches any word-constituent character. The editor syntax table
6879 determines which characters these are. *Note Syntax::.
6882 matches any character that is not a word constituent.
6885 matches any character whose syntax is CODE. Here CODE is a
6886 character that represents a syntax code: thus, `w' for word
6887 constituent, `-' for whitespace, `(' for open parenthesis, etc.
6888 *Note Syntax::, for a list of syntax codes and the characters that
6892 matches any character whose syntax is not CODE.
6894 The following regular expression constructs match the empty
6895 string--that is, they don't use up any characters--but whether they
6896 match depends on the context.
6899 matches the empty string, but only at the beginning of the buffer
6900 or string being matched against.
6903 matches the empty string, but only at the end of the buffer or
6904 string being matched against.
6907 matches the empty string, but only at point. (This construct is
6908 not defined when matching against a string.)
6911 matches the empty string, but only at the beginning or end of a
6912 word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
6913 separate word. `\bballs?\b' matches `ball' or `balls' as a
6917 matches the empty string, but _not_ at the beginning or end of a
6921 matches the empty string, but only at the beginning of a word.
6924 matches the empty string, but only at the end of a word.
6926 Here is a complicated regexp used by Emacs to recognize the end of a
6927 sentence together with any whitespace that follows. It is given in Lisp
6928 syntax to enable you to distinguish the spaces from the tab characters.
6929 In Lisp syntax, the string constant begins and ends with a
6930 double-quote. `\"' stands for a double-quote as part of the regexp,
6931 `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for
6934 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
6936 This regexp contains four parts: a character set matching period, `?'
6937 or `!'; a character set matching close-brackets, quotes or parentheses,
6938 repeated any number of times; an alternative in backslash-parentheses
6939 that matches end-of-line, a tab or two spaces; and a character set
6940 matching whitespace characters, repeated any number of times.
6943 File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search
6945 12.6 Searching and Case
6946 =======================
6948 All searches in Emacs normally ignore the case of the text they are
6949 searching through; if you specify searching for `FOO', `Foo' and `foo'
6950 are also considered a match. Regexps, and in particular character
6951 sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
6953 If you want a case-sensitive search, set the variable
6954 `case-fold-search' to `nil'. Then all letters must match exactly,
6955 including case. `case-fold-search' is a per-buffer variable; altering
6956 it affects only the current buffer, but there is a default value which
6957 you can change as well. *Note Locals::. You can also use Case
6958 Sensitive Search from the Options menu on your screen.
6961 File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search
6963 12.7 Replacement Commands
6964 =========================
6966 Global search-and-replace operations are not needed as often in Emacs as
6967 they are in other editors, but they are available. In addition to the
6968 simple `replace-string' command which is like that found in most
6969 editors, there is a `query-replace' command which asks you, for each
6970 occurrence of a pattern, whether to replace it.
6972 The replace commands all replace one string (or regexp) with one
6973 replacement string. It is possible to perform several replacements in
6974 parallel using the command `expand-region-abbrevs'. *Note Expanding
6979 * Unconditional Replace:: Replacing all matches for a string.
6980 * Regexp Replace:: Replacing all matches for a regexp.
6981 * Replacement and Case:: How replacements preserve case of letters.
6982 * Query Replace:: How to use querying.