1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: TeX Editing, Next: TeX Print, Prev: TeX Mode, Up: TeX Mode
38 Here are the special commands provided in TeX mode for editing the
42 Insert, according to context, either ```' or `"' or `'''
46 Insert a paragraph break (two newlines) and check the previous
47 paragraph for unbalanced braces or dollar signs (`tex-terminate-
50 `M-x validate-tex-buffer'
51 Check each paragraph in the buffer for unbalanced braces or dollar
55 Insert `{}' and position point between them (`tex-insert-braces').
58 Move forward past the next unmatched close brace (`up-list').
61 Close a block for LaTeX (`tex-close-latex-block').
63 In TeX, the character `"' is not normally used; you use ```' to
64 start a quotation and `''' to end one. TeX mode defines the key `"' to
65 insert ```' after whitespace or an open brace, `"' after a backslash,
66 or `''' otherwise. This is done by the command `tex-insert-quote'. If
67 you need the character `"' itself in unusual contexts, use `C-q' to
68 insert it. Also, `"' with a numeric argument always inserts that
69 number of `"' characters.
71 In TeX mode, `$' has a special syntax code which attempts to
72 understand the way TeX math mode delimiters match. When you insert a
73 `$' that is meant to exit math mode, the position of the matching `$'
74 that entered math mode is displayed for a second. This is the same
75 feature that displays the open brace that matches a close brace that is
76 inserted. However, there is no way to tell whether a `$' enters math
77 mode or leaves it; so when you insert a `$' that enters math mode, the
78 previous `$' position is shown as if it were a match, even though they
79 are actually unrelated.
81 If you prefer to keep braces balanced at all times, you can use `C-c
82 {' (`tex-insert-braces') to insert a pair of braces. It leaves point
83 between the two braces so you can insert the text that belongs inside.
84 Afterward, use the command `C-c }' (`up-list') to move forward past the
87 There are two commands for checking the matching of braces. <LFD>
88 (`tex-terminate-paragraph') checks the paragraph before point, and
89 inserts two newlines to start a new paragraph. It prints a message in
90 the echo area if any mismatch is found. `M-x validate-tex-buffer'
91 checks the entire buffer, paragraph by paragraph. When it finds a
92 paragraph that contains a mismatch, it displays point at the beginning
93 of the paragraph for a few seconds and pushes a mark at that spot.
94 Scanning continues until the whole buffer has been checked or until you
95 type another key. The positions of the last several paragraphs with
96 mismatches can be found in the mark ring (*note Mark Ring::).
98 Note that square brackets and parentheses, not just braces, are
99 matched in TeX mode. This is wrong if you want to check TeX syntax.
100 However, parentheses and square brackets are likely to be used in text
101 as matching delimiters and it is useful for the various motion commands
102 and automatic match display to work with them.
104 In LaTeX input, `\begin' and `\end' commands must balance. After
105 you insert a `\begin', use `C-c C-f' (`tex-close-latex-block') to
106 insert automatically a matching `\end' (on a new line following the
107 `\begin'). A blank line is inserted between the two, and point is left
111 File: xemacs.info, Node: TeX Print, Prev: TeX Editing, Up: TeX Mode
113 TeX Printing Commands
114 .....................
116 You can invoke TeX as an inferior of Emacs on either the entire
117 contents of the buffer or just a region at a time. Running TeX in this
118 way on just one chapter is a good way to see what your changes look
119 like without taking the time to format the entire file.
122 Invoke TeX on the current region, plus the buffer's header
126 Invoke TeX on the entire current buffer (`tex-buffer').
129 Recenter the window showing output from the inferior TeX so that
130 the last line can be seen (`tex-recenter-output-buffer').
133 Kill the inferior TeX (`tex-kill-job').
136 Print the output from the last `C-c C-r' or `C-c C-b' command
140 Show the printer queue (`tex-show-print-queue').
142 You can pass the current buffer through an inferior TeX using `C-c
143 C-b' (`tex-buffer'). The formatted output appears in a file in `/tmp';
144 to print it, type `C-c C-p' (`tex-print'). Afterward use `C-c C-q'
145 (`tex-show-print-queue') to view the progress of your output towards
148 The console output from TeX, including any error messages, appears
149 in a buffer called `*TeX-shell*'. If TeX gets an error, you can switch
150 to this buffer and feed it input (this works as in Shell mode; *note
151 Interactive Shell::). Without switching to this buffer, you can scroll
152 it so that its last line is visible by typing `C-c C-l'.
154 Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
155 that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also
156 kills any TeX process still running.
158 You can pass an arbitrary region through an inferior TeX by typing
159 `C-c C-r' (`tex-region'). This is tricky, however, because most files
160 of TeX input contain commands at the beginning to set parameters and
161 define macros. Without them, no later part of the file will format
162 correctly. To solve this problem, `C-c C-r' allows you to designate a
163 part of the file as containing essential commands; it is included
164 before the specified region as part of the input to TeX. The
165 designated part of the file is called the "header".
167 To indicate the bounds of the header in Plain TeX mode, insert two
168 special strings in the file: `%**start of header' before the header,
169 and `%**end of header' after it. Each string must appear entirely on
170 one line, but there may be other text on the line before or after. The
171 lines containing the two strings are included in the header. If
172 `%**start of header' does not appear within the first 100 lines of the
173 buffer, `C-c C-r' assumes there is no header.
175 In LaTeX mode, the header begins with `\documentstyle' and ends with
176 `\begin{document}'. These are commands that LaTeX requires you to use,
177 so you don't need to do anything special to identify the header.
179 When you enter either kind of TeX mode, Emacs calls with no
180 arguments the value of the variable `text-mode-hook', if that value
181 exists and is not `nil'. Emacs then calls the variable `TeX-mode-hook'
182 and either `plain-TeX-mode-hook' or `LaTeX-mode-hook' under the same
186 File: xemacs.info, Node: Outline Mode, Prev: TeX Mode, Up: Text Mode
191 Outline mode is a major mode similar to Text mode but intended for
192 editing outlines. It allows you to make parts of the text temporarily
193 invisible so that you can see just the overall structure of the
194 outline. Type `M-x outline-mode' to turn on Outline mode in the
197 When you enter Outline mode, Emacs calls with no arguments the value
198 of the variable `text-mode-hook', if that value exists and is not
199 `nil'; then it does the same with the variable `outline-mode-hook'.
201 When a line is invisible in outline mode, it does not appear on the
202 screen. The screen appears exactly as if the invisible line were
203 deleted, except that an ellipsis (three periods in a row) appears at
204 the end of the previous visible line (only one ellipsis no matter how
205 many invisible lines follow).
207 All editing commands treat the text of the invisible line as part of
208 the previous visible line. For example, `C-n' moves onto the next
209 visible line. Killing an entire visible line, including its
210 terminating newline, really kills all the following invisible lines as
211 well; yanking everything back yanks the invisible lines and they remain
216 * Format: Outline Format. What the text of an outline looks like.
217 * Motion: Outline Motion. Special commands for moving through outlines.
218 * Visibility: Outline Visibility. Commands to control what is visible.
221 File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
226 Outline mode assumes that the lines in the buffer are of two types:
227 "heading lines" and "body lines". A heading line represents a topic in
228 the outline. Heading lines start with one or more stars; the number of
229 stars determines the depth of the heading in the outline structure.
230 Thus, a heading line with one star is a major topic; all the heading
231 lines with two stars between it and the next one-star heading are its
232 subtopics; and so on. Any line that is not a heading line is a body
233 line. Body lines belong to the preceding heading line. Here is an
239 which says something about the topic of food.
243 This is the body of the second-level header.
255 A second first-level topic with its header line.
257 A heading line together with all following body lines is called
258 collectively an "entry". A heading line together with all following
259 deeper heading lines and their body lines is called a "subtree".
261 You can customize the criterion for distinguishing heading lines by
262 setting the variable `outline-regexp'. Any line whose beginning has a
263 match for this regexp is considered a heading line. Matches that start
264 within a line (not at the beginning) do not count. The length of the
265 matching text determines the level of the heading; longer matches make
266 a more deeply nested level. Thus, for example, if a text formatter has
267 commands `@chapter', `@section' and `@subsection' to divide the
268 document into chapters and sections, you can make those lines count as
269 heading lines by setting `outline-regexp' to
270 `"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words
271 `chapter' and `section' are the same length, but by defining the regexp
272 to match only `chap' we ensure that the length of the text matched on a
273 chapter heading is shorter, so that Outline mode will know that
274 sections are contained in chapters. This works as long as no other
275 command starts with `@chap'.
277 Outline mode makes a line invisible by changing the newline before it
278 into an ASCII Control-M (code 015). Most editing commands that work on
279 lines treat an invisible line as part of the previous line because,
280 strictly speaking, it is part of that line, since there is no longer a
281 newline in between. When you save the file in Outline mode, Control-M
282 characters are saved as newlines, so the invisible lines become ordinary
283 lines in the file. Saving does not change the visibility status of a
287 File: xemacs.info, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode
289 Outline Motion Commands
290 .......................
292 Some special commands in Outline mode move backward and forward to
296 Move point to the next visible heading line
297 (`outline-next-visible-heading').
300 Move point to the previous visible heading line
301 (`outline-previous-visible-heading').
304 Move point to the next visible heading line at the same level as
305 the one point is on (`outline-forward-same-level').
308 Move point to the previous visible heading line at the same level
309 (`outline-backward-same-level').
312 Move point up to a lower-level (more inclusive) visible heading
313 line (`outline-up-heading').
315 `C-c C-n' (`next-visible-heading') moves down to the next heading
316 line. `C-c C-p' (`previous-visible-heading') moves similarly backward.
317 Both accept numeric arguments as repeat counts. The names emphasize
318 that invisible headings are skipped, but this is not really a special
319 feature. All editing commands that look for lines ignore the invisible
322 More advanced motion commands understand the levels of headings.
323 The commands `C-c C-f' (`outline-forward-same-level') and `C-c C-b'
324 (`outline-backward-same-level') move from one heading line to another
325 visible heading at the same depth in the outline. `C-c C-u'
326 (`outline-up-heading') moves backward to another heading that is less
330 File: xemacs.info, Node: Outline Visibility, Prev: Outline Motion, Up: Outline Mode
332 Outline Visibility Commands
333 ...........................
335 The other special commands of outline mode are used to make lines
336 visible or invisible. Their names all start with `hide' or `show'.
337 Most of them exist as pairs of opposites. They are not undoable;
338 instead, you can undo right past them. Making lines visible or
339 invisible is simply not recorded by the undo mechanism.
342 Make all body lines in the buffer invisible.
345 Make all lines in the buffer visible.
348 Make everything under this heading invisible, not including this
349 heading itself (`hide-subtree').
352 Make everything under this heading visible, including body,
353 subheadings, and their bodies (`show-subtree').
356 Make the body of this heading line, and of all its subheadings,
360 Make all subheadings of this heading line, at all levels, visible.
363 Make immediate subheadings (one level down) of this heading line
364 visible (`show-children').
367 Make this heading line's body invisible.
370 Make this heading line's body visible.
372 Two commands that are exact opposites are `M-x hide-entry' and `M-x
373 show-entry'. They are used with point on a heading line, and apply
374 only to the body lines of that heading. The subtopics and their bodies
377 Two more powerful opposites are `C-c C-h' (`hide-subtree') and `C-c
378 C-s' (`show-subtree'). Both should be used when point is on a heading
379 line, and both apply to all the lines of that heading's "subtree": its
380 body, all its subheadings, both direct and indirect, and all of their
381 bodies. In other words, the subtree contains everything following this
382 heading line, up to and not including the next heading of the same or
385 Intermediate between a visible subtree and an invisible one is having
386 all the subheadings visible but none of the body. There are two
387 commands for doing this, one that hides the bodies and one that makes
388 the subheadings visible. They are `M-x hide-leaves' and `M-x
391 A little weaker than `show-branches' is `C-c C-i' (`show-children').
392 It makes just the direct subheadings visible--those one level down.
393 Deeper subheadings remain invisible.
395 Two commands have a blanket effect on the whole file. `M-x
396 hide-body' makes all body lines invisible, so that you see just the
397 outline structure. `M-x show-all' makes all lines visible. You can
398 think of these commands as a pair of opposites even though `M-x
399 show-all' applies to more than just body lines.
401 You can turn off the use of ellipses at the ends of visible lines by
402 setting `selective-display-ellipses' to `nil'. The result is no
403 visible indication of the presence of invisible lines.
406 File: xemacs.info, Node: Words, Next: Sentences, Prev: Text Mode, Up: Text
411 Emacs has commands for moving over or operating on words. By
412 convention, the keys for them are all `Meta-' characters.
415 Move forward over a word (`forward-word').
418 Move backward over a word (`backward-word').
421 Kill up to the end of a word (`kill-word').
424 Kill back to the beginning of a word (`backward-kill-word').
427 Mark the end of the next word (`mark-word').
430 Transpose two words; drag a word forward or backward across other
431 words (`transpose-words').
433 Notice how these keys form a series that parallels the
434 character-based `C-f', `C-b', `C-d', `C-t' and <DEL>. `M-@' is related
435 to `C-@', which is an alias for `C-<SPC>'.
437 The commands `Meta-f' (`forward-word') and `Meta-b'
438 (`backward-word') move forward and backward over words. They are
439 analogous to `Control-f' and `Control-b', which move over single
440 characters. Like their `Control-' analogues, `Meta-f' and `Meta-b'
441 move several words if given an argument. `Meta-f' with a negative
442 argument moves backward, and `Meta-b' with a negative argument moves
443 forward. Forward motion stops after the last letter of the word, while
444 backward motion stops before the first letter.
446 `Meta-d' (`kill-word') kills the word after point. To be precise,
447 it kills everything from point to the place `Meta-f' would move to.
448 Thus, if point is in the middle of a word, `Meta-d' kills just the part
449 after point. If some punctuation comes between point and the next
450 word, it is killed along with the word. (To kill only the next word
451 but not the punctuation before it, simply type `Meta-f' to get to the
452 end and kill the word backwards with `Meta-<DEL>'.) `Meta-d' takes
453 arguments just like `Meta-f'.
455 `Meta-<DEL>' (`backward-kill-word') kills the word before point. It
456 kills everything from point back to where `Meta-b' would move to. If
457 point is after the space in `FOO, BAR', then `FOO, ' is killed. To
458 kill just `FOO', type `Meta-b Meta-d' instead of `Meta-<DEL>'.
460 `Meta-t' (`transpose-words') exchanges the word before or containing
461 point with the following word. The delimiter characters between the
462 words do not move. For example, transposing `FOO, BAR' results in
463 `BAR, FOO' rather than `BAR FOO,'. *Note Transpose::, for more on
464 transposition and on arguments to transposition commands.
466 To operate on the next N words with an operation which applies
467 between point and mark, you can either set the mark at point and then
468 move over the words, or you can use the command `Meta-@' (`mark-word')
469 which does not move point but sets the mark where `Meta-f' would move
470 to. It can be given arguments just like `Meta-f'.
472 The word commands' understanding of syntax is completely controlled
473 by the syntax table. For example, any character can be declared to be
474 a word delimiter. *Note Syntax::.
477 File: xemacs.info, Node: Sentences, Next: Paragraphs, Prev: Words, Up: Text
482 The Emacs commands for manipulating sentences and paragraphs are
483 mostly on `Meta-' keys, and therefore are like the word-handling
487 Move back to the beginning of the sentence (`backward-sentence').
490 Move forward to the end of the sentence (`forward-sentence').
493 Kill forward to the end of the sentence (`kill-sentence').
496 Kill back to the beginning of the sentence
497 (`backward-kill-sentence').
499 The commands `Meta-a' and `Meta-e' (`backward-sentence' and
500 `forward-sentence') move to the beginning and end of the current
501 sentence, respectively. They resemble `Control-a' and `Control-e',
502 which move to the beginning and end of a line. Unlike their
503 counterparts, `Meta-a' and `Meta-e' move over successive sentences if
504 repeated or given numeric arguments. Emacs assumes the typist's
505 convention is followed, and thus considers a sentence to end wherever
506 there is a `.', `?', or `!' followed by the end of a line or two
507 spaces, with any number of `)', `]', `'', or `"' characters allowed in
508 between. A sentence also begins or ends wherever a paragraph begins or
511 Neither `M-a' nor `M-e' moves past the newline or spaces beyond the
512 sentence edge at which it is stopping.
514 `M-a' and `M-e' have a corresponding kill command, just like `C-a'
515 and `C-e' have `C-k'. The command is `M-k' (`kill-sentence') which
516 kills from point to the end of the sentence. With minus one as an
517 argument it kills back to the beginning of the sentence. Larger
518 arguments serve as repeat counts.
520 There is a special command, `C-x <DEL>' (`backward-kill-sentence'),
521 for killing back to the beginning of a sentence, which is useful when
522 you change your mind in the middle of composing text.
524 The variable `sentence-end' controls recognition of the end of a
525 sentence. It is a regexp that matches the last few characters of a
526 sentence, together with the whitespace following the sentence. Its
529 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
531 This example is explained in the section on regexps. *Note Regexps::.
534 File: xemacs.info, Node: Paragraphs, Next: Pages, Prev: Sentences, Up: Text
539 The Emacs commands for manipulating paragraphs are also `Meta-' keys.
542 Move back to previous paragraph beginning
543 (`backward-paragraph').
546 Move forward to next paragraph end (`forward-paragraph').
549 Put point and mark around this or next paragraph
552 `Meta-[' moves to the beginning of the current or previous paragraph,
553 while `Meta-]' moves to the end of the current or next paragraph.
554 Blank lines and text formatter command lines separate paragraphs and are
555 not part of any paragraph. An indented line starts a new paragraph.
557 In major modes for programs (as opposed to Text mode), paragraphs
558 begin and end only at blank lines. As a result, the paragraph commands
559 continue to be useful even though there are no paragraphs per se.
561 When there is a fill prefix, paragraphs are delimited by all lines
562 which don't start with the fill prefix. *Note Filling::.
564 To operate on a paragraph, you can use the command `Meta-h'
565 (`mark-paragraph') to set the region around it. This command puts
566 point at the beginning and mark at the end of the paragraph point was
567 in. If point is between paragraphs (in a run of blank lines or at a
568 boundary), the paragraph following point is surrounded by point and
569 mark. If there are blank lines preceding the first line of the
570 paragraph, one of the blank lines is included in the region. Thus, for
571 example, `M-h C-w' kills the paragraph around or after point.
573 The precise definition of a paragraph boundary is controlled by the
574 variables `paragraph-separate' and `paragraph-start'. The value of
575 `paragraph-start' is a regexp that matches any line that either starts
576 or separates paragraphs. The value of `paragraph-separate' is another
577 regexp that matches only lines that separate paragraphs without being
578 part of any paragraph. Lines that start a new paragraph and are
579 contained in it must match both regexps. For example, normally
580 `paragraph-start' is `"^[ \t\n\f]"' and `paragraph-separate' is `"^[
583 Normally it is desirable for page boundaries to separate paragraphs.
584 The default values of these variables recognize the usual separator for
588 File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
593 Files are often thought of as divided into "pages" by the "formfeed"
594 character (ASCII Control-L, octal code 014). For example, if a file is
595 printed on a line printer, each "page" of the file starts on a new page
596 of paper. Emacs treats a page-separator character just like any other
597 character. It can be inserted with `C-q C-l' or deleted with <DEL>.
598 You are free to paginate your file or not. However, since pages are
599 often meaningful divisions of the file, commands are provided to move
600 over them and operate on them.
603 Move point to previous page boundary (`backward-page').
606 Move point to next page boundary (`forward-page').
609 Put point and mark around this page (or another page)
613 Count the lines in this page (`count-lines-page').
615 The `C-x [' (`backward-page') command moves point to immediately
616 after the previous page delimiter. If point is already right after a
617 page delimiter, the command skips that one and stops at the previous
618 one. A numeric argument serves as a repeat count. The `C-x ]'
619 (`forward-page') command moves forward past the next page delimiter.
621 The `C-x C-p' command (`mark-page') puts point at the beginning of
622 the current page and the mark at the end. The page delimiter at the end
623 is included (the mark follows it). The page delimiter at the front is
624 excluded (point follows it). You can follow this command by `C-w' to
625 kill a page you want to move elsewhere. If you insert the page after a
626 page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
627 page will be properly delimited before and after once again.
629 A numeric argument to `C-x C-p' is used to specify which page to go
630 to, relative to the current one. Zero means the current page. One
631 means the next page, and -1 means the previous one.
633 The `C-x l' command (`count-lines-page') can help you decide where
634 to break a page in two. It prints the total number of lines in the
635 current page in the echo area, then divides the lines into those
636 preceding the current line and those following it, for example
638 Page has 96 (72+25) lines
640 Notice that the sum is off by one; this is correct if point is not at
641 the beginning of a line.
643 The variable `page-delimiter' should have as its value a regexp that
644 matches the beginning of a line that separates pages. This defines
645 where pages begin. The normal value of this variable is `"^\f"', which
646 matches a formfeed character at the beginning of a line.
649 File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text
654 If you use Auto Fill mode, Emacs "fills" text (breaks it up into
655 lines that fit in a specified width) as you insert it. When you alter
656 existing text it is often no longer be properly filled afterwards and
657 you can use explicit commands for filling.
661 * Auto Fill:: Auto Fill mode breaks long lines automatically.
662 * Fill Commands:: Commands to refill paragraphs and center lines.
663 * Fill Prefix:: Filling when every line is indented or in a comment, etc.
666 File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
671 "Auto Fill" mode is a minor mode in which lines are broken
672 automatically when they become too wide. Breaking happens only when
673 you type a <SPC> or <RET>.
676 Enable or disable Auto Fill mode.
680 In Auto Fill mode, break lines when appropriate.
682 `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
683 if it was on. With a positive numeric argument the command always turns
684 Auto Fill mode on, and with a negative argument it always turns it off.
685 The presence of the word `Fill' in the mode line, inside the
686 parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode
687 is a minor mode; you can turn it on or off for each buffer individually.
690 In Auto Fill mode, lines are broken automatically at spaces when
691 they get longer than desired. Line breaking and rearrangement takes
692 place only when you type <SPC> or <RET>. To insert a space or newline
693 without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
694 (recall that a newline is really a linefeed). `C-o' inserts a newline
695 without line breaking.
697 Auto Fill mode works well with Lisp mode: when it makes a new line in
698 Lisp mode, it indents that line with <TAB>. If a line ending in a Lisp
699 comment gets too long, the text of the comment is split into two
700 comment lines. Optionally, new comment delimiters are inserted at the
701 end of the first line and the beginning of the second, so that each line
702 is a separate comment. The variable `comment-multi-line' controls the
703 choice (*note Comments::).
705 Auto Fill mode does not refill entire paragraphs. It can break
706 lines but cannot merge lines. Editing in the middle of a paragraph can
707 result in a paragraph that is not correctly filled. The easiest way to
708 make the paragraph properly filled again is using an explicit fill
711 Many users like Auto Fill mode and want to use it in all text files.
712 The section on init files explains how you can arrange this permanently
713 for yourself. *Note Init File::.
716 File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
718 Explicit Fill Commands
719 ----------------------
722 Fill current paragraph (`fill-paragraph').
725 Fill each paragraph in the region (`fill-region').
728 Set the fill column (`set-fill-column').
730 `M-x fill-region-as-paragraph'
731 Fill the region, considering it as one paragraph.
736 To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
737 It causes the paragraph containing point, or the one after point if
738 point is between paragraphs, to be refilled. All line breaks are
739 removed, and new ones are inserted where necessary. `M-q' can be
740 undone with `C-_'. *Note Undo::.
742 To refill many paragraphs, use `M-g' (`fill-region'), which divides
743 the region into paragraphs and fills each of them.
745 `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
746 paragraph boundaries (*note Paragraphs::). For more control, you can
747 use `M-x fill-region-as-paragraph', which refills everything between
748 point and mark. This command recognizes only blank lines as paragraph
751 A numeric argument to `M-g' or `M-q' causes it to "justify" the text
752 as well as filling it. Extra spaces are inserted to make the right
753 margin line up exactly at the fill column. To remove the extra spaces,
754 use `M-q' or `M-g' with no argument.
756 The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
757 match lines that should not be auto-filled.
759 The command `Meta-s' (`center-line') centers the current line within
760 the current fill column. With an argument, it centers several lines
761 individually and moves past them.
763 The maximum line width for filling is in the variable `fill-column'.
764 Altering the value of `fill-column' makes it local to the current
765 buffer; until then, the default value--initially 70--is in effect.
768 The easiest way to set `fill-column' is to use the command `C-x f'
769 (`set-fill-column'). With no argument, it sets `fill-column' to the
770 current horizontal position of point. With a numeric argument, it uses
771 that number as the new fill column.
774 File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
779 To fill a paragraph in which each line starts with a special marker
780 (which might be a few spaces, giving an indented paragraph), use the
781 "fill prefix" feature. The fill prefix is a string which is not
782 included in filling. Emacs expects every line to start with a fill
786 Set the fill prefix (`set-fill-prefix').
789 Fill a paragraph using current fill prefix (`fill-paragraph').
791 `M-x fill-individual-paragraphs'
792 Fill the region, considering each change of indentation as
793 starting a new paragraph.
795 To specify a fill prefix, move to a line that starts with the desired
796 prefix, put point at the end of the prefix, and give the command
797 `C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
798 off the fill prefix, specify an empty prefix: type `C-x .' with point
799 at the beginning of a line.
801 When a fill prefix is in effect, the fill commands remove the fill
802 prefix from each line before filling and insert it on each line after
803 filling. Auto Fill mode also inserts the fill prefix inserted on new
804 lines it creates. Lines that do not start with the fill prefix are
805 considered to start paragraphs, both in `M-q' and the paragraph
806 commands; this is just right if you are using paragraphs with hanging
807 indentation (every line indented except the first one). Lines which are
808 blank or indented once the prefix is removed also separate or start
809 paragraphs; this is what you want if you are writing multi-paragraph
810 comments with a comment delimiter on each line.
812 The fill prefix is stored in the variable `fill-prefix'. Its value
813 is a string, or `nil' when there is no fill prefix. This is a
814 per-buffer variable; altering the variable affects only the current
815 buffer, but there is a default value which you can change as well.
818 Another way to use fill prefixes is through `M-x
819 fill-individual-paragraphs'. This function divides the region into
820 groups of consecutive lines with the same amount and kind of
821 indentation and fills each group as a paragraph, using its indentation
825 File: xemacs.info, Node: Case, Prev: Filling, Up: Text
827 Case Conversion Commands
828 ========================
830 Emacs has commands for converting either a single word or any
831 arbitrary range of text to upper case or to lower case.
834 Convert following word to lower case (`downcase-word').
837 Convert following word to upper case (`upcase-word').
840 Capitalize the following word (`capitalize-word').
843 Convert region to lower case (`downcase-region').
846 Convert region to upper case (`upcase-region').
848 The word conversion commands are used most frequently. `Meta-l'
849 (`downcase-word') converts the word after point to lower case, moving
850 past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
851 (`upcase-word') converts to all capitals instead, while `Meta-c'
852 (`capitalize-word') puts the first letter of the word into upper case
853 and the rest into lower case. The word conversion commands convert
854 several words at once if given an argument. They are especially
855 convenient for converting a large amount of text from all upper case to
856 mixed case: you can move through the text using `M-l', `M-u', or `M-c'
857 on each word as appropriate, occasionally using `M-f' instead to skip a
860 When given a negative argument, the word case conversion commands
861 apply to the appropriate number of words before point, but do not move
862 point. This is convenient when you have just typed a word in the wrong
863 case: you can give the case conversion command and continue typing.
865 If a word case conversion command is given in the middle of a word,
866 it applies only to the part of the word which follows point. This is
867 just like what `Meta-d' (`kill-word') does. With a negative argument,
868 case conversion applies only to the part of the word before point.
870 The other case conversion commands are `C-x C-u' (`upcase-region')
871 and `C-x C-l' (`downcase-region'), which convert everything between
872 point and mark to the specified case. Point and mark do not move.
875 File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top
880 Emacs has many commands designed to understand the syntax of
881 programming languages such as Lisp and C. These commands can:
883 * Move over or kill balanced expressions or "sexps" (*note Lists::).
885 * Move over or mark top-level balanced expressions ("defuns", in
886 Lisp; functions, in C).
888 * Show how parentheses balance (*note Matching::).
890 * Insert, kill, or align comments (*note Comments::).
892 * Follow the usual indentation conventions of the language (*note
895 The commands available for words, sentences, and paragraphs are
896 useful in editing code even though their canonical application is for
897 editing human language text. Most symbols contain words (*note
898 Words::); sentences can be found in strings and comments (*note
899 Sentences::). Paragraphs per se are not present in code, but the
900 paragraph commands are useful anyway, because Lisp mode and C mode
901 define paragraphs to begin and end at blank lines (*note Paragraphs::).
902 Judicious use of blank lines to make the program clearer also provides
903 interesting chunks of text for the paragraph commands to work on.
905 The selective display feature is useful for looking at the overall
906 structure of a function (*note Selective Display::). This feature
907 causes only the lines that are indented less than a specified amount to
908 appear on the screen.
912 * Program Modes:: Major modes for editing programs.
913 * Lists:: Expressions with balanced parentheses.
914 There are editing commands to operate on them.
915 * Defuns:: Each program is made up of separate functions.
916 There are editing commands to operate on them.
917 * Grinding:: Adjusting indentation to show the nesting.
918 * Matching:: Insertion of a close-delimiter flashes matching open.
919 * Comments:: Inserting, filling and aligning comments.
920 * Balanced Editing:: Inserting two matching parentheses at once, etc.
921 * Lisp Completion:: Completion on symbol names in Lisp code.
922 * Documentation:: Getting documentation of functions you plan to call.
923 * Change Log:: Maintaining a change history for your program.
924 * Tags:: Go direct to any function in your program in one
925 command. Tags remembers which file it is in.
926 * Fortran:: Fortran mode and its special features.
927 * Asm Mode:: Asm mode and its special features.
930 File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
932 Major Modes for Programming Languages
933 =====================================
935 Emacs has several major modes for the programming languages Lisp,
936 Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major
937 mode should be implemented for each programming language you might want
938 to edit with Emacs; but often the mode for one language can serve for
939 other syntactically similar languages. The language modes that exist
940 are those that someone decided to take the trouble to write.
942 There are several variants of Lisp mode, which differ in the way they
943 interface to Lisp execution. *Note Lisp Modes::.
945 Each of the programming language modes defines the <TAB> key to run
946 an indentation function that knows the indentation conventions of that
947 language and updates the current line's indentation accordingly. For
948 example, in C mode <TAB> is bound to `c-indent-line'. <LFD> is
949 normally defined to do <RET> followed by <TAB>; thus it, too, indents
950 in a mode-specific fashion.
952 In most programming languages, indentation is likely to vary from
953 line to line. So the major modes for those languages rebind <DEL> to
954 treat a tab as if it were the equivalent number of spaces (using the
955 command `backward-delete-char-untabify'). This makes it possible to
956 rub out indentation one column at a time without worrying whether it is
957 made up of spaces or tabs. In these modes, use `C-b C-d' to delete a
958 tab character before point.
960 Programming language modes define paragraphs to be separated only by
961 blank lines, so that the paragraph commands remain useful. Auto Fill
962 mode, if enabled in a programming language major mode, indents the new
963 lines which it creates.
965 Turning on a major mode calls a user-supplied function called the
966 "mode hook", which is the value of a Lisp variable. For example,
967 turning on C mode calls the value of the variable `c-mode-hook' if that
968 value exists and is non-`nil'. Mode hook variables for other
969 programming language modes include `lisp-mode-hook',
970 `emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
971 `scheme-mode-hook', and `muddle-mode-hook'. The mode hook function
972 receives no arguments.
975 File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
980 By convention, Emacs keys for dealing with balanced expressions are
981 usually `Control-Meta-' characters. They tend to be analogous in
982 function to their `Control-' and `Meta-' equivalents. These commands
983 are usually thought of as pertaining to expressions in programming
984 languages, but can be useful with any language in which some sort of
985 parentheses exist (including English).
987 The commands fall into two classes. Some commands deal only with
988 "lists" (parenthetical groupings). They see nothing except
989 parentheses, brackets, braces (depending on what must balance in the
990 language you are working with), and escape characters that might be used
993 The other commands deal with expressions or "sexps". The word `sexp'
994 is derived from "s-expression", the term for a symbolic expression in
995 Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It
996 refers to an expression in the language your program is written in.
997 Each programming language has its own major mode, which customizes the
998 syntax tables so that expressions in that language count as sexps.
1000 Sexps typically include symbols, numbers, and string constants, as
1001 well as anything contained in parentheses, brackets, or braces.
1003 In languages that use prefix and infix operators, such as C, it is
1004 not possible for all expressions to be sexps. For example, C mode does
1005 not recognize `foo + bar' as an sexp, even though it is a C expression;
1006 it recognizes `foo' as one sexp and `bar' as another, with the `+' as
1007 punctuation between them. This is a fundamental ambiguity: both `foo +
1008 bar' and `foo' are legitimate choices for the sexp to move over if
1009 point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
1011 Some languages have obscure forms of syntax for expressions that
1012 nobody has bothered to make Emacs understand properly.
1015 Move forward over an sexp (`forward-sexp').
1018 Move backward over an sexp (`backward-sexp').
1021 Kill sexp forward (`kill-sexp').
1024 Move up and backward in list structure (`backward-up-list').
1027 Move down and forward in list structure (`down-list').
1030 Move forward over a list (`forward-list').
1033 Move backward over a list (`backward-list').
1036 Transpose expressions (`transpose-sexps').
1039 Put mark after following expression (`mark-sexp').
1041 To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the
1042 first significant character after point is an opening delimiter (`(' in
1043 Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
1044 delimiter. If the character begins a symbol, string, or number,
1045 `C-M-f' moves over that. If the character after point is a closing
1046 delimiter, `C-M-f' just moves past it. (This last is not really moving
1047 across an sexp; it is an exception which is included in the definition
1048 of `C-M-f' because it is as useful a behavior as anyone can think of
1049 for that situation.)
1051 The command `C-M-b' (`backward-sexp') moves backward over a sexp.
1052 The detailed rules are like those above for `C-M-f', but with
1053 directions reversed. If there are any prefix characters (single quote,
1054 back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
1057 `C-M-f' or `C-M-b' with an argument repeats that operation the
1058 specified number of times; with a negative argument, it moves in the
1061 In languages such as C where the comment-terminator can be
1062 recognized, the sexp commands move across comments as if they were
1063 whitespace. In Lisp and other languages where comments run until the
1064 end of a line, it is very difficult to ignore comments when parsing
1065 backwards; therefore, in such languages the sexp commands treat the
1066 text of comments as if it were code.
1068 Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
1069 `C-M-k' kills the characters that `C-M-f' would move over.
1071 The "list commands", `C-M-n' (`forward-list') and `C-M-p'
1072 (`backward-list'), move over lists like the sexp commands but skip over
1073 any number of other kinds of sexps (symbols, strings, etc). In some
1074 situations, these commands are useful because they usually ignore
1075 comments, since the comments usually do not contain any lists.
1077 `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
1078 is possible. To move up one (or N) levels, use `C-M-u'
1079 (`backward-up-list'). `C-M-u' moves backward up past one unmatched
1080 opening delimiter. A positive argument serves as a repeat count; a
1081 negative argument reverses direction of motion and also requests
1082 repetition, so it moves forward and up one or more levels.
1084 To move down in list structure, use `C-M-d' (`down-list'). In Lisp
1085 mode, where `(' is the only opening delimiter, this is nearly the same
1086 as searching for a `('. An argument specifies the number of levels of
1087 parentheses to go down.
1089 `C-M-t' (`transpose-sexps') drags the previous sexp across the next
1090 one. An argument serves as a repeat count, and a negative argument
1091 drags backwards (thus canceling out the effect of `C-M-t' with a
1092 positive argument). An argument of zero, rather than doing nothing,
1093 transposes the sexps ending after point and the mark.
1095 To make the region be the next sexp in the buffer, use `C-M-@'
1096 (`mark-sexp') which sets the mark at the same place that `C-M-f' would
1097 move to. `C-M-@' takes arguments like `C-M-f'. In particular, a
1098 negative argument is useful for putting the mark at the beginning of
1101 The list and sexp commands' understanding of syntax is completely
1102 controlled by the syntax table. Any character can, for example, be
1103 declared to be an opening delimiter and act like an open parenthesis.
1107 File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
1112 In Emacs, a parenthetical grouping at the top level in the buffer is
1113 called a "defun". The name derives from the fact that most top-level
1114 lists in Lisp are instances of the special form `defun', but Emacs
1115 calls any top-level parenthetical grouping counts a defun regardless of
1116 its contents or the programming language. For example, in C, the body
1117 of a function definition is a defun.
1120 Move to beginning of current or preceding defun
1121 (`beginning-of-defun').
1124 Move to end of current or following defun (`end-of-defun').
1127 Put region around whole current or following defun (`mark-defun').
1129 The commands to move to the beginning and end of the current defun
1130 are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
1132 To operate on the current defun, use `C-M-h' (`mark-defun') which
1133 puts point at the beginning and the mark at the end of the current or
1134 next defun. This is the easiest way to prepare for moving the defun to
1135 a different place. In C mode, `C-M-h' runs the function
1136 `mark-c-function', which is almost the same as `mark-defun', but which
1137 backs up over the argument declarations, function name, and returned
1138 data type so that the entire C function is inside the region.
1140 To compile and evaluate the current defun, use `M-x compile-defun'.
1141 This function prints the results in the minibuffer. If you include an
1142 argument, it inserts the value in the current buffer after the defun.
1144 Emacs assumes that any open-parenthesis found in the leftmost column
1145 is the start of a defun. Therefore, never put an open-parenthesis at
1146 the left margin in a Lisp file unless it is the start of a top level
1147 list. Never put an open-brace or other opening delimiter at the
1148 beginning of a line of C code unless it starts the body of a function.
1149 The most likely problem case is when you want an opening delimiter at
1150 the start of a line inside a string. To avoid trouble, put an escape
1151 character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
1152 before the opening delimiter. It will not affect the contents of the
1155 The original Emacs found defuns by moving upward a level of
1156 parentheses until there were no more levels to go up. This required
1157 scanning back to the beginning of the buffer for every function. To
1158 speed this up, Emacs was changed to assume that any `(' (or other
1159 character assigned the syntactic class of opening-delimiter) at the
1160 left margin is the start of a defun. This heuristic is nearly always
1161 right; however, it mandates the convention described above.
1164 File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
1166 Indentation for Programs
1167 ========================
1169 The best way to keep a program properly indented ("ground") is to
1170 use Emacs to re-indent it as you change the program. Emacs has commands
1171 to indent properly either a single line, a specified number of lines, or
1172 all of the lines inside a single parenthetical grouping.
1177 * Multi-line Indent:: Commands to reindent many lines at once.
1178 * Lisp Indent:: Specifying how each Lisp function should be indented.
1179 * C Indent:: Choosing an indentation style for C code.