1 This is ../info/xemacs.info, produced by makeinfo version 4.0 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: Options Menu, Next: Buffers Menu, Prev: Apps Menu, Up: Pull-down Menus
38 The Options pull-down menu contains the Read Only, Case Sensitive
39 Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
40 Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
41 Menu Length..., Buffers Sub-Menus and Save Options menu items. When
42 you select a menu item, Emacs executes the equivalent command. For
43 some of the menu items, there are sub-menus which you will need to
47 Selecting this item will cause the buffer to visit the file in a
48 read-only mode. Changes to the file will not be allowed. This is
49 equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
52 Selecting this item will cause searches to be case-sensitive. If
53 its not selected then searches will ignore case. This option is
57 After selecting this item, when you type letters they will replace
58 existing text on a one-to-one basis, rather than pushing it to the
59 right. At the end of a line, such characters extend the line.
60 Before a tab, such characters insert until the tab is filled in.
61 This is the same as Emacs command `quoted-insert' (`C-q').
64 Selecting this item will cause automatic deletion of the selected
65 region. The typed text will replace the selection if the selection
66 is active (i.e. if its highlighted). If the option is not selected
67 then the typed text is just inserted at the point.
69 Teach Extended Commands
70 After you select this item, any time you execute a command with
71 `M-x'which has a shorter keybinding, you will be shown the
72 alternate binding before the command executes.
75 You can customize your init file to include the font-lock mode so
76 that when you select this item, the comments will be displayed in
77 one face, strings in another, reserved words in another, and so
78 on. *Note Init File::. When Fonts is selected, different parts of
79 the program will appear in different Fonts. When Colors is
80 selected, then the program will be displayed in different colors.
81 Selecting None causes the program to appear in just one Font and
82 Color. Selecting Less resets the Fonts and Colors to a fast,
83 minimal set of decorations. Selecting More resets the Fonts and
84 Colors to a larger set of decorations. For example, if Less is
85 selected (which is the default setting) then you might have all
86 comments in green color. Whereas, if More is selected then a
87 function name in the comments themselves might appear in a
88 different Color or Font.
91 After selecting Blink from this item, if you place the cursor on a
92 parenthesis, the matching parenthesis will blink. If you select
93 Highlight and place the cursor on a parenthesis, the whole
94 expression of the parenthesis under the cursor will be highlighted.
95 Selecting None will turn off the options (regarding Paren
96 Highlighting) which you had selected earlier.
99 You can select any Font for your program by choosing from one of
103 You can select any size ranging from 2 to 24 by selecting the
107 You can choose either Bold or Medium for the weight.
109 Buffers Menu Length...
110 Prompts you for the number of buffers to display. Then it will
111 display that number of most recently selected buffers.
114 After selection of this item the Buffers menu will contain several
115 commands, as submenus of each buffer line. If this item is
116 unselected, then there are no submenus for each buffer line, the
117 only command available will be selecting that buffer.
120 Selecting this item will save the current settings of your Options
121 menu to your init file. *Note Init File::.
124 File: xemacs.info, Node: Buffers Menu, Next: Tools Menu, Prev: Options Menu, Up: Pull-down Menus
129 The Buffers menu provides a selection of up to ten buffers and the
130 item List All Buffers, which provides a Buffer List. *Note List
131 Buffers::, for more information.
134 File: xemacs.info, Node: Tools Menu, Next: Help Menu, Prev: Buffers Menu, Up: Pull-down Menus
139 The Tools pull-down menu contains the Grep..., Compile..., Shell
140 Command..., Shell Command on Region..., Debug(GDB)... and
141 Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
142 sub-menus. When you select a menu item, Emacs executes the equivalent
143 command. For some of the menu items, there are sub-menus which you
147 File: xemacs.info, Node: Help Menu, Next: Menu Customization, Prev: Tools Menu, Up: Pull-down Menus
152 The Help Menu gives you access to Emacs Info and provides a menu
153 equivalent for each of the choices you have when using `C-h'. *Note
154 Help::, for more information.
156 The Help menu also gives access to UNIX online manual pages via the
157 UNIX Manual Page option.
160 File: xemacs.info, Node: Menu Customization, Prev: Help Menu, Up: Pull-down Menus
162 Customizing XEmacs Menus
163 ------------------------
165 You can customize any of the pull-down menus by adding or removing
166 menu items and disabling or enabling existing menu items.
168 The following functions are available:
169 `add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)'
170 Add a menu to the menu bar or one of its submenus.
172 `add-menu-item: (MENU-PATH ITEM-NAME FUNCTION'
173 ENABLED-P &optional BEFORE) Add a menu item to a menu, creating
174 the menu first if necessary.
176 `delete-menu-item: (PATH)'
177 Remove the menu item defined by PATH from the menu hierarchy.
179 `disable-menu-item: (PATH)'
180 Disable the specified menu item.
182 `enable-menu-item: (PATH)'
183 Enable the specified previously disabled menu item.
185 `relabel-menu-item: (PATH NEW-NAME)'
186 Change the string of the menu item specified by PATH to NEW-NAME.
188 Use the function `add-menu' to add a new menu or submenu. If a menu
189 or submenu of the given name exists already, it is changed.
191 MENU-PATH identifies the menu under which the new menu should be
192 inserted. It is a list of strings; for example, `("File")' names the
193 top-level File menu. `("File" "Foo")' names a hypothetical submenu of
194 File. If MENU-PATH is `nil', the menu is added to the menu bar itself.
196 MENU-NAME is the string naming the menu to be added.
198 MENU-ITEMS is a list of menu item descriptions. Each menu item
199 should be a vector of three elements:
201 * A string, which is the name of the menu item
203 * A symbol naming a command, or a form to evaluate
205 * `t' or `nil' to indicate whether the item is selectable
207 The optional argument BEFORE is the name of the menu before which
208 the new menu or submenu should be added. If the menu is already
209 present, it is not moved.
211 The function `add-menu-item' adds a menu item to the specified menu,
212 creating the menu first if necessary. If the named item already
213 exists, the menu remains unchanged.
215 MENU-PATH identifies the menu into which the new menu item should be
216 inserted. It is a list of strings; for example, `("File")' names the
217 top-level File menu. `("File" "Foo")' names a hypothetical submenu of
220 ITEM-NAME is the string naming the menu item to add.
222 FUNCTION is the command to invoke when this menu item is selected.
223 If it is a symbol, it is invoked with `call-interactively', in the same
224 way that functions bound to keys are invoked. If it is a list, the
225 list is simply evaluated.
227 ENABLED-P controls whether the item is selectable or not. It should
228 be `t', `nil', or a form to evaluate to decide. This form will be
229 evaluated just before the menu is displayed, and the menu item will be
230 selectable if that form returns non-`nil'.
232 For example, to make the `rename-file' command available from the
233 File menu, use the following code:
235 (add-menu-item '("File") "Rename File" 'rename-file t)
237 To add a submenu of file management commands using a File Management
238 item, use the following code:
240 (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
241 (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
242 (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
244 The optional BEFORE argument is the name of a menu item before which
245 the new item should be added. If the item is already present, it is
248 To remove a specified menu item from the menu hierarchy, use
251 PATH is a list of strings that identify the position of the menu
252 item in the menu hierarchy. `("File" "Save")' means the menu item
253 called Save under the top level File menu. `("Menu" "Foo" "Item")'
254 means the menu item called Item under the Foo submenu of Menu.
256 To disable a menu item, use `disable-menu-item'. The disabled menu
257 item is grayed and can no longer be selected. To make the item
258 selectable again, use `enable-menu-item'. `disable-menu-item' and
259 `enable-menu-item' both have the argument PATH.
261 To change the string of the specified menu item, use
262 `relabel-menu-item'. This function also takes the argument PATH.
264 NEW-NAME is the string to which the menu item will be changed.
267 File: xemacs.info, Node: Entering Emacs, Next: Exiting, Prev: Pull-down Menus, Up: Top
269 Entering and Exiting Emacs
270 **************************
272 The usual way to invoke XEmacs is to type `xemacs <RET>' at the
273 shell. XEmacs clears the screen and then displays an initial advisory
274 message and copyright notice. You can begin typing XEmacs commands
275 immediately afterward.
277 Some operating systems insist on discarding all type-ahead when
278 XEmacs starts up; they give XEmacs no way to prevent this. Therefore,
279 it is advisable to wait until XEmacs clears the screen before typing
280 your first editing command.
282 If you run XEmacs from a shell window under the X Window System, run
283 it in the background with `xemacs&'. This way, XEmacs does not tie up
284 the shell window, so you can use that to run other shell commands while
285 XEmacs operates its own X windows. You can begin typing XEmacs commands
286 as soon as you direct your keyboard input to the XEmacs frame.
288 Before Emacs reads the first command, you have not had a chance to
289 give a command to specify a file to edit. Since Emacs must always have
290 a current buffer for editing, it presents a buffer, by default, a buffer
291 named `*scratch*'. The buffer is in Lisp Interaction mode; you can use
292 it to type Lisp expressions and evaluate them, or you can ignore that
293 capability and simply doodle. (You can specify a different major mode
294 for this buffer by setting the variable `initial-major-mode' in your
295 init file. *Note Init File::.)
297 It is possible to specify files to be visited, Lisp files to be
298 loaded, and functions to be called, by giving Emacs arguments in the
299 shell command line. *Note Command Switches::. But we don't recommend
300 doing this. The feature exists mainly for compatibility with other
303 Many other editors are designed to be started afresh each time you
304 want to edit. You edit one file and then exit the editor. The next
305 time you want to edit either another file or the same one, you must run
306 the editor again. With these editors, it makes sense to use a
307 command-line argument to say which file to edit.
309 But starting a new Emacs each time you want to edit a different file
310 does not make sense. For one thing, this would be annoyingly slow. For
311 another, this would fail to take advantage of Emacs's ability to visit
312 more than one file in a single editing session. And it would lose the
313 other accumulated context, such as registers, undo history, and the mark
316 The recommended way to use XEmacs is to start it only once, just
317 after you log in, and do all your editing in the same Emacs session.
318 Each time you want to edit a different file, you visit it with the
319 existing Emacs, which eventually comes to have many files in it ready
320 for editing. Usually you do not kill the Emacs until you are about to
321 log out. *Note Files::, for more information on visiting more than one
325 File: xemacs.info, Node: Exiting, Next: Command Switches, Prev: Entering Emacs, Up: Top
330 There are two commands for exiting Emacs because there are two kinds
331 of exiting: "suspending" Emacs and "killing" Emacs.
333 "Suspending" means stopping Emacs temporarily and returning control
334 to its parent process (usually a shell), allowing you to resume editing
335 later in the same Emacs job, with the same buffers, same kill ring,
336 same undo history, and so on. This is the usual way to exit.
338 "Killing" Emacs means destroying the Emacs job. You can run Emacs
339 again later, but you will get a fresh Emacs; there is no way to resume
340 the same editing session after it has been killed.
343 Suspend Emacs or iconify a frame
344 (`suspend-emacs-or-iconify-frame'). If used under the X window
345 system, shrink the X window containing the Emacs frame to an icon
349 Kill Emacs (`save-buffers-kill-emacs').
351 If you use XEmacs under the X window system, `C-z' shrinks the X
352 window containing the Emacs frame to an icon. The Emacs process is
353 stopped temporarily, and control is returned to the window manager. If
354 more than one frame is associated with the Emacs process, only the
355 frame from which you used `C-z' is iconified.
357 To activate the "suspended" Emacs, use the appropriate window manager
358 mouse gestures. Usually left-clicking on the icon reactivates and
359 reopens the X window containing the Emacs frame, but the window manager
360 you use determines what exactly happens. To actually kill the Emacs
361 process, use `C-x C-c' or the Exit XEmacs item on the File menu.
363 To suspend Emacs, type `C-z' (`suspend-emacs'). This takes you back
364 to the shell from which you invoked Emacs. You can resume Emacs with
365 the shell command `%xemacs' in most common shells.
367 On systems that do not support suspending programs, `C-z' starts an
368 inferior shell that communicates directly with the terminal. Emacs
369 waits until you exit the subshell. (The way to do that is probably
370 with `C-d' or `exit', but it depends on which shell you use.) The only
371 way on these systems to get back to the shell from which Emacs was run
372 (to log out, for example) is to kill Emacs.
374 Suspending also fails if you run Emacs under a shell that doesn't
375 support suspending programs, even if the system itself does support it.
376 In such a case, you can set the variable `cannot-suspend' to a
377 non-`nil' value to force `C-z' to start an inferior shell. (One might
378 also describe Emacs's parent shell as "inferior" for failing to support
379 job control properly, but that is a matter of taste.)
381 When Emacs communicates directly with an X server and creates its own
382 dedicated X windows, `C-z' has a different meaning. Suspending an
383 applications that uses its own X windows is not meaningful or useful.
384 Instead, `C-z' runs the command `iconify-or-deiconify-frame', which
385 temporarily closes up the selected Emacs frame. The way to get back to
386 a shell window is with the window manager.
388 To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs'). A
389 two-character key is used for this to make it harder to type. Selecting
390 the Exit XEmacs option of the File menu is an alternate way of issuing
393 Unless a numeric argument is used, this command first offers to save
394 any modified file-visiting buffers. If you do not save all buffers,
395 you are asked for reconfirmation with `yes' before killing Emacs, since
396 any changes not saved will be lost forever. If any subprocesses are
397 still running, `C-x C-c' asks you to confirm killing them, since killing
398 Emacs will kill the subprocesses immediately.
400 There is no way to restart an Emacs session once you have killed it.
401 You can, however, arrange for Emacs to record certain session
402 information, such as which files are visited, when you kill it, so that
403 the next time you restart Emacs it will try to visit the same files and
406 The operating system usually listens for certain special characters
407 whose meaning is to kill or suspend the program you are running. This
408 operating system feature is turned off while you are in Emacs. The
409 meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the
410 use of `C-z' and `C-c' on several operating systems as the characters
411 for stopping or killing a program, but that is their only relationship
412 with the operating system. You can customize these keys to run any
413 commands of your choice (*note Keymaps::).
416 File: xemacs.info, Node: Command Switches, Next: Startup Paths, Prev: Exiting, Up: Top
418 Command Line Switches and Arguments
419 ===================================
421 XEmacs supports command line arguments you can use to request
422 various actions when invoking Emacs. The commands are for compatibility
423 with other editors and for sophisticated activities. If you are using
424 XEmacs under the X window system, you can also use a number of standard
425 Xt command line arguments. Command line arguments are not usually
426 needed for editing with Emacs; new users can skip this section.
428 Many editors are designed to be started afresh each time you want to
429 edit. You start the editor to edit one file; then exit the editor. The
430 next time you want to edit either another file or the same one, you
431 start the editor again. Under these circumstances, it makes sense to
432 use a command line argument to say which file to edit.
434 The recommended way to use XEmacs is to start it only once, just
435 after you log in, and do all your editing in the same Emacs process.
436 Each time you want to edit a file, you visit it using the existing
437 Emacs. Emacs creates a new buffer for each file, and (unless you kill
438 some of the buffers) Emacs eventually has many files in it ready for
439 editing. Usually you do not kill the Emacs process until you are about
440 to log out. Since you usually read files by typing commands to Emacs,
441 command line arguments for specifying a file when Emacs is started are
444 Emacs accepts command-line arguments that specify files to visit,
445 functions to call, and other activities and operating modes. If you
446 are running XEmacs under the X window system, a number of standard Xt
447 command line arguments are available, as well as a few X parameters
448 that are XEmacs-specific.
450 Options with long names with a single initial hyphen are also
451 recognized with the GNU double initial hyphen syntax. (The reverse is
454 The following subsections list:
455 * Command line arguments that you can always use
457 * Command line arguments that have to appear at the beginning of the
460 * Command line arguments that are only relevant if you are running
463 Command Line Arguments for Any Position
464 ---------------------------------------
466 Command line arguments are processed in the order they appear on the
467 command line; however, certain arguments (the ones in the second table)
468 must be at the front of the list if they are used.
470 Here are the arguments allowed:
473 Visit FILE using `find-file'. *Note Visiting::.
476 Visit FILE using `find-file', then go to line number LINENUM in it.
480 Load a file FILE of Lisp code with the function `load'. *Note
485 Call Lisp function FUNCTION with no arguments.
488 Interpret the next argument as a Lisp expression, and evaluate it.
489 You must be very careful of the shell quoting here.
493 Insert the contents of FILE into the current buffer. This is like
494 what `M-x insert-buffer' does; *Note Misc File Ops::.
497 Exit from Emacs without asking for confirmation. Always the last
498 argument processed, no matter where it appears in the command line.
502 Prints version information. This implies `-batch'.
505 XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs]
508 Prints a summary of command-line options and then exits.
510 Command Line Arguments (Beginning of Line Only)
511 -----------------------------------------------
513 The following arguments are recognized only at the beginning of the
514 command line. If more than one of them appears, they must appear in the
515 order in which they appear in this table.
519 Print the ID for the new portable dumper's dump file on the
520 terminal and exit. (Prints an error message and exits if XEmacs
521 was not configured `--pdump'.)
525 Don't load the dump file. Roughly equivalent to old temacs.
526 (Ignored if XEmacs was not configured `--pdump'.)
530 Use FILE instead of the terminal for input and output. This
531 implies the `-nw' option, documented below.
534 Run Emacs in "batch mode", which means that the text being edited
535 is not displayed and the standard Unix interrupt characters such as
536 `C-z' and `C-c' continue to have their normal effect. Emacs in
537 batch mode outputs to `stderr' only what would normally be printed
538 in the echo area under program control.
540 Batch mode is used for running programs written in Emacs Lisp from
541 shell scripts, makefiles, and so on. Normally the `-l' switch or
542 `-f' switch will be used as well, to invoke a Lisp program to do
543 the batch processing.
545 `-batch' implies `-q' (do not load an init file). It also causes
546 Emacs to kill itself after all command switches have been
547 processed. In addition, auto-saving is not done except in buffers
548 for which it has been explicitly requested.
552 Start up XEmacs in TTY mode (using the TTY XEmacs was started
553 from), rather than trying to connect to an X display. Note that
554 this happens automatically if the `DISPLAY' environment variable
558 Enter the debugger if an error in the init file occurs.
561 Displays information on how XEmacs constructs the various paths
562 into its hierarchy on startup. (See also *note Startup Paths::.)
565 Do not map the initial frame. This is useful if you want to start
566 up XEmacs as a server (e.g. for gnuserv screens or external client
571 Do not load your Emacs init file. *Note Init File::.
574 Do not load the site-specific init file `lisp/site-start.el'.
577 Do not load global symbol files (`auto-autoloads') at startup.
578 This implies `-vanilla'.
581 Do not process early packages. (For more information on startup
582 issues concerning the package system, *Note Startup Paths::.)
585 This is equivalent to `-q -no-site-file -no-early-packages'.
587 `-user-init-file FILE'
588 Load FILE as your Emacs init file instead of
589 `~/.xemacs/init.el'/`~/.emacs'.
591 `-user-init-directory DIRECTORY'
592 Use DIRECTORY as the location of your early package hierarchies
593 and the various user-specific initialization files.
597 Equivalent to `-user-init-file ~USER/.xemacs/init.el
598 -user-init-directory ~USER/.xemacs', or `-user-init-file
599 ~USER/.emacs -user-init-directory ~USER/.xemacs', whichever init
600 file comes first. *Note Init File::.
602 Note that the init file can get access to the command line argument
603 values as the elements of a list in the variable `command-line-args'.
604 (The arguments in the second table above will already have been
605 processed and will not be in the list.) The init file can override the
606 normal processing of the other arguments by setting this variable.
608 One way to use command switches is to visit many files automatically:
612 passes each `.c' file as a separate argument to Emacs, so that Emacs
613 visits each file (*note Visiting::).
615 Here is an advanced example that assumes you have a Lisp program file
616 called `hack-c-program.el' which, when loaded, performs some useful
617 operation on the current buffer, expected to be a C program.
619 xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
621 Here Emacs is told to visit `foo.c', load `hack-c-program.el' (which
622 makes changes in the visited file), save `foo.c' (note that
623 `save-buffer' is the function that `C-x C-s' is bound to), and then
624 exit to the shell from which the command was executed. `-batch'
625 guarantees there will be no problem redirecting output to `log',
626 because Emacs will not assume that it has a display terminal to work
629 Command Line Arguments (for XEmacs Under X)
630 -------------------------------------------
632 If you are running XEmacs under X, a number of options are available
633 to control color, border, and window title and icon name:
638 Use TITLE as the window title. This sets the `frame-title-format'
639 variable, which controls the title of the X window corresponding
640 to the selected frame. This is the same format as
645 Use TITLE as the icon name. This sets the
646 `frame-icon-title-format' variable, which controls the title of
647 the icon corresponding to the selected frame.
650 Use COLOR as the mouse color.
653 Use COLOR as the text-cursor foreground color.
656 Install a private colormap for XEmacs.
658 In addition, XEmacs allows you to use a number of standard Xt
659 command line arguments.
663 Use COLOR as the background color.
667 Use COLOR as the border color.
671 Use WIDTH as the border width.
675 When running under the X window system, create the window
676 containing the Emacs frame on the display named DISPLAY.
680 Use COLOR as the foreground color.
684 Use NAME as the default font.
689 Use the geometry (window size and/or position) specified by SPEC.
695 Bring up Emacs in reverse video.
698 Use the resource manager resources specified by NAME. The default
699 is to use the name of the program (`argv[0]') as the resource
703 Read something into the resource database for this invocation of
707 File: xemacs.info, Node: Startup Paths, Next: Packages, Prev: Command Switches, Up: Top
709 How XEmacs finds Directories and Files
710 ======================================
712 XEmacs deals with a multitude of files during operation. These files
713 are spread over many directories, and XEmacs determines the location of
714 most of these directories at startup and organizes them into various
715 paths. (A "path", for the purposes of this section, is simply a list
716 of directories which XEmacs searches successively in order to locate a
719 XEmacs Directory Hierarchies
720 ----------------------------
722 Many of the files XEmacs looks for are located within the XEmacs
723 installation itself. However, there are several views of what actually
724 constitutes the "XEmacs installation": XEmacs may be run from the
725 compilation directory, it may be installed into arbitrary directories,
726 spread over several directories unrelated to each other. Moreover, it
727 may subsequently be moved to a different place. (This last case is not
728 as uncommon as it sounds. Binary kits work this way.) Consequently,
729 XEmacs has quite complex procedures in place to find directories, no
730 matter where they may be hidden.
732 XEmacs will always respect directory options passed to `configure'.
733 However, if it cannot locate a directory at the configured place, it
734 will initiate a search for the directory in any of a number of
735 "hierarchies" rooted under a directory which XEmacs assumes contain
736 parts of the XEmacs installation; it may locate several such hierarchies
737 and search across them. (Typically, there are just one or two
738 hierarchies: the hierarchy where XEmacs was or will be installed, and
739 the one where it is being built.) Such a directory containing a
740 hierarchy is called a "root". Whenever this section refers to a
741 directory using the shorthand `<root>', it means that XEmacs searches
742 for it under all hierarchies XEmacs was able to scrounge up. In a
743 running XEmacs, the hierarchy roots are stored in the variable
749 Many relevant directories and files XEmacs uses are actually not
750 part of the core installation. They are part of any of the many
751 packages usually installed on top of an XEmacs installation. (*Note
752 Packages::.) Hence, they play a prominent role in the various paths
755 XEmacs locates packages in any of a number of package hierarchies.
756 Package hierarchies fall into three groups: "early", "late", and "last",
757 according to the relative location at which they show up in the various
758 XEmacs paths. Early package hierarchies are at the very front, late
759 ones somewhere in the middle, and last hierarchies are (you guessed it)
762 By default, XEmacs expects an early package hierarchy in the
763 subdirectory `.xemacs/xemacs-packages' of the user's home directory.
765 Moreover, XEmacs expects late hierarchies in the subdirectories
766 `site-packages', `mule-packages', and `xemacs-packages' (in that order)
767 of the `<root>/lib/xemacs' subdirectory of one of the installation
768 hierarchies. (If you run in-place, these are direct subdirectories of
769 the build directory.) Furthermore, XEmacs will also search these
770 subdirectories in the `<root>/lib/xemacs-<VERSION>' subdirectory and
771 prefer directories found there.
773 By default, XEmacs does not have a pre-configured last package
774 hierarchy. Last hierarchies are primarily for using package hierarchies
775 of outdated versions of XEmacs as a fallback option. For example, it is
776 possible to run XEmacs 21 with the 20.4 package hierarchy as a last
779 It is possible to specify at configure-time the location of the
780 various package hierarchies with the `--package-path' option to
781 configure. The early, late, and last components of the package path
782 are separated by double instead of single colons. If all three
783 components are present, they locate the early, late, and last package
784 hierarchies respectively. If two components are present, they locate
785 the early and late hierarchies. If only one component is present, it
786 locates the late hierarchy. At run time, the package path may also be
787 specified via the `EMACSPACKAGEPATH' environment variable.
789 An XEmacs package is laid out just like a normal installed XEmacs
790 lisp directory. It may have `lisp', `etc', `info', and `lib-src'
791 subdirectories. XEmacs adds these at appropriate places within the
792 various system-wide paths.
794 There may be any number of package hierarchy directories.
796 Directories and Paths
797 ---------------------
799 Here is a list of the various directories and paths XEmacs tries to
800 locate during startup. XEmacs distinguishes between directories and
801 paths specific to "version", "site", and "architecture" when looking
805 directories are specific to the version of XEmacs they belong to
806 and typically reside under `<root>/lib/xemacs-<VERSION>'.
809 directories are independent of the version of XEmacs they belong
810 to and typically reside under `<root>/lib/xemacs'
812 `architecture-specific'
813 directories are specific both to the version of XEmacs and the
814 architecture it runs on and typically reside under
815 `<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>'.
817 During installation, all of these directories may also reside
818 directly under `<root>', because that is where they are in the XEmacs
821 If XEmacs runs with the `-debug-paths' option (*note Command
822 Switches::), it will print the values of these variables, hopefully
823 aiding in debugging any problems which come up.
826 Contains the version-specific location of the Lisp files that come
827 with the core distribution of XEmacs. XEmacs will search it
828 recursively to a depth of 1 when setting up `load-path'.
831 Is where XEmacs searches for XEmacs Lisp files with commands like
832 `load-library'. It contains the package lisp directories (see
833 further down) and the version-specific core Lisp directories. If
834 the environment variable `EMACSLOADPATH' is set at startup, its
835 directories are prepended to `load-path'.
837 `Info-directory-list'
838 Contains the location of info files. (See *Note (info)::.) It
839 contains the package info directories and the version-specific core
840 documentation. Moreover, XEmacs will add `/usr/info',
841 `/usr/local/info' as well as the directories of the environment
842 variable `INFOPATH' to `Info-directory-list'.
845 Is the directory of architecture-dependent files that come with
846 XEmacs, especially executable programs intended for XEmacs to
850 Is the path for executables which XEmacs may want to start. It
851 contains the package executable paths as well as `exec-directory',
852 and the directories of the environment variables `PATH' and
856 Is the directory containing the architecture-specific `DOC' file
857 that contains documentation for XEmacs' commands.
860 Is the version-specific directory that contains core data files
861 XEmacs uses. It may be initialized from the `EMACSDATA'
862 environment variable.
864 `data-directory-list'
865 Is the path where XEmacs looks for data files. It contains
866 package data directories as well as `data-directory'.
869 File: xemacs.info, Node: Basic, Next: Undo, Prev: Packages, Up: Top
871 Basic Editing Commands
872 **********************
874 We now give the basics of how to enter text, make corrections, and
875 save the text in a file. If this material is new to you, you might
876 learn it more easily by running the Emacs learn-by-doing tutorial. To
877 use the tutorial, run Emacs and type `Control-h t'
878 (`help-with-tutorial'). You can also use Tutorials item from the Help
881 XEmacs comes with many translations of tutorial. If your XEmacs is
882 with MULE and you set up language environment correctly, XEmacs chooses
883 right tutorial when available (*note Language Environments::). If you
884 want specific translation, give `C-h t' a prefix argument, like `C-u
887 To clear the screen and redisplay, type `C-l' (`recenter').
892 * Inserting Text:: Inserting text by simply typing it.
893 * Moving Point:: How to move the cursor to the place where you want to
895 * Erasing:: Deleting and killing text.
896 * Files: Basic Files. Visiting, creating, and saving files.
897 * Help: Basic Help. Asking what a character does.
898 * Blank Lines:: Commands to make or delete blank lines.
899 * Continuation Lines:: Lines too wide for the screen.
900 * Position Info:: What page, line, row, or column is point on?
901 * Arguments:: Numeric arguments for repeating a command.
904 File: xemacs.info, Node: Inserting Text, Next: Moving Point, Up: Basic
909 To insert printing characters into the text you are editing, just
910 type them. This inserts the characters you type into the buffer at the
911 cursor (that is, at "point"; *note Point::). The cursor moves forward,
912 and any text after the cursor moves forward too. If the text in the
913 buffer is `FOOBAR', with the cursor before the `B', then if you type
914 `XX', you get `FOOXXBAR', with the cursor still before the `B'.
916 To "delete" text you have just inserted, use <BS>. <BS> deletes the
917 character _before_ the cursor (not the one that the cursor is on top of
918 or under; that is the character AFTER the cursor). The cursor and all
919 characters after it move backwards. Therefore, if you type a printing
920 character and then type <BS>, they cancel out.
922 To end a line and start typing a new one, type <RET>. This inserts
923 a newline character in the buffer. If point is in the middle of a
924 line, <RET> splits the line. Typing <DEL> when the cursor is at the
925 beginning of a line deletes the preceding newline, thus joining the
926 line with the preceding line.
928 Emacs can split lines automatically when they become too long, if you
929 turn on a special minor mode called "Auto Fill" mode. *Note Filling::,
930 for how to use Auto Fill mode.
932 If you prefer to have text characters replace (overwrite) existing
933 text rather than shove it to the right, you can enable Overwrite mode,
934 a minor mode. *Note Minor Modes::.
936 Direct insertion works for printing characters and <SPC>, but other
937 characters act as editing commands and do not insert themselves. If you
938 need to insert a control character or a character whose code is above
939 200 octal, you must "quote" it by typing the character `Control-q'
940 (`quoted-insert') first. (This character's name is normally written
941 `C-q' for short.) There are two ways to use `C-q':
943 * `C-q' followed by any non-graphic character (even `C-g') inserts
946 * `C-q' followed by a sequence of octal digits inserts the character
947 with the specified octal character code. You can use any number of
948 octal digits; any non-digit terminates the sequence. If the
949 terminating character is <RET>, it serves only to terminate the
950 sequence; any other non-digit is itself used as input after
951 terminating the sequence. (The use of octal sequences is disabled
952 in ordinary non-binary Overwrite mode, to give you a convenient
953 way to insert a digit instead of overwriting with it.)
955 A numeric argument to `C-q' specifies how many copies of the quoted
956 character should be inserted (*note Arguments::).
958 Customization information: <DEL>, in most modes, runs the command
959 `backward-or-forward-delete-char'; <RET> runs the command `newline',
960 and self-inserting printing characters run the command `self-insert',
961 which inserts whatever character was typed to invoke it. Some major
962 modes rebind <DEL> to other commands.
965 File: xemacs.info, Node: Moving Point, Next: Erasing, Prev: Inserting Text, Up: Basic
967 Changing the Location of Point
968 ==============================
970 To do more than insert characters, you have to know how to move point
971 (*note Point::). The simplest way to do this is with arrow keys, or by
972 clicking the left mouse button where you want to move to.
974 NOTE: Many of the following commands have two versions, one that uses
975 the function keys (e.g. <LEFT> or <END>) and one that doesn't. The
976 former versions may only be available on X terminals (i.e. not on
977 TTY's), but the latter are available on all terminals.
981 Move to the beginning of the line (`beginning-of-line').
985 Move to the end of the line (`end-of-line').
989 Move forward one character (`forward-char').
993 Move backward one character (`backward-char').
997 Move forward one word (`forward-word').
1001 Move backward one word (`backward-word').
1005 Move down one line, vertically (`next-line'). This command
1006 attempts to keep the horizontal position unchanged, so if you
1007 start in the middle of one line, you end in the middle of the
1008 next. When on the last line of text, `C-n' creates a new line and
1013 Move up one line, vertically (`previous-line').
1017 Move down one page, vertically (`scroll-up').
1021 Move up one page, vertically (`scroll-down').
1024 Clear the frame and reprint everything (`recenter'). Text moves
1025 on the frame to bring point to the center of the window.
1028 Move point to left margin, vertically centered in the window
1029 (`move-to-window-line'). Text does not move on the screen.
1031 A numeric argument says which screen line to place point on. It
1032 counts screen lines down from the top of the window (zero for the
1033 top line). A negative argument counts lines from the bottom (-1
1034 for the bottom line).
1037 Transpose two characters, the ones before and after the cursor
1038 (`transpose-chars').
1042 Move to the top of the buffer (`beginning-of-buffer'). With
1043 numeric argument N, move to N/10 of the way from the top. *Note
1044 Arguments::, for more information on numeric arguments.
1048 Move to the end of the buffer (`end-of-buffer').
1051 Read a number N and move point to buffer position N. Position 1
1052 is the beginning of the buffer.
1055 Read a number N and move point to line number N (`goto-line').
1056 Line 1 is the beginning of the buffer.
1058 `M-x set-goal-column'
1059 Use the current column of point as the "semi-permanent goal
1060 column" for `C-n' and `C-p' (`set-goal-column'). Henceforth, those
1061 commands always move to this column in each line moved into, or as
1062 close as possible given the contents of the line. This goal
1063 column remains in effect until canceled.
1065 `C-u M-x set-goal-column'
1066 Cancel the goal column. Henceforth, `C-n' and `C-p' once again
1067 try to avoid changing the horizontal position, as usual.
1069 If you set the variable `track-eol' to a non-`nil' value, then `C-n'
1070 and `C-p' when at the end of the starting line move to the end of
1071 another line. Normally, `track-eol' is `nil'. *Note Variables::, for
1072 how to set variables such as `track-eol'.
1074 Normally, `C-n' on the last line of a buffer appends a newline to
1075 it. If the variable `next-line-add-newlines' is `nil', then `C-n' gets
1076 an error instead (like `C-p' on the first line).
1079 File: xemacs.info, Node: Erasing, Next: Basic Files, Prev: Moving Point, Up: Basic
1085 Delete the character before or after point
1086 (`backward-or-forward-delete-char'). You can customize this
1087 behavior by setting the variable `delete-key-deletes-forward'.
1090 Delete the character after point (`delete-char').
1093 Kill to the end of the line (`kill-line').
1096 Kill forward to the end of the next word (`kill-word').
1099 Kill back to the beginning of the previous word
1100 (`backward-kill-word').
1102 You already know about the <DEL> key which deletes the character
1103 before point (that is, before the cursor). Another key, `Control-d'
1104 (`C-d' for short), deletes the character after point (that is, the
1105 character that the cursor is on). This shifts the rest of the text on
1106 the line to the left. If you type `C-d' at the end of a line, it joins
1107 together that line and the next line.
1109 To erase a larger amount of text, use the `C-k' key, which kills a
1110 line at a time. If you type `C-k' at the beginning or middle of a
1111 line, it kills all the text up to the end of the line. If you type
1112 `C-k' at the end of a line, it joins that line and the next line.
1114 *Note Killing::, for more flexible ways of killing text.
1117 File: xemacs.info, Node: Basic Files, Next: Basic Help, Prev: Erasing, Up: Basic
1122 The commands described above are sufficient for creating and altering
1123 text in an Emacs buffer; the more advanced Emacs commands just make
1124 things easier. But to keep any text permanently you must put it in a
1125 "file". Files are named units of text which are stored by the
1126 operating system for you to retrieve later by name. To look at or use
1127 the contents of a file in any way, including editing the file with
1128 Emacs, you must specify the file name.
1130 Consider a file named `/usr/rms/foo.c'. To begin editing this file
1133 C-x C-f /usr/rms/foo.c <RET>
1135 Here the file name is given as an "argument" to the command `C-x C-f'
1136 (`find-file'). That command uses the "minibuffer" to read the
1137 argument, and you type <RET> to terminate the argument (*note
1140 You can also use the Open... menu item from the File menu, then type
1141 the name of the file to the prompt.
1143 Emacs obeys the command by "visiting" the file: creating a buffer,
1144 copying the contents of the file into the buffer, and then displaying
1145 the buffer for you to edit. If you alter the text, you can "save" the
1146 new text in the file by typing `C-x C-s' (`save-buffer') or choosing
1147 Save Buffer from the File menu. This makes the changes permanent by
1148 copying the altered buffer contents back into the file
1149 `/usr/rms/foo.c'. Until you save, the changes exist only inside Emacs,
1150 and the file `foo.c' is unaltered.
1152 To create a file, visit the file with `C-x C-f' as if it already
1153 existed or choose Open... from the File menu and provide the name for
1154 the new file. Emacs will create an empty buffer in which you can
1155 insert the text you want to put in the file. When you save the buffer
1156 with `C-x C-s', or by choosing Save Buffer from the File menu, the file
1159 To learn more about using files, *Note Files::.
1162 File: xemacs.info, Node: Basic Help, Next: Blank Lines, Prev: Basic Files, Up: Basic
1167 If you forget what a key does, you can find out with the Help
1168 character, which is `C-h' (or <F1>, which is an alias for `C-h'). Type
1169 `C-h k' followed by the key you want to know about; for example, `C-h k
1170 C-n' tells you all about what `C-n' does. `C-h' is a prefix key; `C-h
1171 k' is just one of its subcommands (the command `describe-key'). The
1172 other subcommands of `C-h' provide different kinds of help. Type `C-h'
1173 twice to get a description of all the help facilities. *Note Help::.
1176 File: xemacs.info, Node: Blank Lines, Next: Continuation Lines, Prev: Basic Help, Up: Basic
1181 Here are special commands and techniques for putting in and taking
1185 Insert one or more blank lines after the cursor (`open-line').
1188 Delete all but one of many consecutive blank lines
1189 (`delete-blank-lines').
1191 When you want to insert a new line of text before an existing line,
1192 you can do it by typing the new line of text, followed by <RET>.
1193 However, it may be easier to see what you are doing if you first make a
1194 blank line and then insert the desired text into it. This is easy to do
1195 using the key `C-o' (`open-line'), which inserts a newline after point
1196 but leaves point in front of the newline. After `C-o', type the text
1197 for the new line. `C-o F O O' has the same effect as `F O O <RET>',
1198 except for the final location of point.
1200 You can make several blank lines by typing `C-o' several times, or
1201 by giving it a numeric argument to tell it how many blank lines to make.
1202 *Note Arguments::, for how. If you have a fill prefix, then `C-o'
1203 command inserts the fill prefix on the new line, when you use it at the
1204 beginning of a line. *Note Fill Prefix::.
1206 The easy way to get rid of extra blank lines is with the command
1207 `C-x C-o' (`delete-blank-lines'). `C-x C-o' in a run of several blank
1208 lines deletes all but one of them. `C-x C-o' on a solitary blank line
1209 deletes that blank line. When point is on a nonblank line, `C-x C-o'
1210 deletes any blank lines following that nonblank line.
1213 File: xemacs.info, Node: Continuation Lines, Next: Position Info, Prev: Blank Lines, Up: Basic
1218 If you add too many characters to one line without breaking it with
1219 <RET>, the line will grow to occupy two (or more) lines on the screen,
1220 with a curved arrow at the extreme right margin of all but the last of
1221 them. The curved arrow says that the following screen line is not
1222 really a distinct line in the text, but just the "continuation" of a
1223 line too long to fit the screen. Continuation is also called "line
1226 Sometimes it is nice to have Emacs insert newlines automatically when
1227 a line gets too long. Continuation on the screen does not do that. Use
1228 Auto Fill mode (*note Filling::) if that's what you want.
1230 Instead of continuation, long lines can be displayed by "truncation".
1231 This means that all the characters that do not fit in the width of the
1232 frame or window do not appear at all. They remain in the buffer,
1233 temporarily invisible. Right arrow in the last column (instead of the
1234 curved arrow) inform you that truncation is in effect.
1236 Truncation instead of continuation happens whenever horizontal
1237 scrolling is in use, and optionally in all side-by-side windows (*note
1238 Windows::). You can enable truncation for a particular buffer by
1239 setting the variable `truncate-lines' to non-`nil' in that buffer.
1240 (*Note Variables::.) Altering the value of `truncate-lines' makes it
1241 local to the current buffer; until that time, the default value is in
1242 effect. The default is initially `nil'. *Note Locals::.
1244 *Note Display Vars::, for additional variables that affect how text
projects / chise / xemacs-chise.git.1 / blob