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: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
38 Outline mode assumes that the lines in the buffer are of two types:
39 "heading lines" and "body lines". A heading line represents a topic in
40 the outline. Heading lines start with one or more stars; the number of
41 stars determines the depth of the heading in the outline structure.
42 Thus, a heading line with one star is a major topic; all the heading
43 lines with two stars between it and the next one-star heading are its
44 subtopics; and so on. Any line that is not a heading line is a body
45 line. Body lines belong to the preceding heading line. Here is an
51 which says something about the topic of food.
55 This is the body of the second-level header.
67 A second first-level topic with its header line.
69 A heading line together with all following body lines is called
70 collectively an "entry". A heading line together with all following
71 deeper heading lines and their body lines is called a "subtree".
73 You can customize the criterion for distinguishing heading lines by
74 setting the variable `outline-regexp'. Any line whose beginning has a
75 match for this regexp is considered a heading line. Matches that start
76 within a line (not at the beginning) do not count. The length of the
77 matching text determines the level of the heading; longer matches make
78 a more deeply nested level. Thus, for example, if a text formatter has
79 commands `@chapter', `@section' and `@subsection' to divide the
80 document into chapters and sections, you can make those lines count as
81 heading lines by setting `outline-regexp' to
82 `"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words
83 `chapter' and `section' are the same length, but by defining the regexp
84 to match only `chap' we ensure that the length of the text matched on a
85 chapter heading is shorter, so that Outline mode will know that
86 sections are contained in chapters. This works as long as no other
87 command starts with `@chap'.
89 Outline mode makes a line invisible by changing the newline before it
90 into an ASCII Control-M (code 015). Most editing commands that work on
91 lines treat an invisible line as part of the previous line because,
92 strictly speaking, it is part of that line, since there is no longer a
93 newline in between. When you save the file in Outline mode, Control-M
94 characters are saved as newlines, so the invisible lines become ordinary
95 lines in the file. Saving does not change the visibility status of a
99 File: xemacs.info, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode
101 Outline Motion Commands
102 .......................
104 Some special commands in Outline mode move backward and forward to
108 Move point to the next visible heading line
109 (`outline-next-visible-heading').
112 Move point to the previous visible heading line
113 (`outline-previous-visible-heading').
116 Move point to the next visible heading line at the same level as
117 the one point is on (`outline-forward-same-level').
120 Move point to the previous visible heading line at the same level
121 (`outline-backward-same-level').
124 Move point up to a lower-level (more inclusive) visible heading
125 line (`outline-up-heading').
127 `C-c C-n' (`next-visible-heading') moves down to the next heading
128 line. `C-c C-p' (`previous-visible-heading') moves similarly backward.
129 Both accept numeric arguments as repeat counts. The names emphasize
130 that invisible headings are skipped, but this is not really a special
131 feature. All editing commands that look for lines ignore the invisible
134 More advanced motion commands understand the levels of headings.
135 The commands `C-c C-f' (`outline-forward-same-level') and `C-c C-b'
136 (`outline-backward-same-level') move from one heading line to another
137 visible heading at the same depth in the outline. `C-c C-u'
138 (`outline-up-heading') moves backward to another heading that is less
142 File: xemacs.info, Node: Outline Visibility, Prev: Outline Motion, Up: Outline Mode
144 Outline Visibility Commands
145 ...........................
147 The other special commands of outline mode are used to make lines
148 visible or invisible. Their names all start with `hide' or `show'.
149 Most of them exist as pairs of opposites. They are not undoable;
150 instead, you can undo right past them. Making lines visible or
151 invisible is simply not recorded by the undo mechanism.
154 Make all body lines in the buffer invisible.
157 Make all lines in the buffer visible.
160 Make everything under this heading invisible, not including this
161 heading itself (`hide-subtree').
164 Make everything under this heading visible, including body,
165 subheadings, and their bodies (`show-subtree').
168 Make the body of this heading line, and of all its subheadings,
172 Make all subheadings of this heading line, at all levels, visible.
175 Make immediate subheadings (one level down) of this heading line
176 visible (`show-children').
179 Make this heading line's body invisible.
182 Make this heading line's body visible.
184 Two commands that are exact opposites are `M-x hide-entry' and `M-x
185 show-entry'. They are used with point on a heading line, and apply
186 only to the body lines of that heading. The subtopics and their bodies
189 Two more powerful opposites are `C-c C-h' (`hide-subtree') and `C-c
190 C-s' (`show-subtree'). Both should be used when point is on a heading
191 line, and both apply to all the lines of that heading's "subtree": its
192 body, all its subheadings, both direct and indirect, and all of their
193 bodies. In other words, the subtree contains everything following this
194 heading line, up to and not including the next heading of the same or
197 Intermediate between a visible subtree and an invisible one is having
198 all the subheadings visible but none of the body. There are two
199 commands for doing this, one that hides the bodies and one that makes
200 the subheadings visible. They are `M-x hide-leaves' and `M-x
203 A little weaker than `show-branches' is `C-c C-i' (`show-children').
204 It makes just the direct subheadings visible--those one level down.
205 Deeper subheadings remain invisible.
207 Two commands have a blanket effect on the whole file. `M-x
208 hide-body' makes all body lines invisible, so that you see just the
209 outline structure. `M-x show-all' makes all lines visible. You can
210 think of these commands as a pair of opposites even though `M-x
211 show-all' applies to more than just body lines.
213 You can turn off the use of ellipses at the ends of visible lines by
214 setting `selective-display-ellipses' to `nil'. The result is no
215 visible indication of the presence of invisible lines.
218 File: xemacs.info, Node: Words, Next: Sentences, Prev: Text Mode, Up: Text
223 Emacs has commands for moving over or operating on words. By
224 convention, the keys for them are all `Meta-' characters.
227 Move forward over a word (`forward-word').
230 Move backward over a word (`backward-word').
233 Kill up to the end of a word (`kill-word').
236 Kill back to the beginning of a word (`backward-kill-word').
239 Mark the end of the next word (`mark-word').
242 Transpose two words; drag a word forward or backward across other
243 words (`transpose-words').
245 Notice how these keys form a series that parallels the
246 character-based `C-f', `C-b', `C-d', `C-t' and <DEL>. `M-@' is related
247 to `C-@', which is an alias for `C-<SPC>'.
249 The commands `Meta-f' (`forward-word') and `Meta-b'
250 (`backward-word') move forward and backward over words. They are
251 analogous to `Control-f' and `Control-b', which move over single
252 characters. Like their `Control-' analogues, `Meta-f' and `Meta-b'
253 move several words if given an argument. `Meta-f' with a negative
254 argument moves backward, and `Meta-b' with a negative argument moves
255 forward. Forward motion stops after the last letter of the word, while
256 backward motion stops before the first letter.
258 `Meta-d' (`kill-word') kills the word after point. To be precise,
259 it kills everything from point to the place `Meta-f' would move to.
260 Thus, if point is in the middle of a word, `Meta-d' kills just the part
261 after point. If some punctuation comes between point and the next
262 word, it is killed along with the word. (To kill only the next word
263 but not the punctuation before it, simply type `Meta-f' to get to the
264 end and kill the word backwards with `Meta-<DEL>'.) `Meta-d' takes
265 arguments just like `Meta-f'.
267 `Meta-<DEL>' (`backward-kill-word') kills the word before point. It
268 kills everything from point back to where `Meta-b' would move to. If
269 point is after the space in `FOO, BAR', then `FOO, ' is killed. To
270 kill just `FOO', type `Meta-b Meta-d' instead of `Meta-<DEL>'.
272 `Meta-t' (`transpose-words') exchanges the word before or containing
273 point with the following word. The delimiter characters between the
274 words do not move. For example, transposing `FOO, BAR' results in
275 `BAR, FOO' rather than `BAR FOO,'. *Note Transpose::, for more on
276 transposition and on arguments to transposition commands.
278 To operate on the next N words with an operation which applies
279 between point and mark, you can either set the mark at point and then
280 move over the words, or you can use the command `Meta-@' (`mark-word')
281 which does not move point but sets the mark where `Meta-f' would move
282 to. It can be given arguments just like `Meta-f'.
284 The word commands' understanding of syntax is completely controlled
285 by the syntax table. For example, any character can be declared to be
286 a word delimiter. *Note Syntax::.
289 File: xemacs.info, Node: Sentences, Next: Paragraphs, Prev: Words, Up: Text
294 The Emacs commands for manipulating sentences and paragraphs are
295 mostly on `Meta-' keys, and therefore are like the word-handling
299 Move back to the beginning of the sentence (`backward-sentence').
302 Move forward to the end of the sentence (`forward-sentence').
305 Kill forward to the end of the sentence (`kill-sentence').
308 Kill back to the beginning of the sentence
309 (`backward-kill-sentence').
311 The commands `Meta-a' and `Meta-e' (`backward-sentence' and
312 `forward-sentence') move to the beginning and end of the current
313 sentence, respectively. They resemble `Control-a' and `Control-e',
314 which move to the beginning and end of a line. Unlike their
315 counterparts, `Meta-a' and `Meta-e' move over successive sentences if
316 repeated or given numeric arguments. Emacs assumes the typist's
317 convention is followed, and thus considers a sentence to end wherever
318 there is a `.', `?', or `!' followed by the end of a line or two
319 spaces, with any number of `)', `]', `'', or `"' characters allowed in
320 between. A sentence also begins or ends wherever a paragraph begins or
323 Neither `M-a' nor `M-e' moves past the newline or spaces beyond the
324 sentence edge at which it is stopping.
326 `M-a' and `M-e' have a corresponding kill command, just like `C-a'
327 and `C-e' have `C-k'. The command is `M-k' (`kill-sentence') which
328 kills from point to the end of the sentence. With minus one as an
329 argument it kills back to the beginning of the sentence. Larger
330 arguments serve as repeat counts.
332 There is a special command, `C-x <DEL>' (`backward-kill-sentence'),
333 for killing back to the beginning of a sentence, which is useful when
334 you change your mind in the middle of composing text.
336 The variable `sentence-end' controls recognition of the end of a
337 sentence. It is a regexp that matches the last few characters of a
338 sentence, together with the whitespace following the sentence. Its
341 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
343 This example is explained in the section on regexps. *Note Regexps::.
346 File: xemacs.info, Node: Paragraphs, Next: Pages, Prev: Sentences, Up: Text
351 The Emacs commands for manipulating paragraphs are also `Meta-' keys.
354 Move back to previous paragraph beginning
355 (`backward-paragraph').
358 Move forward to next paragraph end (`forward-paragraph').
361 Put point and mark around this or next paragraph
364 `Meta-[' moves to the beginning of the current or previous paragraph,
365 while `Meta-]' moves to the end of the current or next paragraph.
366 Blank lines and text formatter command lines separate paragraphs and are
367 not part of any paragraph. An indented line starts a new paragraph.
369 In major modes for programs (as opposed to Text mode), paragraphs
370 begin and end only at blank lines. As a result, the paragraph commands
371 continue to be useful even though there are no paragraphs per se.
373 When there is a fill prefix, paragraphs are delimited by all lines
374 which don't start with the fill prefix. *Note Filling::.
376 To operate on a paragraph, you can use the command `Meta-h'
377 (`mark-paragraph') to set the region around it. This command puts
378 point at the beginning and mark at the end of the paragraph point was
379 in. If point is between paragraphs (in a run of blank lines or at a
380 boundary), the paragraph following point is surrounded by point and
381 mark. If there are blank lines preceding the first line of the
382 paragraph, one of the blank lines is included in the region. Thus, for
383 example, `M-h C-w' kills the paragraph around or after point.
385 The precise definition of a paragraph boundary is controlled by the
386 variables `paragraph-separate' and `paragraph-start'. The value of
387 `paragraph-start' is a regexp that matches any line that either starts
388 or separates paragraphs. The value of `paragraph-separate' is another
389 regexp that matches only lines that separate paragraphs without being
390 part of any paragraph. Lines that start a new paragraph and are
391 contained in it must match both regexps. For example, normally
392 `paragraph-start' is `"^[ \t\n\f]"' and `paragraph-separate' is `"^[
395 Normally it is desirable for page boundaries to separate paragraphs.
396 The default values of these variables recognize the usual separator for
400 File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
405 Files are often thought of as divided into "pages" by the "formfeed"
406 character (ASCII Control-L, octal code 014). For example, if a file is
407 printed on a line printer, each "page" of the file starts on a new page
408 of paper. Emacs treats a page-separator character just like any other
409 character. It can be inserted with `C-q C-l' or deleted with <DEL>.
410 You are free to paginate your file or not. However, since pages are
411 often meaningful divisions of the file, commands are provided to move
412 over them and operate on them.
415 Move point to previous page boundary (`backward-page').
418 Move point to next page boundary (`forward-page').
421 Put point and mark around this page (or another page)
425 Count the lines in this page (`count-lines-page').
427 The `C-x [' (`backward-page') command moves point to immediately
428 after the previous page delimiter. If point is already right after a
429 page delimiter, the command skips that one and stops at the previous
430 one. A numeric argument serves as a repeat count. The `C-x ]'
431 (`forward-page') command moves forward past the next page delimiter.
433 The `C-x C-p' command (`mark-page') puts point at the beginning of
434 the current page and the mark at the end. The page delimiter at the end
435 is included (the mark follows it). The page delimiter at the front is
436 excluded (point follows it). You can follow this command by `C-w' to
437 kill a page you want to move elsewhere. If you insert the page after a
438 page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
439 page will be properly delimited before and after once again.
441 A numeric argument to `C-x C-p' is used to specify which page to go
442 to, relative to the current one. Zero means the current page. One
443 means the next page, and -1 means the previous one.
445 The `C-x l' command (`count-lines-page') can help you decide where
446 to break a page in two. It prints the total number of lines in the
447 current page in the echo area, then divides the lines into those
448 preceding the current line and those following it, for example
450 Page has 96 (72+25) lines
452 Notice that the sum is off by one; this is correct if point is not at
453 the beginning of a line.
455 The variable `page-delimiter' should have as its value a regexp that
456 matches the beginning of a line that separates pages. This defines
457 where pages begin. The normal value of this variable is `"^\f"', which
458 matches a formfeed character at the beginning of a line.
461 File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text
466 If you use Auto Fill mode, Emacs "fills" text (breaks it up into
467 lines that fit in a specified width) as you insert it. When you alter
468 existing text it is often no longer be properly filled afterwards and
469 you can use explicit commands for filling.
473 * Auto Fill:: Auto Fill mode breaks long lines automatically.
474 * Fill Commands:: Commands to refill paragraphs and center lines.
475 * Fill Prefix:: Filling when every line is indented or in a comment, etc.
478 File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
483 "Auto Fill" mode is a minor mode in which lines are broken
484 automatically when they become too wide. Breaking happens only when
485 you type a <SPC> or <RET>.
488 Enable or disable Auto Fill mode.
492 In Auto Fill mode, break lines when appropriate.
494 `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
495 if it was on. With a positive numeric argument the command always turns
496 Auto Fill mode on, and with a negative argument it always turns it off.
497 The presence of the word `Fill' in the mode line, inside the
498 parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode
499 is a minor mode; you can turn it on or off for each buffer individually.
502 In Auto Fill mode, lines are broken automatically at spaces when
503 they get longer than desired. Line breaking and rearrangement takes
504 place only when you type <SPC> or <RET>. To insert a space or newline
505 without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
506 (recall that a newline is really a linefeed). `C-o' inserts a newline
507 without line breaking.
509 Auto Fill mode works well with Lisp mode: when it makes a new line in
510 Lisp mode, it indents that line with <TAB>. If a line ending in a Lisp
511 comment gets too long, the text of the comment is split into two
512 comment lines. Optionally, new comment delimiters are inserted at the
513 end of the first line and the beginning of the second, so that each line
514 is a separate comment. The variable `comment-multi-line' controls the
515 choice (*note Comments::).
517 Auto Fill mode does not refill entire paragraphs. It can break
518 lines but cannot merge lines. Editing in the middle of a paragraph can
519 result in a paragraph that is not correctly filled. The easiest way to
520 make the paragraph properly filled again is using an explicit fill
523 Many users like Auto Fill mode and want to use it in all text files.
524 The section on init files explains how you can arrange this permanently
525 for yourself. *Note Init File::.
528 File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
530 Explicit Fill Commands
531 ----------------------
534 Fill current paragraph (`fill-paragraph').
537 Fill each paragraph in the region (`fill-region').
540 Set the fill column (`set-fill-column').
542 `M-x fill-region-as-paragraph'
543 Fill the region, considering it as one paragraph.
548 To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
549 It causes the paragraph containing point, or the one after point if
550 point is between paragraphs, to be refilled. All line breaks are
551 removed, and new ones are inserted where necessary. `M-q' can be
552 undone with `C-_'. *Note Undo::.
554 To refill many paragraphs, use `M-g' (`fill-region'), which divides
555 the region into paragraphs and fills each of them.
557 `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
558 paragraph boundaries (*note Paragraphs::). For more control, you can
559 use `M-x fill-region-as-paragraph', which refills everything between
560 point and mark. This command recognizes only blank lines as paragraph
563 A numeric argument to `M-g' or `M-q' causes it to "justify" the text
564 as well as filling it. Extra spaces are inserted to make the right
565 margin line up exactly at the fill column. To remove the extra spaces,
566 use `M-q' or `M-g' with no argument.
568 The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
569 match lines that should not be auto-filled.
571 The command `Meta-s' (`center-line') centers the current line within
572 the current fill column. With an argument, it centers several lines
573 individually and moves past them.
575 The maximum line width for filling is in the variable `fill-column'.
576 Altering the value of `fill-column' makes it local to the current
577 buffer; until then, the default value--initially 70--is in effect.
580 The easiest way to set `fill-column' is to use the command `C-x f'
581 (`set-fill-column'). With no argument, it sets `fill-column' to the
582 current horizontal position of point. With a numeric argument, it uses
583 that number as the new fill column.
586 File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
591 To fill a paragraph in which each line starts with a special marker
592 (which might be a few spaces, giving an indented paragraph), use the
593 "fill prefix" feature. The fill prefix is a string which is not
594 included in filling. Emacs expects every line to start with a fill
598 Set the fill prefix (`set-fill-prefix').
601 Fill a paragraph using current fill prefix (`fill-paragraph').
603 `M-x fill-individual-paragraphs'
604 Fill the region, considering each change of indentation as
605 starting a new paragraph.
607 To specify a fill prefix, move to a line that starts with the desired
608 prefix, put point at the end of the prefix, and give the command
609 `C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
610 off the fill prefix, specify an empty prefix: type `C-x .' with point
611 at the beginning of a line.
613 When a fill prefix is in effect, the fill commands remove the fill
614 prefix from each line before filling and insert it on each line after
615 filling. Auto Fill mode also inserts the fill prefix inserted on new
616 lines it creates. Lines that do not start with the fill prefix are
617 considered to start paragraphs, both in `M-q' and the paragraph
618 commands; this is just right if you are using paragraphs with hanging
619 indentation (every line indented except the first one). Lines which are
620 blank or indented once the prefix is removed also separate or start
621 paragraphs; this is what you want if you are writing multi-paragraph
622 comments with a comment delimiter on each line.
624 The fill prefix is stored in the variable `fill-prefix'. Its value
625 is a string, or `nil' when there is no fill prefix. This is a
626 per-buffer variable; altering the variable affects only the current
627 buffer, but there is a default value which you can change as well.
630 Another way to use fill prefixes is through `M-x
631 fill-individual-paragraphs'. This function divides the region into
632 groups of consecutive lines with the same amount and kind of
633 indentation and fills each group as a paragraph, using its indentation
637 File: xemacs.info, Node: Case, Prev: Filling, Up: Text
639 Case Conversion Commands
640 ========================
642 Emacs has commands for converting either a single word or any
643 arbitrary range of text to upper case or to lower case.
646 Convert following word to lower case (`downcase-word').
649 Convert following word to upper case (`upcase-word').
652 Capitalize the following word (`capitalize-word').
655 Convert region to lower case (`downcase-region').
658 Convert region to upper case (`upcase-region').
660 The word conversion commands are used most frequently. `Meta-l'
661 (`downcase-word') converts the word after point to lower case, moving
662 past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
663 (`upcase-word') converts to all capitals instead, while `Meta-c'
664 (`capitalize-word') puts the first letter of the word into upper case
665 and the rest into lower case. The word conversion commands convert
666 several words at once if given an argument. They are especially
667 convenient for converting a large amount of text from all upper case to
668 mixed case: you can move through the text using `M-l', `M-u', or `M-c'
669 on each word as appropriate, occasionally using `M-f' instead to skip a
672 When given a negative argument, the word case conversion commands
673 apply to the appropriate number of words before point, but do not move
674 point. This is convenient when you have just typed a word in the wrong
675 case: you can give the case conversion command and continue typing.
677 If a word case conversion command is given in the middle of a word,
678 it applies only to the part of the word which follows point. This is
679 just like what `Meta-d' (`kill-word') does. With a negative argument,
680 case conversion applies only to the part of the word before point.
682 The other case conversion commands are `C-x C-u' (`upcase-region')
683 and `C-x C-l' (`downcase-region'), which convert everything between
684 point and mark to the specified case. Point and mark do not move.
687 File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top
692 Emacs has many commands designed to understand the syntax of
693 programming languages such as Lisp and C. These commands can:
695 * Move over or kill balanced expressions or "sexps" (*note Lists::).
697 * Move over or mark top-level balanced expressions ("defuns", in
698 Lisp; functions, in C).
700 * Show how parentheses balance (*note Matching::).
702 * Insert, kill, or align comments (*note Comments::).
704 * Follow the usual indentation conventions of the language (*note
707 The commands available for words, sentences, and paragraphs are
708 useful in editing code even though their canonical application is for
709 editing human language text. Most symbols contain words (*note
710 Words::); sentences can be found in strings and comments (*note
711 Sentences::). Paragraphs per se are not present in code, but the
712 paragraph commands are useful anyway, because Lisp mode and C mode
713 define paragraphs to begin and end at blank lines (*note Paragraphs::).
714 Judicious use of blank lines to make the program clearer also provides
715 interesting chunks of text for the paragraph commands to work on.
717 The selective display feature is useful for looking at the overall
718 structure of a function (*note Selective Display::). This feature
719 causes only the lines that are indented less than a specified amount to
720 appear on the screen.
724 * Program Modes:: Major modes for editing programs.
725 * Lists:: Expressions with balanced parentheses.
726 There are editing commands to operate on them.
727 * Defuns:: Each program is made up of separate functions.
728 There are editing commands to operate on them.
729 * Grinding:: Adjusting indentation to show the nesting.
730 * Matching:: Insertion of a close-delimiter flashes matching open.
731 * Comments:: Inserting, illing and aligning comments.
732 * Balanced Editing:: Inserting two matching parentheses at once, etc.
733 * Lisp Completion:: Completion on symbol names in Lisp code.
734 * Documentation:: Getting documentation of functions you plan to call.
735 * Change Log:: Maintaining a change history for your program.
736 * Tags:: Go direct to any function in your program in one
737 command. Tags remembers which file it is in.
738 * Fortran:: Fortran mode and its special features.
739 * Asm Mode:: Asm mode and its special features.
742 File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
744 Major Modes for Programming Languages
745 =====================================
747 Emacs has several major modes for the programming languages Lisp,
748 Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major
749 mode should be implemented for each programming language you might want
750 to edit with Emacs; but often the mode for one language can serve for
751 other syntactically similar languages. The language modes that exist
752 are those that someone decided to take the trouble to write.
754 There are several variants of Lisp mode, which differ in the way they
755 interface to Lisp execution. *Note Lisp Modes::.
757 Each of the programming language modes defines the <TAB> key to run
758 an indentation function that knows the indentation conventions of that
759 language and updates the current line's indentation accordingly. For
760 example, in C mode <TAB> is bound to `c-indent-line'. <LFD> is
761 normally defined to do <RET> followed by <TAB>; thus it, too, indents
762 in a mode-specific fashion.
764 In most programming languages, indentation is likely to vary from
765 line to line. So the major modes for those languages rebind <DEL> to
766 treat a tab as if it were the equivalent number of spaces (using the
767 command `backward-delete-char-untabify'). This makes it possible to
768 rub out indentation one column at a time without worrying whether it is
769 made up of spaces or tabs. In these modes, use `C-b C-d' to delete a
770 tab character before point.
772 Programming language modes define paragraphs to be separated only by
773 blank lines, so that the paragraph commands remain useful. Auto Fill
774 mode, if enabled in a programming language major mode, indents the new
775 lines which it creates.
777 Turning on a major mode calls a user-supplied function called the
778 "mode hook", which is the value of a Lisp variable. For example,
779 turning on C mode calls the value of the variable `c-mode-hook' if that
780 value exists and is non-`nil'. Mode hook variables for other
781 programming language modes include `lisp-mode-hook',
782 `emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
783 `scheme-mode-hook', and `muddle-mode-hook'. The mode hook function
784 receives no arguments.
787 File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
792 By convention, Emacs keys for dealing with balanced expressions are
793 usually `Control-Meta-' characters. They tend to be analogous in
794 function to their `Control-' and `Meta-' equivalents. These commands
795 are usually thought of as pertaining to expressions in programming
796 languages, but can be useful with any language in which some sort of
797 parentheses exist (including English).
799 The commands fall into two classes. Some commands deal only with
800 "lists" (parenthetical groupings). They see nothing except
801 parentheses, brackets, braces (depending on what must balance in the
802 language you are working with), and escape characters that might be used
805 The other commands deal with expressions or "sexps". The word `sexp'
806 is derived from "s-expression", the term for a symbolic expression in
807 Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It
808 refers to an expression in the language your program is written in.
809 Each programming language has its own major mode, which customizes the
810 syntax tables so that expressions in that language count as sexps.
812 Sexps typically include symbols, numbers, and string constants, as
813 well as anything contained in parentheses, brackets, or braces.
815 In languages that use prefix and infix operators, such as C, it is
816 not possible for all expressions to be sexps. For example, C mode does
817 not recognize `foo + bar' as an sexp, even though it is a C expression;
818 it recognizes `foo' as one sexp and `bar' as another, with the `+' as
819 punctuation between them. This is a fundamental ambiguity: both `foo +
820 bar' and `foo' are legitimate choices for the sexp to move over if
821 point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
823 Some languages have obscure forms of syntax for expressions that
824 nobody has bothered to make Emacs understand properly.
827 Move forward over an sexp (`forward-sexp').
830 Move backward over an sexp (`backward-sexp').
833 Kill sexp forward (`kill-sexp').
836 Move up and backward in list structure (`backward-up-list').
839 Move down and forward in list structure (`down-list').
842 Move forward over a list (`forward-list').
845 Move backward over a list (`backward-list').
848 Transpose expressions (`transpose-sexps').
851 Put mark after following expression (`mark-sexp').
853 To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the
854 first significant character after point is an opening delimiter (`(' in
855 Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
856 delimiter. If the character begins a symbol, string, or number,
857 `C-M-f' moves over that. If the character after point is a closing
858 delimiter, `C-M-f' just moves past it. (This last is not really moving
859 across an sexp; it is an exception which is included in the definition
860 of `C-M-f' because it is as useful a behavior as anyone can think of
863 The command `C-M-b' (`backward-sexp') moves backward over a sexp.
864 The detailed rules are like those above for `C-M-f', but with
865 directions reversed. If there are any prefix characters (single quote,
866 back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
869 `C-M-f' or `C-M-b' with an argument repeats that operation the
870 specified number of times; with a negative argument, it moves in the
873 In languages such as C where the comment-terminator can be
874 recognized, the sexp commands move across comments as if they were
875 whitespace. In Lisp and other languages where comments run until the
876 end of a line, it is very difficult to ignore comments when parsing
877 backwards; therefore, in such languages the sexp commands treat the
878 text of comments as if it were code.
880 Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
881 `C-M-k' kills the characters that `C-M-f' would move over.
883 The "list commands", `C-M-n' (`forward-list') and `C-M-p'
884 (`backward-list'), move over lists like the sexp commands but skip over
885 any number of other kinds of sexps (symbols, strings, etc). In some
886 situations, these commands are useful because they usually ignore
887 comments, since the comments usually do not contain any lists.
889 `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
890 is possible. To move up one (or N) levels, use `C-M-u'
891 (`backward-up-list'). `C-M-u' moves backward up past one unmatched
892 opening delimiter. A positive argument serves as a repeat count; a
893 negative argument reverses direction of motion and also requests
894 repetition, so it moves forward and up one or more levels.
896 To move down in list structure, use `C-M-d' (`down-list'). In Lisp
897 mode, where `(' is the only opening delimiter, this is nearly the same
898 as searching for a `('. An argument specifies the number of levels of
899 parentheses to go down.
901 `C-M-t' (`transpose-sexps') drags the previous sexp across the next
902 one. An argument serves as a repeat count, and a negative argument
903 drags backwards (thus canceling out the effect of `C-M-t' with a
904 positive argument). An argument of zero, rather than doing nothing,
905 transposes the sexps ending after point and the mark.
907 To make the region be the next sexp in the buffer, use `C-M-@'
908 (`mark-sexp') which sets the mark at the same place that `C-M-f' would
909 move to. `C-M-@' takes arguments like `C-M-f'. In particular, a
910 negative argument is useful for putting the mark at the beginning of
913 The list and sexp commands' understanding of syntax is completely
914 controlled by the syntax table. Any character can, for example, be
915 declared to be an opening delimiter and act like an open parenthesis.
919 File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
924 In Emacs, a parenthetical grouping at the top level in the buffer is
925 called a "defun". The name derives from the fact that most top-level
926 lists in Lisp are instances of the special form `defun', but Emacs
927 calls any top-level parenthetical grouping counts a defun regardless of
928 its contents or the programming language. For example, in C, the body
929 of a function definition is a defun.
932 Move to beginning of current or preceding defun
933 (`beginning-of-defun').
936 Move to end of current or following defun (`end-of-defun').
939 Put region around whole current or following defun (`mark-defun').
941 The commands to move to the beginning and end of the current defun
942 are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
944 To operate on the current defun, use `C-M-h' (`mark-defun') which
945 puts point at the beginning and the mark at the end of the current or
946 next defun. This is the easiest way to prepare for moving the defun to
947 a different place. In C mode, `C-M-h' runs the function
948 `mark-c-function', which is almost the same as `mark-defun', but which
949 backs up over the argument declarations, function name, and returned
950 data type so that the entire C function is inside the region.
952 To compile and evaluate the current defun, use `M-x compile-defun'.
953 This function prints the results in the minibuffer. If you include an
954 argument, it inserts the value in the current buffer after the defun.
956 Emacs assumes that any open-parenthesis found in the leftmost column
957 is the start of a defun. Therefore, never put an open-parenthesis at
958 the left margin in a Lisp file unless it is the start of a top level
959 list. Never put an open-brace or other opening delimiter at the
960 beginning of a line of C code unless it starts the body of a function.
961 The most likely problem case is when you want an opening delimiter at
962 the start of a line inside a string. To avoid trouble, put an escape
963 character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
964 before the opening delimiter. It will not affect the contents of the
967 The original Emacs found defuns by moving upward a level of
968 parentheses until there were no more levels to go up. This required
969 scanning back to the beginning of the buffer for every function. To
970 speed this up, Emacs was changed to assume that any `(' (or other
971 character assigned the syntactic class of opening-delimiter) at the
972 left margin is the start of a defun. This heuristic is nearly always
973 right; however, it mandates the convention described above.
976 File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
978 Indentation for Programs
979 ========================
981 The best way to keep a program properly indented ("ground") is to
982 use Emacs to re-indent it as you change the program. Emacs has commands
983 to indent properly either a single line, a specified number of lines, or
984 all of the lines inside a single parenthetical grouping.
989 * Multi-line Indent:: Commands to reindent many lines at once.
990 * Lisp Indent:: Specifying how each Lisp function should be indented.
991 * C Indent:: Choosing an indentation style for C code.
994 File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
996 Basic Program Indentation Commands
997 ----------------------------------
1000 Adjust indentation of current line.
1003 Equivalent to <RET> followed by <TAB> (`newline-and-indent').
1005 The basic indentation command is <TAB>, which gives the current line
1006 the correct indentation as determined from the previous lines. The
1007 function that <TAB> runs depends on the major mode; it is
1008 `lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
1009 functions understand different syntaxes for different languages, but
1010 they all do about the same thing. <TAB> in any programming language
1011 major mode inserts or deletes whitespace at the beginning of the
1012 current line, independent of where point is in the line. If point is
1013 inside the whitespace at the beginning of the line, <TAB> leaves it at
1014 the end of that whitespace; otherwise, <TAB> leaves point fixed with
1015 respect to the characters around it.
1017 Use `C-q <TAB>' to insert a tab at point.
1019 When entering a large amount of new code, use <LFD>
1020 (`newline-and-indent'), which is equivalent to a <RET> followed by a
1021 <TAB>. <LFD> creates a blank line, then gives it the appropriate
1024 <TAB> indents the second and following lines of the body of a
1025 parenthetical grouping each under the preceding one; therefore, if you
1026 alter one line's indentation to be nonstandard, the lines below tend to
1027 follow it. This is the right behavior in cases where the standard
1028 result of <TAB> does not look good.
1030 Remember that Emacs assumes that an open-parenthesis, open-brace, or
1031 other opening delimiter at the left margin (including the indentation
1032 routines) is the start of a function. You should therefore never have
1033 an opening delimiter in column zero that is not the beginning of a
1034 function, not even inside a string. This restriction is vital for
1035 making the indentation commands fast. *Note Defuns::, for more
1036 information on this behavior.
1039 File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
1041 Indenting Several Lines
1042 -----------------------
1044 Several commands are available to re-indent several lines of code
1045 which have been altered or moved to a different level in a list
1049 Re-indent all the lines within one list (`indent-sexp').
1052 Shift an entire list rigidly sideways so that its first line is
1056 Re-indent all lines in the region (`indent-region').
1058 To re-indent the contents of a single list, position point before the
1059 beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
1060 Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
1061 functions in other modes. The indentation of the line the sexp starts
1062 on is not changed; therefore, only the relative indentation within the
1063 list, and not its position, is changed. To correct the position as
1064 well, type a <TAB> before `C-M-q'.
1066 If the relative indentation within a list is correct but the
1067 indentation of its beginning is not, go to the line on which the list
1068 begins and type `C-u <TAB>'. When you give <TAB> a numeric argument,
1069 it moves all the lines in the group, starting on the current line,
1070 sideways the same amount that the current line moves. The command does
1071 not move lines that start inside strings, or C preprocessor lines when
1074 Another way to specify a range to be re-indented is with point and
1075 mark. The command `C-M-\' (`indent-region') applies <TAB> to every
1076 line whose first character is between point and mark.
1079 File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding
1081 Customizing Lisp Indentation
1082 ----------------------------
1084 The indentation pattern for a Lisp expression can depend on the
1085 function called by the expression. For each Lisp function, you can
1086 choose among several predefined patterns of indentation, or define an
1087 arbitrary one with a Lisp program.
1089 The standard pattern of indentation is as follows: the second line
1090 of the expression is indented under the first argument, if that is on
1091 the same line as the beginning of the expression; otherwise, the second
1092 line is indented underneath the function name. Each following line is
1093 indented under the previous line whose nesting depth is the same.
1095 If the variable `lisp-indent-offset' is non-`nil', it overrides the
1096 usual indentation pattern for the second line of an expression, so that
1097 such lines are always indented `lisp-indent-offset' more columns than
1098 the containing list.
1100 Certain functions override the standard pattern. Functions whose
1101 names start with `def' always indent the second line by
1102 `lisp-body-indention' extra columns beyond the open-parenthesis
1103 starting the expression.
1105 Individual functions can override the standard pattern in various
1106 ways, according to the `lisp-indent-function' property of the function
1107 name. (Note: `lisp-indent-function' was formerly called
1108 `lisp-indent-hook'). There are four possibilities for this property:
1111 This is the same as no property; the standard indentation pattern
1115 The pattern used for function names that start with `def' is used
1116 for this function also.
1119 The first NUMBER arguments of the function are "distinguished"
1120 arguments; the rest are considered the "body" of the expression.
1121 A line in the expression is indented according to whether the
1122 first argument on it is distinguished or not. If the argument is
1123 part of the body, the line is indented `lisp-body-indent' more
1124 columns than the open-parenthesis starting the containing
1125 expression. If the argument is distinguished and is either the
1126 first or second argument, it is indented twice that many extra
1127 columns. If the argument is distinguished and not the first or
1128 second argument, the standard pattern is followed for that line.
1131 SYMBOL should be a function name; that function is called to
1132 calculate the indentation of a line within this expression. The
1133 function receives two arguments:
1135 The value returned by `parse-partial-sexp' (a Lisp primitive
1136 for indentation and nesting computation) when it parses up to
1137 the beginning of this line.
1140 The position at which the line being indented begins.
1142 It should return either a number, which is the number of columns of
1143 indentation for that line, or a list whose first element is such a
1144 number. The difference between returning a number and returning a
1145 list is that a number says that all following lines at the same
1146 nesting level should be indented just like this one; a list says
1147 that following lines might call for different indentations. This
1148 makes a difference when the indentation is computed by `C-M-q'; if
1149 the value is a number, `C-M-q' need not recalculate indentation
1150 for the following lines until the end of the list.
projects / chise / xemacs-chise.git- / blob