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 Print, Prev: TeX Editing, Up: TeX Mode
38 You can invoke TeX as an inferior of Emacs on either the entire
39 contents of the buffer or just a region at a time. Running TeX in this
40 way on just one chapter is a good way to see what your changes look
41 like without taking the time to format the entire file.
44 Invoke TeX on the current region, plus the buffer's header
48 Invoke TeX on the entire current buffer (`tex-buffer').
51 Recenter the window showing output from the inferior TeX so that
52 the last line can be seen (`tex-recenter-output-buffer').
55 Kill the inferior TeX (`tex-kill-job').
58 Print the output from the last `C-c C-r' or `C-c C-b' command
62 Show the printer queue (`tex-show-print-queue').
64 You can pass the current buffer through an inferior TeX using `C-c
65 C-b' (`tex-buffer'). The formatted output appears in a file in `/tmp';
66 to print it, type `C-c C-p' (`tex-print'). Afterward use `C-c C-q'
67 (`tex-show-print-queue') to view the progress of your output towards
70 The console output from TeX, including any error messages, appears
71 in a buffer called `*TeX-shell*'. If TeX gets an error, you can switch
72 to this buffer and feed it input (this works as in Shell mode; *note
73 Interactive Shell::). Without switching to this buffer, you can scroll
74 it so that its last line is visible by typing `C-c C-l'.
76 Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
77 that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also
78 kills any TeX process still running.
80 You can pass an arbitrary region through an inferior TeX by typing
81 `C-c C-r' (`tex-region'). This is tricky, however, because most files
82 of TeX input contain commands at the beginning to set parameters and
83 define macros. Without them, no later part of the file will format
84 correctly. To solve this problem, `C-c C-r' allows you to designate a
85 part of the file as containing essential commands; it is included
86 before the specified region as part of the input to TeX. The
87 designated part of the file is called the "header".
89 To indicate the bounds of the header in Plain TeX mode, insert two
90 special strings in the file: `%**start of header' before the header,
91 and `%**end of header' after it. Each string must appear entirely on
92 one line, but there may be other text on the line before or after. The
93 lines containing the two strings are included in the header. If
94 `%**start of header' does not appear within the first 100 lines of the
95 buffer, `C-c C-r' assumes there is no header.
97 In LaTeX mode, the header begins with `\documentstyle' and ends with
98 `\begin{document}'. These are commands that LaTeX requires you to use,
99 so you don't need to do anything special to identify the header.
101 When you enter either kind of TeX mode, Emacs calls with no
102 arguments the value of the variable `text-mode-hook', if that value
103 exists and is not `nil'. Emacs then calls the variable `TeX-mode-hook'
104 and either `plain-TeX-mode-hook' or `LaTeX-mode-hook' under the same
108 File: xemacs.info, Node: Outline Mode, Prev: TeX Mode, Up: Text Mode
113 Outline mode is a major mode similar to Text mode but intended for
114 editing outlines. It allows you to make parts of the text temporarily
115 invisible so that you can see just the overall structure of the
116 outline. Type `M-x outline-mode' to turn on Outline mode in the
119 When you enter Outline mode, Emacs calls with no arguments the value
120 of the variable `text-mode-hook', if that value exists and is not
121 `nil'; then it does the same with the variable `outline-mode-hook'.
123 When a line is invisible in outline mode, it does not appear on the
124 screen. The screen appears exactly as if the invisible line were
125 deleted, except that an ellipsis (three periods in a row) appears at
126 the end of the previous visible line (only one ellipsis no matter how
127 many invisible lines follow).
129 All editing commands treat the text of the invisible line as part of
130 the previous visible line. For example, `C-n' moves onto the next
131 visible line. Killing an entire visible line, including its
132 terminating newline, really kills all the following invisible lines as
133 well; yanking everything back yanks the invisible lines and they remain
138 * Format: Outline Format. What the text of an outline looks like.
139 * Motion: Outline Motion. Special commands for moving through outlines.
140 * Visibility: Outline Visibility. Commands to control what is visible.
143 File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
148 Outline mode assumes that the lines in the buffer are of two types:
149 "heading lines" and "body lines". A heading line represents a topic in
150 the outline. Heading lines start with one or more stars; the number of
151 stars determines the depth of the heading in the outline structure.
152 Thus, a heading line with one star is a major topic; all the heading
153 lines with two stars between it and the next one-star heading are its
154 subtopics; and so on. Any line that is not a heading line is a body
155 line. Body lines belong to the preceding heading line. Here is an
161 which says something about the topic of food.
165 This is the body of the second-level header.
177 A second first-level topic with its header line.
179 A heading line together with all following body lines is called
180 collectively an "entry". A heading line together with all following
181 deeper heading lines and their body lines is called a "subtree".
183 You can customize the criterion for distinguishing heading lines by
184 setting the variable `outline-regexp'. Any line whose beginning has a
185 match for this regexp is considered a heading line. Matches that start
186 within a line (not at the beginning) do not count. The length of the
187 matching text determines the level of the heading; longer matches make
188 a more deeply nested level. Thus, for example, if a text formatter has
189 commands `@chapter', `@section' and `@subsection' to divide the
190 document into chapters and sections, you can make those lines count as
191 heading lines by setting `outline-regexp' to
192 `"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words
193 `chapter' and `section' are the same length, but by defining the regexp
194 to match only `chap' we ensure that the length of the text matched on a
195 chapter heading is shorter, so that Outline mode will know that
196 sections are contained in chapters. This works as long as no other
197 command starts with `@chap'.
199 Outline mode makes a line invisible by changing the newline before it
200 into an ASCII Control-M (code 015). Most editing commands that work on
201 lines treat an invisible line as part of the previous line because,
202 strictly speaking, it is part of that line, since there is no longer a
203 newline in between. When you save the file in Outline mode, Control-M
204 characters are saved as newlines, so the invisible lines become ordinary
205 lines in the file. Saving does not change the visibility status of a
209 File: xemacs.info, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode
211 Outline Motion Commands
212 .......................
214 Some special commands in Outline mode move backward and forward to
218 Move point to the next visible heading line
219 (`outline-next-visible-heading').
222 Move point to the previous visible heading line
223 (`outline-previous-visible-heading').
226 Move point to the next visible heading line at the same level as
227 the one point is on (`outline-forward-same-level').
230 Move point to the previous visible heading line at the same level
231 (`outline-backward-same-level').
234 Move point up to a lower-level (more inclusive) visible heading
235 line (`outline-up-heading').
237 `C-c C-n' (`next-visible-heading') moves down to the next heading
238 line. `C-c C-p' (`previous-visible-heading') moves similarly backward.
239 Both accept numeric arguments as repeat counts. The names emphasize
240 that invisible headings are skipped, but this is not really a special
241 feature. All editing commands that look for lines ignore the invisible
244 More advanced motion commands understand the levels of headings.
245 The commands `C-c C-f' (`outline-forward-same-level') and `C-c C-b'
246 (`outline-backward-same-level') move from one heading line to another
247 visible heading at the same depth in the outline. `C-c C-u'
248 (`outline-up-heading') moves backward to another heading that is less
252 File: xemacs.info, Node: Outline Visibility, Prev: Outline Motion, Up: Outline Mode
254 Outline Visibility Commands
255 ...........................
257 The other special commands of outline mode are used to make lines
258 visible or invisible. Their names all start with `hide' or `show'.
259 Most of them exist as pairs of opposites. They are not undoable;
260 instead, you can undo right past them. Making lines visible or
261 invisible is simply not recorded by the undo mechanism.
264 Make all body lines in the buffer invisible.
267 Make all lines in the buffer visible.
270 Make everything under this heading invisible, not including this
271 heading itself (`hide-subtree').
274 Make everything under this heading visible, including body,
275 subheadings, and their bodies (`show-subtree').
278 Make the body of this heading line, and of all its subheadings,
282 Make all subheadings of this heading line, at all levels, visible.
285 Make immediate subheadings (one level down) of this heading line
286 visible (`show-children').
289 Make this heading line's body invisible.
292 Make this heading line's body visible.
294 Two commands that are exact opposites are `M-x hide-entry' and `M-x
295 show-entry'. They are used with point on a heading line, and apply
296 only to the body lines of that heading. The subtopics and their bodies
299 Two more powerful opposites are `C-c C-h' (`hide-subtree') and `C-c
300 C-s' (`show-subtree'). Both should be used when point is on a heading
301 line, and both apply to all the lines of that heading's "subtree": its
302 body, all its subheadings, both direct and indirect, and all of their
303 bodies. In other words, the subtree contains everything following this
304 heading line, up to and not including the next heading of the same or
307 Intermediate between a visible subtree and an invisible one is having
308 all the subheadings visible but none of the body. There are two
309 commands for doing this, one that hides the bodies and one that makes
310 the subheadings visible. They are `M-x hide-leaves' and `M-x
313 A little weaker than `show-branches' is `C-c C-i' (`show-children').
314 It makes just the direct subheadings visible--those one level down.
315 Deeper subheadings remain invisible.
317 Two commands have a blanket effect on the whole file. `M-x
318 hide-body' makes all body lines invisible, so that you see just the
319 outline structure. `M-x show-all' makes all lines visible. You can
320 think of these commands as a pair of opposites even though `M-x
321 show-all' applies to more than just body lines.
323 You can turn off the use of ellipses at the ends of visible lines by
324 setting `selective-display-ellipses' to `nil'. The result is no
325 visible indication of the presence of invisible lines.
328 File: xemacs.info, Node: Words, Next: Sentences, Prev: Text Mode, Up: Text
333 Emacs has commands for moving over or operating on words. By
334 convention, the keys for them are all `Meta-' characters.
337 Move forward over a word (`forward-word').
340 Move backward over a word (`backward-word').
343 Kill up to the end of a word (`kill-word').
346 Kill back to the beginning of a word (`backward-kill-word').
349 Mark the end of the next word (`mark-word').
352 Transpose two words; drag a word forward or backward across other
353 words (`transpose-words').
355 Notice how these keys form a series that parallels the
356 character-based `C-f', `C-b', `C-d', `C-t' and <DEL>. `M-@' is related
357 to `C-@', which is an alias for `C-<SPC>'.
359 The commands `Meta-f' (`forward-word') and `Meta-b'
360 (`backward-word') move forward and backward over words. They are
361 analogous to `Control-f' and `Control-b', which move over single
362 characters. Like their `Control-' analogues, `Meta-f' and `Meta-b'
363 move several words if given an argument. `Meta-f' with a negative
364 argument moves backward, and `Meta-b' with a negative argument moves
365 forward. Forward motion stops after the last letter of the word, while
366 backward motion stops before the first letter.
368 `Meta-d' (`kill-word') kills the word after point. To be precise,
369 it kills everything from point to the place `Meta-f' would move to.
370 Thus, if point is in the middle of a word, `Meta-d' kills just the part
371 after point. If some punctuation comes between point and the next
372 word, it is killed along with the word. (To kill only the next word
373 but not the punctuation before it, simply type `Meta-f' to get to the
374 end and kill the word backwards with `Meta-<DEL>'.) `Meta-d' takes
375 arguments just like `Meta-f'.
377 `Meta-<DEL>' (`backward-kill-word') kills the word before point. It
378 kills everything from point back to where `Meta-b' would move to. If
379 point is after the space in `FOO, BAR', then `FOO, ' is killed. To
380 kill just `FOO', type `Meta-b Meta-d' instead of `Meta-<DEL>'.
382 `Meta-t' (`transpose-words') exchanges the word before or containing
383 point with the following word. The delimiter characters between the
384 words do not move. For example, transposing `FOO, BAR' results in
385 `BAR, FOO' rather than `BAR FOO,'. *Note Transpose::, for more on
386 transposition and on arguments to transposition commands.
388 To operate on the next N words with an operation which applies
389 between point and mark, you can either set the mark at point and then
390 move over the words, or you can use the command `Meta-@' (`mark-word')
391 which does not move point but sets the mark where `Meta-f' would move
392 to. It can be given arguments just like `Meta-f'.
394 The word commands' understanding of syntax is completely controlled
395 by the syntax table. For example, any character can be declared to be
396 a word delimiter. *Note Syntax::.
399 File: xemacs.info, Node: Sentences, Next: Paragraphs, Prev: Words, Up: Text
404 The Emacs commands for manipulating sentences and paragraphs are
405 mostly on `Meta-' keys, and therefore are like the word-handling
409 Move back to the beginning of the sentence (`backward-sentence').
412 Move forward to the end of the sentence (`forward-sentence').
415 Kill forward to the end of the sentence (`kill-sentence').
418 Kill back to the beginning of the sentence
419 (`backward-kill-sentence').
421 The commands `Meta-a' and `Meta-e' (`backward-sentence' and
422 `forward-sentence') move to the beginning and end of the current
423 sentence, respectively. They resemble `Control-a' and `Control-e',
424 which move to the beginning and end of a line. Unlike their
425 counterparts, `Meta-a' and `Meta-e' move over successive sentences if
426 repeated or given numeric arguments. Emacs assumes the typist's
427 convention is followed, and thus considers a sentence to end wherever
428 there is a `.', `?', or `!' followed by the end of a line or two
429 spaces, with any number of `)', `]', `'', or `"' characters allowed in
430 between. A sentence also begins or ends wherever a paragraph begins or
433 Neither `M-a' nor `M-e' moves past the newline or spaces beyond the
434 sentence edge at which it is stopping.
436 `M-a' and `M-e' have a corresponding kill command, just like `C-a'
437 and `C-e' have `C-k'. The command is `M-k' (`kill-sentence') which
438 kills from point to the end of the sentence. With minus one as an
439 argument it kills back to the beginning of the sentence. Larger
440 arguments serve as repeat counts.
442 There is a special command, `C-x <DEL>' (`backward-kill-sentence'),
443 for killing back to the beginning of a sentence, which is useful when
444 you change your mind in the middle of composing text.
446 The variable `sentence-end' controls recognition of the end of a
447 sentence. It is a regexp that matches the last few characters of a
448 sentence, together with the whitespace following the sentence. Its
451 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
453 This example is explained in the section on regexps. *Note Regexps::.
456 File: xemacs.info, Node: Paragraphs, Next: Pages, Prev: Sentences, Up: Text
461 The Emacs commands for manipulating paragraphs are also `Meta-' keys.
464 Move back to previous paragraph beginning
465 (`backward-paragraph').
468 Move forward to next paragraph end (`forward-paragraph').
471 Put point and mark around this or next paragraph
474 `Meta-[' moves to the beginning of the current or previous paragraph,
475 while `Meta-]' moves to the end of the current or next paragraph.
476 Blank lines and text formatter command lines separate paragraphs and are
477 not part of any paragraph. An indented line starts a new paragraph.
479 In major modes for programs (as opposed to Text mode), paragraphs
480 begin and end only at blank lines. As a result, the paragraph commands
481 continue to be useful even though there are no paragraphs per se.
483 When there is a fill prefix, paragraphs are delimited by all lines
484 which don't start with the fill prefix. *Note Filling::.
486 To operate on a paragraph, you can use the command `Meta-h'
487 (`mark-paragraph') to set the region around it. This command puts
488 point at the beginning and mark at the end of the paragraph point was
489 in. If point is between paragraphs (in a run of blank lines or at a
490 boundary), the paragraph following point is surrounded by point and
491 mark. If there are blank lines preceding the first line of the
492 paragraph, one of the blank lines is included in the region. Thus, for
493 example, `M-h C-w' kills the paragraph around or after point.
495 The precise definition of a paragraph boundary is controlled by the
496 variables `paragraph-separate' and `paragraph-start'. The value of
497 `paragraph-start' is a regexp that matches any line that either starts
498 or separates paragraphs. The value of `paragraph-separate' is another
499 regexp that matches only lines that separate paragraphs without being
500 part of any paragraph. Lines that start a new paragraph and are
501 contained in it must match both regexps. For example, normally
502 `paragraph-start' is `"^[ \t\n\f]"' and `paragraph-separate' is `"^[
505 Normally it is desirable for page boundaries to separate paragraphs.
506 The default values of these variables recognize the usual separator for
510 File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
515 Files are often thought of as divided into "pages" by the "formfeed"
516 character (ASCII Control-L, octal code 014). For example, if a file is
517 printed on a line printer, each "page" of the file starts on a new page
518 of paper. Emacs treats a page-separator character just like any other
519 character. It can be inserted with `C-q C-l' or deleted with <DEL>.
520 You are free to paginate your file or not. However, since pages are
521 often meaningful divisions of the file, commands are provided to move
522 over them and operate on them.
525 Move point to previous page boundary (`backward-page').
528 Move point to next page boundary (`forward-page').
531 Put point and mark around this page (or another page)
535 Count the lines in this page (`count-lines-page').
537 The `C-x [' (`backward-page') command moves point to immediately
538 after the previous page delimiter. If point is already right after a
539 page delimiter, the command skips that one and stops at the previous
540 one. A numeric argument serves as a repeat count. The `C-x ]'
541 (`forward-page') command moves forward past the next page delimiter.
543 The `C-x C-p' command (`mark-page') puts point at the beginning of
544 the current page and the mark at the end. The page delimiter at the end
545 is included (the mark follows it). The page delimiter at the front is
546 excluded (point follows it). You can follow this command by `C-w' to
547 kill a page you want to move elsewhere. If you insert the page after a
548 page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
549 page will be properly delimited before and after once again.
551 A numeric argument to `C-x C-p' is used to specify which page to go
552 to, relative to the current one. Zero means the current page. One
553 means the next page, and -1 means the previous one.
555 The `C-x l' command (`count-lines-page') can help you decide where
556 to break a page in two. It prints the total number of lines in the
557 current page in the echo area, then divides the lines into those
558 preceding the current line and those following it, for example
560 Page has 96 (72+25) lines
562 Notice that the sum is off by one; this is correct if point is not at
563 the beginning of a line.
565 The variable `page-delimiter' should have as its value a regexp that
566 matches the beginning of a line that separates pages. This defines
567 where pages begin. The normal value of this variable is `"^\f"', which
568 matches a formfeed character at the beginning of a line.
571 File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text
576 If you use Auto Fill mode, Emacs "fills" text (breaks it up into
577 lines that fit in a specified width) as you insert it. When you alter
578 existing text it is often no longer be properly filled afterwards and
579 you can use explicit commands for filling.
583 * Auto Fill:: Auto Fill mode breaks long lines automatically.
584 * Fill Commands:: Commands to refill paragraphs and center lines.
585 * Fill Prefix:: Filling when every line is indented or in a comment, etc.
588 File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
593 "Auto Fill" mode is a minor mode in which lines are broken
594 automatically when they become too wide. Breaking happens only when
595 you type a <SPC> or <RET>.
598 Enable or disable Auto Fill mode.
602 In Auto Fill mode, break lines when appropriate.
604 `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
605 if it was on. With a positive numeric argument the command always turns
606 Auto Fill mode on, and with a negative argument it always turns it off.
607 The presence of the word `Fill' in the mode line, inside the
608 parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode
609 is a minor mode; you can turn it on or off for each buffer individually.
612 In Auto Fill mode, lines are broken automatically at spaces when
613 they get longer than desired. Line breaking and rearrangement takes
614 place only when you type <SPC> or <RET>. To insert a space or newline
615 without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
616 (recall that a newline is really a linefeed). `C-o' inserts a newline
617 without line breaking.
619 Auto Fill mode works well with Lisp mode: when it makes a new line in
620 Lisp mode, it indents that line with <TAB>. If a line ending in a Lisp
621 comment gets too long, the text of the comment is split into two
622 comment lines. Optionally, new comment delimiters are inserted at the
623 end of the first line and the beginning of the second, so that each line
624 is a separate comment. The variable `comment-multi-line' controls the
625 choice (*note Comments::).
627 Auto Fill mode does not refill entire paragraphs. It can break
628 lines but cannot merge lines. Editing in the middle of a paragraph can
629 result in a paragraph that is not correctly filled. The easiest way to
630 make the paragraph properly filled again is using an explicit fill
633 Many users like Auto Fill mode and want to use it in all text files.
634 The section on init files explains how you can arrange this permanently
635 for yourself. *Note Init File::.
638 File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
640 Explicit Fill Commands
641 ----------------------
644 Fill current paragraph (`fill-paragraph').
647 Fill each paragraph in the region (`fill-region').
650 Set the fill column (`set-fill-column').
652 `M-x fill-region-as-paragraph'
653 Fill the region, considering it as one paragraph.
658 To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
659 It causes the paragraph containing point, or the one after point if
660 point is between paragraphs, to be refilled. All line breaks are
661 removed, and new ones are inserted where necessary. `M-q' can be
662 undone with `C-_'. *Note Undo::.
664 To refill many paragraphs, use `M-g' (`fill-region'), which divides
665 the region into paragraphs and fills each of them.
667 `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
668 paragraph boundaries (*note Paragraphs::). For more control, you can
669 use `M-x fill-region-as-paragraph', which refills everything between
670 point and mark. This command recognizes only blank lines as paragraph
673 A numeric argument to `M-g' or `M-q' causes it to "justify" the text
674 as well as filling it. Extra spaces are inserted to make the right
675 margin line up exactly at the fill column. To remove the extra spaces,
676 use `M-q' or `M-g' with no argument.
678 The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
679 match lines that should not be auto-filled.
681 The command `Meta-s' (`center-line') centers the current line within
682 the current fill column. With an argument, it centers several lines
683 individually and moves past them.
685 The maximum line width for filling is in the variable `fill-column'.
686 Altering the value of `fill-column' makes it local to the current
687 buffer; until then, the default value--initially 70--is in effect.
690 The easiest way to set `fill-column' is to use the command `C-x f'
691 (`set-fill-column'). With no argument, it sets `fill-column' to the
692 current horizontal position of point. With a numeric argument, it uses
693 that number as the new fill column.
696 File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
701 To fill a paragraph in which each line starts with a special marker
702 (which might be a few spaces, giving an indented paragraph), use the
703 "fill prefix" feature. The fill prefix is a string which is not
704 included in filling. Emacs expects every line to start with a fill
708 Set the fill prefix (`set-fill-prefix').
711 Fill a paragraph using current fill prefix (`fill-paragraph').
713 `M-x fill-individual-paragraphs'
714 Fill the region, considering each change of indentation as
715 starting a new paragraph.
717 To specify a fill prefix, move to a line that starts with the desired
718 prefix, put point at the end of the prefix, and give the command
719 `C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
720 off the fill prefix, specify an empty prefix: type `C-x .' with point
721 at the beginning of a line.
723 When a fill prefix is in effect, the fill commands remove the fill
724 prefix from each line before filling and insert it on each line after
725 filling. Auto Fill mode also inserts the fill prefix inserted on new
726 lines it creates. Lines that do not start with the fill prefix are
727 considered to start paragraphs, both in `M-q' and the paragraph
728 commands; this is just right if you are using paragraphs with hanging
729 indentation (every line indented except the first one). Lines which are
730 blank or indented once the prefix is removed also separate or start
731 paragraphs; this is what you want if you are writing multi-paragraph
732 comments with a comment delimiter on each line.
734 The fill prefix is stored in the variable `fill-prefix'. Its value
735 is a string, or `nil' when there is no fill prefix. This is a
736 per-buffer variable; altering the variable affects only the current
737 buffer, but there is a default value which you can change as well.
740 Another way to use fill prefixes is through `M-x
741 fill-individual-paragraphs'. This function divides the region into
742 groups of consecutive lines with the same amount and kind of
743 indentation and fills each group as a paragraph, using its indentation
747 File: xemacs.info, Node: Case, Prev: Filling, Up: Text
749 Case Conversion Commands
750 ========================
752 Emacs has commands for converting either a single word or any
753 arbitrary range of text to upper case or to lower case.
756 Convert following word to lower case (`downcase-word').
759 Convert following word to upper case (`upcase-word').
762 Capitalize the following word (`capitalize-word').
765 Convert region to lower case (`downcase-region').
768 Convert region to upper case (`upcase-region').
770 The word conversion commands are used most frequently. `Meta-l'
771 (`downcase-word') converts the word after point to lower case, moving
772 past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
773 (`upcase-word') converts to all capitals instead, while `Meta-c'
774 (`capitalize-word') puts the first letter of the word into upper case
775 and the rest into lower case. The word conversion commands convert
776 several words at once if given an argument. They are especially
777 convenient for converting a large amount of text from all upper case to
778 mixed case: you can move through the text using `M-l', `M-u', or `M-c'
779 on each word as appropriate, occasionally using `M-f' instead to skip a
782 When given a negative argument, the word case conversion commands
783 apply to the appropriate number of words before point, but do not move
784 point. This is convenient when you have just typed a word in the wrong
785 case: you can give the case conversion command and continue typing.
787 If a word case conversion command is given in the middle of a word,
788 it applies only to the part of the word which follows point. This is
789 just like what `Meta-d' (`kill-word') does. With a negative argument,
790 case conversion applies only to the part of the word before point.
792 The other case conversion commands are `C-x C-u' (`upcase-region')
793 and `C-x C-l' (`downcase-region'), which convert everything between
794 point and mark to the specified case. Point and mark do not move.
797 File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top
802 Emacs has many commands designed to understand the syntax of
803 programming languages such as Lisp and C. These commands can:
805 * Move over or kill balanced expressions or "sexps" (*note Lists::).
807 * Move over or mark top-level balanced expressions ("defuns", in
808 Lisp; functions, in C).
810 * Show how parentheses balance (*note Matching::).
812 * Insert, kill, or align comments (*note Comments::).
814 * Follow the usual indentation conventions of the language (*note
817 The commands available for words, sentences, and paragraphs are
818 useful in editing code even though their canonical application is for
819 editing human language text. Most symbols contain words (*note
820 Words::); sentences can be found in strings and comments (*note
821 Sentences::). Paragraphs per se are not present in code, but the
822 paragraph commands are useful anyway, because Lisp mode and C mode
823 define paragraphs to begin and end at blank lines (*note Paragraphs::).
824 Judicious use of blank lines to make the program clearer also provides
825 interesting chunks of text for the paragraph commands to work on.
827 The selective display feature is useful for looking at the overall
828 structure of a function (*note Selective Display::). This feature
829 causes only the lines that are indented less than a specified amount to
830 appear on the screen.
834 * Program Modes:: Major modes for editing programs.
835 * Lists:: Expressions with balanced parentheses.
836 There are editing commands to operate on them.
837 * Defuns:: Each program is made up of separate functions.
838 There are editing commands to operate on them.
839 * Grinding:: Adjusting indentation to show the nesting.
840 * Matching:: Insertion of a close-delimiter flashes matching open.
841 * Comments:: Inserting, illing and aligning comments.
842 * Balanced Editing:: Inserting two matching parentheses at once, etc.
843 * Lisp Completion:: Completion on symbol names in Lisp code.
844 * Documentation:: Getting documentation of functions you plan to call.
845 * Change Log:: Maintaining a change history for your program.
846 * Tags:: Go direct to any function in your program in one
847 command. Tags remembers which file it is in.
848 * Fortran:: Fortran mode and its special features.
849 * Asm Mode:: Asm mode and its special features.
852 File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
854 Major Modes for Programming Languages
855 =====================================
857 Emacs has several major modes for the programming languages Lisp,
858 Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major
859 mode should be implemented for each programming language you might want
860 to edit with Emacs; but often the mode for one language can serve for
861 other syntactically similar languages. The language modes that exist
862 are those that someone decided to take the trouble to write.
864 There are several variants of Lisp mode, which differ in the way they
865 interface to Lisp execution. *Note Lisp Modes::.
867 Each of the programming language modes defines the <TAB> key to run
868 an indentation function that knows the indentation conventions of that
869 language and updates the current line's indentation accordingly. For
870 example, in C mode <TAB> is bound to `c-indent-line'. <LFD> is
871 normally defined to do <RET> followed by <TAB>; thus it, too, indents
872 in a mode-specific fashion.
874 In most programming languages, indentation is likely to vary from
875 line to line. So the major modes for those languages rebind <DEL> to
876 treat a tab as if it were the equivalent number of spaces (using the
877 command `backward-delete-char-untabify'). This makes it possible to
878 rub out indentation one column at a time without worrying whether it is
879 made up of spaces or tabs. In these modes, use `C-b C-d' to delete a
880 tab character before point.
882 Programming language modes define paragraphs to be separated only by
883 blank lines, so that the paragraph commands remain useful. Auto Fill
884 mode, if enabled in a programming language major mode, indents the new
885 lines which it creates.
887 Turning on a major mode calls a user-supplied function called the
888 "mode hook", which is the value of a Lisp variable. For example,
889 turning on C mode calls the value of the variable `c-mode-hook' if that
890 value exists and is non-`nil'. Mode hook variables for other
891 programming language modes include `lisp-mode-hook',
892 `emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
893 `scheme-mode-hook', and `muddle-mode-hook'. The mode hook function
894 receives no arguments.
897 File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
902 By convention, Emacs keys for dealing with balanced expressions are
903 usually `Control-Meta-' characters. They tend to be analogous in
904 function to their `Control-' and `Meta-' equivalents. These commands
905 are usually thought of as pertaining to expressions in programming
906 languages, but can be useful with any language in which some sort of
907 parentheses exist (including English).
909 The commands fall into two classes. Some commands deal only with
910 "lists" (parenthetical groupings). They see nothing except
911 parentheses, brackets, braces (depending on what must balance in the
912 language you are working with), and escape characters that might be used
915 The other commands deal with expressions or "sexps". The word `sexp'
916 is derived from "s-expression", the term for a symbolic expression in
917 Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It
918 refers to an expression in the language your program is written in.
919 Each programming language has its own major mode, which customizes the
920 syntax tables so that expressions in that language count as sexps.
922 Sexps typically include symbols, numbers, and string constants, as
923 well as anything contained in parentheses, brackets, or braces.
925 In languages that use prefix and infix operators, such as C, it is
926 not possible for all expressions to be sexps. For example, C mode does
927 not recognize `foo + bar' as an sexp, even though it is a C expression;
928 it recognizes `foo' as one sexp and `bar' as another, with the `+' as
929 punctuation between them. This is a fundamental ambiguity: both `foo +
930 bar' and `foo' are legitimate choices for the sexp to move over if
931 point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
933 Some languages have obscure forms of syntax for expressions that
934 nobody has bothered to make Emacs understand properly.
937 Move forward over an sexp (`forward-sexp').
940 Move backward over an sexp (`backward-sexp').
943 Kill sexp forward (`kill-sexp').
946 Move up and backward in list structure (`backward-up-list').
949 Move down and forward in list structure (`down-list').
952 Move forward over a list (`forward-list').
955 Move backward over a list (`backward-list').
958 Transpose expressions (`transpose-sexps').
961 Put mark after following expression (`mark-sexp').
963 To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the
964 first significant character after point is an opening delimiter (`(' in
965 Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
966 delimiter. If the character begins a symbol, string, or number,
967 `C-M-f' moves over that. If the character after point is a closing
968 delimiter, `C-M-f' just moves past it. (This last is not really moving
969 across an sexp; it is an exception which is included in the definition
970 of `C-M-f' because it is as useful a behavior as anyone can think of
973 The command `C-M-b' (`backward-sexp') moves backward over a sexp.
974 The detailed rules are like those above for `C-M-f', but with
975 directions reversed. If there are any prefix characters (single quote,
976 back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
979 `C-M-f' or `C-M-b' with an argument repeats that operation the
980 specified number of times; with a negative argument, it moves in the
983 In languages such as C where the comment-terminator can be
984 recognized, the sexp commands move across comments as if they were
985 whitespace. In Lisp and other languages where comments run until the
986 end of a line, it is very difficult to ignore comments when parsing
987 backwards; therefore, in such languages the sexp commands treat the
988 text of comments as if it were code.
990 Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
991 `C-M-k' kills the characters that `C-M-f' would move over.
993 The "list commands", `C-M-n' (`forward-list') and `C-M-p'
994 (`backward-list'), move over lists like the sexp commands but skip over
995 any number of other kinds of sexps (symbols, strings, etc). In some
996 situations, these commands are useful because they usually ignore
997 comments, since the comments usually do not contain any lists.
999 `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
1000 is possible. To move up one (or N) levels, use `C-M-u'
1001 (`backward-up-list'). `C-M-u' moves backward up past one unmatched
1002 opening delimiter. A positive argument serves as a repeat count; a
1003 negative argument reverses direction of motion and also requests
1004 repetition, so it moves forward and up one or more levels.
1006 To move down in list structure, use `C-M-d' (`down-list'). In Lisp
1007 mode, where `(' is the only opening delimiter, this is nearly the same
1008 as searching for a `('. An argument specifies the number of levels of
1009 parentheses to go down.
1011 `C-M-t' (`transpose-sexps') drags the previous sexp across the next
1012 one. An argument serves as a repeat count, and a negative argument
1013 drags backwards (thus canceling out the effect of `C-M-t' with a
1014 positive argument). An argument of zero, rather than doing nothing,
1015 transposes the sexps ending after point and the mark.
1017 To make the region be the next sexp in the buffer, use `C-M-@'
1018 (`mark-sexp') which sets the mark at the same place that `C-M-f' would
1019 move to. `C-M-@' takes arguments like `C-M-f'. In particular, a
1020 negative argument is useful for putting the mark at the beginning of
1023 The list and sexp commands' understanding of syntax is completely
1024 controlled by the syntax table. Any character can, for example, be
1025 declared to be an opening delimiter and act like an open parenthesis.
1029 File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
1034 In Emacs, a parenthetical grouping at the top level in the buffer is
1035 called a "defun". The name derives from the fact that most top-level
1036 lists in Lisp are instances of the special form `defun', but Emacs
1037 calls any top-level parenthetical grouping counts a defun regardless of
1038 its contents or the programming language. For example, in C, the body
1039 of a function definition is a defun.
1042 Move to beginning of current or preceding defun
1043 (`beginning-of-defun').
1046 Move to end of current or following defun (`end-of-defun').
1049 Put region around whole current or following defun (`mark-defun').
1051 The commands to move to the beginning and end of the current defun
1052 are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
1054 To operate on the current defun, use `C-M-h' (`mark-defun') which
1055 puts point at the beginning and the mark at the end of the current or
1056 next defun. This is the easiest way to prepare for moving the defun to
1057 a different place. In C mode, `C-M-h' runs the function
1058 `mark-c-function', which is almost the same as `mark-defun', but which
1059 backs up over the argument declarations, function name, and returned
1060 data type so that the entire C function is inside the region.
1062 To compile and evaluate the current defun, use `M-x compile-defun'.
1063 This function prints the results in the minibuffer. If you include an
1064 argument, it inserts the value in the current buffer after the defun.
1066 Emacs assumes that any open-parenthesis found in the leftmost column
1067 is the start of a defun. Therefore, never put an open-parenthesis at
1068 the left margin in a Lisp file unless it is the start of a top level
1069 list. Never put an open-brace or other opening delimiter at the
1070 beginning of a line of C code unless it starts the body of a function.
1071 The most likely problem case is when you want an opening delimiter at
1072 the start of a line inside a string. To avoid trouble, put an escape
1073 character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
1074 before the opening delimiter. It will not affect the contents of the
1077 The original Emacs found defuns by moving upward a level of
1078 parentheses until there were no more levels to go up. This required
1079 scanning back to the beginning of the buffer for every function. To
1080 speed this up, Emacs was changed to assume that any `(' (or other
1081 character assigned the syntactic class of opening-delimiter) at the
1082 left margin is the start of a defun. This heuristic is nearly always
1083 right; however, it mandates the convention described above.
1086 File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
1088 Indentation for Programs
1089 ========================
1091 The best way to keep a program properly indented ("ground") is to
1092 use Emacs to re-indent it as you change the program. Emacs has commands
1093 to indent properly either a single line, a specified number of lines, or
1094 all of the lines inside a single parenthetical grouping.
1099 * Multi-line Indent:: Commands to reindent many lines at once.
1100 * Lisp Indent:: Specifying how each Lisp function should be indented.
1101 * C Indent:: Choosing an indentation style for C code.
1104 File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
1106 Basic Program Indentation Commands
1107 ----------------------------------
1110 Adjust indentation of current line.
1113 Equivalent to <RET> followed by <TAB> (`newline-and-indent').
1115 The basic indentation command is <TAB>, which gives the current line
1116 the correct indentation as determined from the previous lines. The
1117 function that <TAB> runs depends on the major mode; it is
1118 `lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
1119 functions understand different syntaxes for different languages, but
1120 they all do about the same thing. <TAB> in any programming language
1121 major mode inserts or deletes whitespace at the beginning of the
1122 current line, independent of where point is in the line. If point is
1123 inside the whitespace at the beginning of the line, <TAB> leaves it at
1124 the end of that whitespace; otherwise, <TAB> leaves point fixed with
1125 respect to the characters around it.
1127 Use `C-q <TAB>' to insert a tab at point.
1129 When entering a large amount of new code, use <LFD>
1130 (`newline-and-indent'), which is equivalent to a <RET> followed by a
1131 <TAB>. <LFD> creates a blank line, then gives it the appropriate
1134 <TAB> indents the second and following lines of the body of a
1135 parenthetical grouping each under the preceding one; therefore, if you
1136 alter one line's indentation to be nonstandard, the lines below tend to
1137 follow it. This is the right behavior in cases where the standard
1138 result of <TAB> does not look good.
1140 Remember that Emacs assumes that an open-parenthesis, open-brace, or
1141 other opening delimiter at the left margin (including the indentation
1142 routines) is the start of a function. You should therefore never have
1143 an opening delimiter in column zero that is not the beginning of a
1144 function, not even inside a string. This restriction is vital for
1145 making the indentation commands fast. *Note Defuns::, for more
1146 information on this behavior.
1149 File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
1151 Indenting Several Lines
1152 -----------------------
1154 Several commands are available to re-indent several lines of code
1155 which have been altered or moved to a different level in a list
1159 Re-indent all the lines within one list (`indent-sexp').
1162 Shift an entire list rigidly sideways so that its first line is
1166 Re-indent all lines in the region (`indent-region').
1168 To re-indent the contents of a single list, position point before the
1169 beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
1170 Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
1171 functions in other modes. The indentation of the line the sexp starts
1172 on is not changed; therefore, only the relative indentation within the
1173 list, and not its position, is changed. To correct the position as
1174 well, type a <TAB> before `C-M-q'.
1176 If the relative indentation within a list is correct but the
1177 indentation of its beginning is not, go to the line on which the list
1178 begins and type `C-u <TAB>'. When you give <TAB> a numeric argument,
1179 it moves all the lines in the group, starting on the current line,
1180 sideways the same amount that the current line moves. The command does
1181 not move lines that start inside strings, or C preprocessor lines when
1184 Another way to specify a range to be re-indented is with point and
1185 mark. The command `C-M-\' (`indent-region') applies <TAB> to every
1186 line whose first character is between point and mark.