1 This is ../info/xemacs.info, produced by makeinfo version 4.6 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace
35 Replace Commands and Case
36 -------------------------
38 If the arguments to a replace command are in lower case, the command
39 preserves case when it makes a replacement. Thus, the following
42 M-x replace-string <RET> foo <RET> bar <RET>
44 replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR',
45 and `Foo' with `Bar'. If upper-case letters are used in the second
46 argument, they remain upper-case every time that argument is inserted.
47 If upper-case letters are used in the first argument, the second
48 argument is always substituted exactly as given, with no case
49 conversion. Likewise, if the variable `case-replace' is set to `nil',
50 replacement is done without case conversion. If `case-fold-search' is
51 set to `nil', case is significant in matching occurrences of `foo' to
52 replace; also, case conversion of the replacement string is not done.
55 File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace
60 `M-% STRING <RET> NEWSTRING <RET>'
61 `M-x query-replace <RET> STRING <RET> NEWSTRING <RET>'
62 Replace some occurrences of STRING with NEWSTRING.
64 `M-x query-replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
65 Replace some matches for REGEXP with NEWSTRING.
67 If you want to change only some of the occurrences of `foo' to
68 `bar', not all of them, you can use `query-replace' instead of `M-%'.
69 This command finds occurrences of `foo' one by one, displays each
70 occurrence, and asks you whether to replace it. A numeric argument to
71 `query-replace' tells it to consider only occurrences that are bounded
72 by word-delimiter characters.
74 Aside from querying, `query-replace' works just like
75 `replace-string', and `query-replace-regexp' works just like
78 The things you can type when you are shown an occurrence of STRING
79 or a match for REGEXP are:
82 to replace the occurrence with NEWSTRING. This preserves case,
83 just like `replace-string', provided `case-replace' is non-`nil',
87 to skip to the next occurrence without replacing this one.
90 to replace this occurrence and display the result. You are then
91 prompted for another input character. However, since the
92 replacement has already been made, <DEL> and <SPC> are equivalent.
93 At this point, you can type `C-r' (see below) to alter the
94 replaced text. To undo the replacement, you can type `C-x u'.
95 This exits the `query-replace'. If you want to do further
96 replacement you must use `C-x <ESC> <ESC>' to restart (*note
100 to exit without doing any more replacements.
103 to replace this occurrence and then exit.
106 to replace all remaining occurrences without asking again.
109 to go back to the location of the previous occurrence (or what
110 used to be an occurrence), in case you changed it by mistake.
111 This works by popping the mark ring. Only one `^' in a row is
112 allowed, because only one previous replacement location is kept
113 during `query-replace'.
116 to enter a recursive editing level, in case the occurrence needs
117 to be edited rather than just replaced with NEWSTRING. When you
118 are done, exit the recursive editing level with `C-M-c' and the
119 next occurrence will be displayed. *Note Recursive Edit::.
122 to delete the occurrence, and then enter a recursive editing level
123 as in `C-r'. Use the recursive edit to insert text to replace the
124 deleted occurrence of STRING. When done, exit the recursive
125 editing level with `C-M-c' and the next occurrence will be
129 to redisplay the screen and then give another answer.
132 to display a message summarizing these options, then give another
135 If you type any other character, Emacs exits the `query-replace', and
136 executes the character as a command. To restart the `query-replace',
137 use `C-x <ESC> <ESC>', which repeats the `query-replace' because it
138 used the minibuffer to read its arguments. *Note C-x ESC ESC:
142 File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search
144 Other Search-and-Loop Commands
145 ==============================
147 Here are some other commands that find matches for a regular expression.
148 They all operate from point to the end of the buffer.
151 Print each line that follows point and contains a match for the
152 specified regexp. A numeric argument specifies the number of
153 context lines to print before and after each matching line; the
156 The buffer `*Occur*' containing the output serves as a menu for
157 finding occurrences in their original context. Find an occurrence
158 as listed in `*Occur*', position point there, and type `C-c C-c';
159 this switches to the buffer that was searched and moves point to
160 the original of the same occurrence.
162 `M-x list-matching-lines'
163 Synonym for `M-x occur'.
166 Print the number of matches following point for the specified
169 `M-x delete-non-matching-lines'
170 Delete each line that follows point and does not contain a match
171 for the specified regexp.
173 `M-x delete-matching-lines'
174 Delete each line that follows point and contains a match for the
178 File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top
180 Commands for Fixing Typos
181 *************************
183 This chapter describes commands that are especially useful when you
184 catch a mistake in your text just after you have made it, or when you
185 change your mind while composing text on line.
189 * Kill Errors:: Commands to kill a batch of recently entered text.
190 * Transpose:: Exchanging two characters, words, lines, lists...
191 * Fixing Case:: Correcting case of last word entered.
192 * Spelling:: Apply spelling checker to a word, or a whole file.
195 File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit
197 Killing Your Mistakes
198 =====================
201 Delete last character (`delete-backward-char').
204 Kill last word (`backward-kill-word').
207 Kill to beginning of sentence (`backward-kill-sentence').
209 The <DEL> character (`delete-backward-char') is the most important
210 correction command. When used among graphic (self-inserting)
211 characters, it can be thought of as canceling the last character typed.
213 When your mistake is longer than a couple of characters, it might be
214 more convenient to use `M-<DEL>' or `C-x <DEL>'. `M-<DEL>' kills back
215 to the start of the last word, and `C-x <DEL>' kills back to the start
216 of the last sentence. `C-x <DEL>' is particularly useful when you are
217 thinking of what to write as you type it, in case you change your mind
218 about phrasing. `M-<DEL>' and `C-x <DEL>' save the killed text for
219 `C-y' and `M-y' to retrieve. *Note Yanking::.
221 `M-<DEL>' is often useful even when you have typed only a few
222 characters wrong, if you know you are confused in your typing and aren't
223 sure exactly what you typed. At such a time, you cannot correct with
224 <DEL> except by looking at the screen to see what you did. It requires
225 less thought to kill the whole word and start over.
228 File: xemacs.info, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit
234 Transpose two characters (`transpose-chars').
237 Transpose two words (`transpose-words').
240 Transpose two balanced expressions (`transpose-sexps').
243 Transpose two lines (`transpose-lines').
245 The common error of transposing two adjacent characters can be fixed
246 with the `C-t' command (`transpose-chars'). Normally, `C-t' transposes
247 the two characters on either side of point. When given at the end of a
248 line, `C-t' transposes the last two characters on the line, rather than
249 transposing the last character of the line with the newline, which
250 would be useless. If you catch a transposition error right away, you
251 can fix it with just `C-t'. If you catch the error later, move the
252 cursor back to between the two transposed characters. If you
253 transposed a space with the last character of the word before it, the
254 word motion commands are a good way of getting there. Otherwise, a
255 reverse search (`C-r') is often the best way. *Note Search::.
257 `Meta-t' (`transpose-words') transposes the word before point with
258 the word after point. It moves point forward over a word, dragging the
259 word preceding or containing point forward as well. The punctuation
260 characters between the words do not move. For example, `FOO, BAR'
261 transposes into `BAR, FOO' rather than `BAR FOO,'.
263 `C-M-t' (`transpose-sexps') is a similar command for transposing two
264 expressions (*note Lists::), and `C-x C-t' (`transpose-lines')
265 exchanges lines. It works like `M-t' but in determines the division of
266 the text into syntactic units differently.
268 A numeric argument to a transpose command serves as a repeat count:
269 it tells the transpose command to move the character (word, sexp, line)
270 before or containing point across several other characters (words,
271 sexps, lines). For example, `C-u 3 C-t' moves the character before
272 point forward across three other characters. This is equivalent to
273 repeating `C-t' three times. `C-u - 4 M-t' moves the word before point
274 backward across four words. `C-u - C-M-t' would cancel the effect of
277 A numeric argument of zero transposes the character (word, sexp,
278 line) ending after point with the one ending after the mark (otherwise a
279 command with a repeat count of zero would do nothing).
282 File: xemacs.info, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit
288 Convert last word to lower case. Note that `Meta--' is
292 Convert last word to all upper case.
295 Convert last word to lower case with capital initial.
297 A common error is to type words in the wrong case. Because of this,
298 the word case-conversion commands `M-l', `M-u', and `M-c' do not move
299 the cursor when used with a negative argument. As soon as you see you
300 have mistyped the last word, you can simply case-convert it and
301 continue typing. *Note Case::.
304 File: xemacs.info, Node: Spelling, Prev: Fixing Case, Up: Fixit
306 Checking and Correcting Spelling
307 ================================
310 Check and correct spelling of word (`spell-word').
313 Check and correct spelling of each word in the buffer.
316 Check and correct spelling of each word in the region.
319 Check spelling of specified word.
321 To check the spelling of the word before point, and optionally
322 correct it, use the command `M-$' (`spell-word'). This command runs an
323 inferior process containing the `spell' program to see whether the word
324 is correct English. If it is not, it asks you to edit the word (in the
325 minibuffer) into a corrected spelling, and then performs a
326 `query-replace' to substitute the corrected spelling for the old one
327 throughout the buffer.
329 If you exit the minibuffer without altering the original spelling, it
330 means you do not want to do anything to that word. In that case, the
331 `query-replace' is not done.
333 `M-x spell-buffer' checks each word in the buffer the same way that
334 `spell-word' does, doing a `query-replace' for every incorrect word if
337 `M-x spell-region' is similar to `spell-buffer' but operates only on
338 the region, not the entire buffer.
340 `M-x spell-string' reads a string as an argument and checks whether
341 that is a correctly spelled English word. It prints a message giving
342 the answer in the echo area.
345 File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top
350 The basic unit of stored data in Unix is the "file". To edit a file,
351 you must tell Emacs to examine the file and prepare a buffer containing
352 a copy of the file's text. This is called "visiting" the file. Editing
353 commands apply directly to text in the buffer; that is, to the copy
354 inside Emacs. Your changes appear in the file itself only when you
355 "save" the buffer back into the file.
357 Emacs is also able to handle "remote files" which are stored on
358 other hosts. Not only is Emacs somewhat aware of the special issues
359 involved with network file systems, but it can also use FTP and ssh (or
360 rsh) to make local copies of the files, and refresh them on the remote
361 host automatically when you save the buffer. The FTP interface is
362 provided by the standard `efs' package *Note EFS: (efs)Top. The
363 ssh/rsh interface is provided by the optional `tramp' package *Note
364 TRAMP: (tramp)Top. These packages attempt to implement all of the
365 operations described below, making remote file use transparent (except
366 for unavoidable network delays).
368 In addition to visiting and saving files, Emacs can delete, copy,
369 rename, and append to files, and operate on file directories.
373 * File Names:: How to type and edit file name arguments.
374 * Visiting:: Visiting a file prepares Emacs to edit the file.
375 * Saving:: Saving makes your changes permanent.
376 * Reverting:: Reverting cancels all the changes not saved.
377 * Auto Save:: Auto Save periodically protects against loss of data.
378 * Version Control:: Version control systems (RCS and SCCS).
379 * ListDir:: Listing the contents of a file directory.
380 * Comparing Files:: Finding where two files differ.
381 * Dired:: ``Editing'' a directory to delete, rename, etc.
383 * Misc File Ops:: Other things you can do on files.
386 File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
391 Most Emacs commands that operate on a file require you to specify the
392 file name. (Saving and reverting are exceptions; the buffer knows which
393 file name to use for them.) File names are specified in the minibuffer
394 (*note Minibuffer::). "Completion" is available, to make it easier to
395 specify long file names. *Note Completion::.
397 There is always a "default file name" which is used if you enter an
398 empty argument by typing just <RET>. Normally the default file name is
399 the name of the file visited in the current buffer; this makes it easy
400 to operate on that file with any of the Emacs file commands.
402 The syntax for accessing remote files unfortunately varies depending
403 on the method used. The syntax for using FTP is
404 `/USER@REMOTE-HOST:PATH-ON-REMOTE-HOST'. The syntax for using ssh is
405 `/[USER@REMOTE-HOST]PATH-ON-REMOTE-HOST'.
407 In both cases the `USER@' portion is optional (it defaults to your
408 local user name). PATH-ON-REMOTE-HOST may use the `~' notation to
409 indicate USER's home directory on the remote host. The default file
410 name will reflect the remote host information.
412 Each buffer has a default directory, normally the same as the
413 directory of the file visited in that buffer. When Emacs reads a file
414 name, the default directory is used if you do not specify a directory.
415 If you specify a directory in a relative fashion, with a name that does
416 not start with a slash, it is interpreted with respect to the default
417 directory. The default directory of the current buffer is kept in the
418 variable `default-directory', which has a separate value in every
419 buffer. The value of the variable should end with a slash.
421 For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
422 the default directory is `/u/rms/gnu/'. If you type just `foo', which
423 does not specify a directory, it is short for `/u/rms/gnu/foo'.
424 `../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
425 the filename `/u/rms/gnu/new/foo'.
427 When visiting a remote file via EFS or TRAMP, the remote directory
428 becomes the default directory (*note Visiting::) for that buffer, just
429 as a local directory would.
431 The variable `default-directory-alist' takes an alist of major modes
432 and their opinions on `default-directory' as a Lisp expression to
433 evaluate. A resulting value of `nil' is ignored in favor of
436 You can create a new directory with the function `make-directory',
437 which takes as an argument a file name string. The current directory is
438 displayed in the minibuffer when the function is called; you can delete
439 the old directory name and supply a new directory name. For example, if
440 the current directory is `/u/rms/gnu', you can delete `gnu' and type
441 `oryx' and <RET> to create `/u/rms/oryx'. Removing a directory is
442 similar to creating one. To remove a directory, use
443 `remove-directory'; it takes one argument, a file name string.
445 The command `M-x pwd' prints the current buffer's default directory,
446 and the command `M-x cd' sets it (to a value read using the
447 minibuffer). A buffer's default directory changes only when the `cd'
448 command is used. A file-visiting buffer's default directory is
449 initialized to the directory of the file that is visited there. If a
450 buffer is created with `C-x b', its default directory is copied from
451 that of the buffer that was current at the time.
453 The default directory name actually appears in the minibuffer when
454 the minibuffer becomes active to read a file name. This serves two
455 purposes: it shows you what the default is, so that you can type a
456 relative file name and know with certainty what it will mean, and it
457 allows you to edit the default to specify a different directory. To
458 inhibit the insertion of the default directory, set the variable
459 `insert-default-directory' to `nil'.
461 Note that it is legitimate to type an absolute file name after you
462 enter the minibuffer, ignoring the presence of the default directory
463 name. The final minibuffer contents may look invalid, but that is not
464 so. *Note Minibuffer File::.
466 `$' in a file name is used to substitute environment variables. For
467 example, if you have used the shell command `setenv FOO rms/hacks' to
468 set up an environment variable named `FOO', then you can use
469 `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
470 `/u/rms/hacks/test.c'. The environment variable name consists of all
471 the alphanumeric characters after the `$'; alternatively, it may be
472 enclosed in braces after the `$'. Note that the `setenv' command
473 affects Emacs only if done before Emacs is started.
475 To access a file with `$' in its name, type `$$'. This pair is
476 converted to a single `$' at the same time variable substitution is
477 performed for single `$'. The Lisp function that performs the
478 substitution is called `substitute-in-file-name'. The substitution is
479 performed only on filenames read as such using the minibuffer.
482 File: xemacs.info, Node: Visiting, Next: Saving, Prev: File Names, Up: Files
488 Visit a file (`find-file').
491 Visit a different file instead of the one visited last
492 (`find-alternate-file').
495 Visit a file, in another window (`find-file-other-window'). Don't
499 Visit a file, in another frame (`find-file-other-frame'). Don't
500 change this window or frame.
502 "Visiting" a file means copying its contents into an Emacs buffer so
503 you can edit it. Emacs creates a new buffer for each file you visit.
504 We say that the buffer is visiting the file that it was created to
505 hold. Emacs constructs the buffer name from the file name by throwing
506 away the directory and keeping just the file name. For example, a file
507 named `/usr/rms/emacs.tex' is displayed in a buffer named `emacs.tex'.
508 If a buffer with that name exists, a unique name is constructed by
509 appending `<2>', `<3>',and so on, using the lowest number that makes a
510 name that is not already in use.
512 Each window's mode line shows the name of the buffer that is being
513 displayed in that window, so you can always tell what buffer you are
516 The changes you make with Emacs are made in the Emacs buffer. They
517 do not take effect in the file that you visit, or any other permanent
518 place, until you "save" the buffer. Saving the buffer means that Emacs
519 writes the current contents of the buffer into its visited file. *Note
522 If a buffer contains changes that have not been saved, the buffer is
523 said to be "modified". This is important because it implies that some
524 changes will be lost if the buffer is not saved. The mode line displays
525 two stars near the left margin if the buffer is modified.
527 To visit a file, use the command `C-x C-f' (`find-file'). Follow
528 the command with the name of the file you wish to visit, terminated by a
529 <RET>. If you are using XEmacs under X, you can also use the Open...
530 command from the File menu bar item.
532 The file name is read using the minibuffer (*note Minibuffer::), with
533 defaulting and completion in the standard manner (*note File Names::).
534 While in the minibuffer, you can abort `C-x C-f' by typing `C-g'.
536 `C-x C-f' has completed successfully when text appears on the screen
537 and a new buffer name appears in the mode line. If the specified file
538 does not exist and could not be created or cannot be read, an error
539 results. The error message is printed in the echo area, and includes
540 the name of the file that Emacs was trying to visit.
542 If you visit a file that is already in Emacs, `C-x C-f' does not make
543 another copy. It selects the existing buffer containing that file.
544 However, before doing so, it checks that the file itself has not changed
545 since you visited or saved it last. If the file has changed, Emacs
546 prints a warning message. *Note Simultaneous Editing: Interlocking.
548 You can switch to a specific file called out in the current buffer by
549 calling the function `find-this-file'. By providing a prefix argument,
550 this function calls `filename-at-point' and switches to a buffer
551 visiting the file FILENAME. It creates one if none already exists. You
552 can use this function to edit the file mentioned in the buffer you are
553 working in or to test if the file exists. You can do that by using the
554 minibuffer completion after snatching the all or part of the filename.
556 If the variable `find-file-use-truenames''s value is non-`nil', a
557 buffer's visited filename will always be traced back to the real file.
558 The filename will never be a symbolic link, and there will never be a
559 symbolic link anywhere in its directory path. In other words, the
560 `buffer-file-name' and `buffer-file-truename' will be equal.
562 If the variable `find-file-compare-truenames' value is non-`nil',
563 the `find-file' command will check the `buffer-file-truename' of all
564 visited files when deciding whether a given file is already in a
565 buffer, instead of just `buffer-file-name'. If you attempt to visit
566 another file which is a symbolic link to a file that is already in a
567 buffer, the existing buffer will be found instead of a newly created
568 one. This works if any component of the pathname (including a
569 non-terminal component) is a symbolic link as well, but doesn't work
570 with hard links (nothing does).
572 If you want to create a file, just visit it. Emacs prints `(New
573 File)' in the echo area, but in other respects behaves as if you had
574 visited an existing empty file. If you make any changes and save them,
577 If you visit a nonexistent file unintentionally (because you typed
578 the wrong file name), use the `C-x C-v' (`find-alternate-file') command
579 to visit the file you wanted. `C-x C-v' is similar to `C-x C-f', but
580 it kills the current buffer (after first offering to save it if it is
581 modified). `C-x C-v' is allowed even if the current buffer is not
584 If the file you specify is actually a directory, Dired is called on
585 that directory (*note Dired::). To inhibit this, set the variable
586 `find-file-run-dired' to `nil'; then it is an error to try to visit a
589 `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that
590 the buffer containing the specified file is selected in another window.
591 The window that was selected before `C-x 4 f' continues to show the
592 same buffer it was already showing. If you use this command when only
593 one window is being displayed, that window is split in two, with one
594 window showing the same buffer as before, and the other one showing the
595 newly requested file. *Note Windows::.
597 `C-x 5 C-f' (`find-file-other-frame') is like `C-x C-f' except that
598 it creates a new frame in which the file is displayed.
600 Use the function `find-this-file-other-window' to edit a file
601 mentioned in the buffer you are editing or to test if that file exists.
602 To do this, use the minibuffer completion after snatching the part or
603 all of the filename. By providing a prefix argument, the function calls
604 `filename-at-point' and switches you to a buffer visiting the file
605 FILENAME in another window. The function creates a buffer if none
606 already exists. This function is similar to `find-file-other-window'.
608 There are two hook variables that allow extensions to modify the
609 operation of visiting files. Visiting a file that does not exist runs
610 the functions in the list `find-file-not-found-hooks'; the value of this
611 variable is expected to be a list of functions which are called one by
612 one until one of them returns non-`nil'. Any visiting of a file,
613 whether extant or not, expects `find-file-hooks' to contain list of
614 functions and calls them all, one by one. In both cases the functions
615 receive no arguments. Visiting a nonexistent file runs the
616 `find-file-not-found-hooks' first.
619 File: xemacs.info, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files
624 "Saving" a buffer in Emacs means writing its contents back into the file
625 that was visited in the buffer.
628 Save the current buffer in its visited file (`save-buffer').
631 Save any or all buffers in their visited files
632 (`save-some-buffers').
635 Forget that the current buffer has been changed (`not-modified').
638 Save the current buffer in a specified file, and record that file
639 as the one visited in the buffer (`write-file').
641 `M-x set-visited-file-name'
642 Change file the name under which the current buffer will be saved.
644 To save a file and make your changes permanent, type `C-x C-s'
645 (`save-buffer'). After saving is finished, `C-x C-s' prints a message
648 Wrote /u/rms/gnu/gnu.tasks
650 If the selected buffer is not modified (no changes have been made in it
651 since the buffer was created or last saved), Emacs does not save it
652 because it would have no effect. Instead, `C-x C-s' prints a message
653 in the echo area saying:
655 (No changes need to be saved)
657 The command `C-x s' (`save-some-buffers') can save any or all
658 modified buffers. First it asks, for each modified buffer, whether to
659 save it. The questions should be answered with `y' or `n'. `C-x C-c',
660 the key that kills Emacs, invokes `save-some-buffers' and therefore
661 asks the same questions.
663 If you have changed a buffer and do not want the changes to be saved,
664 you should take some action to prevent it. Otherwise, you are liable to
665 save it by mistake each time you use `save-some-buffers' or a related
666 command. One thing you can do is type `M-~' (`not-modified'), which
667 removes the indication that the buffer is modified. If you do this,
668 none of the save commands will believe that the buffer needs to be
669 saved. (`~' is often used as a mathematical symbol for `not'; thus
670 `Meta-~' is `not', metafied.) You could also use
671 `set-visited-file-name' (see below) to mark the buffer as visiting a
672 different file name, not in use for anything important.
674 You can also undo all the changes made since the file was visited or
675 saved, by reading the text from the file again. This is called
676 "reverting". *Note Reverting::. Alternatively, you can undo all the
677 changes by repeating the undo command `C-x u'; but this only works if
678 you have not made more changes than the undo mechanism can remember.
680 `M-x set-visited-file-name' alters the name of the file that the
681 current buffer is visiting. It prompts you for the new file name in the
682 minibuffer. You can also use `set-visited-file-name' on a buffer that
683 is not visiting a file. The buffer's name is changed to correspond to
684 the file it is now visiting unless the new name is already used by a
685 different buffer; in that case, the buffer name is not changed.
686 `set-visited-file-name' does not save the buffer in the newly visited
687 file; it just alters the records inside Emacs so that it will save the
688 buffer in that file. It also marks the buffer as "modified" so that
691 If you wish to mark a buffer as visiting a different file and save it
692 right away, use `C-x C-w' (`write-file'). It is precisely equivalent
693 to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s' used on a
694 buffer that is not visiting a file has the same effect as `C-x C-w';
695 that is, it reads a file name, marks the buffer as visiting that file,
696 and saves it there. The default file name in a buffer that is not
697 visiting a file is made by combining the buffer name with the buffer's
700 If Emacs is about to save a file and sees that the date of the latest
701 version on disk does not match what Emacs last read or wrote, Emacs
702 notifies you of this fact, because it probably indicates a problem
703 caused by simultaneous editing and requires your immediate attention.
704 *Note Simultaneous Editing: Interlocking.
706 If the variable `require-final-newline' is non-`nil', Emacs puts a
707 newline at the end of any file that doesn't already end in one, every
708 time a file is saved or written.
710 Use the hook variable `write-file-hooks' to implement other ways to
711 write files, and specify things to be done before files are written.
712 The value of this variable should be a list of Lisp functions. When a
713 file is to be written, the functions in the list are called, one by
714 one, with no arguments. If one of them returns a non-`nil' value, Emacs
715 takes this to mean that the file has been written in some suitable
716 fashion; the rest of the functions are not called, and normal writing is
717 not done. Use the hook variable `after-save-hook' to list all the
718 functions to be called after writing out a buffer to a file.
722 * Backup:: How Emacs saves the old version of your file.
723 * Interlocking:: How Emacs protects against simultaneous editing
724 of one file by two users.
727 File: xemacs.info, Node: Backup, Next: Interlocking, Prev: Saving, Up: Saving
732 Because Unix does not provide version numbers in file names, rewriting a
733 file in Unix automatically destroys all record of what the file used to
734 contain. Thus, saving a file from Emacs throws away the old contents of
735 the file--or it would, except that Emacs carefully copies the old
736 contents to another file, called the "backup" file, before actually
737 saving. (Make sure that the variable `make-backup-files' is non-`nil'.
738 Backup files are not written if this variable is `nil').
740 At your option, Emacs can keep either a single backup file or a
741 series of numbered backup files for each file you edit.
743 Emacs makes a backup for a file only the first time a file is saved
744 from one buffer. No matter how many times you save a file, its backup
745 file continues to contain the contents from before the file was visited.
746 Normally this means that the backup file contains the contents from
747 before the current editing session; however, if you kill the buffer and
748 then visit the file again, a new backup file is made by the next save.
752 * Names: Backup Names. How backup files are named;
753 Choosing single or numbered backup files.
754 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
755 * Copying: Backup Copying. Backups can be made by copying or renaming.
758 File: xemacs.info, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup
760 Single or Numbered Backups
761 ..........................
763 If you choose to have a single backup file (the default), the backup
764 file's name is constructed by appending `~' to the file name being
765 edited; thus, the backup file for `eval.c' is `eval.c~'.
767 If you choose to have a series of numbered backup files, backup file
768 names are made by appending `.~', the number, and another `~' to the
769 original file name. Thus, the backup files of `eval.c' would be called
770 `eval.c.~1~', `eval.c.~2~', and so on, through names like
771 `eval.c.~259~' and beyond.
773 If protection stops you from writing backup files under the usual
774 names, the backup file is written as `%backup%~' in your home directory.
775 Only one such file can exist, so only the most recently made backup is
778 The choice of single backup or numbered backups is controlled by the
779 variable `version-control'. Its possible values are:
782 Make numbered backups.
785 Make numbered backups for files that have numbered backups already.
786 Otherwise, make single backups.
789 Never make numbered backups; always make single backups.
791 `version-control' may be set locally in an individual buffer to control
792 the making of backups for that buffer's file. For example, Rmail mode
793 locally sets `version-control' to `never' to make sure that there is
794 only one backup for an Rmail file. *Note Locals::.
797 File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup
799 Automatic Deletion of Backups
800 .............................
802 To prevent unlimited consumption of disk space, Emacs can delete
803 numbered backup versions automatically. Generally Emacs keeps the
804 first few backups and the latest few backups, deleting any in between.
805 This happens every time a new backup is made. The two variables that
806 control the deletion are `kept-old-versions' and `kept-new-versions'.
807 Their values are, respectively the number of oldest (lowest-numbered)
808 backups to keep and the number of newest (highest-numbered) ones to
809 keep, each time a new backup is made. The values are used just after a
810 new backup version is made; that newly made backup is included in the
811 count in `kept-new-versions'. By default, both variables are 2.
813 If `delete-old-versions' is non-`nil', excess middle versions are
814 deleted without notification. If it is `nil', the default, you are
815 asked whether the excess middle versions should really be deleted.
817 You can also use Dired's `.' (Period) command to delete old versions.
821 File: xemacs.info, Node: Backup Copying, Prev: Backup Deletion, Up: Backup
826 You can make backup files by copying the old file or by renaming it.
827 This makes a difference when the old file has multiple names. If you
828 rename the old file into the backup file, the alternate names become
829 names for the backup file. If you copy the old file instead, the
830 alternate names remain names for the file that you are editing, and the
831 contents accessed by those names will be the new contents.
833 How you make a backup file may also affect the file's owner and
834 group. If you use copying, they do not change. If renaming is used,
835 you become the file's owner, and the file's group becomes the default
836 (different operating systems have different defaults for the group).
838 Having the owner change is usually a good idea, because then the
839 owner is always the person who last edited the file. Occasionally
840 there is a file whose owner should not change. Since most files should
841 change owners, it is a good idea to use local variable lists to set
842 `backup-by-copying-when-mismatch' for the special cases where the owner
843 should not change (*note File Variables::).
845 Three variables control the choice of renaming or copying.
846 Normally, renaming is done. If the variable `backup-by-copying' is
847 non-`nil', copying is used. Otherwise, if the variable
848 `backup-by-copying-when-linked' is non-`nil', copying is done for files
849 that have multiple names, but renaming may still be done when the file
850 being edited has only one name. If the variable
851 `backup-by-copying-when-mismatch' is non-`nil', copying is done if
852 renaming would cause the file's owner or group to change.
855 File: xemacs.info, Node: Interlocking, Prev: Backup, Up: Saving
857 Protection Against Simultaneous Editing
858 ---------------------------------------
860 Simultaneous editing occurs when two users visit the same file, both
861 make changes, and both save their changes. If no one was informed that
862 this was happening, and you saved first, you would later find that your
863 changes were lost. On some systems, Emacs notices immediately when the
864 second user starts to change a file already being edited, and issues a
865 warning. When this is not possible, or if the second user has started
866 to change the file despite the warning, Emacs checks when the file is
867 saved, and issues a second warning when a user is about to overwrite a
868 file containing another user's changes. If you are the user editing the
869 file, you can take corrective action at this point and prevent actual
872 When you make the first modification in an Emacs buffer that is
873 visiting a file, Emacs records that you have locked the file. (It does
874 this by writing another file in a directory reserved for this purpose.)
875 The lock is removed when you save the changes. The idea is that the
876 file is locked whenever the buffer is modified. If you begin to modify
877 the buffer while the visited file is locked by someone else, this
878 constitutes a collision, and Emacs asks you what to do. It does this
879 by calling the Lisp function `ask-user-about-lock', which you can
880 redefine to customize what it does. The standard definition of this
881 function asks you a question and accepts three possible answers:
884 Steal the lock. Whoever was already changing the file loses the
885 lock, and you get the lock.
888 Proceed. Go ahead and edit the file despite its being locked by
892 Quit. This causes an error (`file-locked') and the modification
893 you were trying to make in the buffer does not actually take place.
895 Note that locking works on the basis of a file name; if a file has
896 multiple names, Emacs does not realize that the two names are the same
897 file and cannot prevent two users from editing it simultaneously under
898 different names. However, basing locking on names means that Emacs can
899 interlock the editing of new files that do not really exist until they
902 Some systems are not configured to allow Emacs to make locks. On
903 these systems, Emacs cannot detect trouble in advance, but it can still
904 detect it in time to prevent you from overwriting someone else's
907 Every time Emacs saves a buffer, it first checks the
908 last-modification date of the existing file on disk to see that it has
909 not changed since the file was last visited or saved. If the date does
910 not match, it implies that changes were made in the file in some other
911 way, and these changes are about to be lost if Emacs actually does
912 save. To prevent this, Emacs prints a warning message and asks for
913 confirmation before saving. Occasionally you will know why the file
914 was changed and know that it does not matter; then you can answer `yes'
915 and proceed. Otherwise, you should cancel the save with `C-g' and
916 investigate the situation.
918 The first thing you should do when notified that simultaneous editing
919 has already taken place is to list the directory with `C-u C-x C-d'
920 (*note Directory Listing: ListDir.). This will show the file's current
921 author. You should attempt to contact that person and ask him not to
922 continue editing. Often the next step is to save the contents of your
923 Emacs buffer under a different name, and use `diff' to compare the two
926 Simultaneous editing checks are also made when you visit a file that
927 is already visited with `C-x C-f' and when you start to modify a file.
928 This is not strictly necessary, but it is useful to find out about such
929 a problem as early as possible, when corrective action takes less work.
931 Another way to protect your file is to set the read, write, and
932 executable permissions for the file. Use the function
933 `set-default-file-modes' to set the UNIX `umask' value to the NMASK
934 argument. The `umask' value is the default protection mode for new
938 File: xemacs.info, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files
943 If you have made extensive changes to a file and then change your mind
944 about them, you can get rid of all changes by reading in the previous
945 version of the file. To do this, use `M-x revert-buffer', which
946 operates on the current buffer. Since reverting a buffer can result in
947 very extensive changes, you must confirm it with `yes'.
949 You may request that `revert-buffer' check for an auto-save file
950 that is more recent than the visited file by providing a prefix
951 argument. If a recent auto-save file exists, `revert-buffer' offers to
952 read the auto-save file instead of the visited file (*note Auto
953 Save::). Emacs asks you about the auto-save file before the request
954 for confirmation of the `revert-buffer' operation, and demands `y' or
955 `n' as an answer. If you have started to type `yes' to confirm the
956 revert operation, the `y' will answer the question about using the
957 auto-save file, but the `es' will not be valid confirmation for the
958 reversion. This gives you a chance to cancel the operation with `C-g'
959 and try again with the answers you really intend.
961 `revert-buffer' preserves the value of point (in characters from the
962 beginning of the file). If the file was edited only slightly, you will
963 be at approximately the same piece of text after reverting as before.
964 If you have made more extensive changes, after reversion point may be
965 in a totally different context than your last edits before reversion.
967 A buffer reverted from its visited file is marked "not modified"
968 until you make a change. The buffer's modes will also be recalculated,
971 Some kinds of buffers whose contents reflect data bases other than
972 files, such as Dired buffers, can also be reverted. For them,
973 reverting means refreshing their contents from the appropriate data.
974 Buffers created randomly with `C-x b' cannot be reverted;
975 `revert-buffer' reports an error when asked to do so.
978 File: xemacs.info, Node: Auto Save, Next: Version Control, Prev: Reverting, Up: Files
980 Auto-Saving: Protection Against Disasters
981 =========================================
983 Emacs saves all the visited files from time to time (based on counting
984 your keystrokes) without being asked. This is called "auto-saving".
985 It prevents you from losing more than a limited amount of work if the
988 When Emacs determines it is time for auto-saving, each buffer is
989 considered and is auto-saved if auto-saving is turned on for it and it
990 has changed since the last time it was auto-saved. If any auto-saving
991 is done, the message `Auto-saving...' is displayed in the echo area
992 until auto-saving is finished. Errors occurring during auto-saving are
993 caught so that they do not interfere with the execution of commands you
998 * Files: Auto Save Files.
999 * Control: Auto Save Control.
1000 * Recover:: Recovering text from auto-save files.
1003 File: xemacs.info, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save
1008 Auto-saving does not normally write to the files you visited, because
1009 it can be undesirable to save a program that is in an inconsistent
1010 state when you have made only half of a planned change. Instead,
1011 auto-saving is done in a different file called the "auto-save file",
1012 and the visited file is changed only when you save explicitly, for
1013 example, with `C-x C-s'.
1015 Normally, the name of the auto-save file is generated by appending
1016 `#' to the front and back of the visited file name. Thus, a buffer
1017 visiting file `foo.c' would be auto-saved in a file `#foo.c#'. Most
1018 buffers that are not visiting files are auto-saved only if you request
1019 it explicitly; when they are auto-saved, the auto-save file name is
1020 generated by appending `#%' to the front and `#' to the back of buffer
1021 name. For example, the `*mail*' buffer in which you compose messages
1022 to be sent is auto-saved in a file named `#%*mail*#'. Names of
1023 auto-save files are generated this way unless you customize the
1024 functions `make-auto-save-file-name' and `auto-save-file-name-p' to do
1025 something different. The file name to be used for auto-saving a buffer
1026 is calculated at the time auto-saving is turned on in that buffer.
1028 If you want auto-saving to be done in the visited file, set the
1029 variable `auto-save-visited-file-name' to be non-`nil'. In this mode,
1030 there is really no difference between auto-saving and explicit saving.
1032 Emacs deletes a buffer's auto-save file when you explicitly save the
1033 buffer. To inhibit the deletion, set the variable
1034 `delete-auto-save-files' to `nil'. Changing the visited file name with
1035 `C-x C-w' or `set-visited-file-name' renames any auto-save file to
1036 correspond to the new visited name.
1039 File: xemacs.info, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save
1041 Controlling Auto-Saving
1042 -----------------------
1044 Each time you visit a file, auto-saving is turned on for that file's
1045 buffer if the variable `auto-save-default' is non-`nil' (but not in
1046 batch mode; *note Entering Emacs::). The default for this variable is
1047 `t', so Emacs auto-saves buffers that visit files by default. You can
1048 use the command `M-x auto-save-mode' to turn auto-saving for a buffer
1049 on or off. Like other minor mode commands, `M-x auto-save-mode' turns
1050 auto-saving on with a positive argument, off with a zero or negative
1051 argument; with no argument, it toggles.
1053 Emacs performs auto-saving periodically based on counting how many
1054 characters you have typed since the last time auto-saving happened. The
1055 variable `auto-save-interval' specifies the number of characters
1056 between auto-saves. By default, it is 300. Emacs also auto-saves
1057 whenever you call the function `do-auto-save'.
1059 Emacs also does auto-saving whenever it gets a fatal error. This
1060 includes killing the Emacs job with a shell command such as `kill
1061 -emacs', or disconnecting a phone line or network connection.
1063 You can set the number of seconds of idle time before an auto-save is
1064 done. Setting the value of the variable `auto-save-timeout' to zero or
1065 `nil' will disable auto-saving due to idleness.
1067 The actual amount of idle time between auto-saves is logarithmically
1068 related to the size of the current buffer. This variable is the number
1069 of seconds after which an auto-save will happen when the current buffer
1070 is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3
1071 3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k
1074 For this variable to have any effect, you must do `(require 'timer)'.
1077 File: xemacs.info, Node: Recover, Prev: Auto Save Control, Up: Auto Save
1079 Recovering Data from Auto-Saves
1080 -------------------------------
1082 If you want to use the contents of an auto-save file to recover from a
1083 loss of data, use the command `M-x recover-file <RET> FILE <RET>'.
1084 Emacs visits FILE and then (after your confirmation) restores the
1085 contents from the auto-save file `#FILE#'. You can then save the file
1086 with `C-x C-s' to put the recovered text into FILE itself. For
1087 example, to recover file `foo.c' from its auto-save file `#foo.c#', do:
1089 M-x recover-file <RET> foo.c <RET>
1092 Before asking for confirmation, `M-x recover-file' displays a
1093 directory listing describing the specified file and the auto-save file,
1094 so you can compare their sizes and dates. If the auto-save file is
1095 older, `M-x recover-file' does not offer to read it.
1097 Auto-saving is disabled by `M-x recover-file' because using this
1098 command implies that the auto-save file contains valuable data from a
1099 past session. If you save the data in the visited file and then go on
1100 to make new changes, turn auto-saving back on with `M-x auto-save-mode'.
1103 File: xemacs.info, Node: Version Control, Next: ListDir, Prev: Auto Save, Up: Files
1108 "Version control systems" are packages that can record multiple
1109 versions of a source file, usually storing the unchanged parts of the
1110 file just once. Version control systems also record history information
1111 such as the creation time of each version, who created it, and a
1112 description of what was changed in that version.
1114 The GNU project recommends the version control system known as RCS,
1115 which is free software and available from the Free Software Foundation.
1116 Emacs supports use of either RCS or SCCS (a proprietary, but widely
1117 used, version control system that is not quite as powerful as RCS)
1118 through a facility called VC. The same Emacs commands work with either
1119 RCS or SCCS, so you hardly have to know which one of them you are using.
1123 * Concepts of VC:: Basic version control information;
1124 checking files in and out.
1125 * Editing with VC:: Commands for editing a file maintained
1126 with version control.
1127 * Variables for Check-in/out:: Variables that affect the commands used
1128 to check files in or out.
1129 * Log Entries:: Logging your changes.
1130 * Change Logs and VC:: Generating a change log file from log
1132 * Old Versions:: Examining and comparing old versions.
1133 * VC Status:: Commands to view the VC status of files and
1134 look at log entries.
1135 * Renaming and VC:: A command to rename both the source and
1136 master file correctly.
1137 * Snapshots:: How to make and use snapshots, a set of
1138 file versions that can be treated as a unit.
1139 * Version Headers:: Inserting version control headers into
1143 File: xemacs.info, Node: Concepts of VC, Next: Editing with VC, Prev: Version Control, Up: Version Control
1145 Concepts of Version Control
1146 ---------------------------
1148 When a file is under version control, we also say that it is
1149 "registered" in the version control system. Each registered file has a
1150 corresponding "master file" which represents the file's present state
1151 plus its change history, so that you can reconstruct from it either the
1152 current version or any specified earlier version. Usually the master
1153 file also records a "log entry" for each version describing what was
1154 changed in that version.
1156 The file that is maintained under version control is sometimes called
1157 the "work file" corresponding to its master file.
1159 To examine a file, you "check it out". This extracts a version of
1160 the source file (typically, the most recent) from the master file. If
1161 you want to edit the file, you must check it out "locked". Only one
1162 user can do this at a time for any given source file. (This kind of
1163 locking is completely unrelated to the locking that Emacs uses to
1164 detect simultaneous editing of a file.)
1166 When you are done with your editing, you must "check in" the new
1167 version. This records the new version in the master file, and unlocks
1168 the source file so that other people can lock it and thus modify it.
1170 Checkin and checkout are the basic operations of version control.
1171 You can do both of them with a single Emacs command: `C-x C-q'
1172 (`vc-toggle-read-only').
1174 A "snapshot" is a coherent collection of versions of the various
1175 files that make up a program. *Note Snapshots::.
1178 File: xemacs.info, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control
1180 Editing with Version Control
1181 ----------------------------
1183 When you visit a file that is maintained using version control, the
1184 mode line displays `RCS' or `SCCS' to inform you that version control
1185 is in use, and also (in case you care) which low-level system the file
1186 is actually stored in. Normally, such a source file is read-only, and
1187 the mode line indicates this with `%%'. With RCS, the mode line also
1188 indicates the number of the head version, which is normally also the
1189 version you are looking at.
1191 These are the commands for editing a file maintained with version
1195 Check the visited file in or out.
1198 Revert the buffer and the file to the last checked in version.
1201 Remove the last-entered change from the master for the visited
1202 file. This undoes your last check-in.
1205 Register the visited file in version control.
1207 (`C-x v' is the prefix key for version control commands; all of these
1208 commands except for `C-x C-q' start with `C-x v'.)
1210 When you want to modify a file maintained with version control, type
1211 `C-x C-q' (`vc-toggle-read-only'). This "checks out" the file, and
1212 tells RCS or SCCS to lock the file. This means making the file
1213 writable for you (but not for anyone else).
1215 When you are finished editing the file, type `C-x C-q' again. When
1216 used on a file that is checked out, this command checks the file in.
1217 But check-in does not start immediately; first, you must enter the "log
1218 entry"--a description of the changes in the new version. `C-x C-q'
1219 pops up a buffer for you to enter this in. When you are finished
1220 typing in the log entry, type `C-c C-c' to terminate it; this is when
1221 actual check-in takes place.
1223 Once you have checked in your changes, the file is unlocked, so that
1224 other users can lock it and modify it.
1226 Emacs does not save backup files for source files that are maintained
1227 with version control. If you want to make backup files despite version
1228 control, set the variable `vc-make-backup-files' to a non-`nil' value.
1230 Normally the work file exists all the time, whether it is locked or
1231 not. If you set `vc-keep-workfiles' to `nil', then checking in a new
1232 version with `C-x C-q' deletes the work file; but any attempt to visit
1233 the file with Emacs creates it again.
1235 It is not impossible to lock a file that someone else has locked. If
1236 you try to check out a file that is locked, `C-x C-q' asks you whether
1237 you want to "steal the lock." If you say yes, the file becomes locked
1238 by you, but a message is sent to the person who had formerly locked the
1239 file, to inform him of what has happened. The mode line indicates that
1240 a file is locked by someone else by displaying the login name of that
1241 person, before the version number.
1243 If you want to discard your current set of changes and revert to the
1244 last version checked in, use `C-x v u' (`vc-revert-buffer'). This
1245 cancels your last check-out, leaving the file unlocked. If you want to
1246 make a different set of changes, you must first check the file out
1247 again. `C-x v u' requires confirmation, unless it sees that you
1248 haven't made any changes since the last checked-in version.
1250 `C-x v u' is also the command to use if you lock a file and then
1251 don't actually change it.
1253 You can cancel a change after checking it in, with `C-x v c'
1254 (`vc-cancel-version'). This command discards all record of the most
1255 recent checked in version, so be careful about using it. It requires
1256 confirmation with `yes'. By default, `C-x v c' reverts your workfile
1257 and buffer to the previous version (the one that precedes the version
1258 that is deleted), but you can prevent the reversion by giving the
1259 command a prefix argument. Then the buffer does not change.
1261 This command with a prefix argument is useful when you have checked
1262 in a change and then discover a trivial error in it; you can cancel the
1263 erroneous check-in, fix the error, and repeat the check-in.
1265 Be careful when invoking `C-x v c', as it is easy to throw away a
1266 lot of work with it. To help you be careful, this command always
1267 requires confirmation with `yes'.
1269 You can register the visited file for version control using
1270 `C-x v i' (`vc-register'). If the variable `vc-default-back-end' is
1271 non-`nil', it specifies which version control system to use; otherwise,
1272 this uses RCS if it is installed on your system and SCCS if not. After
1273 `C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you
1276 By default, the initial version number is 1.1. If you want to use a
1277 different number, give `C-x v i' a prefix argument; then it reads the
1278 initial version number using the minibuffer.
1280 If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial
1281 comment (much like a log entry) to describe the purpose of this source
1284 To specify the version number for a subsequent checkin, use the
1285 command `C-u C-x v v'. `C-x v v' (`vc-next-action') is the command
1286 that `C-x C-q' uses to do the "real work" when the visited file uses
1287 version control. When used for checkin, and given a prefix argument,
1288 it reads the version number with the minibuffer.
1291 File: xemacs.info, Node: Variables for Check-in/out, Next: Log Entries, Prev: Editing with VC, Up: Version Control
1293 Variables Affecting Check-in and Check-out
1294 ------------------------------------------
1296 If `vc-suppress-confirm' is non-`nil', then `C-x C-q' and `C-x v i' can
1297 save the current buffer without asking, and `C-x v u' also operates
1298 without asking for confirmation. (This variable does not affect `C-x v
1299 c'; that is so drastic that it should always ask for confirmation.)
1301 VC mode does much of its work by running the shell commands for RCS
1302 and SCCS. If `vc-command-messages' is non-`nil', VC displays messages
1303 to indicate which shell commands it runs, and additional messages when
1304 the commands finish.
1306 Normally, VC assumes that it can deduce the locked/unlocked state of
1307 files by looking at the file permissions of the work file; this is
1308 fast. However, if the `RCS' or `SCCS' subdirectory is actually a
1309 symbolic link, then VC does not trust the file permissions to reflect
1312 You can specify the criterion for whether to trust the file
1313 permissions by setting the variable `vc-mistrust-permissions'. Its
1314 value may be `t' (always mistrust the file permissions and check the
1315 master file), `nil' (always trust the file permissions), or a function
1316 of one argument which makes the decision. The argument is the directory
1317 name of the `RCS' or `SCCS' subdirectory. A non-`nil' value from the
1318 function says to mistrust the file permissions.
1320 If you find that the file permissions of work files are changed
1321 erroneously, set `vc-mistrust-permissions' to `t'. Then VC always
1322 checks the master file to determine the file's status.
1324 You can specify additional directories to search for version control
1325 programs by setting the variable `vc-path'. These directories are
1326 searched before the usual search path. The proper result usually
1327 happens automatically.
1330 File: xemacs.info, Node: Log Entries, Next: Change Logs and VC, Prev: Variables for Check-in/out, Up: Version Control
1335 When you're editing an initial comment or log entry for inclusion in a
1336 master file, finish your entry by typing `C-c C-c'.
1339 Finish the comment edit normally (`vc-finish-logentry'). This
1342 To abort check-in, just don't type `C-c C-c' in that buffer. You
1343 can switch buffers and do other editing. As long as you don't try to
1344 check in another file, the entry you were editing remains in its
1345 buffer, and you can go back to that buffer at any time to complete the
1348 If you change several source files for the same reason, it is often
1349 convenient to specify the same log entry for many of the files. To do
1350 this, use the history of previous log entries. The commands `M-n',
1351 `M-p', `M-s' and `M-r' for doing this work just like the minibuffer
1352 history commands (except that these versions are used outside the
1355 Each time you check in a file, the log entry buffer is put into VC
1356 Log mode, which involves running two hooks: `text-mode-hook' and
1360 File: xemacs.info, Node: Change Logs and VC, Next: Old Versions, Prev: Log Entries, Up: Version Control
1365 If you use RCS for a program and also maintain a change log file for it
1366 (*note Change Log::), you can generate change log entries automatically
1367 from the version control log entries:
1370 Visit the current directory's change log file and create new
1371 entries for versions checked in since the most recent entry in the
1372 change log file (`vc-update-change-log').
1374 This command works with RCS only; it does not work with SCCS.
1376 For example, suppose the first line of `ChangeLog' is dated 10 April
1377 1992, and that the only check-in since then was by Nathaniel Bowditch
1378 to `rcs2log' on 8 May 1992 with log text `Ignore log messages that
1379 start with `#'.'. Then `C-x v a' visits `ChangeLog' and inserts text
1382 Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@apn.org)
1384 * rcs2log: Ignore log messages that start with `#'.
1386 You can then edit the new change log entry further as you wish.
1388 Normally, the log entry for file `foo' is displayed as `* foo: TEXT
1389 OF LOG ENTRY'. The `:' after `foo' is omitted if the text of the log
1390 entry starts with `(FUNCTIONNAME): '. For example, if the log entry
1391 for `vc.el' is `(vc-do-command): Check call-process status.', then the
1392 text in `ChangeLog' looks like this:
1394 Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@apn.org)
1396 * vc.el (vc-do-command): Check call-process status.
1398 When `C-x v a' adds several change log entries at once, it groups
1399 related log entries together if they all are checked in by the same
1400 author at nearly the same time. If the log entries for several such
1401 files all have the same text, it coalesces them into a single entry.
1402 For example, suppose the most recent checkins have the following log
1406 Fix expansion typos.
1408 Don't call expand-file-name.
1410 Don't call expand-file-name.
1412 They appear like this in `ChangeLog':
1414 Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org)
1416 * vc.texinfo: Fix expansion typos.
1418 * vc.el, vc-hooks.el: Don't call expand-file-name.
1420 Normally, `C-x v a' separates log entries by a blank line, but you
1421 can mark several related log entries to be clumped together (without an
1422 intervening blank line) by starting the text of each related log entry
1423 with a label of the form `{CLUMPNAME} '. The label itself is not
1424 copied to `ChangeLog'. For example, suppose the log entries are:
1427 {expand} Fix expansion typos.
1429 {expand} Don't call expand-file-name.
1431 {expand} Don't call expand-file-name.
1433 Then the text in `ChangeLog' looks like this:
1435 Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org)
1437 * vc.texinfo: Fix expansion typos.
1438 * vc.el, vc-hooks.el: Don't call expand-file-name.
1440 A log entry whose text begins with `#' is not copied to `ChangeLog'.
1441 For example, if you merely fix some misspellings in comments, you can
1442 log the change with an entry beginning with `#' to avoid putting such
1443 trivia into `ChangeLog'.
1446 File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control
1448 Examining And Comparing Old Versions
1449 ------------------------------------
1451 `C-x v ~ VERSION <RET>'
1452 Examine version VERSION of the visited file, in a buffer of its
1453 own (`vc-version-other-window').
1456 Compare the current buffer contents with the latest checked-in
1457 version of the file.
1459 `C-u C-x v = FILE <RET> OLDVERS <RET> NEWVERS <RET>'
1460 Compare the specified two versions of FILE.
1462 You can examine any version of a file by first visiting it, and then
1463 using `C-x v ~ VERSION <RET>' (`vc-version-other-window'). This puts
1464 the text of version VERSION in a file named `FILENAME.~VERSION~', then
1465 visits it in a separate window.
1467 To compare two versions of a file, use the command `C-x v ='
1470 Plain `C-x v =' compares the current buffer contents (saving them in
1471 the file if necessary) with the last checked-in version of the file.
1472 With a prefix argument, `C-x v =' reads a file name and two version
1473 numbers, then compares those versions of the specified file.
1475 If you supply a directory name instead of the name of a work file,
1476 this command compares the two specified versions of all registered files
1477 in that directory and its subdirectories. You can also specify a
1478 snapshot name (*note Snapshots::) instead of one or both version
1481 You can specify a checked-in version by its number; you can specify
1482 the most recent checked-in version with an empty version number.
1484 This command works by running the `vcdiff' utility, getting the
1485 options from the variable `diff-switches'. It displays the output in a
1486 special buffer in another window. Unlike the `M-x diff' command, `C-x
1487 v =' does not try to find the changes in the old and new versions.
1488 This is because one or both versions normally do not exist as files.
1489 They exist only in the records of the master file. *Note Comparing
1490 Files::, for more information about `M-x diff'.
1493 File: xemacs.info, Node: VC Status, Next: Renaming and VC, Prev: Old Versions, Up: Version Control
1498 To view the detailed version control status and history of a file, type
1499 `C-x v l' (`vc-print-log'). It displays the history of changes to the
1500 current file, including the text of the log entries. The output
1501 appears in a separate window.
1503 When you are working on a large program, it's often useful to find
1504 all the files that are currently locked, or all the files maintained in
1505 version control at all. You can use `C-x v d' (`vc-directory') to show
1506 all the locked files in or beneath the current directory. This
1507 includes all files that are locked by any user. `C-u C-x v d' lists
1508 all files in or beneath the current directory that are maintained with
1511 The list of files is displayed as a buffer that uses an augmented
1512 Dired mode. The names of the users locking various files are shown (in
1513 parentheses) in place of the owner and group. All the normal Dired
1514 commands work in this buffer. Most interactive VC commands work also,
1515 and apply to the file name on the current line.
1517 The `C-x v v' command (`vc-next-action'), when used in the augmented
1518 Dired buffer, operates on all the marked files (or the file on the
1519 current line). If it operates on more than one file, it handles each
1520 file according to its current state; thus, it may check out one file
1521 and check in another (because it is already checked out). If it has to
1522 check in any files, it reads a single log entry, then uses that text
1523 for all the files being checked in. This can be convenient for
1524 registering or checking in several files at once, as part of the same
1528 File: xemacs.info, Node: Renaming and VC, Next: Snapshots, Prev: VC Status, Up: Version Control
1530 Renaming VC Work Files and Master Files
1531 ---------------------------------------
1533 When you rename a registered file, you must also rename its master file
1534 correspondingly to get proper results. Use `vc-rename-file' to rename
1535 the source file as you specify, and rename its master file accordingly.
1536 It also updates any snapshots (*note Snapshots::) that mention the
1537 file, so that they use the new name; despite this, the snapshot thus
1538 modified may not completely work (*note Snapshot Caveats::).
1540 You cannot use `vc-rename-file' on a file that is locked by someone
1544 File: xemacs.info, Node: Snapshots, Next: Version Headers, Prev: Renaming and VC, Up: Version Control
1549 A "snapshot" is a named set of file versions (one for each registered
1550 file) that you can treat as a unit. One important kind of snapshot is
1551 a "release", a (theoretically) stable version of the system that is
1552 ready for distribution to users.
1556 * Making Snapshots:: The snapshot facilities.
1557 * Snapshot Caveats:: Things to be careful of when using snapshots.
1560 File: xemacs.info, Node: Making Snapshots, Next: Snapshot Caveats, Prev: Snapshots, Up: Snapshots
1562 Making and Using Snapshots
1563 ..........................
1565 There are two basic commands for snapshots; one makes a snapshot with a
1566 given name, the other retrieves a named snapshot.
1568 `C-x v s NAME <RET>'
1569 Define the last saved versions of every registered file in or
1570 under the current directory as a snapshot named NAME
1571 (`vc-create-snapshot').
1573 `C-x v r NAME <RET>'
1574 Check out all registered files at or below the current directory
1575 level using whatever versions correspond to the snapshot NAME
1576 (`vc-retrieve-snapshot').
1578 This command reports an error if any files are locked at or below
1579 the current directory, without changing anything; this is to avoid
1580 overwriting work in progress.
1582 A snapshot uses a very small amount of resources--just enough to
1583 record the list of file names and which version belongs to the
1584 snapshot. Thus, you need not hesitate to create snapshots whenever
1587 You can give a snapshot name as an argument to `C-x v =' or `C-x v
1588 ~' (*note Old Versions::). Thus, you can use it to compare a snapshot
1589 against the current files, or two snapshots against each other, or a
1590 snapshot against a named version.
1593 File: xemacs.info, Node: Snapshot Caveats, Prev: Making Snapshots, Up: Snapshots
1598 VC's snapshot facilities are modeled on RCS's named-configuration
1599 support. They use RCS's native facilities for this, so under VC
1600 snapshots made using RCS are visible even when you bypass VC.
1602 For SCCS, VC implements snapshots itself. The files it uses contain
1603 name/file/version-number triples. These snapshots are visible only
1606 A snapshot is a set of checked-in versions. So make sure that all
1607 the files are checked in and not locked when you make a snapshot.
1609 File renaming and deletion can create some difficulties with
1610 snapshots. This is not a VC-specific problem, but a general design
1611 issue in version control systems that no one has solved very well yet.
1613 If you rename a registered file, you need to rename its master along
1614 with it (the command `vc-rename-file' does this automatically). If you
1615 are using SCCS, you must also update the records of the snapshot, to
1616 mention the file by its new name (`vc-rename-file' does this, too). An
1617 old snapshot that refers to a master file that no longer exists under
1618 the recorded name is invalid; VC can no longer retrieve it. It would
1619 be beyond the scope of this manual to explain enough about RCS and SCCS
1620 to explain how to update the snapshots by hand.
1622 Using `vc-rename-file' makes the snapshot remain valid for
1623 retrieval, but it does not solve all problems. For example, some of the
1624 files in the program probably refer to others by name. At the very
1625 least, the makefile probably mentions the file that you renamed. If you
1626 retrieve an old snapshot, the renamed file is retrieved under its new
1627 name, which is not the name that the makefile expects. So the program
1628 won't really work as retrieved.
1631 File: xemacs.info, Node: Version Headers, Prev: Snapshots, Up: Version Control
1633 Inserting Version Control Headers
1634 ---------------------------------
1636 Sometimes it is convenient to put version identification strings
1637 directly into working files. Certain special strings called "version
1638 headers" are replaced in each successive version by the number of that
1641 You can use the `C-x v h' command (`vc-insert-headers') to insert a
1642 suitable header string.
1645 Insert headers in a file for use with your version-control system.
1647 The default header string is `\$Id\$' for RCS and `\%W\%' for SCCS.
1648 (The actual strings inserted do not have the backslashes in them. They
1649 were placed in the Info source file so that the strings don't get
1650 interpreted as version-control headers when the Info source files are
1651 maintained under version control.) You can specify other headers to
1652 insert by setting the variable `vc-header-alist'. Its value is a list
1653 of elements of the form `(PROGRAM . STRING)' where PROGRAM is `RCS' or
1654 `SCCS' and STRING is the string to use.
1656 Instead of a single string, you can specify a list of strings; then
1657 each string in the list is inserted as a separate header on a line of
1660 It is often necessary to use "superfluous" backslashes when writing
1661 the strings that you put in this variable. This is to prevent the
1662 string in the constant from being interpreted as a header itself if the
1663 Emacs Lisp file containing it is maintained with version control.
1665 Each header is inserted surrounded by tabs, inside comment
1666 delimiters, on a new line at the start of the buffer. Normally the
1667 ordinary comment start and comment end strings of the current mode are
1668 used, but for certain modes, there are special comment delimiters for
1669 this purpose; the variable `vc-comment-alist' specifies them. Each
1670 element of this list has the form `(MODE STARTER ENDER)'.
1672 The variable `vc-static-header-alist' specifies further strings to
1673 add based on the name of the buffer. Its value should be a list of
1674 elements of the form `(REGEXP . FORMAT)'. Whenever REGEXP matches the
1675 buffer name, FORMAT is inserted as part of the header. A header line
1676 is inserted for each element that matches the buffer name, and for each
1677 string specified by `vc-header-alist'. The header line is made by
1678 processing the string from `vc-header-alist' with the format taken from
1679 the element. The default value for `vc-static-header-alist' is:
1682 "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
1683 #endif /* lint */\n"))
1685 which specifies insertion of a string of this form:
1689 static char vcid[] = "STRING";
1693 File: xemacs.info, Node: ListDir, Next: Comparing Files, Prev: Version Control, Up: Files
1695 Listing a File Directory
1696 ========================
1698 Files are organized by Unix into "directories". A "directory listing"
1699 is a list of all the files in a directory. Emacs provides directory
1700 listings in brief format (file names only) and verbose format (sizes,
1701 dates, and authors included).
1703 `C-x C-d DIR-OR-PATTERN'
1704 Print a brief directory listing (`list-directory').
1706 `C-u C-x C-d DIR-OR-PATTERN'
1707 Print a verbose directory listing.
1709 To print a directory listing, use `C-x C-d' (`list-directory').
1710 This command prompts in the minibuffer for a file name which is either
1711 a directory to be listed or pattern containing wildcards for the files
1712 to be listed. For example,
1714 C-x C-d /u2/emacs/etc <RET>
1716 lists all the files in directory `/u2/emacs/etc'. An example of
1717 specifying a file name pattern is:
1719 C-x C-d /u2/emacs/src/*.c <RET>
1721 Normally, `C-x C-d' prints a brief directory listing containing just
1722 file names. A numeric argument (regardless of value) tells it to print
1723 a verbose listing (like `ls -l').
1725 Emacs obtains the text of a directory listing by running `ls' in an
1726 inferior process. Two Emacs variables control the switches passed to
1727 `ls': `list-directory-brief-switches' is a string giving the switches
1728 to use in brief listings (`"-CF"' by default).
1729 `list-directory-verbose-switches' is a string giving the switches to
1730 use in a verbose listing (`"-l"' by default).
1732 The variable `directory-abbrev-alist' is an alist of abbreviations
1733 for file directories. The list consists of elements of the form `(FROM
1734 . TO)', each meaning to replace `FROM' with `TO' when it appears in a
1735 directory name. This replacement is done when setting up the default
1736 directory of a newly visited file. Every `FROM' string should start
1739 Use this feature when you have directories which you normally refer
1740 to via absolute symbolic links. Make `TO' the name of the link, and
1741 `FROM' the name it is linked to.
1744 File: xemacs.info, Node: Comparing Files, Next: Dired, Prev: ListDir, Up: Files
1749 The command `M-x diff' compares two files, displaying the differences
1750 in an Emacs buffer named `*Diff*'. It works by running the `diff'
1751 program, using options taken from the variable `diff-switches', whose
1752 value should be a string.
1754 The buffer `*Diff*' has Compilation mode as its major mode, so you
1755 can use `C-x `' to visit successive changed locations in the two source
1756 files. You can also move to a particular hunk of changes and type `C-c
1757 C-c' to find the corresponding source location. You can also use the
1758 other special commands of Compilation mode: <SPC> and <DEL> for
1759 scrolling, and `M-p' and `M-n' for cursor motion. *Note Compilation::.
1761 The command `M-x diff-backup' compares a specified file with its most
1762 recent backup. If you specify the name of a backup file, `diff-backup'
1763 compares it with the source file that it is a backup of.
1765 The command `M-x compare-windows' compares the text in the current
1766 window with that in the next window. Comparison starts at point in each
1767 window. Point moves forward in each window, a character at a time in
1768 each window, until the next characters in the two windows are
1769 different. Then the command is finished. For more information about
1770 windows in Emacs, *Note Windows::.
1772 With a numeric argument, `compare-windows' ignores changes in
1773 whitespace. If the variable `compare-ignore-case' is non-`nil', it
1774 ignores differences in case as well.
1777 File: xemacs.info, Node: Dired, Next: Misc File Ops, Prev: Comparing Files, Up: Files
1779 Dired, the Directory Editor
1780 ===========================
1782 Dired makes it easy to delete or visit many of the files in a single
1783 directory at once. It creates an Emacs buffer containing a listing of
1784 the directory. You can use the normal Emacs commands to move around in
1785 this buffer and special Dired commands to operate on the files.
1789 * Enter: Dired Enter. How to invoke Dired.
1790 * Edit: Dired Edit. Editing the Dired buffer.
1791 * Deletion: Dired Deletion. Deleting files with Dired.
1792 * Immed: Dired Immed. Other file operations through Dired.
1795 File: xemacs.info, Node: Dired Enter, Next: Dired Edit, Prev: Dired, Up: Dired
1800 To invoke dired, type `C-x d' or `M-x dired'. The command reads a
1801 directory name or wildcard file name pattern as a minibuffer argument
1802 just like the `list-directory' command, `C-x C-d'. Where `dired'
1803 differs from `list-directory' is in naming the buffer after the
1804 directory name or the wildcard pattern used for the listing, and putting
1805 the buffer into Dired mode so that the special commands of Dired are
1806 available in it. The variable `dired-listing-switches' is a string
1807 used as an argument to `ls' in making the directory; this string must
1810 To display the Dired buffer in another window rather than in the
1811 selected window, use `C-x 4 d' (`dired-other-window)' instead of `C-x
1815 File: xemacs.info, Node: Dired Edit, Next: Dired Deletion, Prev: Dired Enter, Up: Dired
1820 Once the Dired buffer exists, you can switch freely between it and other
1821 Emacs buffers. Whenever the Dired buffer is selected, certain special
1822 commands are provided that operate on files that are listed. The Dired
1823 buffer is "read-only", and inserting text in it is not useful, so
1824 ordinary printing characters such as `d' and `x' are used for Dired
1825 commands. Most Dired commands operate on the file described by the line
1826 that point is on. Some commands perform operations immediately; others
1827 "flag" a file to be operated on later.
1829 Most Dired commands that operate on the current line's file also
1830 treat a numeric argument as a repeat count, meaning to act on the files
1831 of the next few lines. A negative argument means to operate on the
1832 files of the preceding lines, and leave point on the first of those
1835 All the usual Emacs cursor motion commands are available in Dired
1836 buffers. Some special purpose commands are also provided. The keys
1837 `C-n' and `C-p' are redefined so that they try to position the cursor
1838 at the beginning of the filename on the line, rather than at the
1839 beginning of the line.
1841 For extra convenience, <SPC> and `n' in Dired are equivalent to
1842 `C-n'. `p' is equivalent to `C-p'. Moving by lines is done so often
1843 in Dired that it deserves to be easy to type. <DEL> (move up and
1844 unflag) is often useful simply for moving up.
1846 The `g' command in Dired runs `revert-buffer' to reinitialize the
1847 buffer from the actual disk directory and show any changes made in the
1848 directory by programs other than Dired. All deletion flags in the Dired
1849 buffer are lost when this is done.
1852 File: xemacs.info, Node: Dired Deletion, Next: Dired Immed, Prev: Dired Edit, Up: Dired
1854 Deleting Files With Dired
1855 -------------------------
1857 The primary use of Dired is to flag files for deletion and then delete
1861 Flag this file for deletion.
1864 Remove deletion-flag on this line.
1867 Remove deletion-flag on previous line, moving point to that line.
1870 Delete the files that are flagged for deletion.
1873 Flag all auto-save files (files whose names start and end with `#')
1874 for deletion (*note Auto Save::).
1877 Flag all backup files (files whose names end with `~') for deletion
1881 Flag excess numeric backup files for deletion. The oldest and
1882 newest few backup files of any one file are exempt; the middle
1885 You can flag a file for deletion by moving to the line describing the
1886 file and typing `d' or `C-d'. The deletion flag is visible as a `D' at
1887 the beginning of the line. Point is moved to the beginning of the next
1888 line, so that repeated `d' commands flag successive files.
1890 The files are flagged for deletion rather than deleted immediately to
1891 avoid the danger of deleting a file accidentally. Until you direct
1892 Dired to delete the flagged files, you can remove deletion flags using
1893 the commands `u' and <DEL>. `u' works just like `d', but removes flags
1894 rather than making flags. <DEL> moves upward, removing flags; it is
1895 like `u' with numeric argument automatically negated.
1897 To delete the flagged files, type `x'. This command first displays a
1898 list of all the file names flagged for deletion, and requests
1899 confirmation with `yes'. Once you confirm, all the flagged files are
1900 deleted, and their lines are deleted from the text of the Dired buffer.
1901 The shortened Dired buffer remains selected. If you answer `no' or
1902 quit with `C-g', you return immediately to Dired, with the deletion
1903 flags still present and no files actually deleted.
1905 The `#', `~', and `.' commands flag many files for deletion, based
1906 on their names. These commands are useful precisely because they do
1907 not actually delete any files; you can remove the deletion flags from
1908 any flagged files that you really wish to keep.
1910 `#' flags for deletion all files that appear to have been made by
1911 auto-saving (that is, files whose names begin and end with `#'). `~'
1912 flags for deletion all files that appear to have been made as backups
1913 for files that were edited (that is, files whose names end with `~').
1915 `.' (Period) flags just some of the backup files for deletion: only
1916 numeric backups that are not among the oldest few nor the newest few
1917 backups of any one file. Normally `dired-kept-versions' (not
1918 `kept-new-versions'; that applies only when saving) specifies the
1919 number of newest versions of each file to keep, and `kept-old-versions'
1920 specifies the number of oldest versions to keep. Period with a
1921 positive numeric argument, as in `C-u 3 .', specifies the number of
1922 newest versions to keep, overriding `dired-kept-versions'. A negative
1923 numeric argument overrides `kept-old-versions', using minus the value
1924 of the argument to specify the number of oldest versions of each file
1928 File: xemacs.info, Node: Dired Immed, Prev: Dired Deletion, Up: Dired
1930 Immediate File Operations in Dired
1931 ----------------------------------
1933 Some file operations in Dired take place immediately when they are
1937 Copies the file described on the current line. You must supply a
1938 file name to copy to, using the minibuffer.
1941 Visits the file described on the current line. It is just like
1942 typing `C-x C-f' and supplying that file name. If the file on
1943 this line is a subdirectory, `f' actually causes Dired to be
1944 invoked on that subdirectory. *Note Visiting::.
1947 Like `f', but uses another window to display the file's buffer.
1948 The Dired buffer remains visible in the first window. This is
1949 like using `C-x 4 C-f' to visit the file. *Note Windows::.
1952 Renames the file described on the current line. You must supply a
1953 file name to rename to, using the minibuffer.
1956 Views the file described on this line using `M-x view-file'.
1957 Viewing a file is like visiting it, but is slanted toward moving
1958 around in the file conveniently and does not allow changing the
1959 file. *Note View File: Misc File Ops. Viewing a file that is a
1960 directory runs Dired on that directory.
1963 File: xemacs.info, Node: Misc File Ops, Prev: Dired, Up: Files
1965 Miscellaneous File Operations
1966 =============================
1968 Emacs has commands for performing many other operations on files. All
1969 operate on one file; they do not accept wildcard file names.
1971 You can use the command `M-x add-name-to-file' to add a name to an
1972 existing file without removing the old name. The new name must belong
1973 on the file system that the file is on.
1975 `M-x append-to-file' adds the text of the region to the end of the
1978 `M-x copy-file' reads the file OLD and writes a new file named NEW
1979 with the same contents. Confirmation is required if a file named NEW
1980 already exists, because copying overwrites the old contents of the file
1983 `M-x delete-file' deletes a specified file, like the `rm' command in
1984 the shell. If you are deleting many files in one directory, it may be
1985 more convenient to use Dired (*note Dired::).
1987 `M-x insert-file' inserts a copy of the contents of a specified file
1988 into the current buffer at point, leaving point unchanged before the
1989 contents and the mark after them. *Note Mark::.
1991 `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and
1992 then creates a symbolic link named LINKNAME and pointing at OLD.
1993 Future attempts to open file LINKNAME will then refer to the file named
1994 OLD at the time the opening is done, or will result in an error if the
1995 name OLD is not in use at that time. Confirmation is required if you
1996 create the link while LINKNAME is in use. Note that not all systems
1997 support symbolic links.
1999 `M-x rename-file' reads two file names OLD and NEW using the
2000 minibuffer, then renames file OLD as NEW. If a file named NEW already
2001 exists, you must confirm with `yes' or renaming is not done; this is
2002 because renaming causes the previous meaning of the name NEW to be
2003 lost. If OLD and NEW are on different file systems, the file OLD is
2006 `M-x view-file' allows you to scan or read a file by sequential
2007 screenfuls. It reads a file name argument using the minibuffer. After
2008 reading the file into an Emacs buffer, `view-file' reads and displays
2009 one windowful. You can then type <SPC> to scroll forward one window,
2010 or <DEL> to scroll backward. Various other commands are provided for
2011 moving around in the file, but none for changing it; type `C-h' while
2012 viewing a file for a list of them. Most commands are the default Emacs
2013 cursor motion commands. To exit from viewing, type `C-c'.
2016 File: xemacs.info, Node: Buffers, Next: Windows, Prev: Files, Up: Top
2018 Using Multiple Buffers
2019 **********************
2021 Text you are editing in Emacs resides in an object called a "buffer".
2022 Each time you visit a file, Emacs creates a buffer to hold the file's
2023 text. Each time you invoke Dired, Emacs creates a buffer to hold the
2024 directory listing. If you send a message with `C-x m', a buffer named
2025 `*mail*' is used to hold the text of the message. When you ask for a
2026 command's documentation, it appears in a buffer called `*Help*'.
2028 At any time, one and only one buffer is "selected". It is also
2029 called the "current buffer". Saying a command operates on "the buffer"
2030 really means that the command operates on the selected buffer, as most
2033 When Emacs creates multiple windows, each window has a chosen buffer
2034 which is displayed there, but at any time only one of the windows is
2035 selected and its chosen buffer is the selected buffer. Each window's
2036 mode line displays the name of the buffer the window is displaying
2039 Each buffer has a name which can be of any length but is
2040 case-sensitive. You can select a buffer using its name. Most buffers
2041 are created when you visit files; their names are derived from the
2042 files' names. You can also create an empty buffer with any name you
2043 want. A newly started Emacs has a buffer named `*scratch*' which you
2044 can use for evaluating Lisp expressions in Emacs.
2046 Each buffer records what file it is visiting, whether it is
2047 modified, and what major mode and minor modes are in effect in it
2048 (*note Major Modes::). Any Emacs variable can be made "local to" a
2049 particular buffer, meaning its value in that buffer can be different
2050 from the value in other buffers. *Note Locals::.
2054 * Select Buffer:: Creating a new buffer or reselecting an old one.
2055 * List Buffers:: Getting a list of buffers that exist.
2056 * Misc Buffer:: Renaming; changing read-onliness; copying text.
2057 * Kill Buffer:: Killing buffers you no longer need.
2058 * Several Buffers:: How to go through the list of all buffers
2059 and operate variously on several of them.
2062 File: xemacs.info, Node: Select Buffer, Next: List Buffers, Prev: Buffers, Up: Buffers
2064 Creating and Selecting Buffers
2065 ==============================
2067 `C-x b BUFFER <RET>'
2068 Select or create a buffer named BUFFER (`switch-to-buffer').
2070 `C-x 4 b BUFFER <RET>'
2071 Similar, but select a buffer named BUFFER in another window
2072 (`switch-to-buffer-other-window').
2074 `M-x switch-to-other-buffer N'
2075 Switch to the previous buffer.
2077 To select a buffer named BUFNAME, type `C-x b BUFNAME <RET>'. This
2078 is the command `switch-to-buffer' with argument BUFNAME. You can use
2079 completion on an abbreviation for the buffer name you want (*note
2080 Completion::). An empty argument to `C-x b' specifies the most
2081 recently selected buffer that is not displayed in any window.
2083 Most buffers are created when you visit files, or use Emacs commands
2084 that display text. You can also create a buffer explicitly by typing
2085 `C-x b BUFNAME <RET>', which creates a new, empty buffer that is not
2086 visiting any file, and selects it for editing. The new buffer's major
2087 mode is determined by the value of `default-major-mode' (*note Major
2088 Modes::). Buffers not visiting files are usually used for making notes
2089 to yourself. If you try to save one, you are asked for the file name
2092 The function `switch-to-buffer-other-frame' is similar to
2093 `switch-to-buffer' except that it creates a new frame in which to
2094 display the selected buffer.
2096 Use `M-x switch-to-other-buffer' to visit the previous buffer. If
2097 you supply a positive integer N, the Nth most recent buffer is
2098 displayed. If you supply an argument of 0, the current buffer is moved
2099 to the bottom of the buffer stack.
2101 Note that you can also use `C-x C-f' and any other command for
2102 visiting a file to switch buffers. *Note Visiting::.
2105 File: xemacs.info, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers
2107 Listing Existing Buffers
2108 ========================
2111 List the existing buffers (`list-buffers').
2113 To print a list of all existing buffers, type `C-x C-b'. Each line
2114 in the list shows one buffer's name, major mode, and visited file. A
2115 `*' at the beginning of a line indicates the buffer has been
2116 "modified". If several buffers are modified, it may be time to save
2117 some with `C-x s' (*note Saving::). A `%' indicates a read-only
2118 buffer. A `.' marks the selected buffer. Here is an example of a
2121 MR Buffer Size Mode File
2122 -- ------ ---- ---- ----
2123 .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
2124 *Help* 1287 Fundamental
2125 files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
2126 % RMAIL 64042 RMAIL /u/rms/RMAIL
2127 *% man 747 Dired /u2/emacs/man/
2128 net.emacs 343885 Fundamental /u/rms/net.emacs
2129 fileio.c 27691 C /u2/emacs/src/fileio.c
2130 NEWS 67340 Text /u2/emacs/etc/NEWS
2131 *scratch* 0 Lisp Interaction
2133 Note that the buffer `*Help*' was made by a help request; it is not
2134 visiting any file. The buffer `man' was made by Dired on the directory
2137 As you move the mouse over the `*Buffer List*' buffer, the lines are
2138 highlighted. This visual cue indicates that clicking the right mouse
2139 button (`button3') will pop up a menu of commands on the buffer
2140 represented by this line. This menu duplicates most of those commands
2141 which are bound to keys in the `*Buffer List*' buffer.
2144 File: xemacs.info, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers
2146 Miscellaneous Buffer Operations
2147 ===============================
2150 Toggle read-only status of buffer (`toggle-read-only').
2153 Change the name of the current buffer.
2156 Scroll through a buffer.
2158 A buffer can be "read-only", which means that commands to change its
2159 text are not allowed. Normally, read-only buffers are created by
2160 subsystems such as Dired and Rmail that have special commands to operate
2161 on the text. Emacs also creates a read-only buffer if you visit a file
2162 that is protected. To make changes in a read-only buffer, use the
2163 command `C-x C-q' (`toggle-read-only'). It makes a read-only buffer
2164 writable, and makes a writable buffer read-only. This works by setting
2165 the variable `buffer-read-only', which has a local value in each buffer
2166 and makes a buffer read-only if its value is non-`nil'.
2168 `M-x rename-buffer' changes the name of the current buffer,
2169 prompting for the new name in the minibuffer. There is no default. If
2170 you specify a name that is used by a different buffer, an error is
2171 signalled and renaming is not done.
2173 `M-x view-buffer' is similar to `M-x view-file' (*note Misc File
2174 Ops::), but it examines an already existing Emacs buffer. View mode
2175 provides convenient commands for scrolling through the buffer but not
2176 for changing it. When you exit View mode, the resulting value of point
2179 To copy text from one buffer to another, use the commands `M-x
2180 append-to-buffer' and `M-x insert-buffer'. *Note Accumulating Text::.
2183 File: xemacs.info, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers
2188 After using Emacs for a while, you may accumulate a large number of
2189 buffers and may want to eliminate the ones you no longer need. There
2190 are several commands for doing this.
2193 Kill a buffer, specified by name (`kill-buffer').
2195 `M-x kill-some-buffers'
2196 Offer to kill each buffer, one by one.
2198 `C-x k' (`kill-buffer') kills one buffer, whose name you specify in
2199 the minibuffer. If you type just <RET> in the minibuffer, the default,
2200 killing the current buffer, is used. If the current buffer is killed,
2201 the buffer that has been selected recently but does not appear in any
2202 window now is selected. If the buffer being killed contains unsaved
2203 changes, you are asked to confirm with `yes' before the buffer is
2206 The command `M-x kill-some-buffers' asks about each buffer, one by
2207 one. An answer of `y' means to kill the buffer. Killing the current
2208 buffer or a buffer containing unsaved changes selects a new buffer or
2209 asks for confirmation just like `kill-buffer'.
2212 File: xemacs.info, Node: Several Buffers, Prev: Kill Buffer, Up: Buffers
2214 Operating on Several Buffers
2215 ============================
2217 The "buffer-menu" facility is like a "Dired for buffers"; it allows you
2218 to request operations on various Emacs buffers by editing a buffer
2219 containing a list of them. You can save buffers, kill them (here
2220 called "deleting" them, for consistency with Dired), or display them.
2223 Begin editing a buffer listing all Emacs buffers.
2225 The command `buffer-menu' writes a list of all Emacs buffers into
2226 the buffer `*Buffer List*', and selects that buffer in Buffer Menu
2227 mode. The buffer is read-only. You can only change it using the
2228 special commands described in this section. Most of the commands are
2229 graphic characters. You can use Emacs cursor motion commands in the
2230 `*Buffer List*' buffer. If the cursor is on a line describing a
2231 buffer, the following special commands apply to that buffer:
2234 Request to delete (kill) the buffer, then move down. A `D' before
2235 the buffer name on a line indicates a deletion request. Requested
2236 deletions actually take place when you use the `x' command.
2242 Like `d' but move up afterwards instead of down.
2245 Request to save the buffer. An `S' before the buffer name on a
2246 line indicates the request. Requested saves actually take place
2247 when you use the `x' command. You can request both saving and
2248 deletion for the same buffer.
2251 Mark buffer "unmodified". The command `~' does this immediately
2255 Perform previously requested deletions and saves.
2258 Remove any request made for the current line, and move down.
2261 Move to previous line and remove any request made for that line.
2263 All commands that add or remove flags to request later operations
2264 also move down a line. They accept a numeric argument as a repeat
2265 count, unless otherwise specified.
2267 There are also special commands to use the buffer list to select
2268 another buffer, and to specify one or more other buffers for display in
2272 Select the buffer in a full-frame window. This command takes
2276 Immediately set up two windows, with this buffer in one and the
2277 buffer selected before `*Buffer List*' in the other.
2280 Immediately select the buffer in place of the `*Buffer List*'
2284 Immediately select the buffer in another window as if by `C-x 4 b',
2285 leaving `*Buffer List*' visible.
2288 Immediately select this buffer, and display any buffers previously
2289 flagged with the `m' command in other windows. If there are no
2290 buffers flagged with `m', this command is equivalent to `1'.
2293 Flag this buffer to be displayed in another window if the `q'
2294 command is used. The request shows as a `>' at the beginning of
2295 the line. The same buffer may not have both a delete request and a
2298 Going back between a `buffer-menu' buffer and other Emacs buffers is
2299 easy. You can, for example, switch from the `*Buffer List*' buffer to
2300 another Emacs buffer, and edit there. You can then reselect the
2301 `buffer-menu' buffer and perform operations already requested, or you
2302 can kill that buffer or pay no further attention to it. All that
2303 `buffer-menu' does directly is create and select a suitable buffer, and
2304 turn on Buffer Menu mode. All the other capabilities of the buffer
2305 menu are implemented by special commands provided in Buffer Menu mode.
2307 The only difference between `buffer-menu' and `list-buffers' is that
2308 `buffer-menu' selects the `*Buffer List*' buffer and `list-buffers'
2309 does not. If you run `list-buffers' (that is, type `C-x C-b') and
2310 select the buffer list manually, you can use all the commands described
2314 File: xemacs.info, Node: Windows, Next: Mule, Prev: Buffers, Up: Top
2319 Emacs can split the frame into two or many windows, which can display
2320 parts of different buffers or different parts of one buffer. If you are
2321 running XEmacs under X, that means you can have the X window that
2322 contains the Emacs frame have multiple subwindows.
2326 * Basic Window:: Introduction to Emacs windows.
2327 * Split Window:: New windows are made by splitting existing windows.
2328 * Other Window:: Moving to another window or doing something to it.
2329 * Pop Up Window:: Finding a file or buffer in another window.
2330 * Change Window:: Deleting windows and changing their sizes.
2333 File: xemacs.info, Node: Basic Window, Next: Split Window, Prev: Windows, Up: Windows
2335 Concepts of Emacs Windows
2336 =========================
2338 When Emacs displays multiple windows, each window has one Emacs buffer
2339 designated for display. The same buffer may appear in more than one
2340 window; if it does, any changes in its text are displayed in all the
2341 windows that display it. Windows showing the same buffer can show
2342 different parts of it, because each window has its own value of point.
2344 At any time, one window is the "selected window"; the buffer
2345 displayed by that window is the current buffer. The cursor shows the
2346 location of point in that window. Each other window has a location of
2347 point as well, but since the terminal has only one cursor, it cannot
2348 show the location of point in the other windows.
2350 Commands to move point affect the value of point for the selected
2351 Emacs window only. They do not change the value of point in any other
2352 Emacs window, including those showing the same buffer. The same is
2353 true for commands such as `C-x b' to change the selected buffer in the
2354 selected window; they do not affect other windows at all. However,
2355 there are other commands such as `C-x 4 b' that select a different
2356 window and switch buffers in it. Also, all commands that display
2357 information in a window, including (for example) `C-h f'
2358 (`describe-function') and `C-x C-b' (`list-buffers'), work by switching
2359 buffers in a non-selected window without affecting the selected window.
2361 Each window has its own mode line, which displays the buffer name,
2362 modification status, and major and minor modes of the buffer that is
2363 displayed in the window. *Note Mode Line::, for details on the mode
2367 File: xemacs.info, Node: Split Window, Next: Other Window, Prev: Basic Window, Up: Windows
2373 Split the selected window into two windows, one above the other
2374 (`split-window-vertically').
2377 Split the selected window into two windows positioned side by side
2378 (`split-window-horizontally').
2381 Save the current window configuration in register REG (a letter).
2384 Restore (make current) the window configuration in register REG (a
2385 letter). Use with a register previously set with `C-x 6'.
2387 The command `C-x 2' (`split-window-vertically') breaks the selected
2388 window into two windows, one above the other. Both windows start out
2389 displaying the same buffer, with the same value of point. By default
2390 each of the two windows gets half the height of the window that was
2391 split. A numeric argument specifies how many lines to give to the top
2394 `C-x 3' (`split-window-horizontally') breaks the selected window
2395 into two side-by-side windows. A numeric argument specifies how many
2396 columns to give the one on the left. A line of vertical bars separates
2397 the two windows. Windows that are not the full width of the frame have
2398 truncated mode lines which do not always appear in inverse video,
2399 because Emacs display routines cannot display a region of inverse video
2400 that is only part of a line on the screen.
2402 When a window is less than the full width, many text lines are too
2403 long to fit. Continuing all those lines might be confusing. Set the
2404 variable `truncate-partial-width-windows' to non-`nil' to force
2405 truncation in all windows less than the full width of the frame,
2406 independent of the buffer and its value for `truncate-lines'. *Note
2407 Continuation Lines::.
2409 Horizontal scrolling is often used in side-by-side windows. *Note
2412 You can resize a window and store that configuration in a register by
2413 supplying a REGISTER argument to `window-configuration-to-register'
2414 (`C-x 6'). To return to the window configuration established with
2415 `window-configuration-to-register', use `jump-to-register' (`C-x j').
2418 File: xemacs.info, Node: Other Window, Next: Pop Up Window, Prev: Split Window, Up: Windows
2424 Select another window (`other-window'). That is the letter `o',
2428 Scroll the next window (`scroll-other-window').
2430 `M-x compare-windows'
2431 Find the next place where the text in the selected window does not
2432 match the text in the next window.
2434 `M-x other-window-any-frame N'
2435 Select the Nth different window on any frame.
2437 To select a different window, use `C-x o' (`other-window'). That is
2438 an `o', for `other', not a zero. When there are more than two windows,
2439 the command moves through all the windows in a cyclic order, generally
2440 top to bottom and left to right. From the rightmost and bottommost
2441 window, it goes back to the one at the upper left corner. A numeric
2442 argument, N, moves several steps in the cyclic order of windows. A
2443 negative numeric argument moves around the cycle in the opposite order.
2444 If the optional second argument WHICH-FRAMES is non-`nil', the
2445 function cycles through all frames. When the minibuffer is active, the
2446 minibuffer is the last window in the cycle; you can switch from the
2447 minibuffer window to one of the other windows, and later switch back
2448 and finish supplying the minibuffer argument that is requested. *Note
2451 The command `M-x other-window-any-frame' also selects the window N
2452 steps away in the cyclic order. However, unlike `other-window', this
2453 command selects a window on the next or previous frame instead of
2454 wrapping around to the top or bottom of the current frame, when there
2455 are no more windows.
2457 The usual scrolling commands (*note Display::) apply to the selected
2458 window only. `M-C-v' (`scroll-other-window') scrolls the window that
2459 `C-x o' would select. Like `C-v', it takes positive and negative
2462 The command `M-x compare-windows' compares the text in the current
2463 window with the text in the next window. Comparison starts at point in
2464 each window. Point moves forward in each window, a character at a time,
2465 until the next set of characters in the two windows are different.
2466 Then the command is finished.
2468 A prefix argument IGNORE-WHITESPACE means ignore changes in
2469 whitespace. The variable `compare-windows-whitespace' controls how
2470 whitespace is skipped.
2472 If `compare-ignore-case' is non-`nil', changes in case are also
2476 File: xemacs.info, Node: Pop Up Window, Next: Change Window, Prev: Other Window, Up: Windows
2478 Displaying in Another Window
2479 ============================
2481 `C-x 4' is a prefix key for commands that select another window
2482 (splitting the window if there is only one) and select a buffer in that
2483 window. Different `C-x 4' commands have different ways of finding the
2486 `C-x 4 b BUFNAME <RET>'
2487 Select buffer BUFNAME in another window. This runs
2488 `switch-to-buffer-other-window'.
2490 `C-x 4 f FILENAME <RET>'
2491 Visit file FILENAME and select its buffer in another window. This
2492 runs `find-file-other-window'. *Note Visiting::.
2494 `C-x 4 d DIRECTORY <RET>'
2495 Select a Dired buffer for directory DIRECTORY in another window.
2496 This runs `dired-other-window'. *Note Dired::.
2499 Start composing a mail message in another window. This runs
2500 `mail-other-window', and its same-window version is `C-x m' (*note
2504 Find a tag in the current tag table in another window. This runs
2505 `find-tag-other-window', the multiple-window variant of `M-.'
2508 If the variable `display-buffer-function' is non-`nil', its value is
2509 the function to call to handle `display-buffer'. It receives two
2510 arguments, the buffer and a flag that if non-`nil' means that the
2511 currently selected window is not acceptable. Commands such as
2512 `switch-to-buffer-other-window' and `find-file-other-window' work using
2516 File: xemacs.info, Node: Change Window, Prev: Pop Up Window, Up: Windows
2518 Deleting and Rearranging Windows
2519 ================================
2522 Get rid of the selected window (`delete-window'). That is a zero.
2523 If there is more than one Emacs frame, deleting the sole remaining
2524 window on that frame deletes the frame as well. If the current
2525 frame is the only frame, it is not deleted.
2528 Get rid of all windows except the selected one
2529 (`delete-other-windows').
2532 Make the selected window taller, at the expense of the other(s)
2536 Make the selected window wider (`enlarge-window-horizontally').
2538 To delete a window, type `C-x 0' (`delete-window'). (That is a
2539 zero.) The space occupied by the deleted window is distributed among
2540 the other active windows (but not the minibuffer window, even if that
2541 is active at the time). Once a window is deleted, its attributes are
2542 forgotten; there is no automatic way to make another window of the same
2543 shape or showing the same buffer. The buffer continues to exist, and
2544 you can select it in any window with `C-x b'.
2546 `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it
2547 deletes all the windows except the selected one (and the minibuffer).
2548 The selected window expands to use the whole frame except for the echo
2551 To readjust the division of space among existing windows, use `C-x
2552 ^' (`enlarge-window'). It makes the currently selected window longer
2553 by one line or as many lines as a numeric argument specifies. With a
2554 negative argument, it makes the selected window smaller. `C-x }'
2555 (`enlarge-window-horizontally') makes the selected window wider by the
2556 specified number of columns. The extra screen space given to a window
2557 comes from one of its neighbors, if that is possible; otherwise, all
2558 the competing windows are shrunk in the same proportion. If this makes
2559 some windows too small, those windows are deleted and their space is
2560 divided up. Minimum window size is specified by the variables
2561 `window-min-height' and `window-min-width'.
2563 You can also resize windows within a frame by clicking the left mouse
2564 button on a modeline, and dragging.
2566 Clicking the right button on a mode line pops up a menu of common
2567 window manager operations. This menu contains the following options:
2570 Remove the window above this modeline from the frame.
2572 Delete Other Windows
2573 Delete all windows on the frame except for the one above this
2577 Split the window above the mode line in half, creating another
2580 Split Window Horizontally
2581 Split the window above the mode line in half horizontally, so that
2582 there will be two windows side-by-side.
2585 Readjust the sizes of all windows on the frame until all windows
2586 have roughly the same number of lines.
2589 File: xemacs.info, Node: Mule, Next: Major Modes, Prev: Windows, Up: Top
2591 World Scripts Support
2592 *********************
2594 If you compile XEmacs with Mule option, it supports a wide variety of
2595 world scripts, including Latin script, as well as Arabic script,
2596 Simplified Chinese script (for mainland of China), Traditional Chinese
2597 script (for Taiwan and Hong-Kong), Greek script, Hebrew script, IPA
2598 symbols, Japanese scripts (Hiragana, Katakana and Kanji), Korean scripts
2599 (Hangul and Hanja) and Cyrillic script (for Byelorussian, Bulgarian,
2600 Russian, Serbian and Ukrainian). These features have been merged from
2601 the modified version of Emacs known as MULE (for "MULti-lingual
2602 Enhancement to GNU Emacs").
2606 * Mule Intro:: Basic concepts of Mule.
2607 * Language Environments:: Setting things up for the language you use.
2608 * Input Methods:: Entering text characters not on your keyboard.
2609 * Select Input Method:: Specifying your choice of input methods.
2610 * Mule and Fonts:: Additional font-related issues
2611 * Coding Systems:: Character set conversion when you read and
2612 write files, and so on.
2613 * Recognize Coding:: How XEmacs figures out which conversion to use.
2614 * Specify Coding:: Various ways to choose which conversion to use.
2617 File: xemacs.info, Node: Mule Intro, Next: Language Environments, Prev: Mule, Up: Mule
2622 Mule is the MUltiLingual Extension to XEmacs. It provides facilities
2623 not only for handling text written in many different languages, but in
2624 fact multilingual texts containing several languages in the same buffer.
2625 This goes beyond the simple facilities offered by Unicode for
2626 representation of multilingual text. Mule also supports input methods,
2627 composing display using fonts in various different encodings, changing
2628 character syntax and other editing facilities to correspond to local
2629 language usage, and more.
2631 The most obvious problem is that of the different character coding
2632 systems used by different languages. ASCII supplies all the characters
2633 needed for most computer programming languages and US English (it lacks
2634 the currency symbol for British English), but other Western European
2635 languages (French, Spanish, German) require more than 96 code positions
2636 for accented characters. In fact, even with 8 bits to represent 96 more
2637 character (including accented characters and symbols such as currency
2638 symbols), some languages' alphabets remain incomplete (Croatian,
2639 Polish). (The 64 "missing characters" are reserved for control
2640 characters.) Furthermore, many European languages have their own
2641 alphabets, which must conflict with the accented characters since the
2642 ASCII characters are needed for computer interaction (error and log
2643 messages are typically in ASCII).
2645 For economy of space, historical practice has been for each language
2646 to establish its own encoding for the characters it needs. This allows
2647 most European languages to represented with one octet (byte) per
2648 character. However, many Asian languages have thousands of characters
2649 and require two or more octets per character. For multilingual
2650 purposes, the ISO 2022 standard establishes escape codes that allow
2651 switching encodings in midstream. (It's also ISO 2022 that establishes
2652 the standard that code points 0-31 and 128-159 are control codes.)
2654 However, this is error-prone and complex for internal processing.
2655 For this reason XEmacs uses an internal coding system which can encode
2656 all of the world's scripts. Unfortunately, for historical reasons, this
2657 code is not Unicode, although we are moving in that direction.
2659 XEmacs translates between the internal character encoding and various
2660 other coding systems when reading and writing files, when exchanging
2661 data with subprocesses, and (in some cases) in the `C-q' command (see
2662 below). The internal encoding is never visible to the user in a
2663 production XEmacs, but unfortunately the process cannot be completely
2664 transparent to the user. This is because the same ranges of octets may
2665 represent 1-octet ISO-8859-1 (which is satisfactory for most Western
2666 European use prior to the introduction of the Euro currency), 1-octet
2667 ISO-8859-15 (which substitutes the Euro for the rarely used "generic
2668 currency" symbol), 1-octet ISO-8859-5 (Cyrillic), or multioctet EUC-JP
2669 (Japanese). There's no way to tell without being able to read!
2671 A number of heuristics are incorporated in Mule for automatic
2672 recognition, there are facilities for the user to set defaults, and
2673 where necessary (rarely, we hope) to set coding systems directly.
2675 The command `C-h h' (`view-hello-file') displays the file
2676 `etc/HELLO', which shows how to say "hello" in many languages. This
2677 illustrates various scripts.
2679 Keyboards, even in the countries where these character sets are used,
2680 generally don't have keys for all the characters in them. So XEmacs
2681 supports various "input methods", typically one for each script or
2682 language, to make it convenient to type them.
2684 The prefix key `C-x <RET>' is used for commands that pertain to
2685 world scripts, coding systems, and input methods.
2688 File: xemacs.info, Node: Language Environments, Next: Input Methods, Prev: Mule Intro, Up: Mule
2690 Language Environments
2691 =====================
2693 All supported character sets are supported in XEmacs buffers if it is
2694 compiled with Mule; there is no need to select a particular language in
2695 order to display its characters in an XEmacs buffer. However, it is
2696 important to select a "language environment" in order to set various
2697 defaults. The language environment really represents a choice of
2698 preferred script (more or less) rather that a choice of language.
2700 The language environment controls which coding systems to recognize
2701 when reading text (*note Recognize Coding::). This applies to files,
2702 incoming mail, netnews, and any other text you read into XEmacs. It may
2703 also specify the default coding system to use when you create a file.
2704 Each language environment also specifies a default input method.
2706 The command to select a language environment is `M-x
2707 set-language-environment'. It makes no difference which buffer is
2708 current when you use this command, because the effects apply globally to
2709 the XEmacs session. The supported language environments include:
2711 ASCII, Chinese-BIG5, Chinese-GB, Croatian, Cyrillic-ALT,
2712 Cyrillic-ISO, Cyrillic-KOI8, Cyrillic-Win, Czech, English,
2713 Ethiopic, French, German, Greek, Hebrew, IPA, Japanese, Korean,
2714 Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Norwegian, Polish,
2715 Romanian, Slovenian, Thai-XTIS, Vietnamese.
2717 Some operating systems let you specify the language you are using by
2718 setting locale environment variables. XEmacs handles one common special
2719 case of this: if your locale name for character types contains the
2720 string `8859-N', XEmacs automatically selects the corresponding
2721 language environment.
2723 To display information about the effects of a certain language
2724 environment LANG-ENV, use the command `C-h L LANG-ENV <RET>'
2725 (`describe-language-environment'). This tells you which languages this
2726 language environment is useful for, and lists the character sets,
2727 coding systems, and input methods that go with it. It also shows some
2728 sample text to illustrate scripts used in this language environment.
2729 By default, this command describes the chosen language environment.
2732 File: xemacs.info, Node: Input Methods, Next: Select Input Method, Prev: Language Environments, Up: Mule
2737 An "input method" is a kind of character conversion designed
2738 specifically for interactive input. In XEmacs, typically each language
2739 has its own input method; sometimes several languages which use the same
2740 characters can share one input method. A few languages support several
2743 The simplest kind of input method works by mapping ASCII letters into
2744 another alphabet. This is how the Greek and Russian input methods work.
2746 A more powerful technique is composition: converting sequences of
2747 characters into one letter. Many European input methods use composition
2748 to produce a single non-ASCII letter from a sequence that consists of a
2749 letter followed by accent characters. For example, some methods convert
2750 the sequence `'a' into a single accented letter.
2752 The input methods for syllabic scripts typically use mapping followed
2753 by composition. The input methods for Thai and Korean work this way.
2754 First, letters are mapped into symbols for particular sounds or tone
2755 marks; then, sequences of these which make up a whole syllable are
2756 mapped into one syllable sign.
2758 Chinese and Japanese require more complex methods. In Chinese input
2759 methods, first you enter the phonetic spelling of a Chinese word (in
2760 input method `chinese-py', among others), or a sequence of portions of
2761 the character (input methods `chinese-4corner' and `chinese-sw', and
2762 others). Since one phonetic spelling typically corresponds to many
2763 different Chinese characters, you must select one of the alternatives
2764 using special XEmacs commands. Keys such as `C-f', `C-b', `C-n',
2765 `C-p', and digits have special definitions in this situation, used for
2766 selecting among the alternatives. <TAB> displays a buffer showing all
2769 In Japanese input methods, first you input a whole word using
2770 phonetic spelling; then, after the word is in the buffer, XEmacs
2771 converts it into one or more characters using a large dictionary. One
2772 phonetic spelling corresponds to many differently written Japanese
2773 words, so you must select one of them; use `C-n' and `C-p' to cycle
2774 through the alternatives.
2776 Sometimes it is useful to cut off input method processing so that the
2777 characters you have just entered will not combine with subsequent
2778 characters. For example, in input method `latin-1-postfix', the
2779 sequence `e '' combines to form an `e' with an accent. What if you
2780 want to enter them as separate characters?
2782 One way is to type the accent twice; that is a special feature for
2783 entering the separate letter and accent. For example, `e ' '' gives
2784 you the two characters `e''. Another way is to type another letter
2785 after the `e'--something that won't combine with that--and immediately
2786 delete it. For example, you could type `e e <DEL> '' to get separate
2789 Another method, more general but not quite as easy to type, is to use
2790 `C-\ C-\' between two characters to stop them from combining. This is
2791 the command `C-\' (`toggle-input-method') used twice. *Note Select
2794 `C-\ C-\' is especially useful inside an incremental search, because
2795 stops waiting for more characters to combine, and starts searching for
2796 what you have already entered.
2798 The variables `input-method-highlight-flag' and
2799 `input-method-verbose-flag' control how input methods explain what is
2800 happening. If `input-method-highlight-flag' is non-`nil', the partial
2801 sequence is highlighted in the buffer. If `input-method-verbose-flag'
2802 is non-`nil', the list of possible characters to type next is displayed
2803 in the echo area (but not when you are in the minibuffer).
2806 File: xemacs.info, Node: Select Input Method, Next: Mule and Fonts, Prev: Input Methods, Up: Mule
2808 Selecting an Input Method
2809 =========================
2812 Enable or disable use of the selected input method.
2814 `C-x <RET> C-\ METHOD <RET>'
2815 Select a new input method for the current buffer.
2817 `C-h I METHOD <RET>'
2818 `C-h C-\ METHOD <RET>'
2819 Describe the input method METHOD (`describe-input-method'). By
2820 default, it describes the current input method (if any).
2822 `M-x list-input-methods'
2823 Display a list of all the supported input methods.
2825 To choose an input method for the current buffer, use `C-x <RET>
2826 C-\' (`select-input-method'). This command reads the input method name
2827 with the minibuffer; the name normally starts with the language
2828 environment that it is meant to be used with. The variable
2829 `current-input-method' records which input method is selected.
2831 Input methods use various sequences of ASCII characters to stand for
2832 non-ASCII characters. Sometimes it is useful to turn off the input
2833 method temporarily. To do this, type `C-\' (`toggle-input-method').
2834 To reenable the input method, type `C-\' again.
2836 If you type `C-\' and you have not yet selected an input method, it
2837 prompts for you to specify one. This has the same effect as using `C-x
2838 <RET> C-\' to specify an input method.
2840 Selecting a language environment specifies a default input method for
2841 use in various buffers. When you have a default input method, you can
2842 select it in the current buffer by typing `C-\'. The variable
2843 `default-input-method' specifies the default input method (`nil' means
2846 Some input methods for alphabetic scripts work by (in effect)
2847 remapping the keyboard to emulate various keyboard layouts commonly used
2848 for those scripts. How to do this remapping properly depends on your
2849 actual keyboard layout. To specify which layout your keyboard has, use
2850 the command `M-x quail-set-keyboard-layout'.
2852 To display a list of all the supported input methods, type `M-x
2853 list-input-methods'. The list gives information about each input
2854 method, including the string that stands for it in the mode line.
2857 File: xemacs.info, Node: Mule and Fonts, Next: Coding Systems, Prev: Select Input Method, Up: Mule
2862 (This section is X11-specific.)
2864 Text in XEmacs buffers is displayed using various faces. In
2865 addition to specifying properties of a face, such as font and color,
2866 there are some additional properties of Mule charsets that are used in
2869 There is currently two properties of a charset that could be
2870 adjusted by user: font registry and so called "ccl-program".
2872 Font registry is a regular expression matching the font registry
2873 field for this character set. For example, both the `ascii' and
2874 `latin-iso8859-1' charsets use the registry `"ISO8859-1"'. This field
2875 is used to choose an appropriate font when the user gives a general
2876 font specification such as `-*-courier-medium-r-*-140-*', i.e. a
2877 14-point upright medium-weight Courier font.
2879 You can set font registry for a charset using `set-charset-registry'
2880 function in one of your startup files. This function takes two
2881 arguments: character set (as a symbol) and font registry (as a string).
2883 E. g., for Cyrillic texts Mule uses `cyrillic-iso8859-5' charset
2884 with `"ISO8859-5"' as a default registry, and we want to use `"koi8-r"'
2885 instead, because fonts in that encoding are installed on our system.
2888 (set-charset-registry 'cyrillic-iso8859-5 "koi8-r")
2890 (Please note that you probably also want to set font registry for
2891 `ascii' charset so that mixed English/Cyrillic texts be displayed using
2894 "CCL-programs" are a little special-purpose scripts defined within
2895 XEmacs or in some package. Those scripts allow XEmacs to use fonts that
2896 are in different encoding from the encoding that is used by Mule for
2897 text in buffer. Returning to the above example, we need to somehow tell
2898 XEmacs that we have different encodings of fonts and text and so it
2899 needs to convert characters between those encodings when displaying.
2900 That's what `set-charset-ccl-program' function is used for. There are
2901 quite a few various CCL programs defined within XEmacs, and there is no
2902 comprehensive list of them, so you currently have to consult sources.
2904 We know that there is a CCL program called `ccl-encode-koi8-r-font'
2905 that is used exactly for needed purpose: to convert characters between
2906 `ISO8859-5' encoding and `koi8-r'. Use:
2908 (set-charset-ccl-program 'cyrillic-iso8859-5 'ccl-encode-koi8-r-font)
2910 There are several more uses for CCL programs, not related to fonts,
2911 but those uses are not described here.
2914 File: xemacs.info, Node: Coding Systems, Next: Recognize Coding, Prev: Mule and Fonts, Up: Mule
2919 Users of various languages have established many more-or-less standard
2920 coding systems for representing them. XEmacs does not use these coding
2921 systems internally; instead, it converts from various coding systems to
2922 its own system when reading data, and converts the internal coding
2923 system to other coding systems when writing data. Conversion is
2924 possible in reading or writing files, in sending or receiving from the
2925 terminal, and in exchanging data with subprocesses.
2927 XEmacs assigns a name to each coding system. Most coding systems are
2928 used for one language, and the name of the coding system starts with the
2929 language name. Some coding systems are used for several languages;
2930 their names usually start with `iso'. There are also special coding
2931 systems `binary' and `no-conversion' which do not convert printing
2934 In addition to converting various representations of non-ASCII
2935 characters, a coding system can perform end-of-line conversion. XEmacs
2936 handles three different conventions for how to separate lines in a file:
2937 newline, carriage-return linefeed, and just carriage-return.
2939 `C-h C CODING <RET>'
2940 Describe coding system CODING.
2943 Describe the coding systems currently in use.
2945 `M-x list-coding-systems'
2946 Display a list of all the supported coding systems.
2948 `C-u M-x list-coding-systems'
2949 Display comprehensive list of specific details of all supported
2952 The command `C-x RET C' (`describe-coding-system') displays
2953 information about particular coding systems. You can specify a coding
2954 system name as argument; alternatively, with an empty argument, it
2955 describes the coding systems currently selected for various purposes,
2956 both in the current buffer and as the defaults, and the priority list
2957 for recognizing coding systems (*note Recognize Coding::).
2959 To display a list of all the supported coding systems, type `M-x
2960 list-coding-systems'. The list gives information about each coding
2961 system, including the letter that stands for it in the mode line (*note
2964 Each of the coding systems that appear in this list--except for
2965 `binary', which means no conversion of any kind--specifies how and
2966 whether to convert printing characters, but leaves the choice of
2967 end-of-line conversion to be decided based on the contents of each file.
2968 For example, if the file appears to use carriage-return linefeed between
2969 lines, that end-of-line conversion will be used.
2971 Each of the listed coding systems has three variants which specify
2972 exactly what to do for end-of-line conversion:
2975 Don't do any end-of-line conversion; assume the file uses newline
2976 to separate lines. (This is the convention normally used on Unix
2980 Assume the file uses carriage-return linefeed to separate lines,
2981 and do the appropriate conversion. (This is the convention
2982 normally used on Microsoft systems.)
2985 Assume the file uses carriage-return to separate lines, and do the
2986 appropriate conversion. (This is the convention normally used on
2987 the Macintosh system.)
2989 These variant coding systems are omitted from the
2990 `list-coding-systems' display for brevity, since they are entirely
2991 predictable. For example, the coding system `iso-8859-1' has variants
2992 `iso-8859-1-unix', `iso-8859-1-dos' and `iso-8859-1-mac'.
2994 In contrast, the coding system `binary' specifies no character code
2995 conversion at all--none for non-Latin-1 byte values and none for end of
2996 line. This is useful for reading or writing binary files, tar files,
2997 and other files that must be examined verbatim.
2999 The easiest way to edit a file with no conversion of any kind is with
3000 the `M-x find-file-literally' command. This uses `binary', and also
3001 suppresses other XEmacs features that might convert the file contents
3002 before you see them. *Note Visiting::.
3004 The coding system `no-conversion' means that the file contains
3005 non-Latin-1 characters stored with the internal XEmacs encoding. It
3006 handles end-of-line conversion based on the data encountered, and has
3007 the usual three variants to specify the kind of end-of-line conversion.
3010 File: xemacs.info, Node: Recognize Coding, Next: Specify Coding, Prev: Coding Systems, Up: Mule
3012 Recognizing Coding Systems
3013 ==========================
3015 Most of the time, XEmacs can recognize which coding system to use for
3016 any given file-once you have specified your preferences.
3018 Some coding systems can be recognized or distinguished by which byte
3019 sequences appear in the data. However, there are coding systems that
3020 cannot be distinguished, not even potentially. For example, there is no
3021 way to distinguish between Latin-1 and Latin-2; they use the same byte
3022 values with different meanings.
3024 XEmacs handles this situation by means of a priority list of coding
3025 systems. Whenever XEmacs reads a file, if you do not specify the coding
3026 system to use, XEmacs checks the data against each coding system,
3027 starting with the first in priority and working down the list, until it
3028 finds a coding system that fits the data. Then it converts the file
3029 contents assuming that they are represented in this coding system.
3031 The priority list of coding systems depends on the selected language
3032 environment (*note Language Environments::). For example, if you use
3033 French, you probably want XEmacs to prefer Latin-1 to Latin-2; if you
3034 use Czech, you probably want Latin-2 to be preferred. This is one of
3035 the reasons to specify a language environment.
3037 However, you can alter the priority list in detail with the command
3038 `M-x prefer-coding-system'. This command reads the name of a coding
3039 system from the minibuffer, and adds it to the front of the priority
3040 list, so that it is preferred to all others. If you use this command
3041 several times, each use adds one element to the front of the priority
3044 Sometimes a file name indicates which coding system to use for the
3045 file. The variable `file-coding-system-alist' specifies this
3046 correspondence. There is a special function
3047 `modify-coding-system-alist' for adding elements to this list. For
3048 example, to read and write all `.txt' using the coding system
3049 `china-iso-8bit', you can execute this Lisp expression:
3051 (modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
3053 The first argument should be `file', the second argument should be a
3054 regular expression that determines which files this applies to, and the
3055 third argument says which coding system to use for these files.
3057 You can specify the coding system for a particular file using the
3058 `-*-...-*-' construct at the beginning of a file, or a local variables
3059 list at the end (*note File Variables::). You do this by defining a
3060 value for the "variable" named `coding'. XEmacs does not really have a
3061 variable `coding'; instead of setting a variable, it uses the specified
3062 coding system for the file. For example, `-*-mode: C; coding:
3063 iso-8859-1;-*-' specifies use of the iso-8859-1 coding system, as well
3066 Once XEmacs has chosen a coding system for a buffer, it stores that
3067 coding system in `buffer-file-coding-system' and uses that coding
3068 system, by default, for operations that write from this buffer into a
3069 file. This includes the commands `save-buffer' and `write-region'. If
3070 you want to write files from this buffer using a different coding
3071 system, you can specify a different coding system for the buffer using
3072 `set-buffer-file-coding-system' (*note Specify Coding::).
3075 File: xemacs.info, Node: Specify Coding, Prev: Recognize Coding, Up: Mule
3077 Specifying a Coding System
3078 ==========================
3080 In cases where XEmacs does not automatically choose the right coding
3081 system, you can use these commands to specify one:
3083 `C-x <RET> f CODING <RET>'
3084 Use coding system CODING for the visited file in the current
3087 `C-x <RET> c CODING <RET>'
3088 Specify coding system CODING for the immediately following command.
3090 `C-x <RET> k CODING <RET>'
3091 Use coding system CODING for keyboard input. (This feature is
3092 non-functional and is temporarily disabled.)
3094 `C-x <RET> t CODING <RET>'
3095 Use coding system CODING for terminal output.
3097 `C-x <RET> p CODING <RET>'
3098 Use coding system CODING for subprocess input and output in the
3101 The command `C-x RET f' (`set-buffer-file-coding-system') specifies
3102 the file coding system for the current buffer--in other words, which
3103 coding system to use when saving or rereading the visited file. You
3104 specify which coding system using the minibuffer. Since this command
3105 applies to a file you have already visited, it affects only the way the
3108 Another way to specify the coding system for a file is when you visit
3109 the file. First use the command `C-x <RET> c'
3110 (`universal-coding-system-argument'); this command uses the minibuffer
3111 to read a coding system name. After you exit the minibuffer, the
3112 specified coding system is used for _the immediately following command_.
3114 So if the immediately following command is `C-x C-f', for example,
3115 it reads the file using that coding system (and records the coding
3116 system for when the file is saved). Or if the immediately following
3117 command is `C-x C-w', it writes the file using that coding system.
3118 Other file commands affected by a specified coding system include `C-x
3119 C-i' and `C-x C-v', as well as the other-window variants of `C-x C-f'.
3121 In addition, if you run some file input commands with the precedent
3122 `C-u', you can specify coding system to read from minibuffer. So if
3123 the immediately following command is `C-x C-f', for example, it reads
3124 the file using that coding system (and records the coding system for
3125 when the file is saved). Other file commands affected by a specified
3126 coding system include `C-x C-i' and `C-x C-v', as well as the
3127 other-window variants of `C-x C-f'.
3129 The variable `default-buffer-file-coding-system' specifies the
3130 choice of coding system to use when you create a new file. It applies
3131 when you find a new file, and when you create a buffer and then save it
3132 in a file. Selecting a language environment typically sets this
3133 variable to a good choice of default coding system for that language
3136 The command `C-x <RET> t' (`set-terminal-coding-system') specifies
3137 the coding system for terminal output. If you specify a character code
3138 for terminal output, all characters output to the terminal are
3139 translated into that coding system.
3141 This feature is useful for certain character-only terminals built to
3142 support specific languages or character sets--for example, European
3143 terminals that support one of the ISO Latin character sets.
3145 By default, output to the terminal is not translated at all.
3147 The command `C-x <RET> k' (`set-keyboard-coding-system') specifies
3148 the coding system for keyboard input. Character-code translation of
3149 keyboard input is useful for terminals with keys that send non-ASCII
3150 graphic characters--for example, some terminals designed for ISO
3151 Latin-1 or subsets of it.
3153 By default, keyboard input is not translated at all.
3155 There is a similarity between using a coding system translation for
3156 keyboard input, and using an input method: both define sequences of
3157 keyboard input that translate into single characters. However, input
3158 methods are designed to be convenient for interactive use by humans, and
3159 the sequences that are translated are typically sequences of ASCII
3160 printing characters. Coding systems typically translate sequences of
3161 non-graphic characters.
3163 (This feature is non-functional and is temporarily disabled.)
3165 The command `C-x <RET> p' (`set-buffer-process-coding-system')
3166 specifies the coding system for input and output to a subprocess. This
3167 command applies to the current buffer; normally, each subprocess has its
3168 own buffer, and thus you can use this command to specify translation to
3169 and from a particular subprocess by giving the command in the
3170 corresponding buffer.
3172 By default, process input and output are not translated at all.
3174 The variable `file-name-coding-system' specifies a coding system to
3175 use for encoding file names. If you set the variable to a coding
3176 system name (as a Lisp symbol or a string), XEmacs encodes file names
3177 using that coding system for all file operations. This makes it
3178 possible to use non-Latin-1 characters in file names--or, at least,
3179 those non-Latin-1 characters which the specified coding system can
3180 encode. By default, this variable is `nil', which implies that you
3181 cannot use non-Latin-1 characters in file names.
3184 File: xemacs.info, Node: Major Modes, Next: Indentation, Prev: Mule, Up: Top
3189 Emacs has many different "major modes", each of which customizes Emacs
3190 for editing text of a particular sort. The major modes are mutually
3191 exclusive; at any time, each buffer has one major mode. The mode line
3192 normally contains the name of the current major mode in parentheses.
3195 The least specialized major mode is called "Fundamental mode". This
3196 mode has no mode-specific redefinitions or variable settings. Each
3197 Emacs command behaves in its most general manner, and each option is in
3198 its default state. For editing any specific type of text, such as Lisp
3199 code or English text, you should switch to the appropriate major mode,
3200 such as Lisp mode or Text mode.
3202 Selecting a major mode changes the meanings of a few keys to become
3203 more specifically adapted to the language being edited. <TAB>, <DEL>,
3204 and <LFD> are changed frequently. In addition, commands which handle
3205 comments use the mode to determine how to delimit comments. Many major
3206 modes redefine the syntactical properties of characters appearing in
3207 the buffer. *Note Syntax::.
3209 The major modes fall into three major groups. Lisp mode (which has
3210 several variants), C mode, and Muddle mode are for specific programming
3211 languages. Text mode, Nroff mode, TeX mode, and Outline mode are for
3212 editing English text. The remaining major modes are not intended for
3213 use on users' files; they are used in buffers created by Emacs for
3214 specific purposes and include Dired mode for buffers made by Dired
3215 (*note Dired::), Mail mode for buffers made by `C-x m' (*note Sending
3216 Mail::), and Shell mode for buffers used for communicating with an
3217 inferior shell process (*note Interactive Shell::).
3219 Most programming language major modes specify that only blank lines
3220 separate paragraphs. This is so that the paragraph commands remain
3221 useful. *Note Paragraphs::. They also cause Auto Fill mode to use the
3222 definition of <TAB> to indent the new lines it creates. This is
3223 because most lines in a program are usually indented. *Note
3228 * Choosing Modes:: How major modes are specified or chosen.
3231 File: xemacs.info, Node: Choosing Modes, Prev: Major Modes, Up: Major Modes
3233 Choosing Major Modes
3234 ====================
3236 You can select a major mode explicitly for the current buffer, but most
3237 of the time Emacs determines which mode to use based on the file name
3238 or some text in the file.
3240 Use a `M-x' command to explicitly select a new major mode. Add
3241 `-mode' to the name of a major mode to get the name of a command to
3242 select that mode. For example, to enter Lisp mode, execute `M-x
3245 When you visit a file, Emacs usually chooses the right major mode
3246 based on the file's name. For example, files whose names end in `.c'
3247 are edited in C mode. The variable `auto-mode-alist' controls the
3248 correspondence between file names and major mode. Its value is a list
3249 in which each element has the form:
3251 (REGEXP . MODE-FUNCTION)
3253 For example, one element normally found in the list has the form
3254 `("\\.c$" . c-mode)'. It is responsible for selecting C mode for files
3255 whose names end in `.c'. (Note that `\\' is needed in Lisp syntax to
3256 include a `\' in the string, which is needed to suppress the special
3257 meaning of `.' in regexps.) The only practical way to change this
3258 variable is with Lisp code.
3260 You can specify which major mode should be used for editing a certain
3261 file by a special sort of text in the first non-blank line of the file.
3262 The mode name should appear in this line both preceded and followed by
3263 `-*-'. Other text may appear on the line as well. For example,
3267 tells Emacs to use Lisp mode. Note how the semicolon is used to make
3268 Lisp treat this line as a comment. Such an explicit specification
3269 overrides any default mode based on the file name.
3271 Another format of mode specification is:
3273 -*-Mode: MODENAME;-*-
3275 which allows other things besides the major mode name to be specified.
3276 However, Emacs does not look for anything except the mode name.
3278 The major mode can also be specified in a local variables list.
3279 *Note File Variables::.
3281 When you visit a file that does not specify a major mode to use, or
3282 when you create a new buffer with `C-x b', Emacs uses the major mode
3283 specified by the variable `default-major-mode'. Normally this value is
3284 the symbol `fundamental-mode', which specifies Fundamental mode. If
3285 `default-major-mode' is `nil', the major mode is taken from the
3286 previously selected buffer.
3289 File: xemacs.info, Node: Indentation, Next: Text, Prev: Major Modes, Up: Top
3295 Indent current line "appropriately" in a mode-dependent fashion.
3298 Perform <RET> followed by <TAB> (`newline-and-indent').
3301 Merge two lines (`delete-indentation'). This would cancel out the
3305 Split line at point; text on the line after point becomes a new
3306 line indented to the same column that it now starts in
3310 Move (forward or back) to the first non-blank character on the
3311 current line (`back-to-indentation').
3314 Indent several lines to same column (`indent-region').
3317 Shift block of lines rigidly right or left (`indent-rigidly').
3320 Indent from point to the next prespecified tab stop column
3321 (`tab-to-tab-stop').
3323 `M-x indent-relative'
3324 Indent from point to under an indentation point in the previous
3327 Most programming languages have some indentation convention. For
3328 Lisp code, lines are indented according to their nesting in
3329 parentheses. The same general idea is used for C code, though details
3332 Use the <TAB> command to indent a line whatever the language. Each
3333 major mode defines this command to perform indentation appropriate for
3334 the particular language. In Lisp mode, <TAB> aligns a line according
3335 to its depth in parentheses. No matter where in the line you are when
3336 you type <TAB>, it aligns the line as a whole. In C mode, <TAB>
3337 implements a subtle and sophisticated indentation style that knows
3338 about many aspects of C syntax.
3340 In Text mode, <TAB> runs the command `tab-to-tab-stop', which
3341 indents to the next tab stop column. You can set the tab stops with
3342 `M-x edit-tab-stops'.
3346 * Indentation Commands:: Various commands and techniques for indentation.
3347 * Tab Stops:: You can set arbitrary "tab stops" and then
3348 indent to the next tab stop when you want to.
3349 * Just Spaces:: You can request indentation using just spaces.
3352 File: xemacs.info, Node: Indentation Commands, Next: Tab Stops, Prev: Indentation, Up: Indentation
3354 Indentation Commands and Techniques
3355 ===================================
3357 If you just want to insert a tab character in the buffer, you can type
3360 To move over the indentation on a line, type `Meta-m'
3361 (`back-to-indentation'). This command, given anywhere on a line,
3362 positions point at the first non-blank character on the line.
3364 To insert an indented line before the current line, type `C-a C-o
3365 <TAB>'. To make an indented line after the current line, use `C-e
3368 `C-M-o' (`split-line') moves the text from point to the end of the
3369 line vertically down, so that the current line becomes two lines.
3370 `C-M-o' first moves point forward over any spaces and tabs. Then it
3371 inserts after point a newline and enough indentation to reach the same
3372 column point is on. Point remains before the inserted newline; in this
3373 regard, `C-M-o' resembles `C-o'.
3375 To join two lines cleanly, use the `Meta-^' (`delete-indentation')
3376 command to delete the indentation at the front of the current line, and
3377 the line boundary as well. Empty spaces are replaced by a single
3378 space, or by no space if at the beginning of a line, before a close
3379 parenthesis, or after an open parenthesis. To delete just the
3380 indentation of a line, go to the beginning of the line and use `Meta-\'
3381 (`delete-horizontal-space'), which deletes all spaces and tabs around
3384 There are also commands for changing the indentation of several
3385 lines at once. `Control-Meta-\' (`indent-region') gives each line which
3386 begins in the region the "usual" indentation by invoking <TAB> at the
3387 beginning of the line. A numeric argument specifies the column to
3388 indent to. Each line is shifted left or right so that its first
3389 non-blank character appears in that column. `C-x <TAB>'
3390 (`indent-rigidly') moves all the lines in the region right by its
3391 argument (left, for negative arguments). The whole group of lines moves
3392 rigidly sideways, which is how the command gets its name.
3394 `M-x indent-relative' indents at point based on the previous line
3395 (actually, the last non-empty line.) It inserts whitespace at point,
3396 moving point, until it is underneath an indentation point in the
3397 previous line. An indentation point is the end of a sequence of
3398 whitespace or the end of the line. If point is farther right than any
3399 indentation point in the previous line, the whitespace before point is
3400 deleted and the first indentation point then applicable is used. If no
3401 indentation point is applicable even then, `tab-to-tab-stop' is run
3404 `indent-relative' is the definition of <TAB> in Indented Text mode.
3408 File: xemacs.info, Node: Tab Stops, Next: Just Spaces, Prev: Indentation Commands, Up: Indentation
3413 For typing in tables, you can use Text mode's definition of <TAB>,
3414 `tab-to-tab-stop'. This command inserts indentation before point,
3415 enough to reach the next tab stop column. Even if you are not in Text
3416 mode, this function is associated with `M-i' anyway.
3418 You can arbitrarily set the tab stops used by `M-i'. They are
3419 stored as a list of column-numbers in increasing order in the variable
3422 The convenient way to set the tab stops is using `M-x
3423 edit-tab-stops', which creates and selects a buffer containing a
3424 description of the tab stop settings. You can edit this buffer to
3425 specify different tab stops, and then type `C-c C-c' to make those new
3426 tab stops take effect. In the tab stop buffer, `C-c C-c' runs the
3427 function `edit-tab-stops-note-changes' rather than the default
3428 `save-buffer'. `edit-tab-stops' records which buffer was current when
3429 you invoked it, and stores the tab stops in that buffer. Normally all
3430 buffers share the same tab stops and changing them in one buffer
3431 affects all. If you make `tab-stop-list' local in one buffer
3432 `edit-tab-stops' in that buffer edits only the local settings.
3434 Below is the text representing ordinary tab stops every eight
3439 0123456789012345678901234567890123456789012345678
3440 To install changes, type C-c C-c
3442 The first line contains a colon at each tab stop. The remaining
3443 lines help you see where the colons are and tell you what to do.
3445 Note that the tab stops that control `tab-to-tab-stop' have nothing
3446 to do with displaying tab characters in the buffer. *Note Display
3447 Vars::, for more information on that.
3450 File: xemacs.info, Node: Just Spaces, Prev: Tab Stops, Up: Indentation
3455 Emacs normally uses both tabs and spaces to indent lines. If you
3456 prefer, all indentation can be made from spaces only. To request this,
3457 set `indent-tabs-mode' to `nil'. This is a per-buffer variable;
3458 altering the variable affects only the current buffer, but there is a
3459 default value which you can change as well. *Note Locals::.
3461 There are also commands to convert tabs to spaces or vice versa,
3462 always preserving the columns of all non-blank text. `M-x tabify'
3463 scans the region for sequences of spaces, and converts sequences of at
3464 least three spaces to tabs if that is possible without changing
3465 indentation. `M-x untabify' changes all tabs in the region to
3466 corresponding numbers of spaces.
3469 File: xemacs.info, Node: Text, Next: Programs, Prev: Indentation, Up: Top
3471 Commands for Human Languages
3472 ****************************
3474 The term "text" has two widespread meanings in our area of the computer
3475 field. One is data that is a sequence of characters. In this sense of
3476 the word any file that you edit with Emacs is text. The other meaning
3477 is more restrictive: a sequence of characters in a human language for
3478 humans to read (possibly after processing by a text formatter), as
3479 opposed to a program or commands for a program.
3481 Human languages have syntactic and stylistic conventions that editor
3482 commands should support or use to advantage: conventions involving
3483 words, sentences, paragraphs, and capital letters. This chapter
3484 describes Emacs commands for all these things. There are also commands
3485 for "filling", or rearranging paragraphs into lines of approximately
3486 equal length. The commands for moving over and killing words,
3487 sentences, and paragraphs, while intended primarily for editing text,
3488 are also often useful for editing programs.
3490 Emacs has several major modes for editing human language text. If a
3491 file contains plain text, use Text mode, which customizes Emacs in
3492 small ways for the syntactic conventions of text. For text which
3493 contains embedded commands for text formatters, Emacs has other major
3494 modes, each for a particular text formatter. Thus, for input to TeX,
3495 you can use TeX mode; for input to nroff, Nroff mode.
3499 * Text Mode:: The major modes for editing text files.
3500 * Nroff Mode:: The major mode for editing input to the formatter nroff.
3501 * TeX Mode:: The major modes for editing input to the formatter TeX.
3502 * Outline Mode:: The major mode for editing outlines.
3503 * Words:: Moving over and killing words.
3504 * Sentences:: Moving over and killing sentences.
3505 * Paragraphs:: Moving over paragraphs.
3506 * Pages:: Moving over pages.
3507 * Filling:: Filling or justifying text
3508 * Case:: Changing the case of text
3511 File: xemacs.info, Node: Text Mode, Next: Words, Prev: Text, Up: Text
3516 You should use Text mode--rather than Fundamental or Lisp mode--to edit
3517 files of text in a human language. Invoke `M-x text-mode' to enter
3518 Text mode. In Text mode, <TAB> runs the function `tab-to-tab-stop',
3519 which allows you to use arbitrary tab stops set with `M-x
3520 edit-tab-stops' (*note Tab Stops::). Features concerned with comments
3521 in programs are turned off unless they are explicitly invoked. The
3522 syntax table is changed so that periods are not considered part of a
3523 word, while apostrophes, backspaces and underlines are.
3525 A similar variant mode is Indented Text mode, intended for editing
3526 text in which most lines are indented. This mode defines <TAB> to run
3527 `indent-relative' (*note Indentation::), and makes Auto Fill indent the
3528 lines it creates. As a result, a line made by Auto Filling, or by
3529 <LFD>, is normally indented just like the previous line. Use `M-x
3530 indented-text-mode' to select this mode.
3532 Entering Text mode or Indented Text mode calls the value of the
3533 variable `text-mode-hook' with no arguments, if that value exists and
3534 is not `nil'. This value is also called when modes related to Text
3535 mode are entered; this includes Nroff mode, TeX mode, Outline mode, and
3536 Mail mode. Your hook can look at the value of `major-mode' to see
3537 which of these modes is actually being entered.
3539 Two modes similar to Text mode are of use for editing text that is to
3540 be passed through a text formatter before achieving its final readable
3545 * Nroff Mode:: The major mode for editing input to the formatter nroff.
3546 * TeX Mode:: The major modes for editing input to the formatter TeX.
3549 Another similar mode is used for editing outlines. It allows you
3550 to view the text at various levels of detail. You can view either
3551 the outline headings alone or both headings and text; you can also
3552 hide some of the headings at lower levels from view to make the high
3553 level structure more visible.
3556 * Outline Mode:: The major mode for editing outlines.
3559 File: xemacs.info, Node: Nroff Mode, Next: TeX Mode, Prev: Text Mode, Up: Text Mode
3564 Nroff mode is a mode like Text mode but modified to handle nroff
3565 commands present in the text. Invoke `M-x nroff-mode' to enter this
3566 mode. Nroff mode differs from Text mode in only a few ways. All nroff
3567 command lines are considered paragraph separators, so that filling never
3568 garbles the nroff commands. Pages are separated by `.bp' commands.
3569 Comments start with backslash-doublequote. There are also three special
3570 commands that are not available in Text mode:
3573 Move to the beginning of the next line that isn't an nroff command
3574 (`forward-text-line'). An argument is a repeat count.
3577 Like `M-n' but move up (`backward-text-line').
3580 Prints in the echo area the number of text lines (lines that are
3581 not nroff commands) in the region (`count-text-lines').
3583 The other feature of Nroff mode is Electric Nroff newline mode.
3584 This is a minor mode that you can turn on or off with `M-x
3585 electric-nroff-mode' (*note Minor Modes::). When the mode is on and
3586 you use <RET> to end a line containing an nroff command that opens a
3587 kind of grouping, Emacs automatically inserts the matching nroff
3588 command to close that grouping on the following line. For example, if
3589 you are at the beginning of a line and type `.(b <RET>', the matching
3590 command `.)b' will be inserted on a new line following point.
3592 Entering Nroff mode calls the value of the variable `text-mode-hook'
3593 with no arguments, if that value exists and is not `nil'; then it does
3594 the same with the variable `nroff-mode-hook'.
3597 File: xemacs.info, Node: TeX Mode, Next: Outline Mode, Prev: Nroff Mode, Up: Text Mode
3602 TeX is a powerful text formatter written by Donald Knuth; like GNU
3603 Emacs, it is free. LaTeX is a simplified input format for TeX,
3604 implemented by TeX macros. It is part of TeX.
3606 Emacs has a special TeX mode for editing TeX input files. It
3607 provides facilities for checking the balance of delimiters and for
3608 invoking TeX on all or part of the file.
3610 TeX mode has two variants, Plain TeX mode and LaTeX mode, which are
3611 two distinct major modes that differ only slightly. These modes are
3612 designed for editing the two different input formats. The command `M-x
3613 tex-mode' looks at the contents of a buffer to determine whether it
3614 appears to be LaTeX input or not; it then selects the appropriate mode.
3615 If it can't tell which is right (e.g., the buffer is empty), the
3616 variable `tex-default-mode' controls which mode is used.
3618 The commands `M-x plain-tex-mode' and `M-x latex-mode' explicitly
3619 select one of the variants of TeX mode. Use these commands when `M-x
3620 tex-mode' does not guess right.
3624 * Editing: TeX Editing. Special commands for editing in TeX mode.
3625 * Printing: TeX Print. Commands for printing part of a file with TeX.
3627 TeX for Unix systems can be obtained from the University of
3628 Washington for a distribution fee.
3630 To order a full distribution, send $140.00 for a 1/2 inch 9-track
3631 tape, $165.00 for two 4-track 1/4 inch cartridge tapes (foreign sites
3632 $150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover the extra
3633 postage) payable to the University of Washington to:
3636 Northwest Computer Support Group, DW-10
3637 University of Washington
3638 Seattle, Washington 98195
3640 Purchase orders are acceptable, but there is an extra charge of $10.00
3641 to pay for processing charges. (The total cost comes to $150 for
3642 domestic sites, $175 for foreign sites).
3644 The normal distribution is a tar tape, blocked 20, 1600 bpi, on an
3645 industry standard 2400 foot half-inch reel. The physical format for
3646 the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track
3647 serpentine recording for the SUN. Also, SystemV tapes can be written
3648 in cpio format, blocked 5120 bytes, ASCII headers.
3651 File: xemacs.info, Node: TeX Editing, Next: TeX Print, Prev: TeX Mode, Up: TeX Mode
3653 TeX Editing Commands
3654 ....................
3656 Here are the special commands provided in TeX mode for editing the text
3660 Insert, according to context, either ```' or `"' or `'''
3661 (`TeX-insert-quote').
3664 Insert a paragraph break (two newlines) and check the previous
3665 paragraph for unbalanced braces or dollar signs (`tex-terminate-
3668 `M-x validate-tex-buffer'
3669 Check each paragraph in the buffer for unbalanced braces or dollar
3673 Insert `{}' and position point between them (`tex-insert-braces').
3676 Move forward past the next unmatched close brace (`up-list').
3679 Close a block for LaTeX (`tex-close-latex-block').
3681 In TeX, the character `"' is not normally used; you use ```' to
3682 start a quotation and `''' to end one. TeX mode defines the key `"' to
3683 insert ```' after whitespace or an open brace, `"' after a backslash,
3684 or `''' otherwise. This is done by the command `tex-insert-quote'. If
3685 you need the character `"' itself in unusual contexts, use `C-q' to
3686 insert it. Also, `"' with a numeric argument always inserts that
3687 number of `"' characters.
3689 In TeX mode, `$' has a special syntax code which attempts to
3690 understand the way TeX math mode delimiters match. When you insert a
3691 `$' that is meant to exit math mode, the position of the matching `$'
3692 that entered math mode is displayed for a second. This is the same
3693 feature that displays the open brace that matches a close brace that is
3694 inserted. However, there is no way to tell whether a `$' enters math
3695 mode or leaves it; so when you insert a `$' that enters math mode, the
3696 previous `$' position is shown as if it were a match, even though they
3697 are actually unrelated.
3699 If you prefer to keep braces balanced at all times, you can use `C-c
3700 {' (`tex-insert-braces') to insert a pair of braces. It leaves point
3701 between the two braces so you can insert the text that belongs inside.
3702 Afterward, use the command `C-c }' (`up-list') to move forward past the
3705 There are two commands for checking the matching of braces. <LFD>
3706 (`tex-terminate-paragraph') checks the paragraph before point, and
3707 inserts two newlines to start a new paragraph. It prints a message in
3708 the echo area if any mismatch is found. `M-x validate-tex-buffer'
3709 checks the entire buffer, paragraph by paragraph. When it finds a
3710 paragraph that contains a mismatch, it displays point at the beginning
3711 of the paragraph for a few seconds and pushes a mark at that spot.
3712 Scanning continues until the whole buffer has been checked or until you
3713 type another key. The positions of the last several paragraphs with
3714 mismatches can be found in the mark ring (*note Mark Ring::).
3716 Note that square brackets and parentheses, not just braces, are
3717 matched in TeX mode. This is wrong if you want to check TeX syntax.
3718 However, parentheses and square brackets are likely to be used in text
3719 as matching delimiters and it is useful for the various motion commands
3720 and automatic match display to work with them.
3722 In LaTeX input, `\begin' and `\end' commands must balance. After
3723 you insert a `\begin', use `C-c C-f' (`tex-close-latex-block') to
3724 insert automatically a matching `\end' (on a new line following the
3725 `\begin'). A blank line is inserted between the two, and point is left
3729 File: xemacs.info, Node: TeX Print, Prev: TeX Editing, Up: TeX Mode
3731 TeX Printing Commands
3732 .....................
3734 You can invoke TeX as an inferior of Emacs on either the entire
3735 contents of the buffer or just a region at a time. Running TeX in this
3736 way on just one chapter is a good way to see what your changes look
3737 like without taking the time to format the entire file.
3740 Invoke TeX on the current region, plus the buffer's header
3744 Invoke TeX on the entire current buffer (`tex-buffer').
3747 Recenter the window showing output from the inferior TeX so that
3748 the last line can be seen (`tex-recenter-output-buffer').
3751 Kill the inferior TeX (`tex-kill-job').
3754 Print the output from the last `C-c C-r' or `C-c C-b' command
3758 Show the printer queue (`tex-show-print-queue').
3760 You can pass the current buffer through an inferior TeX using `C-c
3761 C-b' (`tex-buffer'). The formatted output appears in a file in `/tmp';
3762 to print it, type `C-c C-p' (`tex-print'). Afterward use `C-c C-q'
3763 (`tex-show-print-queue') to view the progress of your output towards
3766 The console output from TeX, including any error messages, appears
3767 in a buffer called `*TeX-shell*'. If TeX gets an error, you can switch
3768 to this buffer and feed it input (this works as in Shell mode; *note
3769 Interactive Shell::). Without switching to this buffer, you can scroll
3770 it so that its last line is visible by typing `C-c C-l'.
3772 Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
3773 that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also
3774 kills any TeX process still running.
3776 You can pass an arbitrary region through an inferior TeX by typing
3777 `C-c C-r' (`tex-region'). This is tricky, however, because most files
3778 of TeX input contain commands at the beginning to set parameters and
3779 define macros. Without them, no later part of the file will format
3780 correctly. To solve this problem, `C-c C-r' allows you to designate a
3781 part of the file as containing essential commands; it is included
3782 before the specified region as part of the input to TeX. The
3783 designated part of the file is called the "header".
3785 To indicate the bounds of the header in Plain TeX mode, insert two
3786 special strings in the file: `%**start of header' before the header,
3787 and `%**end of header' after it. Each string must appear entirely on
3788 one line, but there may be other text on the line before or after. The
3789 lines containing the two strings are included in the header. If
3790 `%**start of header' does not appear within the first 100 lines of the
3791 buffer, `C-c C-r' assumes there is no header.
3793 In LaTeX mode, the header begins with `\documentstyle' and ends with
3794 `\begin{document}'. These are commands that LaTeX requires you to use,
3795 so you don't need to do anything special to identify the header.
3797 When you enter either kind of TeX mode, Emacs calls with no
3798 arguments the value of the variable `text-mode-hook', if that value
3799 exists and is not `nil'. Emacs then calls the variable `TeX-mode-hook'
3800 and either `plain-TeX-mode-hook' or `LaTeX-mode-hook' under the same
3804 File: xemacs.info, Node: Outline Mode, Prev: TeX Mode, Up: Text Mode
3809 Outline mode is a major mode similar to Text mode but intended for
3810 editing outlines. It allows you to make parts of the text temporarily
3811 invisible so that you can see just the overall structure of the
3812 outline. Type `M-x outline-mode' to turn on Outline mode in the
3815 When you enter Outline mode, Emacs calls with no arguments the value
3816 of the variable `text-mode-hook', if that value exists and is not
3817 `nil'; then it does the same with the variable `outline-mode-hook'.
3819 When a line is invisible in outline mode, it does not appear on the
3820 screen. The screen appears exactly as if the invisible line were
3821 deleted, except that an ellipsis (three periods in a row) appears at
3822 the end of the previous visible line (only one ellipsis no matter how
3823 many invisible lines follow).
3825 All editing commands treat the text of the invisible line as part of
3826 the previous visible line. For example, `C-n' moves onto the next
3827 visible line. Killing an entire visible line, including its
3828 terminating newline, really kills all the following invisible lines as
3829 well; yanking everything back yanks the invisible lines and they remain
3834 * Format: Outline Format. What the text of an outline looks like.
3835 * Motion: Outline Motion. Special commands for moving through outlines.
3836 * Visibility: Outline Visibility. Commands to control what is visible.
3839 File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
3844 Outline mode assumes that the lines in the buffer are of two types:
3845 "heading lines" and "body lines". A heading line represents a topic in
3846 the outline. Heading lines start with one or more stars; the number of
3847 stars determines the depth of the heading in the outline structure.
3848 Thus, a heading line with one star is a major topic; all the heading
3849 lines with two stars between it and the next one-star heading are its
3850 subtopics; and so on. Any line that is not a heading line is a body
3851 line. Body lines belong to the preceding heading line. Here is an
3857 which says something about the topic of food.
3861 This is the body of the second-level header.
3873 A second first-level topic with its header line.
3875 A heading line together with all following body lines is called
3876 collectively an "entry". A heading line together with all following
3877 deeper heading lines and their body lines is called a "subtree".
3879 You can customize the criterion for distinguishing heading lines by
3880 setting the variable `outline-regexp'. Any line whose beginning has a
3881 match for this regexp is considered a heading line. Matches that start
3882 within a line (not at the beginning) do not count. The length of the
3883 matching text determines the level of the heading; longer matches make
3884 a more deeply nested level. Thus, for example, if a text formatter has
3885 commands `@chapter', `@section' and `@subsection' to divide the
3886 document into chapters and sections, you can make those lines count as
3887 heading lines by setting `outline-regexp' to
3888 `"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words
3889 `chapter' and `section' are the same length, but by defining the regexp
3890 to match only `chap' we ensure that the length of the text matched on a
3891 chapter heading is shorter, so that Outline mode will know that
3892 sections are contained in chapters. This works as long as no other
3893 command starts with `@chap'.
3895 Outline mode makes a line invisible by changing the newline before it
3896 into an ASCII Control-M (code 015). Most editing commands that work on
3897 lines treat an invisible line as part of the previous line because,
3898 strictly speaking, it is part of that line, since there is no longer a
3899 newline in between. When you save the file in Outline mode, Control-M
3900 characters are saved as newlines, so the invisible lines become ordinary
3901 lines in the file. Saving does not change the visibility status of a
3905 File: xemacs.info, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode
3907 Outline Motion Commands
3908 .......................
3910 Some special commands in Outline mode move backward and forward to
3914 Move point to the next visible heading line
3915 (`outline-next-visible-heading').
3918 Move point to the previous visible heading line
3919 (`outline-previous-visible-heading').
3922 Move point to the next visible heading line at the same level as
3923 the one point is on (`outline-forward-same-level').
3926 Move point to the previous visible heading line at the same level
3927 (`outline-backward-same-level').
3930 Move point up to a lower-level (more inclusive) visible heading
3931 line (`outline-up-heading').
3933 `C-c C-n' (`next-visible-heading') moves down to the next heading
3934 line. `C-c C-p' (`previous-visible-heading') moves similarly backward.
3935 Both accept numeric arguments as repeat counts. The names emphasize
3936 that invisible headings are skipped, but this is not really a special
3937 feature. All editing commands that look for lines ignore the invisible
3938 lines automatically.
3940 More advanced motion commands understand the levels of headings.
3941 The commands `C-c C-f' (`outline-forward-same-level') and `C-c C-b'
3942 (`outline-backward-same-level') move from one heading line to another
3943 visible heading at the same depth in the outline. `C-c C-u'
3944 (`outline-up-heading') moves backward to another heading that is less
3948 File: xemacs.info, Node: Outline Visibility, Prev: Outline Motion, Up: Outline Mode
3950 Outline Visibility Commands
3951 ...........................
3953 The other special commands of outline mode are used to make lines
3954 visible or invisible. Their names all start with `hide' or `show'.
3955 Most of them exist as pairs of opposites. They are not undoable;
3956 instead, you can undo right past them. Making lines visible or
3957 invisible is simply not recorded by the undo mechanism.
3960 Make all body lines in the buffer invisible.
3963 Make all lines in the buffer visible.
3966 Make everything under this heading invisible, not including this
3967 heading itself (`hide-subtree').
3970 Make everything under this heading visible, including body,
3971 subheadings, and their bodies (`show-subtree').
3974 Make the body of this heading line, and of all its subheadings,
3978 Make all subheadings of this heading line, at all levels, visible.
3981 Make immediate subheadings (one level down) of this heading line
3982 visible (`show-children').
3985 Make this heading line's body invisible.
3988 Make this heading line's body visible.
3990 Two commands that are exact opposites are `M-x hide-entry' and `M-x
3991 show-entry'. They are used with point on a heading line, and apply
3992 only to the body lines of that heading. The subtopics and their bodies
3995 Two more powerful opposites are `C-c C-d' (`hide-subtree') and `C-c
3996 C-s' (`show-subtree'). Both should be used when point is on a heading
3997 line, and both apply to all the lines of that heading's "subtree": its
3998 body, all its subheadings, both direct and indirect, and all of their
3999 bodies. In other words, the subtree contains everything following this
4000 heading line, up to and not including the next heading of the same or
4003 Intermediate between a visible subtree and an invisible one is having
4004 all the subheadings visible but none of the body. There are two
4005 commands for doing this, one that hides the bodies and one that makes
4006 the subheadings visible. They are `M-x hide-leaves' and `M-x
4009 A little weaker than `show-branches' is `C-c C-i' (`show-children').
4010 It makes just the direct subheadings visible--those one level down.
4011 Deeper subheadings remain invisible.
4013 Two commands have a blanket effect on the whole file. `M-x
4014 hide-body' makes all body lines invisible, so that you see just the
4015 outline structure. `M-x show-all' makes all lines visible. You can
4016 think of these commands as a pair of opposites even though `M-x
4017 show-all' applies to more than just body lines.
4019 You can turn off the use of ellipses at the ends of visible lines by
4020 setting `selective-display-ellipses' to `nil'. The result is no
4021 visible indication of the presence of invisible lines.
4024 File: xemacs.info, Node: Words, Next: Sentences, Prev: Text Mode, Up: Text
4029 Emacs has commands for moving over or operating on words. By
4030 convention, the keys for them are all `Meta-' characters.
4033 Move forward over a word (`forward-word').
4036 Move backward over a word (`backward-word').
4039 Kill up to the end of a word (`kill-word').
4042 Kill back to the beginning of a word (`backward-kill-word').
4045 Mark the end of the next word (`mark-word').
4048 Transpose two words; drag a word forward or backward across other
4049 words (`transpose-words').
4051 Notice how these keys form a series that parallels the
4052 character-based `C-f', `C-b', `C-d', `C-t' and <DEL>. `M-@' is related
4053 to `C-@', which is an alias for `C-<SPC>'.
4055 The commands `Meta-f' (`forward-word') and `Meta-b'
4056 (`backward-word') move forward and backward over words. They are
4057 analogous to `Control-f' and `Control-b', which move over single
4058 characters. Like their `Control-' analogues, `Meta-f' and `Meta-b'
4059 move several words if given an argument. `Meta-f' with a negative
4060 argument moves backward, and `Meta-b' with a negative argument moves
4061 forward. Forward motion stops after the last letter of the word, while
4062 backward motion stops before the first letter.
4064 `Meta-d' (`kill-word') kills the word after point. To be precise,
4065 it kills everything from point to the place `Meta-f' would move to.
4066 Thus, if point is in the middle of a word, `Meta-d' kills just the part
4067 after point. If some punctuation comes between point and the next
4068 word, it is killed along with the word. (To kill only the next word
4069 but not the punctuation before it, simply type `Meta-f' to get to the
4070 end and kill the word backwards with `Meta-<DEL>'.) `Meta-d' takes
4071 arguments just like `Meta-f'.
4073 `Meta-<DEL>' (`backward-kill-word') kills the word before point. It
4074 kills everything from point back to where `Meta-b' would move to. If
4075 point is after the space in `FOO, BAR', then `FOO, ' is killed. To
4076 kill just `FOO', type `Meta-b Meta-d' instead of `Meta-<DEL>'.
4078 `Meta-t' (`transpose-words') exchanges the word before or containing
4079 point with the following word. The delimiter characters between the
4080 words do not move. For example, transposing `FOO, BAR' results in
4081 `BAR, FOO' rather than `BAR FOO,'. *Note Transpose::, for more on
4082 transposition and on arguments to transposition commands.
4084 To operate on the next N words with an operation which applies
4085 between point and mark, you can either set the mark at point and then
4086 move over the words, or you can use the command `Meta-@' (`mark-word')
4087 which does not move point but sets the mark where `Meta-f' would move
4088 to. It can be given arguments just like `Meta-f'.
4090 The word commands' understanding of syntax is completely controlled
4091 by the syntax table. For example, any character can be declared to be
4092 a word delimiter. *Note Syntax::.
4095 File: xemacs.info, Node: Sentences, Next: Paragraphs, Prev: Words, Up: Text
4100 The Emacs commands for manipulating sentences and paragraphs are mostly
4101 on `Meta-' keys, and therefore are like the word-handling commands.
4104 Move back to the beginning of the sentence (`backward-sentence').
4107 Move forward to the end of the sentence (`forward-sentence').
4110 Kill forward to the end of the sentence (`kill-sentence').
4113 Kill back to the beginning of the sentence
4114 (`backward-kill-sentence').
4116 The commands `Meta-a' and `Meta-e' (`backward-sentence' and
4117 `forward-sentence') move to the beginning and end of the current
4118 sentence, respectively. They resemble `Control-a' and `Control-e',
4119 which move to the beginning and end of a line. Unlike their
4120 counterparts, `Meta-a' and `Meta-e' move over successive sentences if
4121 repeated or given numeric arguments. Emacs assumes the typist's
4122 convention is followed, and thus considers a sentence to end wherever
4123 there is a `.', `?', or `!' followed by the end of a line or two
4124 spaces, with any number of `)', `]', `'', or `"' characters allowed in
4125 between. A sentence also begins or ends wherever a paragraph begins or
4128 Neither `M-a' nor `M-e' moves past the newline or spaces beyond the
4129 sentence edge at which it is stopping.
4131 `M-a' and `M-e' have a corresponding kill command, just like `C-a'
4132 and `C-e' have `C-k'. The command is `M-k' (`kill-sentence') which
4133 kills from point to the end of the sentence. With minus one as an
4134 argument it kills back to the beginning of the sentence. Larger
4135 arguments serve as repeat counts.
4137 There is a special command, `C-x <DEL>' (`backward-kill-sentence'),
4138 for killing back to the beginning of a sentence, which is useful when
4139 you change your mind in the middle of composing text.
4141 The variable `sentence-end' controls recognition of the end of a
4142 sentence. It is a regexp that matches the last few characters of a
4143 sentence, together with the whitespace following the sentence. Its
4146 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
4148 This example is explained in the section on regexps. *Note Regexps::.
4151 File: xemacs.info, Node: Paragraphs, Next: Pages, Prev: Sentences, Up: Text
4156 The Emacs commands for manipulating paragraphs are also `Meta-' keys.
4159 Move back to previous paragraph beginning
4160 (`backward-paragraph').
4163 Move forward to next paragraph end (`forward-paragraph').
4166 Put point and mark around this or next paragraph
4169 `Meta-{' moves to the beginning of the current or previous paragraph,
4170 while `Meta-}' moves to the end of the current or next paragraph.
4171 Blank lines and text formatter command lines separate paragraphs and are
4172 not part of any paragraph. An indented line starts a new paragraph.
4174 In major modes for programs (as opposed to Text mode), paragraphs
4175 begin and end only at blank lines. As a result, the paragraph commands
4176 continue to be useful even though there are no paragraphs per se.
4178 When there is a fill prefix, paragraphs are delimited by all lines
4179 which don't start with the fill prefix. *Note Filling::.
4181 To operate on a paragraph, you can use the command `Meta-h'
4182 (`mark-paragraph') to set the region around it. This command puts
4183 point at the beginning and mark at the end of the paragraph point was
4184 in. If point is between paragraphs (in a run of blank lines or at a
4185 boundary), the paragraph following point is surrounded by point and
4186 mark. If there are blank lines preceding the first line of the
4187 paragraph, one of the blank lines is included in the region. Thus, for
4188 example, `M-h C-w' kills the paragraph around or after point.
4190 The precise definition of a paragraph boundary is controlled by the
4191 variables `paragraph-separate' and `paragraph-start'. The value of
4192 `paragraph-start' is a regexp that matches any line that either starts
4193 or separates paragraphs. The value of `paragraph-separate' is another
4194 regexp that matches only lines that separate paragraphs without being
4195 part of any paragraph. Lines that start a new paragraph and are
4196 contained in it must match both regexps. For example, normally
4197 `paragraph-start' is `"^[ \t\n\f]"' and `paragraph-separate' is `"^[
4200 Normally it is desirable for page boundaries to separate paragraphs.
4201 The default values of these variables recognize the usual separator for
4205 File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
4210 Files are often thought of as divided into "pages" by the "formfeed"
4211 character (ASCII Control-L, octal code 014). For example, if a file is
4212 printed on a line printer, each "page" of the file starts on a new page
4213 of paper. Emacs treats a page-separator character just like any other
4214 character. It can be inserted with `C-q C-l' or deleted with <DEL>.
4215 You are free to paginate your file or not. However, since pages are
4216 often meaningful divisions of the file, commands are provided to move
4217 over them and operate on them.
4220 Move point to previous page boundary (`backward-page').
4223 Move point to next page boundary (`forward-page').
4226 Put point and mark around this page (or another page)
4230 Count the lines in this page (`count-lines-page').
4232 The `C-x [' (`backward-page') command moves point to immediately
4233 after the previous page delimiter. If point is already right after a
4234 page delimiter, the command skips that one and stops at the previous
4235 one. A numeric argument serves as a repeat count. The `C-x ]'
4236 (`forward-page') command moves forward past the next page delimiter.
4238 The `C-x C-p' command (`mark-page') puts point at the beginning of
4239 the current page and the mark at the end. The page delimiter at the end
4240 is included (the mark follows it). The page delimiter at the front is
4241 excluded (point follows it). You can follow this command by `C-w' to
4242 kill a page you want to move elsewhere. If you insert the page after a
4243 page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
4244 page will be properly delimited before and after once again.
4246 A numeric argument to `C-x C-p' is used to specify which page to go
4247 to, relative to the current one. Zero means the current page. One
4248 means the next page, and -1 means the previous one.
4250 The `C-x l' command (`count-lines-page') can help you decide where
4251 to break a page in two. It prints the total number of lines in the
4252 current page in the echo area, then divides the lines into those
4253 preceding the current line and those following it, for example
4255 Page has 96 (72+25) lines
4257 Notice that the sum is off by one; this is correct if point is not at
4258 the beginning of a line.
4260 The variable `page-delimiter' should have as its value a regexp that
4261 matches the beginning of a line that separates pages. This defines
4262 where pages begin. The normal value of this variable is `"^\f"', which
4263 matches a formfeed character at the beginning of a line.
4266 File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text
4271 If you use Auto Fill mode, Emacs "fills" text (breaks it up into lines
4272 that fit in a specified width) as you insert it. When you alter
4273 existing text it is often no longer be properly filled afterwards and
4274 you can use explicit commands for filling.
4278 * Auto Fill:: Auto Fill mode breaks long lines automatically.
4279 * Fill Commands:: Commands to refill paragraphs and center lines.
4280 * Fill Prefix:: Filling when every line is indented or in a comment, etc.
4283 File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
4288 "Auto Fill" mode is a minor mode in which lines are broken
4289 automatically when they become too wide. Breaking happens only when
4290 you type a <SPC> or <RET>.
4292 `M-x auto-fill-mode'
4293 Enable or disable Auto Fill mode.
4297 In Auto Fill mode, break lines when appropriate.
4299 `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
4300 if it was on. With a positive numeric argument the command always turns
4301 Auto Fill mode on, and with a negative argument it always turns it off.
4302 The presence of the word `Fill' in the mode line, inside the
4303 parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode
4304 is a minor mode; you can turn it on or off for each buffer individually.
4305 *Note Minor Modes::.
4307 In Auto Fill mode, lines are broken automatically at spaces when
4308 they get longer than desired. Line breaking and rearrangement takes
4309 place only when you type <SPC> or <RET>. To insert a space or newline
4310 without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
4311 (recall that a newline is really a linefeed). `C-o' inserts a newline
4312 without line breaking.
4314 Auto Fill mode works well with Lisp mode: when it makes a new line in
4315 Lisp mode, it indents that line with <TAB>. If a line ending in a Lisp
4316 comment gets too long, the text of the comment is split into two
4317 comment lines. Optionally, new comment delimiters are inserted at the
4318 end of the first line and the beginning of the second, so that each line
4319 is a separate comment. The variable `comment-multi-line' controls the
4320 choice (*note Comments::).
4322 Auto Fill mode does not refill entire paragraphs. It can break
4323 lines but cannot merge lines. Editing in the middle of a paragraph can
4324 result in a paragraph that is not correctly filled. The easiest way to
4325 make the paragraph properly filled again is using an explicit fill
4328 Many users like Auto Fill mode and want to use it in all text files.
4329 The section on init files explains how you can arrange this permanently
4330 for yourself. *Note Init File::.
4333 File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
4335 Explicit Fill Commands
4336 ----------------------
4339 Fill current paragraph (`fill-paragraph').
4342 Fill each paragraph in the region (`fill-region').
4345 Set the fill column (`set-fill-column').
4347 `M-x fill-region-as-paragraph'
4348 Fill the region, considering it as one paragraph.
4353 To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
4354 It causes the paragraph containing point, or the one after point if
4355 point is between paragraphs, to be refilled. All line breaks are
4356 removed, and new ones are inserted where necessary. `M-q' can be
4357 undone with `C-_'. *Note Undo::.
4359 To refill many paragraphs, use `M-g' (`fill-region'), which divides
4360 the region into paragraphs and fills each of them.
4362 `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
4363 paragraph boundaries (*note Paragraphs::). For more control, you can
4364 use `M-x fill-region-as-paragraph', which refills everything between
4365 point and mark. This command recognizes only blank lines as paragraph
4368 A numeric argument to `M-g' or `M-q' causes it to "justify" the text
4369 as well as filling it. Extra spaces are inserted to make the right
4370 margin line up exactly at the fill column. To remove the extra spaces,
4371 use `M-q' or `M-g' with no argument.
4373 The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
4374 match lines that should not be auto-filled.
4376 The command `Meta-s' (`center-line') centers the current line within
4377 the current fill column. With an argument, it centers several lines
4378 individually and moves past them.
4380 The maximum line width for filling is in the variable `fill-column'.
4381 Altering the value of `fill-column' makes it local to the current
4382 buffer; until then, the default value--initially 70--is in effect.
4385 The easiest way to set `fill-column' is to use the command `C-x f'
4386 (`set-fill-column'). With no argument, it sets `fill-column' to the
4387 current horizontal position of point. With a numeric argument, it uses
4388 that number as the new fill column.
4391 File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
4396 To fill a paragraph in which each line starts with a special marker
4397 (which might be a few spaces, giving an indented paragraph), use the
4398 "fill prefix" feature. The fill prefix is a string which is not
4399 included in filling. Emacs expects every line to start with a fill
4403 Set the fill prefix (`set-fill-prefix').
4406 Fill a paragraph using current fill prefix (`fill-paragraph').
4408 `M-x fill-individual-paragraphs'
4409 Fill the region, considering each change of indentation as
4410 starting a new paragraph.
4412 To specify a fill prefix, move to a line that starts with the desired
4413 prefix, put point at the end of the prefix, and give the command
4414 `C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
4415 off the fill prefix, specify an empty prefix: type `C-x .' with point
4416 at the beginning of a line.
4418 When a fill prefix is in effect, the fill commands remove the fill
4419 prefix from each line before filling and insert it on each line after
4420 filling. Auto Fill mode also inserts the fill prefix inserted on new
4421 lines it creates. Lines that do not start with the fill prefix are
4422 considered to start paragraphs, both in `M-q' and the paragraph
4423 commands; this is just right if you are using paragraphs with hanging
4424 indentation (every line indented except the first one). Lines which are
4425 blank or indented once the prefix is removed also separate or start
4426 paragraphs; this is what you want if you are writing multi-paragraph
4427 comments with a comment delimiter on each line.
4429 The fill prefix is stored in the variable `fill-prefix'. Its value
4430 is a string, or `nil' when there is no fill prefix. This is a
4431 per-buffer variable; altering the variable affects only the current
4432 buffer, but there is a default value which you can change as well.
4435 Another way to use fill prefixes is through `M-x
4436 fill-individual-paragraphs'. This function divides the region into
4437 groups of consecutive lines with the same amount and kind of
4438 indentation and fills each group as a paragraph, using its indentation
4442 File: xemacs.info, Node: Case, Prev: Filling, Up: Text
4444 Case Conversion Commands
4445 ========================
4447 Emacs has commands for converting either a single word or any arbitrary
4448 range of text to upper case or to lower case.
4451 Convert following word to lower case (`downcase-word').
4454 Convert following word to upper case (`upcase-word').
4457 Capitalize the following word (`capitalize-word').
4460 Convert region to lower case (`downcase-region').
4463 Convert region to upper case (`upcase-region').
4465 The word conversion commands are used most frequently. `Meta-l'
4466 (`downcase-word') converts the word after point to lower case, moving
4467 past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
4468 (`upcase-word') converts to all capitals instead, while `Meta-c'
4469 (`capitalize-word') puts the first letter of the word into upper case
4470 and the rest into lower case. The word conversion commands convert
4471 several words at once if given an argument. They are especially
4472 convenient for converting a large amount of text from all upper case to
4473 mixed case: you can move through the text using `M-l', `M-u', or `M-c'
4474 on each word as appropriate, occasionally using `M-f' instead to skip a
4477 When given a negative argument, the word case conversion commands
4478 apply to the appropriate number of words before point, but do not move
4479 point. This is convenient when you have just typed a word in the wrong
4480 case: you can give the case conversion command and continue typing.
4482 If a word case conversion command is given in the middle of a word,
4483 it applies only to the part of the word which follows point. This is
4484 just like what `Meta-d' (`kill-word') does. With a negative argument,
4485 case conversion applies only to the part of the word before point.
4487 The other case conversion commands are `C-x C-u' (`upcase-region')
4488 and `C-x C-l' (`downcase-region'), which convert everything between
4489 point and mark to the specified case. Point and mark do not move.
4492 File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top
4497 Emacs has many commands designed to understand the syntax of programming
4498 languages such as Lisp and C. These commands can:
4500 * Move over or kill balanced expressions or "sexps" (*note Lists::).
4502 * Move over or mark top-level balanced expressions ("defuns", in
4503 Lisp; functions, in C).
4505 * Show how parentheses balance (*note Matching::).
4507 * Insert, kill, or align comments (*note Comments::).
4509 * Follow the usual indentation conventions of the language (*note
4512 The commands available for words, sentences, and paragraphs are
4513 useful in editing code even though their canonical application is for
4514 editing human language text. Most symbols contain words (*note
4515 Words::); sentences can be found in strings and comments (*note
4516 Sentences::). Paragraphs per se are not present in code, but the
4517 paragraph commands are useful anyway, because Lisp mode and C mode
4518 define paragraphs to begin and end at blank lines (*note Paragraphs::).
4519 Judicious use of blank lines to make the program clearer also provides
4520 interesting chunks of text for the paragraph commands to work on.
4522 The selective display feature is useful for looking at the overall
4523 structure of a function (*note Selective Display::). This feature
4524 causes only the lines that are indented less than a specified amount to
4525 appear on the screen.
4529 * Program Modes:: Major modes for editing programs.
4530 * Lists:: Expressions with balanced parentheses.
4531 There are editing commands to operate on them.
4532 * Defuns:: Each program is made up of separate functions.
4533 There are editing commands to operate on them.
4534 * Grinding:: Adjusting indentation to show the nesting.
4535 * Matching:: Insertion of a close-delimiter flashes matching open.
4536 * Comments:: Inserting, filling and aligning comments.
4537 * Balanced Editing:: Inserting two matching parentheses at once, etc.
4538 * Lisp Completion:: Completion on symbol names in Lisp code.
4539 * Documentation:: Getting documentation of functions you plan to call.
4540 * Change Log:: Maintaining a change history for your program.
4541 * Tags:: Go direct to any function in your program in one
4542 command. Tags remembers which file it is in.
4543 * Fortran:: Fortran mode and its special features.
4544 * Asm Mode:: Asm mode and its special features.
4547 File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
4549 Major Modes for Programming Languages
4550 =====================================
4552 Emacs has several major modes for the programming languages Lisp,
4553 Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major
4554 mode should be implemented for each programming language you might want
4555 to edit with Emacs; but often the mode for one language can serve for
4556 other syntactically similar languages. The language modes that exist
4557 are those that someone decided to take the trouble to write.
4559 There are several variants of Lisp mode, which differ in the way they
4560 interface to Lisp execution. *Note Lisp Modes::.
4562 Each of the programming language modes defines the <TAB> key to run
4563 an indentation function that knows the indentation conventions of that
4564 language and updates the current line's indentation accordingly. For
4565 example, in C mode <TAB> is bound to `c-indent-line'. <LFD> is
4566 normally defined to do <RET> followed by <TAB>; thus it, too, indents
4567 in a mode-specific fashion.
4569 In most programming languages, indentation is likely to vary from
4570 line to line. So the major modes for those languages rebind <DEL> to
4571 treat a tab as if it were the equivalent number of spaces (using the
4572 command `backward-delete-char-untabify'). This makes it possible to
4573 rub out indentation one column at a time without worrying whether it is
4574 made up of spaces or tabs. In these modes, use `C-b C-d' to delete a
4575 tab character before point.
4577 Programming language modes define paragraphs to be separated only by
4578 blank lines, so that the paragraph commands remain useful. Auto Fill
4579 mode, if enabled in a programming language major mode, indents the new
4580 lines which it creates.
4582 Turning on a major mode calls a user-supplied function called the
4583 "mode hook", which is the value of a Lisp variable. For example,
4584 turning on C mode calls the value of the variable `c-mode-hook' if that
4585 value exists and is non-`nil'. Mode hook variables for other
4586 programming language modes include `lisp-mode-hook',
4587 `emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
4588 `scheme-mode-hook', and `muddle-mode-hook'. The mode hook function
4589 receives no arguments.
4592 File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
4597 By convention, Emacs keys for dealing with balanced expressions are
4598 usually `Control-Meta-' characters. They tend to be analogous in
4599 function to their `Control-' and `Meta-' equivalents. These commands
4600 are usually thought of as pertaining to expressions in programming
4601 languages, but can be useful with any language in which some sort of
4602 parentheses exist (including English).
4604 The commands fall into two classes. Some commands deal only with
4605 "lists" (parenthetical groupings). They see nothing except
4606 parentheses, brackets, braces (depending on what must balance in the
4607 language you are working with), and escape characters that might be used
4610 The other commands deal with expressions or "sexps". The word `sexp'
4611 is derived from "s-expression", the term for a symbolic expression in
4612 Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It
4613 refers to an expression in the language your program is written in.
4614 Each programming language has its own major mode, which customizes the
4615 syntax tables so that expressions in that language count as sexps.
4617 Sexps typically include symbols, numbers, and string constants, as
4618 well as anything contained in parentheses, brackets, or braces.
4620 In languages that use prefix and infix operators, such as C, it is
4621 not possible for all expressions to be sexps. For example, C mode does
4622 not recognize `foo + bar' as an sexp, even though it is a C expression;
4623 it recognizes `foo' as one sexp and `bar' as another, with the `+' as
4624 punctuation between them. This is a fundamental ambiguity: both `foo +
4625 bar' and `foo' are legitimate choices for the sexp to move over if
4626 point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
4628 Some languages have obscure forms of syntax for expressions that
4629 nobody has bothered to make Emacs understand properly.
4632 Move forward over an sexp (`forward-sexp').
4635 Move backward over an sexp (`backward-sexp').
4638 Kill sexp forward (`kill-sexp').
4641 Move up and backward in list structure (`backward-up-list').
4644 Move down and forward in list structure (`down-list').
4647 Move forward over a list (`forward-list').
4650 Move backward over a list (`backward-list').
4653 Transpose expressions (`transpose-sexps').
4656 Put mark after following expression (`mark-sexp').
4658 To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the
4659 first significant character after point is an opening delimiter (`(' in
4660 Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
4661 delimiter. If the character begins a symbol, string, or number,
4662 `C-M-f' moves over that. If the character after point is a closing
4663 delimiter, `C-M-f' just moves past it. (This last is not really moving
4664 across an sexp; it is an exception which is included in the definition
4665 of `C-M-f' because it is as useful a behavior as anyone can think of
4666 for that situation.)
4668 The command `C-M-b' (`backward-sexp') moves backward over a sexp.
4669 The detailed rules are like those above for `C-M-f', but with
4670 directions reversed. If there are any prefix characters (single quote,
4671 back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
4674 `C-M-f' or `C-M-b' with an argument repeats that operation the
4675 specified number of times; with a negative argument, it moves in the
4678 In languages such as C where the comment-terminator can be
4679 recognized, the sexp commands move across comments as if they were
4680 whitespace. In Lisp and other languages where comments run until the
4681 end of a line, it is very difficult to ignore comments when parsing
4682 backwards; therefore, in such languages the sexp commands treat the
4683 text of comments as if it were code.
4685 Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
4686 `C-M-k' kills the characters that `C-M-f' would move over.
4688 The "list commands", `C-M-n' (`forward-list') and `C-M-p'
4689 (`backward-list'), move over lists like the sexp commands but skip over
4690 any number of other kinds of sexps (symbols, strings, etc). In some
4691 situations, these commands are useful because they usually ignore
4692 comments, since the comments usually do not contain any lists.
4694 `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
4695 is possible. To move up one (or N) levels, use `C-M-u'
4696 (`backward-up-list'). `C-M-u' moves backward up past one unmatched
4697 opening delimiter. A positive argument serves as a repeat count; a
4698 negative argument reverses direction of motion and also requests
4699 repetition, so it moves forward and up one or more levels.
4701 To move down in list structure, use `C-M-d' (`down-list'). In Lisp
4702 mode, where `(' is the only opening delimiter, this is nearly the same
4703 as searching for a `('. An argument specifies the number of levels of
4704 parentheses to go down.
4706 `C-M-t' (`transpose-sexps') drags the previous sexp across the next
4707 one. An argument serves as a repeat count, and a negative argument
4708 drags backwards (thus canceling out the effect of `C-M-t' with a
4709 positive argument). An argument of zero, rather than doing nothing,
4710 transposes the sexps ending after point and the mark.
4712 To make the region be the next sexp in the buffer, use `C-M-@'
4713 (`mark-sexp') which sets the mark at the same place that `C-M-f' would
4714 move to. `C-M-@' takes arguments like `C-M-f'. In particular, a
4715 negative argument is useful for putting the mark at the beginning of
4718 The list and sexp commands' understanding of syntax is completely
4719 controlled by the syntax table. Any character can, for example, be
4720 declared to be an opening delimiter and act like an open parenthesis.
4724 File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
4729 In Emacs, a parenthetical grouping at the top level in the buffer is
4730 called a "defun". The name derives from the fact that most top-level
4731 lists in Lisp are instances of the special form `defun', but Emacs
4732 calls any top-level parenthetical grouping counts a defun regardless of
4733 its contents or the programming language. For example, in C, the body
4734 of a function definition is a defun.
4737 Move to beginning of current or preceding defun
4738 (`beginning-of-defun').
4741 Move to end of current or following defun (`end-of-defun').
4744 Put region around whole current or following defun (`mark-defun').
4746 The commands to move to the beginning and end of the current defun
4747 are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
4749 To operate on the current defun, use `C-M-h' (`mark-defun') which
4750 puts point at the beginning and the mark at the end of the current or
4751 next defun. This is the easiest way to prepare for moving the defun to
4752 a different place. In C mode, `C-M-h' runs the function
4753 `mark-c-function', which is almost the same as `mark-defun', but which
4754 backs up over the argument declarations, function name, and returned
4755 data type so that the entire C function is inside the region.
4757 To compile and evaluate the current defun, use `M-x compile-defun'.
4758 This function prints the results in the minibuffer. If you include an
4759 argument, it inserts the value in the current buffer after the defun.
4761 Emacs assumes that any open-parenthesis found in the leftmost column
4762 is the start of a defun. Therefore, never put an open-parenthesis at
4763 the left margin in a Lisp file unless it is the start of a top level
4764 list. Never put an open-brace or other opening delimiter at the
4765 beginning of a line of C code unless it starts the body of a function.
4766 The most likely problem case is when you want an opening delimiter at
4767 the start of a line inside a string. To avoid trouble, put an escape
4768 character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
4769 before the opening delimiter. It will not affect the contents of the
4772 The original Emacs found defuns by moving upward a level of
4773 parentheses until there were no more levels to go up. This required
4774 scanning back to the beginning of the buffer for every function. To
4775 speed this up, Emacs was changed to assume that any `(' (or other
4776 character assigned the syntactic class of opening-delimiter) at the
4777 left margin is the start of a defun. This heuristic is nearly always
4778 right; however, it mandates the convention described above.
4781 File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
4783 Indentation for Programs
4784 ========================
4786 The best way to keep a program properly indented ("ground") is to use
4787 Emacs to re-indent it as you change the program. Emacs has commands to
4788 indent properly either a single line, a specified number of lines, or
4789 all of the lines inside a single parenthetical grouping.
4794 * Multi-line Indent:: Commands to reindent many lines at once.
4795 * Lisp Indent:: Specifying how each Lisp function should be indented.
4796 * C Indent:: Choosing an indentation style for C code.
4799 File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
4801 Basic Program Indentation Commands
4802 ----------------------------------
4805 Adjust indentation of current line.
4808 Equivalent to <RET> followed by <TAB> (`newline-and-indent').
4810 The basic indentation command is <TAB>, which gives the current line
4811 the correct indentation as determined from the previous lines. The
4812 function that <TAB> runs depends on the major mode; it is
4813 `lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
4814 functions understand different syntaxes for different languages, but
4815 they all do about the same thing. <TAB> in any programming language
4816 major mode inserts or deletes whitespace at the beginning of the
4817 current line, independent of where point is in the line. If point is
4818 inside the whitespace at the beginning of the line, <TAB> leaves it at
4819 the end of that whitespace; otherwise, <TAB> leaves point fixed with
4820 respect to the characters around it.
4822 Use `C-q <TAB>' to insert a tab at point.
4824 When entering a large amount of new code, use <LFD>
4825 (`newline-and-indent'), which is equivalent to a <RET> followed by a
4826 <TAB>. <LFD> creates a blank line, then gives it the appropriate
4829 <TAB> indents the second and following lines of the body of a
4830 parenthetical grouping each under the preceding one; therefore, if you
4831 alter one line's indentation to be nonstandard, the lines below tend to
4832 follow it. This is the right behavior in cases where the standard
4833 result of <TAB> does not look good.
4835 Remember that Emacs assumes that an open-parenthesis, open-brace, or
4836 other opening delimiter at the left margin (including the indentation
4837 routines) is the start of a function. You should therefore never have
4838 an opening delimiter in column zero that is not the beginning of a
4839 function, not even inside a string. This restriction is vital for
4840 making the indentation commands fast. *Note Defuns::, for more
4841 information on this behavior.
4844 File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
4846 Indenting Several Lines
4847 -----------------------
4849 Several commands are available to re-indent several lines of code which
4850 have been altered or moved to a different level in a list structure.
4853 Re-indent all the lines within one list (`indent-sexp').
4856 Shift an entire list rigidly sideways so that its first line is
4860 Re-indent all lines in the region (`indent-region').
4862 To re-indent the contents of a single list, position point before the
4863 beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
4864 Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
4865 functions in other modes. The indentation of the line the sexp starts
4866 on is not changed; therefore, only the relative indentation within the
4867 list, and not its position, is changed. To correct the position as
4868 well, type a <TAB> before `C-M-q'.
4870 If the relative indentation within a list is correct but the
4871 indentation of its beginning is not, go to the line on which the list
4872 begins and type `C-u <TAB>'. When you give <TAB> a numeric argument,
4873 it moves all the lines in the group, starting on the current line,
4874 sideways the same amount that the current line moves. The command does
4875 not move lines that start inside strings, or C preprocessor lines when
4878 Another way to specify a range to be re-indented is with point and
4879 mark. The command `C-M-\' (`indent-region') applies <TAB> to every
4880 line whose first character is between point and mark.
4883 File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding
4885 Customizing Lisp Indentation
4886 ----------------------------
4888 The indentation pattern for a Lisp expression can depend on the function
4889 called by the expression. For each Lisp function, you can choose among
4890 several predefined patterns of indentation, or define an arbitrary one
4891 with a Lisp program.
4893 The standard pattern of indentation is as follows: the second line
4894 of the expression is indented under the first argument, if that is on
4895 the same line as the beginning of the expression; otherwise, the second
4896 line is indented underneath the function name. Each following line is
4897 indented under the previous line whose nesting depth is the same.
4899 If the variable `lisp-indent-offset' is non-`nil', it overrides the
4900 usual indentation pattern for the second line of an expression, so that
4901 such lines are always indented `lisp-indent-offset' more columns than
4902 the containing list.
4904 Certain functions override the standard pattern. Functions whose
4905 names start with `def' always indent the second line by
4906 `lisp-body-indention' extra columns beyond the open-parenthesis
4907 starting the expression.
4909 Individual functions can override the standard pattern in various
4910 ways, according to the `lisp-indent-function' property of the function
4911 name. (Note: `lisp-indent-function' was formerly called
4912 `lisp-indent-hook'). There are four possibilities for this property:
4915 This is the same as no property; the standard indentation pattern
4919 The pattern used for function names that start with `def' is used
4920 for this function also.
4923 The first NUMBER arguments of the function are "distinguished"
4924 arguments; the rest are considered the "body" of the expression.
4925 A line in the expression is indented according to whether the
4926 first argument on it is distinguished or not. If the argument is
4927 part of the body, the line is indented `lisp-body-indent' more
4928 columns than the open-parenthesis starting the containing
4929 expression. If the argument is distinguished and is either the
4930 first or second argument, it is indented twice that many extra
4931 columns. If the argument is distinguished and not the first or
4932 second argument, the standard pattern is followed for that line.
4935 SYMBOL should be a function name; that function is called to
4936 calculate the indentation of a line within this expression. The
4937 function receives two arguments:
4939 The value returned by `parse-partial-sexp' (a Lisp primitive
4940 for indentation and nesting computation) when it parses up to
4941 the beginning of this line.
4944 The position at which the line being indented begins.
4946 It should return either a number, which is the number of columns of
4947 indentation for that line, or a list whose first element is such a
4948 number. The difference between returning a number and returning a
4949 list is that a number says that all following lines at the same
4950 nesting level should be indented just like this one; a list says
4951 that following lines might call for different indentations. This
4952 makes a difference when the indentation is computed by `C-M-q'; if
4953 the value is a number, `C-M-q' need not recalculate indentation
4954 for the following lines until the end of the list.
4957 File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
4959 Customizing C Indentation
4960 -------------------------
4962 Two variables control which commands perform C indentation and when.
4964 If `c-auto-newline' is non-`nil', newlines are inserted both before
4965 and after braces that you insert and after colons and semicolons.
4966 Correct C indentation is done on all the lines that are made this way.
4968 If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
4969 does indentation only if point is at the left margin or within the
4970 line's indentation. If there is non-whitespace to the left of point,
4971 <TAB> just inserts a tab character in the buffer. Normally, this
4972 variable is `nil', and <TAB> always reindents the current line.
4974 C does not have anything analogous to particular function names for
4975 which special forms of indentation are desirable. However, it has a
4976 different need for customization facilities: many different styles of C
4977 indentation are in common use.
4979 There are six variables you can set to control the style that Emacs C
4983 Indentation of C statements within surrounding block. The
4984 surrounding block's indentation is the indentation of the line on
4985 which the open-brace appears.
4987 `c-continued-statement-offset'
4988 Extra indentation given to a substatement, such as the then-clause
4989 of an `if' or body of a `while'.
4992 Extra indentation for lines that start with an open brace.
4994 `c-brace-imaginary-offset'
4995 An open brace following other text is treated as if it were this
4996 far to the right of the start of its line.
4999 Indentation level of declarations of C function arguments.
5002 Extra indentation for a line that is a label, case, or default.
5004 The variable `c-indent-level' controls the indentation for C
5005 statements with respect to the surrounding block. In the example:
5010 the difference in indentation between the lines is `c-indent-level'.
5011 Its standard value is 2.
5013 If the open-brace beginning the compound statement is not at the
5014 beginning of its line, the `c-indent-level' is added to the indentation
5015 of the line, not the column of the open-brace. For example,
5020 One popular indentation style is that which results from setting
5021 `c-indent-level' to 8 and putting open-braces at the end of a line in
5022 this way. Another popular style prefers to put the open-brace on a
5025 In fact, the value of the variable `c-brace-imaginary-offset' is
5026 also added to the indentation of such a statement. Normally this
5027 variable is zero. Think of this variable as the imaginary position of
5028 the open brace, relative to the first non-blank character on the line.
5029 By setting the variable to 4 and `c-indent-level' to 0, you can get
5036 When `c-indent-level' is zero, the statements inside most braces
5037 line up exactly under the open brace. An exception are braces in column
5038 zero, like those surrounding a function's body. The statements inside
5039 those braces are not placed at column zero. Instead, `c-brace-offset'
5040 and `c-continued-statement-offset' (see below) are added to produce a
5041 typical offset between brace levels, and the statements are indented
5044 `c-continued-statement-offset' controls the extra indentation for a
5045 line that starts within a statement (but not within parentheses or
5046 brackets). These lines are usually statements inside other statements,
5047 like the then-clauses of `if' statements and the bodies of `while'
5048 statements. The `c-continued-statement-offset' parameter determines
5049 the difference in indentation between the two lines in:
5054 The default value for `c-continued-statement-offset' is 2. Some
5055 popular indentation styles correspond to a value of zero for
5056 `c-continued-statement-offset'.
5058 `c-brace-offset' is the extra indentation given to a line that
5059 starts with an open-brace. Its standard value is zero; compare:
5069 If you set `c-brace-offset' to 4, the first example becomes:
5074 `c-argdecl-indent' controls the indentation of declarations of the
5075 arguments of a C function. It is absolute: argument declarations
5076 receive exactly `c-argdecl-indent' spaces. The standard value is 5 and
5077 results in code like this:
5080 index (string, char)
5084 `c-label-offset' is the extra indentation given to a line that
5085 contains a label, a case statement, or a `default:' statement. Its
5086 standard value is -2 and results in code like this:
5092 If `c-label-offset' were zero, the same code would be indented as:
5098 This example assumes that the other variables above also have their
5101 Using the indentation style produced by the default settings of the
5102 variables just discussed and putting open braces on separate lines
5103 produces clear and readable files. For an example, look at any of the C
5104 source files of XEmacs.
5107 File: xemacs.info, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs
5109 Automatic Display of Matching Parentheses
5110 =========================================
5112 The Emacs parenthesis-matching feature shows you automatically how
5113 parentheses match in the text. Whenever a self-inserting character that
5114 is a closing delimiter is typed, the cursor moves momentarily to the
5115 location of the matching opening delimiter, provided that is visible on
5116 the screen. If it is not on the screen, some text starting with that
5117 opening delimiter is displayed in the echo area. Either way, you see
5118 the grouping you are closing off.
5120 In Lisp, automatic matching applies only to parentheses. In C, it
5121 also applies to braces and brackets. Emacs knows which characters to
5122 regard as matching delimiters based on the syntax table set by the major
5123 mode. *Note Syntax::.
5125 If the opening delimiter and closing delimiter are mismatched--as in
5126 `[x)'--the echo area displays a warning message. The correct matches
5127 are specified in the syntax table.
5129 Two variables control parenthesis matching displays.
5130 `blink-matching-paren' turns the feature on or off. The default is `t'
5131 (match display is on); `nil' turns it off.
5132 `blink-matching-paren-distance' specifies how many characters back
5133 Emacs searches to find a matching opening delimiter. If the match is
5134 not found in the specified region, scanning stops, and nothing is
5135 displayed. This prevents wasting lots of time scanning when there is no
5136 match. The default is 4000.
5139 File: xemacs.info, Node: Comments, Next: Balanced Editing, Prev: Matching, Up: Programs
5141 Manipulating Comments
5142 =====================
5144 The comment commands insert, kill and align comments.
5147 Insert or align comment (`indent-for-comment').
5150 Set comment column (`set-comment-column').
5153 Kill comment on current line (`kill-comment').
5156 Like <RET> followed by inserting and aligning a comment
5157 (`indent-new-comment-line').
5159 The command that creates a comment is `Meta-;'
5160 (`indent-for-comment'). If there is no comment already on the line, a
5161 new comment is created and aligned at a specific column called the
5162 "comment column". Emacs creates the comment by inserting the string at
5163 the value of `comment-start'; see below. Point is left after that
5164 string. If the text of the line extends past the comment column,
5165 indentation is done to a suitable boundary (usually, at least one space
5166 is inserted). If the major mode has specified a string to terminate
5167 comments, that string is inserted after point, to keep the syntax valid.
5169 You can also use `Meta-;' to align an existing comment. If a line
5170 already contains the string that starts comments, `M-;' just moves
5171 point after it and re-indents it to the conventional place. Exception:
5172 comments starting in column 0 are not moved.
5174 Some major modes have special rules for indenting certain kinds of
5175 comments in certain contexts. For example, in Lisp code, comments which
5176 start with two semicolons are indented as if they were lines of code,
5177 instead of at the comment column. Comments which start with three
5178 semicolons are supposed to start at the left margin. Emacs understands
5179 these conventions by indenting a double-semicolon comment using <TAB>
5180 and by not changing the indentation of a triple-semicolon comment at
5183 ;; This function is just an example.
5184 ;;; Here either two or three semicolons are appropriate.
5186 ;;; And now, the first part of the function:
5187 ;; The following line adds one.
5188 (1+ x)) ; This line adds one.
5190 In C code, a comment preceded on its line by nothing but whitespace
5191 is indented like a line of code.
5193 Even when an existing comment is properly aligned, `M-;' is still
5194 useful for moving directly to the start of the comment.
5196 `C-u - C-x ;' (`kill-comment') kills the comment on the current
5197 line, if there is one. The indentation before the start of the comment
5198 is killed as well. If there does not appear to be a comment in the
5199 line, nothing happens. To reinsert the comment on another line, move
5200 to the end of that line, type first `C-y', and then `M-;' to realign
5201 the comment. Note that `C-u - C-x ;' is not a distinct key; it is `C-x
5202 ;' (`set-comment-column') with a negative argument. That command is
5203 programmed to call `kill-comment' when called with a negative argument.
5204 However, `kill-comment' is a valid command which you could bind
5205 directly to a key if you wanted to.
5207 Multiple Lines of Comments
5208 --------------------------
5210 If you are typing a comment and want to continue it on another line,
5211 use the command `Meta-<LFD>' (`indent-new-comment-line'), which
5212 terminates the comment you are typing, creates a new blank line
5213 afterward, and begins a new comment indented under the old one. If
5214 Auto Fill mode is on and you go past the fill column while typing, the
5215 comment is continued in just this fashion. If point is not at the end
5216 of the line when you type `M-<LFD>', the text on the rest of the line
5217 becomes part of the new comment line.
5219 Options Controlling Comments
5220 ----------------------------
5222 The comment column is stored in the variable `comment-column'. You can
5223 explicitly set it to a number. Alternatively, the command `C-x ;'
5224 (`set-comment-column') sets the comment column to the column point is
5225 at. `C-u C-x ;' sets the comment column to match the last comment
5226 before point in the buffer, and then calls `Meta-;' to align the
5227 current line's comment under the previous one. Note that `C-u - C-x ;'
5228 runs the function `kill-comment' as described above.
5230 `comment-column' is a per-buffer variable; altering the variable
5231 affects only the current buffer. You can also change the default value.
5232 *Note Locals::. Many major modes initialize this variable for the
5235 The comment commands recognize comments based on the regular
5236 expression that is the value of the variable `comment-start-skip'.
5237 This regexp should not match the null string. It may match more than
5238 the comment starting delimiter in the strictest sense of the word; for
5239 example, in C mode the value of the variable is `"/\\*+ *"', which
5240 matches extra stars and spaces after the `/*' itself. (Note that `\\'
5241 is needed in Lisp syntax to include a `\' in the string, which is needed
5242 to deny the first star its special meaning in regexp syntax. *Note
5245 When a comment command makes a new comment, it inserts the value of
5246 `comment-start' to begin it. The value of `comment-end' is inserted
5247 after point and will follow the text you will insert into the comment.
5248 In C mode, `comment-start' has the value `"/* "' and `comment-end' has
5251 `comment-multi-line' controls how `M-<LFD>'
5252 (`indent-new-comment-line') behaves when used inside a comment. If
5253 `comment-multi-line' is `nil', as it normally is, then `M-<LFD>'
5254 terminates the comment on the starting line and starts a new comment on
5255 the new following line. If `comment-multi-line' is not `nil', then
5256 `M-<LFD>' sets up the new following line as part of the same comment
5257 that was found on the starting line. This is done by not inserting a
5258 terminator on the old line and not inserting a starter on the new line.
5259 In languages where multi-line comments are legal, the value you choose
5260 for this variable is a matter of taste.
5262 The variable `comment-indent-hook' should contain a function that is
5263 called to compute the indentation for a newly inserted comment or for
5264 aligning an existing comment. Major modes set this variable
5265 differently. The function is called with no arguments, but with point
5266 at the beginning of the comment, or at the end of a line if a new
5267 comment is to be inserted. The function should return the column in
5268 which the comment ought to start. For example, in Lisp mode, the
5269 indent hook function bases its decision on the number of semicolons
5270 that begin an existing comment and on the code in the preceding lines.
5273 File: xemacs.info, Node: Balanced Editing, Next: Lisp Completion, Prev: Comments, Up: Programs
5275 Editing Without Unbalanced Parentheses
5276 ======================================
5279 Put parentheses around next sexp(s) (`insert-parentheses').
5282 Move past next close parenthesis and re-indent
5283 (`move-over-close-and-reindent').
5285 The commands `M-(' (`insert-parentheses') and `M-)'
5286 (`move-over-close-and-reindent') are designed to facilitate a style of
5287 editing which keeps parentheses balanced at all times. `M-(' inserts a
5288 pair of parentheses, either together as in `()', or, if given an
5289 argument, around the next several sexps, and leaves point after the open
5290 parenthesis. Instead of typing `( F O O )', you can type `M-( F O O',
5291 which has the same effect except for leaving the cursor before the
5292 close parenthesis. You can then type `M-)', which moves past the close
5293 parenthesis, deletes any indentation preceding it (in this example
5294 there is none), and indents with <LFD> after it.
5297 File: xemacs.info, Node: Lisp Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs
5299 Completion for Lisp Symbols
5300 ===========================
5302 Completion usually happens in the minibuffer. An exception is
5303 completion for Lisp symbol names, which is available in all buffers.
5305 The command `M-<TAB>' (`lisp-complete-symbol') takes the partial
5306 Lisp symbol before point to be an abbreviation, and compares it against
5307 all non-trivial Lisp symbols currently known to Emacs. Any additional
5308 characters that they all have in common are inserted at point.
5309 Non-trivial symbols are those that have function definitions, values, or
5312 If there is an open-parenthesis immediately before the beginning of
5313 the partial symbol, only symbols with function definitions are
5314 considered as completions.
5316 If the partial name in the buffer has more than one possible
5317 completion and they have no additional characters in common, a list of
5318 all possible completions is displayed in another window.
5321 File: xemacs.info, Node: Documentation, Next: Change Log, Prev: Lisp Completion, Up: Programs
5323 Documentation Commands
5324 ======================
5326 As you edit Lisp code to be run in Emacs, you can use the commands `C-h
5327 f' (`describe-function') and `C-h v' (`describe-variable') to print
5328 documentation of functions and variables you want to call. These
5329 commands use the minibuffer to read the name of a function or variable
5330 to document, and display the documentation in a window.
5332 For extra convenience, these commands provide default arguments
5333 based on the code in the neighborhood of point. `C-h f' sets the
5334 default to the function called in the innermost list containing point.
5335 `C-h v' uses the symbol name around or adjacent to point as its default.
5337 The `M-x manual-entry' command gives you access to documentation on
5338 Unix commands, system calls, and libraries. The command reads a topic
5339 as an argument, and displays the Unix manual page for that topic.
5340 `manual-entry' always searches all 8 sections of the manual and
5341 concatenates all the entries it finds. For example, the topic
5342 `termcap' finds the description of the termcap library from section 3,
5343 followed by the description of the termcap data base from section 5.
5346 File: xemacs.info, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs
5351 The Emacs command `M-x add-change-log-entry' helps you keep a record of
5352 when and why you have changed a program. It assumes that you have a
5353 file in which you write a chronological sequence of entries describing
5354 individual changes. The default is to store the change entries in a
5355 file called `ChangeLog' in the same directory as the file you are
5356 editing. The same `ChangeLog' file therefore records changes for all
5357 the files in a directory.
5359 A change log entry starts with a header line that contains your name
5360 and the current date. Except for these header lines, every line in the
5361 change log starts with a tab. One entry can describe several changes;
5362 each change starts with a line starting with a tab and a star. `M-x
5363 add-change-log-entry' visits the change log file and creates a new entry
5364 unless the most recent entry is for today's date and your name. In
5365 either case, it adds a new line to start the description of another
5366 change just after the header line of the entry. When `M-x
5367 add-change-log-entry' is finished, all is prepared for you to edit in
5368 the description of what you changed and how. You must then save the
5369 change log file yourself.
5371 The change log file is always visited in Indented Text mode, which
5372 means that <LFD> and auto-filling indent each new line like the previous
5373 line. This is convenient for entering the contents of an entry, which
5374 must be indented. *Note Text Mode::.
5376 Here is an example of the formatting conventions used in the change
5379 Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep)
5381 * xdisp.c (try_window_id):
5382 If C-k is done at end of next-to-last line,
5383 this fn updates window_end_vpos and cannot leave
5384 window_end_pos nonnegative (it is zero, in fact).
5385 If display is preempted before lines are output,
5386 this is inconsistent. Fix by setting
5387 blank_end_of_window to nonzero.
5389 Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep)
5391 * cmds.c (Fnewline):
5392 Call the auto fill hook if appropriate.
5394 * xdisp.c (try_window_id):
5395 If point is found by compute_motion after xp, record that
5396 permanently. If display_text_line sets point position wrong
5397 (case where line is killed, point is at eob and that line is
5398 not displayed), set it again in final compute_motion.
5401 File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs
5406 A "tags table" is a description of how a multi-file program is broken
5407 up into files. It lists the names of the component files and the names
5408 and positions of the functions (or other named subunits) in each file.
5409 Grouping the related files makes it possible to search or replace
5410 through all the files with one command. Recording the function names
5411 and positions makes possible the `M-.' command which finds the
5412 definition of a function by looking up which of the files it is in.
5414 Tags tables are stored in files called "tags table files". The
5415 conventional name for a tags table file is `TAGS'.
5417 Each entry in the tags table records the name of one tag, the name
5418 of the file that the tag is defined in (implicitly), and the position
5419 in that file of the tag's definition.
5421 Just what names from the described files are recorded in the tags
5422 table depends on the programming language of the described file. They
5423 normally include all functions and subroutines, and may also include
5424 global variables, data types, and anything else convenient. Each name
5425 recorded is called a "tag".
5427 The Ebrowse is a separate facility tailored for C++, with tags and a
5428 class browser. *Note Top: (ebrowse)Top.
5432 * Tag Syntax:: Tag syntax for various types of code and text files.
5433 * Create Tags Table:: Creating a tags table with `etags'.
5434 * Etags Regexps:: Create arbitrary tags using regular expressions.
5435 * Select Tags Table:: How to visit a tags table.
5436 * Find Tag:: Commands to find the definition of a specific tag.
5437 * Tags Search:: Using a tags table for searching and replacing.
5438 * List Tags:: Listing and finding tags defined in a file.
5441 File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Up: Tags
5443 Source File Tag Syntax
5444 ----------------------
5446 Here is how tag syntax is defined for the most popular languages:
5448 * In C code, any C function or typedef is a tag, and so are
5449 definitions of `struct', `union' and `enum'. You can tag function
5450 declarations and external variables in addition to function
5451 definitions by giving the `--declarations' option to `etags'.
5452 `#define' macro definitions and `enum' constants are also tags,
5453 unless you specify `--no-defines' when making the tags table.
5454 Similarly, global variables are tags, unless you specify
5455 `--no-globals'. Use of `--no-globals' and `--no-defines' can make
5456 the tags table file much smaller.
5458 * In C++ code, in addition to all the tag constructs of C code,
5459 member functions are also recognized, and optionally member
5460 variables if you use the `--members' option. Tags for variables
5461 and functions in classes are named `CLASS::VARIABLE' and
5462 `CLASS::FUNCTION'. `operator' functions tags are named, for
5463 example `operator+'.
5465 * In Java code, tags include all the constructs recognized in C++,
5466 plus the `interface', `extends' and `implements' constructs. Tags
5467 for variables and functions in classes are named `CLASS.VARIABLE'
5468 and `CLASS.FUNCTION'.
5470 * In LaTeX text, the argument of any of the commands `\chapter',
5471 `\section', `\subsection', `\subsubsection', `\eqno', `\label',
5472 `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
5475 Other commands can make tags as well, if you specify them in the
5476 environment variable `TEXTAGS' before invoking `etags'. The value
5477 of this environment variable should be a colon-separated list of
5478 command names. For example,
5480 TEXTAGS="def:newcommand:newenvironment"
5483 specifies (using Bourne shell syntax) that the commands `\def',
5484 `\newcommand' and `\newenvironment' also define tags.
5486 * In Lisp code, any function defined with `defun', any variable
5487 defined with `defvar' or `defconst', and in general the first
5488 argument of any expression that starts with `(def' in column zero,
5491 * In Scheme code, tags include anything defined with `def' or with a
5492 construct whose name starts with `def'. They also include
5493 variables set with `set!' at top level in the file.
5495 Several other languages are also supported:
5497 * In Ada code, functions, procedures, packages, tasks, and types are
5498 tags. Use the `--packages-only' option to create tags for
5501 With Ada, it is possible to have the same name used for different
5502 entity kinds (e.g. the same name for a procedure and a function).
5503 Also, for things like packages, procedures and functions, there is
5504 the spec (i.e. the interface) and the body (i.e. the
5505 implementation). To facilitate the choice to the user, a tag
5506 value is appended with a qualifier:
5526 So, as an example, `M-x find-tag bidule/b' will go directly to the
5527 body of the package BIDULE while `M-x find-tag bidule' will just
5528 search for any tag BIDULE.
5530 * In assembler code, labels appearing at the beginning of a line,
5531 followed by a colon, are tags.
5533 * In Bison or Yacc input files, each rule defines as a tag the
5534 nonterminal it constructs. The portions of the file that contain
5535 C code are parsed as C code.
5537 * In Cobol code, tags are paragraph names; that is, any word
5538 starting in column 8 and followed by a period.
5540 * In Erlang code, the tags are the functions, records, and macros
5541 defined in the file.
5543 * In Fortran code, functions, subroutines and blockdata are tags.
5545 * In makefiles, targets are tags.
5547 * In Objective C code, tags include Objective C definitions for
5548 classes, class categories, methods, and protocols.
5550 * In Pascal code, the tags are the functions and procedures defined
5553 * In Perl code, the tags are the procedures defined by the `sub',
5554 `my' and `local' keywords. Use `--globals' if you want to tag
5557 * In PostScript code, the tags are the functions.
5559 * In Prolog code, a tag name appears at the left margin.
5561 * In Python code, `def' or `class' at the beginning of a line
5564 You can also generate tags based on regexp matching (*note Etags
5565 Regexps::) to handle other formats and languages.
5568 File: xemacs.info, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags
5570 Creating Tags Tables
5571 --------------------
5573 The `etags' program is used to create a tags table file. It knows the
5574 syntax of several languages, as described in *Note Tag Syntax::. Here
5575 is how to run `etags':
5579 The `etags' program reads the specified files, and writes a tags table
5580 named `TAGS' in the current working directory. You can intermix
5581 compressed and plain text source file names. `etags' knows about the
5582 most common compression formats, and does the right thing. So you can
5583 compress all your source files and have `etags' look for compressed
5584 versions of its file name arguments, if it does not find uncompressed
5585 versions. Under MS-DOS, `etags' also looks for file names like
5586 `mycode.cgz' if it is given `mycode.c' on the command line and
5587 `mycode.c' does not exist.
5589 `etags' recognizes the language used in an input file based on its
5590 file name and contents. You can specify the language with the
5591 `--language=NAME' option, described below.
5593 If the tags table data become outdated due to changes in the files
5594 described in the table, the way to update the tags table is the same
5595 way it was made in the first place. It is not necessary to do this
5598 If the tags table fails to record a tag, or records it for the wrong
5599 file, then Emacs cannot possibly find its definition. However, if the
5600 position recorded in the tags table becomes a little bit wrong (due to
5601 some editing in the file that the tag definition is in), the only
5602 consequence is a slight delay in finding the tag. Even if the stored
5603 position is very wrong, Emacs will still find the tag, but it must
5604 search the entire file for it.
5606 So you should update a tags table when you define new tags that you
5607 want to have listed, or when you move tag definitions from one file to
5608 another, or when changes become substantial. Normally there is no need
5609 to update the tags table after each edit, or even every day.
5611 One tags table can effectively include another. Specify the included
5612 tags file name with the `--include=FILE' option when creating the file
5613 that is to include it. The latter file then acts as if it contained
5614 all the files specified in the included file, as well as the files it
5617 If you specify the source files with relative file names when you run
5618 `etags', the tags file will contain file names relative to the
5619 directory where the tags file was initially written. This way, you can
5620 move an entire directory tree containing both the tags file and the
5621 source files, and the tags file will still refer correctly to the source
5624 If you specify absolute file names as arguments to `etags', then the
5625 tags file will contain absolute file names. This way, the tags file
5626 will still refer to the same files even if you move it, as long as the
5627 source files remain in the same place. Absolute file names start with
5628 `/', or with `DEVICE:/' on MS-DOS and MS-Windows.
5630 When you want to make a tags table from a great number of files, you
5631 may have problems listing them on the command line, because some systems
5632 have a limit on its length. The simplest way to circumvent this limit
5633 is to tell `etags' to read the file names from its standard input, by
5634 typing a dash in place of the file names, like this:
5636 find . -name "*.[chCH]" -print | etags -
5638 Use the option `--language=NAME' to specify the language explicitly.
5639 You can intermix these options with file names; each one applies to
5640 the file names that follow it. Specify `--language=auto' to tell
5641 `etags' to resume guessing the language from the file names and file
5642 contents. Specify `--language=none' to turn off language-specific
5643 processing entirely; then `etags' recognizes tags by regexp matching
5644 alone (*note Etags Regexps::).
5646 `etags --help' prints the list of the languages `etags' knows, and
5647 the file name rules for guessing the language. It also prints a list of
5648 all the available `etags' options, together with a short explanation.
5651 File: xemacs.info, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags
5656 The `--regex' option provides a general way of recognizing tags based
5657 on regexp matching. You can freely intermix it with file names. Each
5658 `--regex' option adds to the preceding ones, and applies only to the
5659 following files. The syntax is:
5661 --regex=/TAGREGEXP[/NAMEREGEXP]/
5663 where TAGREGEXP is used to match the lines to tag. It is always
5664 anchored, that is, it behaves as if preceded by `^'. If you want to
5665 account for indentation, just match any initial number of blanks by
5666 beginning your regular expression with `[ \t]*'. In the regular
5667 expressions, `\' quotes the next character, and `\t' stands for the tab
5668 character. Note that `etags' does not handle the other C escape
5669 sequences for special characters.
5671 The syntax of regular expressions in `etags' is the same as in
5672 Emacs, augmented with the "interval operator", which works as in `grep'
5673 and `ed'. The syntax of an interval operator is `\{M,N\}', and its
5674 meaning is to match the preceding expression at least M times and up to
5677 You should not match more characters with TAGREGEXP than that needed
5678 to recognize what you want to tag. If the match is such that more
5679 characters than needed are unavoidably matched by TAGREGEXP (as will
5680 usually be the case), you should add a NAMEREGEXP, to pick out just the
5681 tag. This will enable Emacs to find tags more accurately and to do
5682 completion on tag names more reliably. You can find some examples
5685 The option `--ignore-case-regex' (or `-c') is like `--regex', except
5686 that the regular expression provided will be matched without regard to
5687 case, which is appropriate for various programming languages.
5689 The `-R' option deletes all the regexps defined with `--regex'
5690 options. It applies to the file names following it, as you can see
5691 from the following example:
5693 etags --regex=/REG1/ voo.doo --regex=/REG2/ \
5694 bar.ber -R --lang=lisp los.er
5696 Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
5697 according to their contents. `etags' also uses REG1 to recognize
5698 additional tags in `voo.doo', and both REG1 and REG2 to recognize
5699 additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no
5700 regexp matching, to recognize tags in `los.er'.
5702 A regular expression can be bound to a given language, by prepending
5703 it with `{lang}'. When you do this, `etags' will use the regular
5704 expression only for files of that language. `etags --help' prints the
5705 list of languages recognised by `etags'. The following example tags
5706 the `DEFVAR' macros in the Emacs source files. `etags' applies this
5707 regular expression to C files only:
5709 --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
5711 This feature is particularly useful when storing a list of regular
5712 expressions in a file. The following option syntax instructs `etags'
5713 to read two files of regular expressions. The regular expressions
5714 contained in the second file are matched without regard to case.
5716 --regex=@first-file --ignore-case-regex=@second-file
5718 A regex file contains one regular expressions per line. Empty lines,
5719 and lines beginning with space or tab are ignored. When the first
5720 character in a line is `@', `etags' assumes that the rest of the line
5721 is the name of a file of regular expressions. This means that such
5722 files can be nested. All the other lines are taken to be regular
5723 expressions. For example, one can create a file called `emacs.tags'
5724 with the following contents (the first line in the file is a comment):
5726 -- This is for GNU Emacs source files
5727 {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
5729 and then use it like this:
5731 etags --regex=@emacs.tags *.[ch] */*.[ch]
5733 Here are some more examples. The regexps are quoted to protect them
5734 from shell interpretation.
5738 etags --language=none \
5739 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
5740 --regex='/###key \(.*\)/\1/' \
5741 --regex='/[ \t]*global[ \t].*/' \
5744 Note that tags are not generated for scripts so that you have to
5745 add a line by yourself of the form `###key <script-name>' if you
5750 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
5755 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
5756 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
5757 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
5760 File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags
5762 Selecting a Tags Table
5763 ----------------------
5765 At any time Emacs has one "selected" tags table, and all the commands
5766 for working with tags tables use the selected one. To select a tags
5767 table, use the variable `tag-table-alist'.
5769 The value of `tag-table-alist' is a list that determines which
5770 `TAGS' files should be active for a given buffer. This is not really
5771 an association list, in that all elements are checked. The car of each
5772 element of this list is a pattern against which the buffers file name
5773 is compared; if it matches, then the cdr of the list should be the name
5774 of the tags table to use. If more than one element of this list
5775 matches the buffers file name, all of the associated tags tables are
5776 used. Earlier ones are searched first.
5778 If the car of elements of this list are strings, they are treated as
5779 regular-expressions against which the file is compared (like the
5780 `auto-mode-alist'). If they are not strings, they are evaluated. If
5781 they evaluate to non-`nil', the current buffer is considered to match.
5783 If the cdr of the elements of this list are strings, they are
5784 assumed to name a tags file. If they name a directory, the string
5785 `tags' is appended to them to get the file name. If they are not
5786 strings, they are evaluated and must return an appropriate string.
5790 (setq tag-table-alist
5791 '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
5792 ("\\.el$" . "/usr/local/emacs/src/")
5793 ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
5794 ("" . "/usr/local/emacs/src/")
5797 The example defines the tags table alist in the following way:
5799 * Anything in the directory `/usr/src/public/perl/' should use the
5800 `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'.
5802 * Files ending in `.el' should use the `TAGS' file
5803 `/usr/local/emacs/src/TAGS'.
5805 * Anything in or below the directory `/jbw/gnu/' should use the
5806 `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'.
5808 If you had a file called `/usr/jbw/foo.el', it would use both `TAGS'
5810 `/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in
5811 that order), because it matches both patterns.
5813 If the buffer-local variable `buffer-tag-table' is set, it names a
5814 tags table that is searched before all others when `find-tag' is
5815 executed from this buffer.
5817 If there is a file called `TAGS' in the same directory as the file
5818 in question, then that tags file will always be used as well (after the
5819 `buffer-tag-table' but before the tables specified by this list).
5821 If the variable `tags-file-name' is set, the `TAGS' file it names
5822 will apply to all buffers (for backwards compatibility.) It is searched
5825 If the value of the variable `tags-always-build-completion-table' is
5826 `t', the tags file will always be added to the completion table without
5827 asking first, regardless of the size of the tags file.
5829 The function `M-x visit-tags-table', is largely made obsolete by the
5830 variable `tag-table-alist', tells tags commands to use the tags table
5831 file FILE first. The FILE should be the name of a file created with
5832 the `etags' program. A directory name is also acceptable; it means the
5833 file `TAGS' in that directory. The function only stores the file name
5834 you provide in the variable `tags-file-name'. Emacs does not actually
5835 read in the tags table contents until you try to use them. You can set
5836 the variable explicitly instead of using `visit-tags-table'. The value
5837 of the variable `tags-file-name' is the name of the tags table used by
5838 all buffers. This is for backward compatibility, and is largely
5839 supplanted by the variable `tag-table-alist'.
5842 File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags
5847 The most important thing that a tags table enables you to do is to find
5848 the definition of a specific tag.
5850 `M-. TAG &OPTIONAL OTHER-WINDOW'
5851 Find first definition of TAG (`find-tag').
5854 Find next alternate definition of last tag specified.
5857 Find first definition of TAG, but display it in another window
5858 (`find-tag-other-window').
5860 `M-.' (`find-tag') is the command to find the definition of a
5861 specified tag. It searches through the tags table for that tag, as a
5862 string, then uses the tags table information to determine the file in
5863 which the definition is used and the approximate character position of
5864 the definition in the file. Then `find-tag' visits the file, moves
5865 point to the approximate character position, and starts searching
5866 ever-increasing distances away for the text that should appear at the
5867 beginning of the definition.
5869 If an empty argument is given (by typing <RET>), the sexp in the
5870 buffer before or around point is used as the name of the tag to find.
5871 *Note Lists::, for information on sexps.
5873 The argument to `find-tag' need not be the whole tag name; it can be
5874 a substring of a tag name. However, there can be many tag names
5875 containing the substring you specify. Since `find-tag' works by
5876 searching the text of the tags table, it finds the first tag in the
5877 table that the specified substring appears in. To find other tags that
5878 match the substring, give `find-tag' a numeric argument, as in `C-u
5879 M-.'. This does not read a tag name, but continues searching the tag
5880 table's text for another tag containing the same substring last used.
5881 If your keyboard has a real <META> key, `M-0 M-.' is an easier
5882 alternative to `C-u M-.'.
5884 If the optional second argument OTHER-WINDOW is non-`nil', it uses
5885 another window to display the tag. Multiple active tags tables and
5886 completion are supported.
5888 Variables of note include the following:
5891 Controls which tables apply to which buffers.
5894 Stores a default tags table.
5896 `tags-build-completion-table'
5897 Controls completion behavior.
5900 Specifies a buffer-local table.
5902 `make-tags-files-invisible'
5903 Sets whether tags tables should be very hidden.
5905 `tag-mark-stack-max'
5906 Specifies how many tags-based hops to remember.
5908 Like most commands that can switch buffers, `find-tag' has another
5909 similar command that displays the new buffer in another window. `C-x 4
5910 .' invokes the function `find-tag-other-window'. (This key sequence
5911 ends with a period.)
5913 Emacs comes with a tags table file `TAGS' (in the directory
5914 containing Lisp libraries) that includes all the Lisp libraries and all
5915 the C sources of Emacs. By specifying this file with `visit-tags-table'
5916 and then using `M-.' you can quickly look at the source of any Emacs
5920 File: xemacs.info, Node: Tags Search, Next: List Tags, Prev: Find Tag, Up: Tags
5922 Searching and Replacing with Tags Tables
5923 ----------------------------------------
5925 The commands in this section visit and search all the files listed in
5926 the selected tags table, one by one. For these commands, the tags
5927 table serves only to specify a sequence of files to search. A related
5928 command is `M-x grep' (*note Compilation::).
5930 `M-x tags-search <RET> REGEXP <RET>'
5931 Search for REGEXP through the files in the selected tags table.
5933 `M-x tags-query-replace <RET> REGEXP <RET> REPLACEMENT <RET>'
5934 Perform a `query-replace-regexp' on each file in the selected tags
5938 Restart one of the commands above, from the current location of
5939 point (`tags-loop-continue').
5941 `M-x tags-search' reads a regexp using the minibuffer, then searches
5942 for matches in all the files in the selected tags table, one file at a
5943 time. It displays the name of the file being searched so you can
5944 follow its progress. As soon as it finds an occurrence, `tags-search'
5947 Having found one match, you probably want to find all the rest. To
5948 find one more match, type `M-,' (`tags-loop-continue') to resume the
5949 `tags-search'. This searches the rest of the current buffer, followed
5950 by the remaining files of the tags table.
5952 `M-x tags-query-replace' performs a single `query-replace-regexp'
5953 through all the files in the tags table. It reads a regexp to search
5954 for and a string to replace with, just like ordinary `M-x
5955 query-replace-regexp'. It searches much like `M-x tags-search', but
5956 repeatedly, processing matches according to your input. *Note
5957 Replace::, for more information on query replace.
5959 It is possible to get through all the files in the tags table with a
5960 single invocation of `M-x tags-query-replace'. But often it is useful
5961 to exit temporarily, which you can do with any input event that has no
5962 special query replace meaning. You can resume the query replace
5963 subsequently by typing `M-,'; this command resumes the last tags search
5964 or replace command that you did.
5966 The commands in this section carry out much broader searches than the
5967 `find-tag' family. The `find-tag' commands search only for definitions
5968 of tags that match your substring or regexp. The commands
5969 `tags-search' and `tags-query-replace' find every occurrence of the
5970 regexp, as ordinary search commands and replace commands do in the
5973 These commands create buffers only temporarily for the files that
5974 they have to search (those which are not already visited in Emacs
5975 buffers). Buffers in which no match is found are quickly killed; the
5976 others continue to exist.
5978 It may have struck you that `tags-search' is a lot like `grep'. You
5979 can also run `grep' itself as an inferior of Emacs and have Emacs show
5980 you the matching lines one by one. This works much like running a
5981 compilation; finding the source locations of the `grep' matches works
5982 like finding the compilation errors. *Note Compilation::.
5984 If you wish to process all the files in a selected tags table, but
5985 `M-x tags-search' and `M-x tags-query-replace' are not giving you the
5986 desired result, you can use `M-x next-file'.
5989 With a numeric argument, regardless of its value, visit the first
5990 file in the tags table and prepare to advance sequentially by
5994 Visit the next file in the selected tags table.
5997 File: xemacs.info, Node: List Tags, Prev: Tags Search, Up: Tags
5999 Tags Table Inquiries
6000 --------------------
6003 Display a list of the tags defined in a specific program file.
6006 Display a list of all tags matching a specified regexp.
6008 `M-x list-tags' reads the name of one of the files described by the
6009 selected tags table, and displays a list of all the tags defined in that
6010 file. The "file name" argument is really just a string to compare
6011 against the names recorded in the tags table; it is read as a string
6012 rather than a file name. Therefore, completion and defaulting are not
6013 available, and you must enter the string the same way it appears in the
6014 tag table. Do not include a directory as part of the file name unless
6015 the file name recorded in the tags table contains that directory.
6017 `M-x tags-apropos' is like `apropos' for tags. It reads a regexp,
6018 then finds all the tags in the selected tags table whose entries match
6019 that regexp, and displays the tag names found.
6022 File: xemacs.info, Node: Fortran, Next: Asm Mode, Prev: Tags, Up: Programs
6027 Fortran mode provides special motion commands for Fortran statements and
6028 subprograms, and indentation commands that understand Fortran
6029 conventions of nesting, line numbers, and continuation statements.
6031 Special commands for comments are provided because Fortran comments
6032 are unlike those of other languages.
6034 Built-in abbrevs optionally save typing when you insert Fortran
6037 Use `M-x fortran-mode' to switch to this major mode. Doing so calls
6038 the value of `fortran-mode-hook' as a function of no arguments if that
6039 variable has a non-`nil' value.
6043 * Motion: Fortran Motion. Moving point by statements or subprograms.
6044 * Indent: Fortran Indent. Indentation commands for Fortran.
6045 * Comments: Fortran Comments. Inserting and aligning comments.
6046 * Columns: Fortran Columns. Measuring columns for valid Fortran.
6047 * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
6049 Fortran mode was contributed by Michael Prange.
6052 File: xemacs.info, Node: Fortran Motion, Next: Fortran Indent, Prev: Fortran, Up: Fortran
6057 Fortran mode provides special commands to move by subprograms (functions
6058 and subroutines) and by statements. There is also a command to put the
6059 region around one subprogram, which is convenient for killing it or
6063 Move to beginning of subprogram
6064 (`beginning-of-fortran-subprogram').
6067 Move to end of subprogram (`end-of-fortran-subprogram').
6070 Put point at beginning of subprogram and mark at end
6071 (`mark-fortran-subprogram').
6074 Move to beginning of current or next statement (`fortran-next-
6078 Move to beginning of current or previous statement (`fortran-
6079 previous-statement').
6082 File: xemacs.info, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran
6087 Special commands and features are available for indenting Fortran code.
6088 They make sure various syntactic entities (line numbers, comment line
6089 indicators, and continuation line flags) appear in the columns that are
6090 required for standard Fortran.
6094 * Commands: ForIndent Commands. Commands for indenting Fortran.
6095 * Numbers: ForIndent Num. How line numbers auto-indent.
6096 * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
6097 * Vars: ForIndent Vars. Variables controlling Fortran indent style.
6100 File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent
6102 Fortran Indentation Commands
6103 ............................
6106 Indent the current line (`fortran-indent-line').
6109 Break the current line and set up a continuation line.
6112 Indent all the lines of the subprogram point is in
6113 (`fortran-indent-subprogram').
6115 <TAB> is redefined by Fortran mode to reindent the current line for
6116 Fortran (`fortran-indent-line'). Line numbers and continuation markers
6117 are indented to their required columns, and the body of the statement
6118 is independently indented, based on its nesting in the program.
6120 The key `C-M-q' is redefined as `fortran-indent-subprogram', a
6121 command that reindents all the lines of the Fortran subprogram
6122 (function or subroutine) containing point.
6124 The key `M-<LFD>' is redefined as `fortran-split-line', a command to
6125 split a line in the appropriate fashion for Fortran. In a non-comment
6126 line, the second half becomes a continuation line and is indented
6127 accordingly. In a comment line, both halves become separate comment
6131 File: xemacs.info, Node: ForIndent Num, Next: ForIndent Conv, Prev: ForIndent Commands, Up: Fortran Indent
6133 Line Numbers and Continuation
6134 .............................
6136 If a number is the first non-whitespace in the line, it is assumed to be
6137 a line number and is moved to columns 0 through 4. (Columns are always
6138 counted from 0 in XEmacs.) If the text on the line starts with the
6139 conventional Fortran continuation marker `$', it is moved to column 5.
6140 If the text begins with any non whitespace character in column 5, it is
6141 assumed to be an unconventional continuation marker and remains in
6144 Line numbers of four digits or less are normally indented one space.
6145 This amount is controlled by the variable `fortran-line-number-indent',
6146 which is the maximum indentation a line number can have. Line numbers
6147 are indented to right-justify them to end in column 4 unless that would
6148 require more than the maximum indentation. The default value of the
6151 Simply inserting a line number is enough to indent it according to
6152 these rules. As each digit is inserted, the indentation is recomputed.
6153 To turn off this feature, set the variable
6154 `fortran-electric-line-number' to `nil'. Then inserting line numbers
6155 is like inserting anything else.
6158 File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent
6160 Syntactic Conventions
6161 .....................
6163 Fortran mode assumes that you follow certain conventions that simplify
6164 the task of understanding a Fortran program well enough to indent it
6167 * Two nested `do' loops never share a `continue' statement.
6169 * The same character appears in column 5 of all continuation lines.
6170 It is the value of the variable `fortran-continuation-char'. By
6171 default, this character is `$'.
6173 If you fail to follow these conventions, the indentation commands may
6174 indent some lines unaesthetically. However, a correct Fortran program
6175 will retain its meaning when reindented even if the conventions are not
6179 File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent
6181 Variables for Fortran Indentation
6182 .................................
6184 Several additional variables control how Fortran indentation works.
6187 Extra indentation within each level of `do' statement (the default
6191 Extra indentation within each level of `if' statement (the default
6194 `fortran-continuation-indent'
6195 Extra indentation for bodies of continuation lines (the default is
6198 `fortran-check-all-num-for-matching-do'
6199 If this is `nil', indentation assumes that each `do' statement
6200 ends on a `continue' statement. Therefore, when computing
6201 indentation for a statement other than `continue', it can save
6202 time by not checking for a `do' statement ending there. If this
6203 is non-`nil', indenting any numbered statement must check for a
6204 `do' that ends there. The default is `nil'.
6206 `fortran-minimum-statement-indent'
6207 Minimum indentation for Fortran statements. For standard Fortran,
6208 this is 6. Statement bodies are always indented at least this
6212 File: xemacs.info, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran
6217 The usual Emacs comment commands assume that a comment can follow a line
6218 of code. In Fortran, the standard comment syntax requires an entire
6219 line to be just a comment. Therefore, Fortran mode replaces the
6220 standard Emacs comment commands and defines some new variables.
6222 Fortran mode can also handle a non-standard comment syntax where
6223 comments start with `!' and can follow other text. Because only some
6224 Fortran compilers accept this syntax, Fortran mode will not insert such
6225 comments unless you have specified to do so in advance by setting the
6226 variable `comment-start' to `"!"' (*note Variables::).
6229 Align comment or insert new comment (`fortran-comment-indent').
6232 Applies to nonstandard `!' comments only.
6235 Turn all lines of the region into comments, or (with arg) turn
6236 them back into real code (`fortran-comment-region').
6238 `M-;' in Fortran mode is redefined as the command
6239 `fortran-comment-indent'. Like the usual `M-;' command, it recognizes
6240 an existing comment and aligns its text appropriately. If there is no
6241 existing comment, a comment is inserted and aligned.
6243 Inserting and aligning comments is not the same in Fortran mode as in
6244 other modes. When a new comment must be inserted, a full-line comment
6245 is inserted if the current line is blank. On a non-blank line, a
6246 non-standard `!' comment is inserted if you previously specified you
6247 wanted to use them. Otherwise a full-line comment is inserted on a new
6248 line before the current line.
6250 Non-standard `!' comments are aligned like comments in other
6251 languages, but full-line comments are aligned differently. In a
6252 standard full-line comment, the comment delimiter itself must always
6253 appear in column zero. What can be aligned is the text within the
6254 comment. You can choose from three styles of alignment by setting the
6255 variable `fortran-comment-indent-style' to one of these values:
6258 The text is aligned at a fixed column, which is the value of
6259 `fortran-comment-line-column'. This is the default.
6262 The text is aligned as if it were a line of code, but with an
6263 additional `fortran-comment-line-column' columns of indentation.
6266 Text in full-line columns is not moved automatically.
6268 You can also specify the character to be used to indent within
6269 full-line comments by setting the variable `fortran-comment-indent-char'
6270 to the character you want to use.
6272 Fortran mode introduces two variables `comment-line-start' and
6273 `comment-line-start-skip', which do for full-line comments what
6274 `comment-start' and `comment-start-skip' do for ordinary text-following
6275 comments. Normally these are set properly by Fortran mode, so you do
6276 not need to change them.
6278 The normal Emacs comment command `C-x ;' has not been redefined. It
6279 can therefore be used if you use `!' comments, but is useless in
6280 Fortran mode otherwise.
6282 The command `C-c ;' (`fortran-comment-region') turns all the lines
6283 of the region into comments by inserting the string `C$$$' at the front
6284 of each one. With a numeric arg, the region is turned back into live
6285 code by deleting `C$$$' from the front of each line. You can control
6286 the string used for the comments by setting the variable
6287 `fortran-comment-region'. Note that here we have an example of a
6288 command and a variable with the same name; the two uses of the name
6289 never conflict because in Lisp and in Emacs it is always clear from the
6290 context which one is referred to.
6293 File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran
6299 Displays a "column ruler" momentarily above the current line
6300 (`fortran-column-ruler').
6303 Splits the current window horizontally so that it is 72 columns
6304 wide. This may help you avoid going over that limit
6305 (`fortran-window-create').
6307 The command `C-c C-r' (`fortran-column-ruler') shows a column ruler
6308 above the current line. The comment ruler consists of two lines of
6309 text that show you the locations of columns with special significance
6310 in Fortran programs. Square brackets show the limits of the columns for
6311 line numbers, and curly brackets show the limits of the columns for the
6312 statement body. Column numbers appear above them.
6314 Note that the column numbers count from zero, as always in XEmacs.
6315 As a result, the numbers may not be those you are familiar with; but the
6316 actual positions in the line are standard Fortran.
6318 The text used to display the column ruler is the value of the
6319 variable `fortran-comment-ruler'. By changing this variable, you can
6322 For even more help, use `C-c C-w' (`fortran-window-create'), a
6323 command which splits the current window horizontally, resulting in a
6324 window 72 columns wide. When you edit in this window, you can
6325 immediately see when a line gets too wide to be correct Fortran.
6328 File: xemacs.info, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran
6330 Fortran Keyword Abbrevs
6331 -----------------------
6333 Fortran mode provides many built-in abbrevs for common keywords and
6334 declarations. These are the same sort of abbrevs that you can define
6335 yourself. To use them, you must turn on Abbrev mode. *note Abbrevs::.
6337 The built-in abbrevs are unusual in one way: they all start with a
6338 semicolon. You cannot normally use semicolon in an abbrev, but Fortran
6339 mode makes this possible by changing the syntax of semicolon to "word
6342 For example, one built-in Fortran abbrev is `;c' for `continue'. If
6343 you insert `;c' and then insert a punctuation character such as a space
6344 or a newline, the `;c' changes automatically to `continue', provided
6345 Abbrev mode is enabled.
6347 Type `;?' or `;C-h' to display a list of all built-in Fortran
6348 abbrevs and what they stand for.
6351 File: xemacs.info, Node: Asm Mode, Prev: Fortran, Up: Programs
6356 Asm mode is a major mode for editing files of assembler code. It
6357 defines these commands:
6363 Insert a newline and then indent using `tab-to-tab-stop'.
6366 Insert a colon and then remove the indentation from before the
6367 label preceding colon. Then do `tab-to-tab-stop'.
6370 Insert or align a comment.
6372 The variable `asm-comment-char' specifies which character starts
6373 comments in assembler syntax.
6376 File: xemacs.info, Node: Running, Next: Abbrevs, Prev: Programs, Up: Top
6378 Compiling and Testing Programs
6379 ******************************
6381 The previous chapter discusses the Emacs commands that are useful for
6382 making changes in programs. This chapter deals with commands that
6383 assist in the larger process of developing and maintaining programs.
6387 * Compilation:: Compiling programs in languages other than Lisp
6389 * Modes: Lisp Modes. Various modes for editing Lisp programs, with
6390 different facilities for running the Lisp programs.
6391 * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
6392 * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
6393 * Debug: Lisp Debug. Debugging Lisp programs running in Emacs.
6394 * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
6395 * External Lisp:: Communicating through Emacs with a separate Lisp.
6398 File: xemacs.info, Node: Compilation, Next: Lisp Modes, Prev: Running, Up: Running
6400 Running "make", or Compilers Generally
6401 ======================================
6403 Emacs can run compilers for non-interactive languages like C and
6404 Fortran as inferior processes, feeding the error log into an Emacs
6405 buffer. It can also parse the error messages and visit the files in
6406 which errors are found, moving point to the line where the error
6410 Run a compiler asynchronously under Emacs, with error messages to
6411 `*compilation*' buffer.
6414 Run `grep' asynchronously under Emacs, with matching lines listed
6415 in the buffer named `*compilation*'.
6417 `M-x kill-compilation'
6418 Kill the process made by the `M-x compile' command.
6421 Kill the running compilation or `grep' subprocess.
6424 Visit the next compiler error message or `grep' match.
6426 To run `make' or another compiler, type `M-x compile'. This command
6427 reads a shell command line using the minibuffer, then executes the
6428 specified command line in an inferior shell with output going to the
6429 buffer named `*compilation*'. By default, the current buffer's default
6430 directory is used as the working directory for the execution of the
6431 command; therefore, the makefile comes from this directory.
6433 When the shell command line is read, the minibuffer appears
6434 containing a default command line (the command you used the last time
6435 you typed `M-x compile'). If you type just <RET>, the same command
6436 line is used again. The first `M-x compile' provides `make -k' as the
6437 default. The default is taken from the variable `compile-command'; if
6438 the appropriate compilation command for a file is something other than
6439 `make -k', it can be useful to have the file specify a local value for
6440 `compile-command' (*note File Variables::).
6442 When you start a compilation, the buffer `*compilation*' is
6443 displayed in another window but not selected. Its mode line displays
6444 the word `run' or `exit' in the parentheses to tell you whether
6445 compilation is finished. You do not have to keep this buffer visible;
6446 compilation continues in any case.
6448 To kill the compilation process, type `M-x kill-compilation'. The
6449 mode line of the `*compilation*' buffer changes to say `signal' instead
6450 of `run'. Starting a new compilation also kills any running
6451 compilation, as only one can occur at any time. Starting a new
6452 compilation prompts for confirmation before actually killing a
6453 compilation that is running.
6455 To parse the compiler error messages, type `C-x `' (`next-error').
6456 The character following `C-x' is the grave accent, not the single
6457 quote. The command displays the buffer `*compilation*' in one window
6458 and the buffer in which the next error occurred in another window.
6459 Point in that buffer is moved to the line where the error was found.
6460 The corresponding error message is scrolled to the top of the window in
6461 which `*compilation*' is displayed.
6463 The first time you use `C-x `' after the start of a compilation, it
6464 parses all the error messages, visits all the files that have error
6465 messages, and creates markers pointing at the lines the error messages
6466 refer to. It then moves to the first error message location.
6467 Subsequent uses of `C-x `' advance down the data set up by the first
6468 use. When the preparsed error messages are exhausted, the next `C-x `'
6469 checks for any more error messages that have come in; this is useful if
6470 you start editing compiler errors while compilation is still going on.
6471 If no additional error messages have come in, `C-x `' reports an error.
6473 `C-u C-x `' discards the preparsed error message data and parses the
6474 `*compilation*' buffer again, then displays the first error. This way,
6475 you can process the same set of errors again.
6477 Instead of running a compiler, you can run `grep' and see the lines
6478 on which matches were found. To do this, type `M-x grep' with an
6479 argument line that contains the same arguments you would give to
6480 `grep': a `grep'-style regexp (usually in single quotes to quote the
6481 shell's special characters) followed by filenames, which may use
6482 wildcard characters. The output from `grep' goes in the
6483 `*compilation*' buffer. You can use `C-x `' to find the lines that
6484 match as if they were compilation errors.
6486 Note: a shell is used to run the compile command, but the shell is
6487 not run in interactive mode. In particular, this means that the shell
6488 starts up with no prompt. If you find your usual shell prompt making an
6489 unsightly appearance in the `*compilation*' buffer, it means you have
6490 made a mistake in your shell's initialization file (`.cshrc' or `.shrc'
6491 or ...) by setting the prompt unconditionally. The shell
6492 initialization file should set the prompt only if there already is a
6493 prompt. Here's how to do it in `csh':
6495 if ($?prompt) set prompt = ...
6498 File: xemacs.info, Node: Lisp Modes, Next: Lisp Libraries, Prev: Compilation, Up: Running
6500 Major Modes for Lisp
6501 ====================
6503 Emacs has four different major modes for Lisp. They are the same in
6504 terms of editing commands, but differ in the commands for executing Lisp
6508 The mode for editing source files of programs to run in Emacs Lisp.
6509 This mode defines `C-M-x' to evaluate the current defun. *Note
6512 Lisp Interaction mode
6513 The mode for an interactive session with Emacs Lisp. It defines
6514 <LFD> to evaluate the sexp before point and insert its value in the
6515 buffer. *Note Lisp Interaction::.
6518 The mode for editing source files of programs that run in other
6519 dialects of Lisp than Emacs Lisp. This mode defines `C-M-x' to
6520 send the current defun to an inferior Lisp process. *Note
6524 The mode for an interactive session with an inferior Lisp process.
6525 This mode combines the special features of Lisp mode and Shell mode
6526 (*note Shell Mode::).
6529 Like Lisp mode but for Scheme programs.
6531 Inferior Scheme mode
6532 The mode for an interactive session with an inferior Scheme
6536 File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running
6538 Libraries of Lisp Code for Emacs
6539 ================================
6541 Lisp code for Emacs editing commands is stored in files whose names
6542 conventionally end in `.el'. This ending tells Emacs to edit them in
6543 Emacs-Lisp mode (*note Lisp Modes::).
6547 * Loading:: Loading libraries of Lisp code into Emacs for use.
6548 * Compiling Libraries:: Compiling a library makes it load and run faster.
6549 * Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
6552 File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries
6557 `M-x load-file FILE'
6558 Load the file FILE of Lisp code.
6560 `M-x load-library LIBRARY'
6561 Load the library named LIBRARY.
6563 `M-x locate-library LIBRARY &optional NOSUFFIX'
6564 Show the full path name of Emacs library LIBRARY.
6566 To execute a file of Emacs Lisp, use `M-x load-file'. This command
6567 reads the file name you provide in the minibuffer, then executes the
6568 contents of that file as Lisp code. It is not necessary to visit the
6569 file first; in fact, this command reads the file as found on disk, not
6570 the text in an Emacs buffer.
6572 Once a file of Lisp code is installed in the Emacs Lisp library
6573 directories, users can load it using `M-x load-library'. Programs can
6574 load it by calling `load-library', or with `load', a more primitive
6575 function that is similar but accepts some additional arguments.
6577 `M-x load-library' differs from `M-x load-file' in that it searches
6578 a sequence of directories and tries three file names in each directory.
6579 The three names are: first, the specified name with `.elc' appended;
6580 second, the name with `.el' appended; third, the specified name alone.
6581 A `.elc' file would be the result of compiling the Lisp file into byte
6582 code; if possible, it is loaded in preference to the Lisp file itself
6583 because the compiled file loads and runs faster.
6585 Because the argument to `load-library' is usually not in itself a
6586 valid file name, file name completion is not available. In fact, when
6587 using this command, you usually do not know exactly what file name will
6590 The sequence of directories searched by `M-x load-library' is
6591 specified by the variable `load-path', a list of strings that are
6592 directory names. The elements of this list may not begin with "`~'",
6593 so you must call `expand-file-name' on them before adding them to the
6594 list. The default value of the list contains the directory where the
6595 Lisp code for Emacs itself is stored. If you have libraries of your
6596 own, put them in a single directory and add that directory to
6597 `load-path'. `nil' in this list stands for the current default
6598 directory, but it is probably not a good idea to put `nil' in the list.
6599 If you start wishing that `nil' were in the list, you should probably
6600 use `M-x load-file' for this case.
6602 The variable is initialized by the EMACSLOADPATH environment
6603 variable. If no value is specified, the variable takes the default value
6604 specified in the file `paths.h' when Emacs was built. If a path isn't
6605 specified in `paths.h', a default value is obtained from the file
6606 system, near the directory in which the Emacs executable resides.
6608 Like `M-x load-library', `M-x locate-library' searches the
6609 directories in `load-path' to find the file that `M-x load-library'
6610 would load. If the optional second argument NOSUFFIX is non-`nil', the
6611 suffixes `.elc' or `.el' are not added to the specified name LIBRARY
6612 (like calling `load' instead of `load-library').
6614 You often do not have to give any command to load a library, because
6615 the commands defined in the library are set up to "autoload" that
6616 library. Running any of those commands causes `load' to be called to
6617 load the library; this replaces the autoload definitions with the real
6618 ones from the library.
6620 If autoloading a file does not finish, either because of an error or
6621 because of a `C-g' quit, all function definitions made by the file are
6622 undone automatically. So are any calls to `provide'. As a
6623 consequence, the entire file is loaded a second time if you use one of
6624 the autoloadable commands again. This prevents problems when the
6625 command is no longer autoloading but is working incorrectly because the
6626 file was only partially loaded. Function definitions are undone only
6627 for autoloading; explicit calls to `load' do not undo anything if
6628 loading is not completed.
6630 The variable `after-load-alist' takes an alist of expressions to be
6631 evaluated when particular files are loaded. Each element has the form
6632 `(FILENAME forms...)'. When `load' is run and the filename argument is
6633 FILENAME, the forms in the corresponding element are executed at the
6636 FILENAME must match exactly. Normally FILENAME is the name of a
6637 library, with no directory specified, since that is how load is
6638 normally called. An error in `forms' does not undo the load, but it
6639 does prevent execution of the rest of the `forms'.
6642 File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries
6647 Emacs Lisp code can be compiled into byte-code which loads faster,
6648 takes up less space when loaded, and executes faster.
6650 `M-x batch-byte-compile'
6651 Run byte-compile-file on the files remaining on the command line.
6653 `M-x byte-compile-buffer &optional BUFFER'
6654 Byte-compile and evaluate contents of BUFFER (default is current
6657 `M-x byte-compile-file'
6658 Compile a file of Lisp code named FILENAME into a file of byte
6661 `M-x byte-compile-and-load-file FILENAME'
6662 Compile a file of Lisp code named FILENAME into a file of byte
6665 `M-x byte-recompile-directory DIRECTORY'
6666 Recompile every `.el' file in DIRECTORY that needs recompilation.
6669 Print disassembled code for OBJECT on (optional) STREAM.
6671 `M-x make-obsolete FUNCTION NEW'
6672 Make the byte-compiler warn that FUNCTION is obsolete and NEW
6673 should be used instead.
6675 `byte-compile-file' creates a byte-code compiled file from an
6676 Emacs-Lisp source file. The default argument for this function is the
6677 file visited in the current buffer. The function reads the specified
6678 file, compiles it into byte code, and writes an output file whose name
6679 is made by appending `c' to the input file name. Thus, the file
6680 `rmail.el' would be compiled into `rmail.elc'. To compile a file of
6681 Lisp code named FILENAME into a file of byte code and then load it, use
6682 `byte-compile-and-load-file'. To compile and evaluate Lisp code in a
6683 given buffer, use `byte-compile-buffer'.
6685 To recompile all changed Lisp files in a directory, use `M-x
6686 byte-recompile-directory'. Specify just the directory name as an
6687 argument. Each `.el' file that has been byte-compiled before is
6688 byte-compiled again if it has changed since the previous compilation.
6689 A numeric argument to this command tells it to offer to compile each
6690 `.el' file that has not been compiled yet. You must answer `y' or `n'
6693 You can use the function `batch-byte-compile' to invoke Emacs
6694 non-interactively from the shell to do byte compilation. When you use
6695 this function, the files to be compiled are specified with command-line
6696 arguments. Use a shell command of the form:
6698 emacs -batch -f batch-byte-compile FILES...
6700 Directory names may also be given as arguments; in that case,
6701 `byte-recompile-directory' is invoked on each such directory.
6702 `batch-byte-compile' uses all remaining command-line arguments as file
6703 or directory names, then kills the Emacs process.
6705 `M-x disassemble' explains the result of byte compilation. Its
6706 argument is a function name. It displays the byte-compiled code in a
6707 help window in symbolic form, one instruction per line. If the
6708 instruction refers to a variable or constant, that is shown, too.
6711 File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries
6713 Converting Mocklisp to Lisp
6714 ---------------------------
6716 XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
6717 To convert a Mocklisp file, visit it and then type `M-x
6718 convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file
6719 in a file whose name ends in `.el' and use the new file as a Lisp
6722 You cannot currently byte-compile converted Mocklisp code. The
6723 reason is that converted Mocklisp code uses some special Lisp features
6724 to deal with Mocklisp's incompatible ideas of how arguments are
6725 evaluated and which values signify "true" or "false".
6728 File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running
6730 Evaluating Emacs-Lisp Expressions
6731 =================================
6733 Lisp programs intended to be run in Emacs should be edited in
6734 Emacs-Lisp mode; this will happen automatically for file names ending in
6735 `.el'. By contrast, Lisp mode itself should be used for editing Lisp
6736 programs intended for other Lisp systems. Emacs-Lisp mode can be
6737 selected with the command `M-x emacs-lisp-mode'.
6739 For testing of Lisp programs to run in Emacs, it is useful to be able
6740 to evaluate part of the program as it is found in the Emacs buffer. For
6741 example, if you change the text of a Lisp function definition and then
6742 evaluate the definition, Emacs installs the change for future calls to
6743 the function. Evaluation of Lisp expressions is also useful in any
6744 kind of editing task for invoking non-interactive functions (functions
6745 that are not commands).
6748 Read a Lisp expression in the minibuffer, evaluate it, and print
6749 the value in the minibuffer (`eval-expression').
6752 Evaluate the Lisp expression before point, and print the value in
6753 the minibuffer (`eval-last-sexp').
6756 Evaluate the defun containing point or after point, and print the
6757 value in the minibuffer (`eval-defun').
6760 Evaluate all the Lisp expressions in the region.
6762 `M-x eval-current-buffer'
6763 Evaluate all the Lisp expressions in the buffer.
6765 `M-:' (`eval-expression') is the most basic command for evaluating a
6766 Lisp expression interactively. It reads the expression using the
6767 minibuffer, so you can execute any expression on a buffer regardless of
6768 what the buffer contains. When evaluation is complete, the current
6769 buffer is once again the buffer that was current when `M-:' was typed.
6771 In Emacs-Lisp mode, the key `C-M-x' is bound to the function
6772 `eval-defun', which parses the defun containing point or following point
6773 as a Lisp expression and evaluates it. The value is printed in the echo
6774 area. This command is convenient for installing in the Lisp environment
6775 changes that you have just made in the text of a function definition.
6777 The command `C-x C-e' (`eval-last-sexp') performs a similar job but
6778 is available in all major modes, not just Emacs-Lisp mode. It finds
6779 the sexp before point, reads it as a Lisp expression, evaluates it, and
6780 prints the value in the echo area. It is sometimes useful to type in an
6781 expression and then, with point still after it, type `C-x C-e'.
6783 If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
6784 value by inserting it into the current buffer at point, rather than in
6785 the echo area. The argument value does not matter.
6787 The most general command for evaluating Lisp expressions from a
6788 buffer is `eval-region'. `M-x eval-region' parses the text of the
6789 region as one or more Lisp expressions, evaluating them one by one.
6790 `M-x eval-current-buffer' is similar, but it evaluates the entire
6791 buffer. This is a reasonable way to install the contents of a file of
6792 Lisp code that you are just ready to test. After finding and fixing a
6793 bug, use `C-M-x' on each function that you change, to keep the Lisp
6794 world in step with the source file.
6797 File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running
6799 The Emacs-Lisp Debugger
6800 =======================
6802 XEmacs contains a debugger for Lisp programs executing inside it. This
6803 debugger is normally not used; many commands frequently get Lisp errors
6804 when invoked in inappropriate contexts (such as `C-f' at the end of the
6805 buffer) and it would be unpleasant to enter a special debugging mode in
6806 this case. When you want to make Lisp errors invoke the debugger, you
6807 must set the variable `debug-on-error' to non-`nil'. Quitting with
6808 `C-g' is not considered an error, and `debug-on-error' has no effect on
6809 the handling of `C-g'. However, if you set `debug-on-quit' to be
6810 non-`nil', `C-g' will invoke the debugger. This can be useful for
6811 debugging an infinite loop; type `C-g' once the loop has had time to
6812 reach its steady state. `debug-on-quit' has no effect on errors.
6814 You can make Emacs enter the debugger when a specified function is
6815 called or at a particular place in Lisp code. Use `M-x debug-on-entry'
6816 with argument FUN-NAME to have Emacs enter the debugger as soon as
6817 FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
6818 function stop entering the debugger when called. (Redefining the
6819 function also does this.) To enter the debugger from some other place
6820 in Lisp code, you must insert the expression `(debug)' there and
6821 install the changed code with `C-M-x'. *Note Lisp Eval::.
6823 When the debugger is entered, it displays the previously selected
6824 buffer in one window and a buffer named `*Backtrace*' in another
6825 window. The backtrace buffer contains one line for each level of Lisp
6826 function execution currently going on. At the beginning of the buffer
6827 is a message describing the reason that the debugger was invoked, for
6828 example, an error message if it was invoked due to an error.
6830 The backtrace buffer is read-only and is in Backtrace mode, a special
6831 major mode in which letters are defined as debugger commands. The
6832 usual Emacs editing commands are available; you can switch windows to
6833 examine the buffer that was being edited at the time of the error, and
6834 you can switch buffers, visit files, and perform any other editing
6835 operations. However, the debugger is a recursive editing level (*note
6836 Recursive Edit::); it is a good idea to return to the backtrace buffer
6837 and explicitly exit the debugger when you don't want to use it any
6838 more. Exiting the debugger kills the backtrace buffer.
6840 The contents of the backtrace buffer show you the functions that are
6841 executing and the arguments that were given to them. It also allows you
6842 to specify a stack frame by moving point to the line describing that
6843 frame. The frame whose line point is on is considered the "current
6844 frame". Some of the debugger commands operate on the current frame.
6845 Debugger commands are mainly used for stepping through code one
6846 expression at a time. Here is a list of them:
6849 Exit the debugger and continue execution. In most cases,
6850 execution of the program continues as if the debugger had never
6851 been entered (aside from the effect of any variables or data
6852 structures you may have changed while inside the debugger). This
6853 includes entry to the debugger due to function entry or exit,
6854 explicit invocation, and quitting or certain errors. Most errors
6855 cannot be continued; trying to continue an error usually causes
6856 the same error to occur again.
6859 Continue execution, but enter the debugger the next time a Lisp
6860 function is called. This allows you to step through the
6861 subexpressions of an expression, and see what the subexpressions
6862 do and what values they compute.
6864 When you enter the debugger this way, Emacs flags the stack frame
6865 for the function call from which you entered. The same function
6866 is then called when you exit the frame. To cancel this flag, use
6870 Set up to enter the debugger when the current frame is exited.
6871 Frames that invoke the debugger on exit are flagged with stars.
6874 Don't enter the debugger when the current frame is exited. This
6875 cancels a `b' command on a frame.
6878 Read a Lisp expression in the minibuffer, evaluate it, and print
6879 the value in the echo area. This is equivalent to the command
6883 Terminate the program being debugged; return to top-level Emacs
6886 If the debugger was entered due to a `C-g' but you really want to
6887 quit, not to debug, use the `q' command.
6890 Return a value from the debugger. The value is computed by
6891 reading an expression with the minibuffer and evaluating it.
6893 The value returned by the debugger makes a difference when the
6894 debugger was invoked due to exit from a Lisp call frame (as
6895 requested with `b'); then the value specified in the `r' command
6896 is used as the value of that frame.
6898 The debugger's return value also matters with many errors. For
6899 example, `wrong-type-argument' errors will use the debugger's
6900 return value instead of the invalid argument; `no-catch' errors
6901 will use the debugger value as a throw tag instead of the tag that
6902 was not found. If an error was signaled by calling the Lisp
6903 function `signal', the debugger's return value is returned as the