1 @c -*- coding: utf-8 -*-
2 @c This is part of the Emacs manual.
3 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software
5 @c See file emacs.texi for copying conditions.
7 @chapter Commands for Human Languages
9 @cindex manipulating text
11 This chapter describes Emacs commands that act on @dfn{text}, by
12 which we mean sequences of characters in a human language (as opposed
13 to, say, a computer programming language). These commands act in ways
14 that take into account the syntactic and stylistic conventions of
15 human languages: conventions involving words, sentences, paragraphs,
16 and capital letters. There are also commands for @dfn{filling}, which
17 means rearranging the lines of a paragraph to be approximately equal
18 in length. These commands, while intended primarily for editing text,
19 are also often useful for editing programs.
21 Emacs has several major modes for editing human-language text. If
22 the file contains ordinary text, use Text mode, which customizes Emacs
23 in small ways for the syntactic conventions of text. Outline mode
24 provides special commands for operating on text with an outline
25 structure. @xref{Outline Mode}.
27 Org mode extends Outline mode and turns Emacs into a full-fledged
28 organizer: you can manage TODO lists, store notes and publish them in
31 @xref{Top, The Org Manual,,org, The Org Manual}.
34 See the Org Info manual, which is distributed with Emacs.
37 Emacs has other major modes for text which contains embedded
38 commands, such as @TeX{} and @LaTeX{} (@pxref{TeX Mode}); HTML and
39 SGML (@pxref{HTML Mode}); XML
41 (@pxref{Top,The nXML Mode Manual,,nxml-mode, nXML Mode});
44 (see the nXML mode Info manual, which is distributed with Emacs);
46 and Groff and Nroff (@pxref{Nroff Mode}).
49 If you need to edit ASCII art pictures made out of text characters,
50 use Picture mode, a special major mode for editing such pictures.
52 @xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}.
62 @cindex automatic typing
63 The automatic typing features may be useful when writing text.
64 @inforef{Top,The Autotype Manual,autotype}.
68 * Words:: Moving over and killing words.
69 * Sentences:: Moving over and killing sentences.
70 * Paragraphs:: Moving over paragraphs.
71 * Pages:: Moving over pages.
72 * Quotation Marks:: Inserting quotation marks.
73 * Filling:: Filling or justifying text.
74 * Case:: Changing the case of text.
75 * Text Mode:: The major modes for editing text files.
76 * Outline Mode:: Editing outlines.
77 * Org Mode:: The Emacs organizer.
78 * TeX Mode:: Editing TeX and LaTeX files.
79 * HTML Mode:: Editing HTML and SGML files.
80 * Nroff Mode:: Editing input to the nroff formatter.
81 * Enriched Text:: Editing text enriched with fonts, colors, etc.
82 * Text Based Tables:: Commands for editing text-based tables.
83 * Two-Column:: Splitting text columns into separate windows.
89 @cindex Meta commands and words
91 Emacs defines several commands for moving over or operating on
96 Move forward over a word (@code{forward-word}).
98 Move backward over a word (@code{backward-word}).
100 Kill up to the end of a word (@code{kill-word}).
102 Kill back to the beginning of a word (@code{backward-kill-word}).
104 Set mark at the end of the next word (@code{mark-word}).
106 Transpose two words or drag a word across others
107 (@code{transpose-words}).
110 Notice how these keys form a series that parallels the character-based
111 @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is
112 cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
117 @findex backward-word
118 The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b}
119 (@code{backward-word}) move forward and backward over words. These
120 @key{META}-based key sequences are analogous to the key sequences
121 @kbd{C-f} and @kbd{C-b}, which move over single characters. The
122 analogy extends to numeric arguments, which serve as repeat counts.
123 @kbd{M-f} with a negative argument moves backward, and @kbd{M-b} with
124 a negative argument moves forward. Forward motion stops right after
125 the last letter of the word, while backward motion stops right before
130 @kbd{M-d} (@code{kill-word}) kills the word after point. To be
131 precise, it kills everything from point to the place @kbd{M-f} would
132 move to. Thus, if point is in the middle of a word, @kbd{M-d} kills
133 just the part after point. If some punctuation comes between point
134 and the next word, it is killed along with the word. (If you wish to
135 kill only the next word but not the punctuation before it, simply do
136 @kbd{M-f} to get the end, and kill the word backwards with
137 @kbd{M-@key{DEL}}.) @kbd{M-d} takes arguments just like @kbd{M-f}.
139 @findex backward-kill-word
141 @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
142 point. It kills everything from point back to where @kbd{M-b} would
143 move to. For instance, if point is after the space in @w{@samp{FOO,
144 BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just
145 @samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead
146 of @kbd{M-@key{DEL}}.
148 @c Don't index M-t and transpose-words here, they are indexed in
149 @c fixit.texi, in the node "Transpose".
151 @c @findex transpose-words
152 @kbd{M-t} (@code{transpose-words}) exchanges the word before or
153 containing point with the following word. The delimiter characters between
154 the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
155 @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
156 more on transposition.
159 To operate on words with an operation which acts on the region, use
160 the command @kbd{M-@@} (@code{mark-word}). This command sets the mark
161 where @kbd{M-f} would move to. @xref{Marking Objects}, for more
162 information about this command.
164 The word commands' understanding of word boundaries is controlled by
165 the syntax table. Any character can, for example, be declared to be a
166 word delimiter. @xref{Syntax Tables,, Syntax Tables, elisp, The Emacs
167 Lisp Reference Manual}.
169 In addition, see @ref{Position Info} for the @kbd{M-=}
170 (@code{count-words-region}) and @kbd{M-x count-words} commands, which
171 count and report the number of words in the region or buffer.
176 @cindex manipulating sentences
178 The Emacs commands for manipulating sentences and paragraphs are
179 mostly on Meta keys, like the word-handling commands.
183 Move back to the beginning of the sentence (@code{backward-sentence}).
185 Move forward to the end of the sentence (@code{forward-sentence}).
187 Kill forward to the end of the sentence (@code{kill-sentence}).
189 Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
194 @findex backward-sentence
195 @findex forward-sentence
196 The commands @kbd{M-a} (@code{backward-sentence}) and @kbd{M-e}
197 (@code{forward-sentence}) move to the beginning and end of the current
198 sentence, respectively. Their bindings were chosen to resemble
199 @kbd{C-a} and @kbd{C-e}, which move to the beginning and end of a
200 line. Unlike them, @kbd{M-a} and @kbd{M-e} move over successive
201 sentences if repeated.
203 Moving backward over a sentence places point just before the first
204 character of the sentence; moving forward places point right after the
205 punctuation that ends the sentence. Neither one moves over the
206 whitespace at the sentence boundary.
209 @findex kill-sentence
210 Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to
211 go with them, @kbd{M-a} and @kbd{M-e} have a corresponding kill
212 command: @kbd{M-k} (@code{kill-sentence}) kills from point to the end
213 of the sentence. With a positive numeric argument @var{n}, it kills
214 the next @var{n} sentences; with a negative argument @minus{}@var{n},
215 it kills back to the beginning of the @var{n}th preceding sentence.
218 @findex backward-kill-sentence
219 The @kbd{C-x @key{DEL}} (@code{backward-kill-sentence}) kills back
220 to the beginning of a sentence.
222 The sentence commands assume that you follow the American typist's
223 convention of putting two spaces at the end of a sentence. That is, a
224 sentence ends wherever there is a @samp{.}, @samp{?} or @samp{!}
225 followed by the end of a line or two spaces, with any number of
226 @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in
227 between. A sentence also begins or ends wherever a paragraph begins
228 or ends. It is useful to follow this convention, because it allows
229 the Emacs sentence commands to distinguish between periods that end a
230 sentence and periods that indicate abbreviations.
232 @vindex sentence-end-double-space
233 If you want to use just one space between sentences, you can set the
234 variable @code{sentence-end-double-space} to @code{nil} to make the
235 sentence commands stop for single spaces. However, this has a
236 drawback: there is no way to distinguish between periods that end
237 sentences and those that indicate abbreviations. For convenient and
238 reliable editing, we therefore recommend you follow the two-space
239 convention. The variable @code{sentence-end-double-space} also
240 affects filling (@pxref{Fill Commands}).
243 The variable @code{sentence-end} controls how to recognize the end
244 of a sentence. If non-@code{nil}, its value should be a regular
245 expression, which is used to match the last few characters of a
246 sentence, together with the whitespace following the sentence
247 (@pxref{Regexps}). If the value is @code{nil}, the default, then
248 Emacs computes sentence ends according to various criteria such as the
249 value of @code{sentence-end-double-space}.
251 @vindex sentence-end-without-period
252 Some languages, such as Thai, do not use periods to indicate the end
253 of a sentence. Set the variable @code{sentence-end-without-period} to
254 @code{t} in such cases.
259 @cindex manipulating paragraphs
261 The Emacs commands for manipulating paragraphs are also on Meta keys.
265 Move back to previous paragraph beginning (@code{backward-paragraph}).
267 Move forward to next paragraph end (@code{forward-paragraph}).
269 Put point and mark around this or next paragraph (@code{mark-paragraph}).
274 @findex backward-paragraph
275 @findex forward-paragraph
276 @kbd{M-@{} (@code{backward-paragraph}) moves to the beginning of the
277 current or previous paragraph (see below for the definition of a
278 paragraph). @kbd{M-@}} (@code{forward-paragraph}) moves to the end of
279 the current or next paragraph. If there is a blank line before the
280 paragraph, @kbd{M-@{} moves to the blank line.
283 @findex mark-paragraph
284 When you wish to operate on a paragraph, type @kbd{M-h}
285 (@code{mark-paragraph}) to set the region around it. For example,
286 @kbd{M-h C-w} kills the paragraph around or after point. @kbd{M-h}
287 puts point at the beginning and mark at the end of the paragraph point
288 was in. If point is between paragraphs (in a run of blank lines, or
289 at a boundary), @kbd{M-h} sets the region around the paragraph
290 following point. If there are blank lines preceding the first line of
291 the paragraph, one of these blank lines is included in the region. If
292 the region is already active, the command sets the mark without
293 changing point, and each subsequent @kbd{M-h} further advances the
294 mark by one paragraph.
296 The definition of a paragraph depends on the major mode. In
297 Fundamental mode, as well as Text mode and related modes, a paragraph
298 is separated from neighboring paragraphs by one or more
299 @dfn{blank lines}---lines that are either empty, or consist solely of
300 space, tab and/or formfeed characters. In programming language modes,
301 paragraphs are usually defined in a similar way, so that you can use
302 the paragraph commands even though there are no paragraphs as such in
305 Note that an indented line is @emph{not} itself a paragraph break in
306 Text mode. If you want indented lines to separate paragraphs, use
307 Paragraph-Indent Text mode instead. @xref{Text Mode}.
309 If you set a fill prefix, then paragraphs are delimited by all lines
310 which don't start with the fill prefix. @xref{Filling}.
312 @vindex paragraph-start
313 @vindex paragraph-separate
314 The precise definition of a paragraph boundary is controlled by the
315 variables @code{paragraph-separate} and @code{paragraph-start}. The
316 value of @code{paragraph-start} is a regular expression that should
317 match lines that either start or separate paragraphs
318 (@pxref{Regexps}). The value of @code{paragraph-separate} is another
319 regular expression that should match lines that separate paragraphs
320 without being part of any paragraph (for example, blank lines). Lines
321 that start a new paragraph and are contained in it must match only
322 @code{paragraph-start}, not @code{paragraph-separate}. For example,
323 in Fundamental mode, @code{paragraph-start} is @w{@code{"\f\\|[
324 \t]*$"}}, and @code{paragraph-separate} is @w{@code{"[ \t\f]*$"}}.
326 Note that @code{paragraph-start} and @code{paragraph-separate} are
327 matched against the text at the left margin, which is not necessarily
328 the beginning of the line, so these regexps should not use @samp{^} as
329 an anchor, to ensure that the paragraph functions will work equally
330 within a region of text indented by a margin setting.
336 @cindex formfeed character
337 Within some text files, text is divided into @dfn{pages} delimited
338 by the @dfn{formfeed character} (@acronym{ASCII} code 12, also denoted
339 as @samp{control-L}), which is displayed in Emacs as the escape
340 sequence @samp{^L} (@pxref{Text Display}). Traditionally, when such
341 text files are printed to hardcopy, each formfeed character forces a
342 page break. Most Emacs commands treat it just like any other
343 character, so you can insert it with @kbd{C-q C-l}, delete it with
344 @key{DEL}, etc. In addition, Emacs provides commands to move over
345 pages and operate on them.
349 Display the page number of point, and the line number within that page.
351 Move point to previous page boundary (@code{backward-page}).
353 Move point to next page boundary (@code{forward-page}).
355 Put point and mark around this page (or another page) (@code{mark-page}).
357 Count the lines in this page (@code{count-lines-page}).
361 @kbd{M-x what-page} counts pages from the beginning of the file, and
362 counts lines within the page, showing both numbers in the echo area.
367 @findex backward-page
368 The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
369 after the previous page delimiter. If point is already right after a page
370 delimiter, it skips that one and stops at the previous one. A numeric
371 argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
372 command moves forward past the next page delimiter.
376 The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
377 beginning of the current page (after that page delimiter at the
378 front), and the mark at the end of the page (after the page delimiter
381 @kbd{C-x C-p C-w} is a handy way to kill a page to move it
382 elsewhere. If you move to another page delimiter with @kbd{C-x [} and
383 @kbd{C-x ]}, then yank the killed page, all the pages will be properly
384 delimited once again. Making sure this works as expected is the
385 reason @kbd{C-x C-p} includes only the following page delimiter in the
388 A numeric argument to @kbd{C-x C-p} specifies which page to go to,
389 relative to the current one. Zero means the current page, one means
390 the next page, and @minus{}1 means the previous one.
393 @findex count-lines-page
394 The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
395 where to break a page in two. It displays in the echo area the total number
396 of lines in the current page, and then divides it up into those preceding
397 the current line and those following, as in
400 Page has 96 (72+25) lines
404 Notice that the sum is off by one; this is correct if point is not at the
407 @vindex page-delimiter
408 The variable @code{page-delimiter} controls where pages begin. Its
409 value is a regular expression that matches the beginning of a line
410 that separates pages (@pxref{Regexps}). The normal value of this
411 variable is @code{"^\f"}, which matches a formfeed character at the
414 @node Quotation Marks
415 @section Quotation Marks
416 @cindex Quotation marks
417 @cindex Electric Quote mode
418 @cindex mode, Electric Quote
420 @cindex curved quotes
422 @findex electric-quote-mode
423 @c The funny quoting below is to make the printed version look
425 One common way to quote is the typewriter convention, which quotes
426 using straight apostrophes @t{'like this'} or double-quotes @t{"like
427 this"}. Another common way is the curved quote convention, which uses
428 left and right single or double quotation marks `@t{like this}' or
429 ``@t{like this}''@footnote{
430 The curved single quote characters are U+2018 LEFT SINGLE QUOTATION
431 MARK and U+2018 RIGHT SINGLE QUOTATION MARK; the curved double quotes
432 are U+201C LEFT DOUBLE QUOTATION MARK and U+201D RIGHT DOUBLE
433 QUOTATION MARK. On text terminals which cannot display these
434 characters, the Info reader might show them as the typewriter ASCII
436 }. In text files, typewriter quotes are simple and
437 portable; curved quotes are less ambiguous and typically look nicer.
439 @vindex electric-quote-chars
440 Electric Quote mode makes it easier to type curved quotes. As you
441 type characters it optionally converts @t{`} to ‘, @t{'} to ',
442 @t{``} to ``, and @t{''} to ''. It's possible to change the
443 default quotes listed above, by customizing the variable
444 @code{electric-quote-chars}, a list of four characters, where the
445 items correspond to the left single quote, the right single quote, the
446 left double quote and the right double quote, respectively, whose
447 default value is @code{'(?@r{`} ?@r{'} ?@r{``} ?@r{''})}.
449 @vindex electric-quote-paragraph
450 @vindex electric-quote-comment
451 @vindex electric-quote-string
452 You can customize the behavior of Electric Quote mode by customizing
453 variables that control where it is active. It is active in text
454 paragraphs if @code{electric-quote-paragraph} is non-@code{nil}, in
455 programming-language comments if @code{electric-quote-comment} is
456 non-@code{nil}, and in programming-language strings if
457 @code{electric-quote-string} is non-@code{nil}. The default is
458 @code{nil} for @code{electric-quote-string} and @code{t} for the other
461 Electric Quote mode is disabled by default. To toggle it in a
462 single buffer, use @kbd{M-x electric-quote-local-mode}.
463 To toggle it globally, type
464 @kbd{M-x electric-quote-mode}. To suppress it for a single use,
465 type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}. To
466 insert a curved quote even when Electric Quote is disabled or
467 inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for
468 @t{’}, @kbd{C-x 8 @{} for ``, and @kbd{C-x 8 @}} for ''.
469 @xref{Inserting Text}. Note that the value of
470 @code{electric-quote-chars} does not affect these keybindings, they
471 are not keybindings of @code{electric-quote-mode} but bound in
475 @section Filling Text
478 @dfn{Filling} text means breaking it up into lines that fit a
479 specified width. Emacs does filling in two ways. In Auto Fill mode,
480 inserting text with self-inserting characters also automatically fills
481 it. There are also explicit fill commands that you can use when editing
485 * Auto Fill:: Auto Fill mode breaks long lines automatically.
486 * Fill Commands:: Commands to refill paragraphs and center lines.
487 * Fill Prefix:: Filling paragraphs that are indented or in a comment, etc.
488 * Adaptive Fill:: How Emacs can determine the fill prefix automatically.
492 @subsection Auto Fill Mode
493 @cindex Auto Fill mode
494 @cindex mode, Auto Fill
496 @dfn{Auto Fill} mode is a buffer-local minor mode (@pxref{Minor
497 Modes}) in which lines are broken automatically at spaces when the
498 line becomes too wide.
501 @item M-x auto-fill-mode
502 Enable or disable Auto Fill mode.
505 In Auto Fill mode, break lines when appropriate.
508 @findex auto-fill-mode
509 The mode command @kbd{M-x auto-fill-mode} toggles Auto Fill mode in
510 the current buffer. Like any other minor mode, with a positive
511 numeric argument, it enables Auto Fill mode, and with a negative
512 argument it disables it. To enable Auto Fill mode automatically in
513 certain major modes, add @code{auto-fill-mode} to the mode hooks
514 (@pxref{Major Modes}). When Auto Fill mode is enabled, the mode
515 indicator @samp{Fill} appears in the mode line (@pxref{Mode Line}).
517 Auto Fill mode breaks lines automatically at spaces whenever they
518 get longer than the desired width. This line breaking occurs only
519 when you type @key{SPC} or @key{RET}. If you wish to insert a space
520 or newline without permitting line-breaking, type @kbd{C-q @key{SPC}}
521 or @kbd{C-q C-j} respectively. Also, @kbd{C-o} inserts a newline
522 without line breaking.
524 When Auto Fill mode breaks a line, it tries to obey the
525 @dfn{adaptive fill prefix}: if a fill prefix can be deduced from the
526 first and/or second line of the current paragraph, it is inserted into
527 the new line (@pxref{Adaptive Fill}). Otherwise the new line is
528 indented, as though you had typed @key{TAB} on it
529 (@pxref{Indentation}). In a programming language mode, if a line is
530 broken in the middle of a comment, the comment is split by inserting
531 new comment delimiters as appropriate.
533 Auto Fill mode does not refill entire paragraphs; it breaks lines
534 but does not merge lines. Therefore, editing in the middle of a
535 paragraph can result in a paragraph that is not correctly filled. To
536 fill it, call the explicit fill commands
538 described in the next section.
541 (@pxref{Fill Commands}).
545 @subsection Explicit Fill Commands
549 Fill current paragraph (@code{fill-paragraph}).
551 Set the fill column (@code{set-fill-column}).
552 @item M-x fill-region
553 Fill each paragraph in the region (@code{fill-region}).
554 @item M-x fill-region-as-paragraph
555 Fill the region, considering it as one paragraph.
561 @findex fill-paragraph
562 The command @kbd{M-q} (@code{fill-paragraph}) @dfn{fills} the
563 current paragraph. It redistributes the line breaks within the
564 paragraph, and deletes any excess space and tab characters occurring
565 within the paragraph, in such a way that the lines end up fitting
566 within a certain maximum width.
569 Normally, @kbd{M-q} acts on the paragraph where point is, but if
570 point is between paragraphs, it acts on the paragraph after point. If
571 the region is active, it acts instead on the text in the region. You
572 can also call @kbd{M-x fill-region} to specifically fill the text in
575 @findex fill-region-as-paragraph
576 @kbd{M-q} and @code{fill-region} use the usual Emacs criteria for
577 finding paragraph boundaries (@pxref{Paragraphs}). For more control,
578 you can use @kbd{M-x fill-region-as-paragraph}, which refills
579 everything between point and mark as a single paragraph. This command
580 deletes any blank lines within the region, so separate blocks of text
581 end up combined into one block.
583 @cindex justification
584 A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text
585 as well as filling it. This means that extra spaces are inserted to
586 make the right margin line up exactly at the fill column. To remove
587 the extra spaces, use @kbd{M-q} with no argument. (Likewise for
592 @findex set-fill-column
593 The maximum line width for filling is specified by the buffer-local
594 variable @code{fill-column}. The default value (@pxref{Locals}) is
595 70. The easiest way to set @code{fill-column} in the current buffer
596 is to use the command @kbd{C-x f} (@code{set-fill-column}). With a
597 numeric argument, it uses that as the new fill column. With just
598 @kbd{C-u} as argument, it sets @code{fill-column} to the current
599 horizontal position of point.
601 @kindex M-o M-s @r{(Text mode)}
604 The command @kbd{M-o M-s} (@code{center-line}) centers the current line
605 within the current fill column. With an argument @var{n}, it centers
606 @var{n} lines individually and moves past them. This binding is
607 made by Text mode and is available only in that and related modes
610 By default, Emacs considers a period followed by two spaces or by a
611 newline as the end of a sentence; a period followed by just one space
612 indicates an abbreviation, not the end of a sentence. Accordingly,
613 the fill commands will not break a line after a period followed by
614 just one space. If you set the variable
615 @code{sentence-end-double-space} to @code{nil}, the fill commands will
616 break a line after a period followed by one space, and put just one
617 space after each period. @xref{Sentences}, for other effects and
618 possible drawbacks of this.
620 @vindex colon-double-space
621 If the variable @code{colon-double-space} is non-@code{nil}, the
622 fill commands put two spaces after a colon.
624 @vindex fill-nobreak-predicate
625 To specify additional conditions where line-breaking is not allowed,
626 customize the abnormal hook variable @code{fill-nobreak-predicate}
627 (@pxref{Hooks}). Each function in this hook is called with no
628 arguments, with point positioned where Emacs is considering breaking a
629 line. If a function returns a non-@code{nil} value, Emacs will not
630 break the line there. Functions you can use there include:
631 @code{fill-single-word-nobreak-p} (don't break after the first word of
632 a sentence or before the last); @code{fill-single-char-nobreak-p}
633 (don't break after a one-letter word); and @code{fill-french-nobreak-p}
634 (don't break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}).
637 @subsection The Fill Prefix
640 The @dfn{fill prefix} feature allows paragraphs to be filled so that
641 each line starts with a special string of characters (such as a
642 sequence of spaces, giving an indented paragraph). You can specify a
643 fill prefix explicitly; otherwise, Emacs tries to deduce one
644 automatically (@pxref{Adaptive Fill}).
648 Set the fill prefix (@code{set-fill-prefix}).
650 Fill a paragraph using current fill prefix (@code{fill-paragraph}).
651 @item M-x fill-individual-paragraphs
652 Fill the region, considering each change of indentation as starting a
654 @item M-x fill-nonuniform-paragraphs
655 Fill the region, considering only paragraph-separator lines as starting
660 @findex set-fill-prefix
661 To specify a fill prefix for the current buffer, move to a line that
662 starts with the desired prefix, put point at the end of the prefix,
663 and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period
664 after the @kbd{C-x}.) To turn off the fill prefix, specify an empty
665 prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line.
667 When a fill prefix is in effect, the fill commands remove the fill
668 prefix from each line of the paragraph before filling, and insert it
669 on each line after filling. (The beginning of the first line of the
670 paragraph is left unchanged, since often that is intentionally
671 different.) Auto Fill mode also inserts the fill prefix automatically
672 when it makes a new line (@pxref{Auto Fill}). The @kbd{C-o} command
673 inserts the fill prefix on new lines it creates, when you use it at
674 the beginning of a line (@pxref{Blank Lines}). Conversely, the
675 command @kbd{M-^} deletes the prefix (if it occurs) after the newline
676 that it deletes (@pxref{Indentation}).
678 For example, if @code{fill-column} is 40 and you set the fill prefix
679 to @samp{;; }, then @kbd{M-q} in the following text
683 ;; example of a paragraph
684 ;; inside a Lisp-style comment.
691 ;; This is an example of a paragraph
692 ;; inside a Lisp-style comment.
695 Lines that do not start with the fill prefix are considered to start
696 paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
697 good results for paragraphs with hanging indentation (every line
698 indented except the first one). Lines which are blank or indented once
699 the prefix is removed also separate or start paragraphs; this is what
700 you want if you are writing multi-paragraph comments with a comment
701 delimiter on each line.
703 @findex fill-individual-paragraphs
704 You can use @kbd{M-x fill-individual-paragraphs} to set the fill
705 prefix for each paragraph automatically. This command divides the
706 region into paragraphs, treating every change in the amount of
707 indentation as the start of a new paragraph, and fills each of these
708 paragraphs. Thus, all the lines in one paragraph have the same
709 amount of indentation. That indentation serves as the fill prefix for
712 @findex fill-nonuniform-paragraphs
713 @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
714 the region into paragraphs in a different way. It considers only
715 paragraph-separating lines (as defined by @code{paragraph-separate}) as
716 starting a new paragraph. Since this means that the lines of one
717 paragraph may have different amounts of indentation, the fill prefix
718 used is the smallest amount of indentation of any of the lines of the
719 paragraph. This gives good results with styles that indent a paragraph's
720 first line more or less that the rest of the paragraph.
723 The fill prefix is stored in the variable @code{fill-prefix}. Its value
724 is a string, or @code{nil} when there is no fill prefix. This is a
725 per-buffer variable; altering the variable affects only the current buffer,
726 but there is a default value which you can change as well. @xref{Locals}.
728 The @code{indentation} text property provides another way to control
729 the amount of indentation paragraphs receive. @xref{Enriched
733 @subsection Adaptive Filling
735 @cindex adaptive filling
736 The fill commands can deduce the proper fill prefix for a paragraph
737 automatically in certain cases: either whitespace or certain punctuation
738 characters at the beginning of a line are propagated to all lines of the
741 If the paragraph has two or more lines, the fill prefix is taken from
742 the paragraph's second line, but only if it appears on the first line as
745 If a paragraph has just one line, fill commands @emph{may} take a
746 prefix from that line. The decision is complicated because there are
747 three reasonable things to do in such a case:
751 Use the first line's prefix on all the lines of the paragraph.
754 Indent subsequent lines with whitespace, so that they line up under the
755 text that follows the prefix on the first line, but don't actually copy
756 the prefix from the first line.
759 Don't do anything special with the second and following lines.
762 All three of these styles of formatting are commonly used. So the
763 fill commands try to determine what you would like, based on the prefix
764 that appears and on the major mode. Here is how.
766 @vindex adaptive-fill-first-line-regexp
767 If the prefix found on the first line matches
768 @code{adaptive-fill-first-line-regexp}, or if it appears to be a
769 comment-starting sequence (this depends on the major mode), then the
770 prefix found is used for filling the paragraph, provided it would not
771 act as a paragraph starter on subsequent lines.
773 Otherwise, the prefix found is converted to an equivalent number of
774 spaces, and those spaces are used as the fill prefix for the rest of the
775 lines, provided they would not act as a paragraph starter on subsequent
778 In Text mode, and other modes where only blank lines and page
779 delimiters separate paragraphs, the prefix chosen by adaptive filling
780 never acts as a paragraph starter, so it can always be used for filling.
782 @vindex adaptive-fill-mode
783 @vindex adaptive-fill-regexp
784 The variable @code{adaptive-fill-regexp} determines what kinds of line
785 beginnings can serve as a fill prefix: any characters at the start of
786 the line that match this regular expression are used. If you set the
787 variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
788 never chosen automatically.
790 @vindex adaptive-fill-function
791 You can specify more complex ways of choosing a fill prefix
792 automatically by setting the variable @code{adaptive-fill-function} to a
793 function. This function is called with point after the left margin of a
794 line, and it should return the appropriate fill prefix based on that
795 line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets
796 a chance to find a prefix.
799 @section Case Conversion Commands
800 @cindex case conversion
802 Emacs has commands for converting either a single word or any arbitrary
803 range of text to upper case or to lower case.
807 Convert following word to lower case (@code{downcase-word}).
809 Convert following word to upper case (@code{upcase-word}).
811 Capitalize the following word (@code{capitalize-word}).
813 Convert region to lower case (@code{downcase-region}).
815 Convert region to upper case (@code{upcase-region}).
821 @cindex words, case conversion
822 @cindex converting text to upper or lower case
823 @cindex capitalizing words
824 @findex downcase-word
826 @findex capitalize-word
827 @kbd{M-l} (@code{downcase-word}) converts the word after point to
828 lower case, moving past it. Thus, repeating @kbd{M-l} converts
829 successive words. @kbd{M-u} (@code{upcase-word}) converts to all
830 capitals instead, while @kbd{M-c} (@code{capitalize-word}) puts the
831 first letter of the word into upper case and the rest into lower case.
832 All these commands convert several words at once if given an argument.
833 They are especially convenient for converting a large amount of text
834 from all upper case to mixed case, because you can move through the
835 text using @kbd{M-l}, @kbd{M-u} or @kbd{M-c} on each word as
836 appropriate, occasionally using @kbd{M-f} instead to skip a word.
838 When given a negative argument, the word case conversion commands apply
839 to the appropriate number of words before point, but do not move point.
840 This is convenient when you have just typed a word in the wrong case: you
841 can give the case conversion command and continue typing.
843 If a word case conversion command is given in the middle of a word,
844 it applies only to the part of the word which follows point. (This is
845 comparable to what @kbd{M-d} (@code{kill-word}) does.) With a
846 negative argument, case conversion applies only to the part of the
851 @findex downcase-region
852 @findex upcase-region
853 The other case conversion commands are @kbd{C-x C-u}
854 (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
855 convert everything between point and mark to the specified case. Point and
858 The region case conversion commands @code{upcase-region} and
859 @code{downcase-region} are normally disabled. This means that they ask
860 for confirmation if you try to use them. When you confirm, you may
861 enable the command, which means it will not ask for confirmation again.
870 Text mode is a major mode for editing files of text in a human
871 language. Files which have names ending in the extension @file{.txt}
872 are usually opened in Text mode (@pxref{Choosing Modes}). To
873 explicitly switch to Text mode, type @kbd{M-x text-mode}.
875 In Text mode, only blank lines and page delimiters separate
876 paragraphs. As a result, paragraphs can be indented, and adaptive
877 filling determines what indentation to use when filling a paragraph.
878 @xref{Adaptive Fill}.
880 @kindex TAB @r{(Text mode)}
881 In Text mode, the @key{TAB} (@code{indent-for-tab-command}) command
882 usually inserts whitespace up to the next tab stop, instead of
883 indenting the current line. @xref{Indentation}, for details.
885 Text mode turns off the features concerned with comments except when
886 you explicitly invoke them. It changes the syntax table so that
887 apostrophes are considered part of words (e.g., @samp{don't} is
888 considered one word). However, if a word starts with an apostrophe,
889 it is treated as a prefix for the purposes of capitalization
890 (e.g., @kbd{M-c} converts @samp{'hello'} into @samp{'Hello'}, as
893 @cindex Paragraph-Indent Text mode
894 @cindex mode, Paragraph-Indent Text
895 @findex paragraph-indent-text-mode
896 @findex paragraph-indent-minor-mode
897 If you indent the first lines of paragraphs, then you should use
898 Paragraph-Indent Text mode (@kbd{M-x paragraph-indent-text-mode})
899 rather than Text mode. In that mode, you do not need to have blank
900 lines between paragraphs, because the first-line indentation is
901 sufficient to start a paragraph; however paragraphs in which every
902 line is indented are not supported. Use @kbd{M-x
903 paragraph-indent-minor-mode} to enable an equivalent minor mode for
904 situations where you shouldn't change the major mode---in mail
905 composition, for instance.
907 @kindex M-TAB @r{(Text mode)}
908 Text mode binds @kbd{M-@key{TAB}} to @code{ispell-complete-word}.
909 This command performs completion of the partial word in the buffer
910 before point, using the spelling dictionary as the space of possible
911 words. @xref{Spelling}. If your window manager defines
912 @kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC}
913 @key{TAB}} or @kbd{C-M-i} instead.
915 @vindex text-mode-hook
916 Entering Text mode runs the mode hook @code{text-mode-hook}
917 (@pxref{Major Modes}).
919 The following sections describe several major modes that are
920 @dfn{derived} from Text mode. These derivatives share most of the
921 features of Text mode described above. In particular, derivatives of
922 Text mode run @code{text-mode-hook} prior to running their own mode
926 @section Outline Mode
928 @cindex mode, Outline
929 @cindex invisible lines
932 @findex outline-minor-mode
933 @vindex outline-minor-mode-prefix
934 @vindex outline-mode-hook
935 Outline mode is a major mode derived from Text mode, which is
936 specialized for editing outlines. It provides commands to navigate
937 between entries in the outline structure, and commands to make parts
938 of a buffer temporarily invisible, so that the outline structure may
939 be more easily viewed. Type @kbd{M-x outline-mode} to switch to
940 Outline mode. Entering Outline mode runs the hook
941 @code{text-mode-hook} followed by the hook @code{outline-mode-hook}
944 When you use an Outline mode command to make a line invisible
945 (@pxref{Outline Visibility}), the line disappears from the screen. An
946 ellipsis (three periods in a row) is displayed at the end of the
947 previous visible line, to indicate the hidden text. Multiple
948 consecutive invisible lines produce just one ellipsis.
950 Editing commands that operate on lines, such as @kbd{C-n} and
951 @kbd{C-p}, treat the text of the invisible line as part of the
952 previous visible line. Killing the ellipsis at the end of a visible
953 line really kills all the following invisible text associated with the
956 Outline minor mode is a buffer-local minor mode which provides the
957 same commands as the major mode, Outline mode, but can be used in
958 conjunction with other major modes. You can type @kbd{M-x
959 outline-minor-mode} to toggle Outline minor mode in the current
960 buffer, or use a file-local variable setting to enable it in a
961 specific file (@pxref{File Variables}).
963 @kindex C-c @@ @r{(Outline minor mode)}
964 The major mode, Outline mode, provides special key bindings on the
965 @kbd{C-c} prefix. Outline minor mode provides similar bindings with
966 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
967 major mode's special commands. (The variable
968 @code{outline-minor-mode-prefix} controls the prefix used.)
971 * Outline Format:: What the text of an outline looks like.
972 * Outline Motion:: Special commands for moving through outlines.
973 * Outline Visibility:: Commands to control what is visible.
974 * Outline Views:: Outlines and multiple views.
975 * Foldout:: Folding means zooming in on outlines.
979 @subsection Format of Outlines
981 @cindex heading lines (Outline mode)
982 @cindex body lines (Outline mode)
983 Outline mode assumes that the lines in the buffer are of two types:
984 @dfn{heading lines} and @dfn{body lines}. A heading line represents a
985 topic in the outline. Heading lines start with one or more asterisk
986 (@samp{*}) characters; the number of asterisks determines the depth of
987 the heading in the outline structure. Thus, a heading line with one
988 @samp{*} is a major topic; all the heading lines with two @samp{*}s
989 between it and the next one-@samp{*} heading are its subtopics; and so
990 on. Any line that is not a heading line is a body line. Body lines
991 belong with the preceding heading line. Here is an example:
996 which says something about the topic of food.
999 This is the body of the second-level header.
1009 Another first-level topic with its header line.
1012 A heading line together with all following body lines is called
1013 collectively an @dfn{entry}. A heading line together with all following
1014 deeper heading lines and their body lines is called a @dfn{subtree}.
1016 @vindex outline-regexp
1017 You can customize the criterion for distinguishing heading lines by
1018 setting the variable @code{outline-regexp}. (The recommended ways to
1019 do this are in a major mode function or with a file local variable.)
1020 Any line whose beginning has a match for this regexp is considered a
1021 heading line. Matches that start within a line (not at the left
1022 margin) do not count.
1024 The length of the matching text determines the level of the heading;
1025 longer matches make a more deeply nested level. Thus, for example, if
1026 a text formatter has commands @samp{@@chapter}, @samp{@@section} and
1027 @samp{@@subsection} to divide the document into chapters and sections,
1028 you could make those lines count as heading lines by setting
1029 @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note
1030 the trick: the two words @samp{chapter} and @samp{section} are equally
1031 long, but by defining the regexp to match only @samp{chap} we ensure
1032 that the length of the text matched on a chapter heading is shorter,
1033 so that Outline mode will know that sections are contained in
1034 chapters. This works as long as no other command starts with
1037 @vindex outline-level
1038 You can explicitly specify a rule for calculating the level of a
1039 heading line by setting the variable @code{outline-level}. The value
1040 of @code{outline-level} should be a function that takes no arguments
1041 and returns the level of the current heading. The recommended ways to
1042 set this variable are in a major mode command or with a file local
1045 @node Outline Motion
1046 @subsection Outline Motion Commands
1048 Outline mode provides special motion commands that move backward and
1049 forward to heading lines.
1053 @findex outline-next-visible-heading
1054 @kindex C-c C-n @r{(Outline mode)}
1055 Move point to the next visible heading line
1056 (@code{outline-next-visible-heading}).
1058 @findex outline-previous-visible-heading
1059 @kindex C-c C-p @r{(Outline mode)}
1060 Move point to the previous visible heading line
1061 (@code{outline-previous-visible-heading}).
1063 @findex outline-forward-same-level
1064 @kindex C-c C-f @r{(Outline mode)}
1065 Move point to the next visible heading line at the same level
1066 as the one point is on (@code{outline-forward-same-level}).
1068 @findex outline-backward-same-level
1069 @kindex C-c C-b @r{(Outline mode)}
1070 Move point to the previous visible heading line at the same level
1071 (@code{outline-backward-same-level}).
1073 @findex outline-up-heading
1074 @kindex C-c C-u @r{(Outline mode)}
1075 Move point up to a lower-level (more inclusive) visible heading line
1076 (@code{outline-up-heading}).
1079 All of the above commands accept numeric arguments as repeat counts.
1080 For example, @kbd{C-c C-f}, when given an argument, moves forward that
1081 many visible heading lines on the same level, and @kbd{C-c C-u} with
1082 an argument moves out of that many nested levels.
1084 @node Outline Visibility
1085 @subsection Outline Visibility Commands
1087 Outline mode provides several commands for temporarily hiding or
1088 revealing parts of the buffer, based on the outline structure. These
1089 commands are not undoable; their effects are simply not recorded by
1090 the undo mechanism, so you can undo right past them (@pxref{Undo}).
1092 Many of these commands act on the current heading line. If
1093 point is on a heading line, that is the current heading line; if point
1094 is on a body line, the current heading line is the nearest preceding
1099 Make the current heading line's body invisible
1100 (@code{outline-hide-entry}).
1102 Make the current heading line's body visible
1103 (@code{outline-show-entry}).
1105 Make everything under the current heading invisible, not including the
1106 heading itself (@code{outline-hide-subtree}).
1108 Make everything under the current heading visible, including body,
1109 subheadings, and their bodies (@code{outline-show-subtree}).
1111 Make the body of the current heading line, and of all its subheadings,
1112 invisible (@code{outline-hide-leaves}).
1114 Make all subheadings of the current heading line, at all levels,
1115 visible (@code{outline-show-branches}).
1117 Make immediate subheadings (one level down) of the current heading
1118 line visible (@code{outline-show-children}).
1120 Make all body lines in the buffer invisible
1121 (@code{outline-hide-body}).
1123 Make all lines in the buffer visible (@code{outline-show-all}).
1125 Hide everything except the top @var{n} levels of heading lines
1126 (@code{outline-hide-sublevels}).
1128 Hide everything except for the heading or body that point is in, plus
1129 the headings leading up from there to the top level of the outline
1130 (@code{outline-hide-other}).
1133 @findex outline-hide-entry
1134 @findex outline-show-entry
1135 @kindex C-c C-c @r{(Outline mode)}
1136 @kindex C-c C-e @r{(Outline mode)}
1137 The simplest of these commands are @kbd{C-c C-c}
1138 (@code{outline-hide-entry}), which hides the body lines directly
1139 following the current heading line, and @kbd{C-c C-e}
1140 (@code{outline-show-entry}), which reveals them. Subheadings and
1141 their bodies are not affected.
1143 @findex outline-hide-subtree
1144 @findex outline-show-subtree
1145 @kindex C-c C-s @r{(Outline mode)}
1146 @kindex C-c C-d @r{(Outline mode)}
1147 @cindex subtree (Outline mode)
1148 The commands @kbd{C-c C-d} (@code{outline-hide-subtree}) and
1149 @kbd{C-c C-s} (@code{outline-show-subtree}) are more powerful. They
1150 apply to the current heading line's @dfn{subtree}: its body, all of
1151 its subheadings, both direct and indirect, and all of their bodies.
1153 @findex outline-hide-leaves
1154 @findex outline-show-branches
1155 @findex outline-show-children
1156 @kindex C-c C-l @r{(Outline mode)}
1157 @kindex C-c C-k @r{(Outline mode)}
1158 @kindex C-c C-i @r{(Outline mode)}
1159 The command @kbd{C-c C-l} (@code{outline-hide-leaves}) hides the
1160 body of the current heading line as well as all the bodies in its
1161 subtree; the subheadings themselves are left visible. The command
1162 @kbd{C-c C-k} (@code{outline-show-branches}) reveals the subheadings,
1163 if they had previously been hidden (e.g., by @kbd{C-c C-d}). The
1164 command @kbd{C-c C-i} (@code{outline-show-children}) is a weaker
1165 version of this; it reveals just the direct subheadings, i.e., those
1168 @findex outline-hide-other
1169 @kindex C-c C-o @r{(Outline mode)}
1170 The command @kbd{C-c C-o} (@code{outline-hide-other}) hides
1171 everything except the entry that point is in, plus its parents (the
1172 headers leading up from there to top level in the outline) and the top
1173 level headings. It also reveals body lines preceding the first
1174 heading in the buffer.
1176 @findex outline-hide-body
1177 @findex outline-show-all
1178 @kindex C-c C-t @r{(Outline mode)}
1179 @kindex C-c C-a @r{(Outline mode)}
1180 @findex hide-sublevels
1181 @kindex C-c C-q @r{(Outline mode)}
1182 The remaining commands affect the whole buffer. @kbd{C-c C-t}
1183 (@code{outline-hide-body}) makes all body lines invisible, so that you
1184 see just the outline structure (as a special exception, it will not
1185 hide lines at the top of the file, preceding the first header line,
1186 even though these are technically body lines). @kbd{C-c C-a}
1187 (@code{outline-show-all}) makes all lines visible. @kbd{C-c C-q}
1188 (@code{outline-hide-sublevels}) hides all but the top level headings
1189 at and above the level of the current heading line (defaulting to 1 if
1190 point is not on a heading); with a numeric argument @var{n}, it hides
1191 everything except the top @var{n} levels of heading lines. Note that
1192 it completely reveals all the @var{n} top levels and the body lines
1193 before the first heading.
1195 @anchor{Outline Search}
1197 @vindex search-invisible
1198 When incremental search finds text that is hidden by Outline mode,
1199 it makes that part of the buffer visible. If you exit the search at
1200 that position, the text remains visible. To toggle whether or not
1201 an active incremental search can match hidden text, type @kbd{M-s i}.
1202 To change the default for future searches, customize the option
1203 @code{search-invisible}. (This option also affects how @code{query-replace}
1204 and related functions treat hidden text, @pxref{Query Replace}.)
1205 You can also automatically make text visible as you navigate in it by
1206 using Reveal mode (@kbd{M-x reveal-mode}), a buffer-local minor mode.
1209 @subsection Viewing One Outline in Multiple Views
1211 @cindex multiple views of outline
1212 @cindex views of an outline
1213 @cindex outline with multiple views
1214 @cindex indirect buffers and outlines
1215 You can display two views of a single outline at the same time, in
1216 different windows. To do this, you must create an indirect buffer using
1217 @kbd{M-x make-indirect-buffer}. The first argument of this command is
1218 the existing outline buffer name, and its second argument is the name to
1219 use for the new indirect buffer. @xref{Indirect Buffers}.
1221 Once the indirect buffer exists, you can display it in a window in the
1222 normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline
1223 mode commands to show and hide parts of the text operate on each buffer
1224 independently; as a result, each buffer can have its own view. If you
1225 want more than two views on the same outline, create additional indirect
1229 @subsection Folding Editing
1231 @cindex folding editing
1232 The Foldout package extends Outline mode and Outline minor mode with
1233 folding commands. The idea of folding is that you zoom in on a
1234 nested portion of the outline, while hiding its relatives at higher
1237 Consider an Outline mode buffer with all the text and subheadings under
1238 level-1 headings hidden. To look at what is hidden under one of these
1239 headings, you could use @kbd{C-c C-e} (@kbd{M-x outline-show-entry})
1240 to expose the body, or @kbd{C-c C-i} to expose the child (level-2)
1244 @findex foldout-zoom-subtree
1245 With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1246 This exposes the body and child subheadings, and narrows the buffer so
1247 that only the @w{level-1} heading, the body and the level-2 headings are
1248 visible. Now to look under one of the level-2 headings, position the
1249 cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body
1250 and its level-3 child subheadings and narrows the buffer again. Zooming
1251 in on successive subheadings can be done as much as you like. A string
1252 in the mode line shows how deep you've gone.
1254 When zooming in on a heading, to see only the child subheadings specify
1255 a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children
1256 can be specified too (compare @kbd{M-x outline-show-children}), e.g.,
1257 @w{@kbd{M-2 C-c C-z}} exposes two levels of child subheadings.
1258 Alternatively, the body can be specified with a negative argument:
1259 @w{@kbd{M-- C-c C-z}}. The whole subtree can be expanded, similarly to
1260 @kbd{C-c C-s} (@kbd{M-x outline-show-subtree}), by specifying a zero
1261 argument: @w{@kbd{M-0 C-c C-z}}.
1263 While you're zoomed in, you can still use Outline mode's exposure and
1264 hiding functions without disturbing Foldout. Also, since the buffer is
1265 narrowed, global editing actions will only affect text under the
1266 zoomed-in heading. This is useful for restricting changes to a
1267 particular chapter or section of your document.
1270 @findex foldout-exit-fold
1271 To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1272 This hides all the text and subheadings under the top-level heading and
1273 returns you to the previous view of the buffer. Specifying a numeric
1274 argument exits that many levels of folds. Specifying a zero argument
1277 To cancel the narrowing of a fold without hiding the text and
1278 subheadings, specify a negative argument. For example, @w{@kbd{M--2 C-c
1279 C-x}} exits two folds and leaves the text and subheadings exposed.
1281 Foldout mode also provides mouse commands for entering and exiting
1282 folds, and for showing and hiding text:
1285 @item @kbd{C-M-mouse-1} zooms in on the heading clicked on
1288 single click: expose body.
1290 double click: expose subheadings.
1292 triple click: expose body and subheadings.
1294 quad click: expose entire subtree.
1296 @item @kbd{C-M-mouse-2} exposes text under the heading clicked on
1299 single click: expose body.
1301 double click: expose subheadings.
1303 triple click: expose body and subheadings.
1305 quad click: expose entire subtree.
1307 @item @kbd{C-M-mouse-3} hides text under the heading clicked on or exits fold
1310 single click: hide subtree.
1312 double click: exit fold and hide text.
1314 triple click: exit fold without hiding text.
1316 quad click: exit all folds and hide text.
1320 @c FIXME not marked as a user variable
1321 @vindex foldout-mouse-modifiers
1322 You can specify different modifier keys (instead of
1323 @kbd{@key{Ctrl}-@key{META}-}) by setting @code{foldout-mouse-modifiers}; but if
1324 you have already loaded the @file{foldout.el} library, you must reload
1325 it in order for this to take effect.
1327 To use the Foldout package, you can type @kbd{M-x load-library
1328 @key{RET} foldout @key{RET}}; or you can arrange for to do that
1329 automatically by putting the following in your init file:
1332 (with-eval-after-load "outline"
1344 Org mode is a variant of Outline mode for using Emacs as an
1345 organizer and/or authoring system. Files with names ending in the
1346 extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}).
1347 To explicitly switch to Org mode, type @kbd{M-x org-mode}.
1349 In Org mode, as in Outline mode, each entry has a heading line that
1350 starts with one or more @samp{*} characters. @xref{Outline Format}.
1351 In addition, any line that begins with the @samp{#} character is
1352 treated as a comment.
1354 @kindex TAB @r{(Org Mode)}
1356 Org mode provides commands for easily viewing and manipulating the
1357 outline structure. The simplest of these commands is @key{TAB}
1358 (@code{org-cycle}). If invoked on a heading line, it cycles through
1359 the different visibility states of the subtree: (i) showing only that
1360 heading line, (ii) showing only the heading line and the heading lines
1361 of its direct children, if any, and (iii) showing the entire subtree.
1362 If invoked in a body line, the global binding for @key{TAB} is
1365 @kindex S-TAB @r{(Org Mode)}
1366 @findex org-shifttab
1367 Typing @kbd{S-@key{TAB}} (@code{org-shifttab}) anywhere in an Org mode
1368 buffer cycles the visibility of the entire outline structure, between
1369 (i) showing only top-level heading lines, (ii) showing all heading
1370 lines but no body lines, and (iii) showing everything.
1372 @kindex M-<up> @r{(Org Mode)}
1373 @kindex M-<down> @r{(Org Mode)}
1374 @kindex M-<left> @r{(Org Mode)}
1375 @kindex M-<right> @r{(Org Mode)}
1377 @findex org-metadown
1378 @findex org-metaleft
1379 @findex org-metaright
1380 You can move an entire entry up or down in the buffer, including its
1381 body lines and subtree (if any), by typing @kbd{M-<up>}
1382 (@code{org-metaup}) or @kbd{M-<down>} (@code{org-metadown}) on the
1383 heading line. Similarly, you can promote or demote a heading line
1384 with @kbd{M-<left>} (@code{org-metaleft}) and @kbd{M-<right>}
1385 (@code{org-metaright}). These commands execute their global bindings
1386 if invoked on a body line.
1388 The following subsections give basic instructions for using Org mode
1389 as an organizer and as an authoring system. For details, @pxref{Top,
1390 The Org Mode Manual, Introduction, org, The Org Manual}.
1393 * Org Organizer:: Managing TODO lists and agendas.
1394 * Org Authoring:: Exporting Org buffers to various formats.
1398 @subsection Org as an organizer
1402 @kindex C-c C-t @r{(Org Mode)}
1404 @vindex org-todo-keywords
1405 You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c
1406 C-t} (@code{org-todo}) anywhere in the entry. This adds the keyword
1407 @samp{TODO} to the heading line. Typing @kbd{C-c C-t} again switches
1408 the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword
1409 entirely, and so forth. You can customize the keywords used by
1410 @kbd{C-c C-t} via the variable @code{org-todo-keywords}.
1412 @kindex C-c C-s @r{(Org Mode)}
1413 @kindex C-c C-d @r{(Org Mode)}
1414 @findex org-schedule
1415 @findex org-deadline
1416 Apart from marking an entry as TODO, you can attach a date to it, by
1417 typing @kbd{C-c C-s} (@code{org-schedule}) in the entry. This prompts
1418 for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}),
1419 and then adds the tag @samp{SCHEDULED}, together with the selected
1420 date, beneath the heading line. The command @kbd{C-c C-d}
1421 (@code{org-deadline}) has the same effect, except that it uses the tag
1424 @kindex C-c [ @r{(Org Mode)}
1425 @findex org-agenda-file-to-front
1426 @vindex org-agenda-files
1427 Once you have some TODO items planned in an Org file, you can add
1428 that file to the list of @dfn{agenda files} by typing @kbd{C-c [}
1429 (@code{org-agenda-file-to-front}). Org mode is designed to let you
1430 easily maintain multiple agenda files, e.g., for organizing different
1431 aspects of your life. The list of agenda files is stored in the
1432 variable @code{org-agenda-files}.
1435 To view items coming from your agenda files, type @kbd{M-x
1436 org-agenda}. This command prompts for what you want to see: a list of
1437 things to do this week, a list of TODO items with specific keywords,
1440 @xref{Agenda views,,,org, The Org Manual}, for details.
1444 @subsection Org as an authoring system
1445 @cindex Org exporting
1448 @kindex C-c C-e @r{(Org mode)}
1449 You may want to format your Org notes nicely and to prepare them for
1450 export and publication. To export the current buffer, type @kbd{C-c
1451 C-e} (@code{org-export}) anywhere in an Org buffer. This command
1452 prompts for an export format; currently supported formats include
1453 HTML, @LaTeX{}, OpenDocument (@file{.odt}), and PDF@. Some formats,
1454 such as PDF, require certain system tools to be installed.
1456 @vindex org-publish-project-alist
1457 To export several files at once to a specific directory, either
1458 locally or over the network, you must define a list of projects
1459 through the variable @code{org-publish-project-alist}. See its
1460 documentation for details.
1462 Org supports a simple markup scheme for applying text formatting to
1466 - This text is /emphasized/
1467 - This text is *in bold*
1468 - This text is _underlined_
1469 - This text uses =a teletype font=
1472 ``This is a quote.''
1480 For further details, @ref{Exporting,,,org, The Org Manual}, and
1481 @ref{Publishing,,,org, The Org Manual}.
1484 @section @TeX{} Mode
1486 @cindex @LaTeX{} mode
1487 @cindex Sli@TeX{} mode
1488 @cindex Doc@TeX{} mode
1489 @cindex mode, @TeX{}
1490 @cindex mode, @LaTeX{}
1491 @cindex mode, Sli@TeX{}
1492 @cindex mode, Doc@TeX{}
1494 @findex plain-tex-mode
1500 Emacs provides special major modes for editing files written in
1501 @TeX{} and its related formats. @TeX{} is a powerful text formatter
1502 written by Donald Knuth; like GNU Emacs, it is free software.
1503 @LaTeX{} is a simplified input format for @TeX{}, implemented using
1504 @TeX{} macros. Doc@TeX{} is a special file format in which the
1505 @LaTeX{} sources are written, combining sources with documentation.
1506 Sli@TeX{} is an obsolete special form of @LaTeX{}.@footnote{It has
1507 been replaced by the @samp{slides} document class, which comes with
1510 @vindex tex-default-mode
1511 @TeX{} mode has four variants: Plain @TeX{} mode, @LaTeX{} mode,
1512 Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ
1513 only slightly, and are designed for editing the four different
1514 formats. Emacs selects the appropriate mode by looking at the
1515 contents of the buffer. (This is done by the @code{tex-mode} command,
1516 which is normally called automatically when you visit a @TeX{}-like
1517 file. @xref{Choosing Modes}.) If the contents are insufficient to
1518 determine this, Emacs chooses the mode specified by the variable
1519 @code{tex-default-mode}; its default value is @code{latex-mode}. If
1520 Emacs does not guess right, you can select the correct variant of
1521 @TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x
1522 latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}.
1524 The following sections document the features of @TeX{} mode and its
1525 variants. There are several other @TeX{}-related Emacs packages,
1526 which are not documented in this manual:
1530 Bib@TeX{} mode is a major mode for Bib@TeX{} files, which are commonly
1531 used for keeping bibliographic references for @LaTeX{} documents. For
1532 more information, see the documentation string for the command
1536 The Ref@TeX{} package provides a minor mode which can be used with
1537 @LaTeX{} mode to manage bibliographic references.
1539 @xref{Top,The Ref@TeX{} Manual,,reftex}.
1542 For more information, see the Ref@TeX{} Info manual, which is
1543 distributed with Emacs.
1547 The AUC@TeX{} package provides more advanced features for editing
1548 @TeX{} and its related formats, including the ability to preview
1549 @TeX{} equations within Emacs buffers. Unlike Bib@TeX{} mode and the
1550 Ref@TeX{} package, AUC@TeX{} is not distributed with Emacs by default.
1551 It can be downloaded via the Package Menu (@pxref{Packages}); once
1554 @ref{Top,The AUC@TeX{} Manual,,auctex}.
1557 the AUC@TeX{} manual, which is included with the package.
1562 * TeX Editing:: Special commands for editing in TeX mode.
1563 * LaTeX Editing:: Additional commands for LaTeX input files.
1564 * TeX Print:: Commands for printing part of a file with TeX.
1565 * TeX Misc:: Customization of TeX mode, and related features.
1569 @subsection @TeX{} Editing Commands
1573 Insert, according to context, either @samp{``} or @samp{"} or
1574 @samp{''} (@code{tex-insert-quote}).
1576 Insert a paragraph break (two newlines) and check the previous
1577 paragraph for unbalanced braces or dollar signs
1578 (@code{tex-terminate-paragraph}).
1579 @item M-x tex-validate-region
1580 Check each paragraph in the region for unbalanced braces or dollar signs.
1582 Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1584 Move forward past the next unmatched close brace (@code{up-list}).
1587 @findex tex-insert-quote
1588 @kindex " @r{(@TeX{} mode)}
1589 In @TeX{}, the character @samp{"} is not normally used; instead,
1590 quotations begin with @samp{``} and end with @samp{''}. @TeX{} mode
1591 therefore binds the @kbd{"} key to the @code{tex-insert-quote}
1592 command. This inserts @samp{``} after whitespace or an open brace,
1593 @samp{"} after a backslash, and @samp{''} after any other character.
1595 As a special exception, if you type @kbd{"} when the text before
1596 point is either @samp{``} or @samp{''}, Emacs replaces that preceding
1597 text with a single @samp{"} character. You can therefore type
1598 @kbd{""} to insert @samp{"}, should you ever need to do so. (You can
1599 also use @kbd{C-q "} to insert this character.)
1601 In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1602 understand the way @TeX{} math mode delimiters match. When you insert a
1603 @samp{$} that is meant to exit math mode, the position of the matching
1604 @samp{$} that entered math mode is displayed for a second. This is the
1605 same feature that displays the open brace that matches a close brace that
1606 is inserted. However, there is no way to tell whether a @samp{$} enters
1607 math mode or leaves it; so when you insert a @samp{$} that enters math
1608 mode, the previous @samp{$} position is shown as if it were a match, even
1609 though they are actually unrelated.
1611 @findex tex-insert-braces
1612 @kindex C-c @{ @r{(@TeX{} mode)}
1614 @kindex C-c @} @r{(@TeX{} mode)}
1615 @TeX{} uses braces as delimiters that must match. Some users prefer
1616 to keep braces balanced at all times, rather than inserting them
1617 singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1618 braces. It leaves point between the two braces so you can insert the
1619 text that belongs inside. Afterward, use the command @kbd{C-c @}}
1620 (@code{up-list}) to move forward past the close brace.
1622 @findex tex-validate-region
1623 @findex tex-terminate-paragraph
1624 @kindex C-j @r{(@TeX{} mode)}
1625 There are two commands for checking the matching of braces.
1626 @kbd{C-j} (@code{tex-terminate-paragraph}) checks the paragraph before
1627 point, and inserts two newlines to start a new paragraph. It outputs
1628 a message in the echo area if any mismatch is found. @kbd{M-x
1629 tex-validate-region} checks a region, paragraph by paragraph. The
1630 errors are listed in an @file{*Occur*} buffer; you can use the usual
1631 Occur mode commands in that buffer, such as @kbd{C-c C-c}, to visit a
1632 particular mismatch (@pxref{Other Repeating Search}).
1634 Note that Emacs commands count square brackets and parentheses in
1635 @TeX{} mode, not just braces. This is not strictly correct for the
1636 purpose of checking @TeX{} syntax. However, parentheses and square
1637 brackets are likely to be used in text as matching delimiters, and it
1638 is useful for the various motion commands and automatic match display
1642 @subsection @LaTeX{} Editing Commands
1644 @LaTeX{} mode provides a few extra features not applicable to plain
1649 Insert @samp{\begin} and @samp{\end} for @LaTeX{} block and position
1650 point on a line between them (@code{tex-latex-block}).
1652 Close the innermost @LaTeX{} block not yet closed
1653 (@code{tex-close-latex-block}).
1656 @findex tex-latex-block
1657 @kindex C-c C-o @r{(@LaTeX{} mode)}
1658 In @LaTeX{} input, @samp{\begin} and @samp{\end} tags are used to
1659 group blocks of text. To insert a block, type @kbd{C-c C-o}
1660 (@code{tex-latex-block}). This prompts for a block type, and inserts
1661 the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a
1662 blank line between the two and moving point there.
1664 @vindex latex-block-names
1665 When entering the block type argument to @kbd{C-c C-o}, you can use
1666 the usual completion commands (@pxref{Completion}). The default
1667 completion list contains the standard @LaTeX{} block types. If you
1668 want additional block types for completion, customize the list
1669 variable @code{latex-block-names}.
1671 @findex tex-close-latex-block
1672 @kindex C-c C-e @r{(@LaTeX{} mode)}
1673 @findex latex-electric-env-pair-mode
1674 In @LaTeX{} input, @samp{\begin} and @samp{\end} tags must balance.
1675 You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an
1676 @samp{\end} tag which matches the last unmatched @samp{\begin}. It
1677 also indents the @samp{\end} to match the corresponding @samp{\begin},
1678 and inserts a newline after the @samp{\end} tag if point is at the
1679 beginning of a line. The minor mode @code{latex-electric-env-pair-mode}
1680 automatically inserts an @samp{\end} or @samp{\begin} tag for you
1681 when you type the corresponding one.
1684 @subsection @TeX{} Printing Commands
1686 You can invoke @TeX{} as an subprocess of Emacs, supplying either
1687 the entire contents of the buffer or just part of it (e.g., one
1688 chapter of a larger document).
1692 Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1694 Invoke @TeX{} on the current region, together with the buffer's header
1695 (@code{tex-region}).
1697 Invoke @TeX{} on the current file (@code{tex-file}).
1700 Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1701 C-f} command (@code{tex-view}).
1704 Print the output from the last @kbd{C-c C-b}, @kbd{C-c C-r}, or
1705 @kbd{C-c C-f} command (@code{tex-print}).
1708 Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1710 Recenter the window showing output from @TeX{} so that the last line
1711 can be seen (@code{tex-recenter-output-buffer}).
1713 Kill the @TeX{} subprocess (@code{tex-kill-job}).
1715 Invoke some other compilation command on the entire current buffer
1716 (@code{tex-compile}).
1720 @kindex C-c C-b @r{(@TeX{} mode)}
1722 @kindex C-c C-v @r{(@TeX{} mode)}
1724 @kindex C-c C-p @r{(@TeX{} mode)}
1725 To pass the current buffer through @TeX{}, type @kbd{C-c C-b}
1726 (@code{tex-buffer}). The formatted output goes in a temporary file,
1727 normally a @file{.dvi} file. Afterwards, you can type @kbd{C-c C-v}
1728 (@code{tex-view}) to launch an external program, such as
1729 @command{xdvi}, to view this output file. You can also type @kbd{C-c
1730 C-p} (@code{tex-print}) to print a hardcopy of the output file.
1732 @cindex @env{TEXINPUTS} environment variable
1733 @vindex tex-directory
1734 By default, @kbd{C-c C-b} runs @TeX{} in the current directory. The
1735 output of @TeX{} also goes in this directory. To run @TeX{} in a
1736 different directory, change the variable @code{tex-directory} to
1737 the desired directory. If your environment variable @env{TEXINPUTS}
1738 contains relative names, or if your files contains
1739 @samp{\input} commands with relative file names, then
1740 @code{tex-directory} @emph{must} be @code{"."} or you will get the
1741 wrong results. Otherwise, it is safe to specify some other directory,
1742 such as @code{"/tmp"}.
1744 @vindex tex-run-command
1745 @vindex latex-run-command
1746 @vindex tex-dvi-view-command
1747 @vindex tex-dvi-print-command
1748 @vindex tex-print-file-extension
1749 The buffer's @TeX{} variant determines what shell command @kbd{C-c
1750 C-b} actually runs. In Plain @TeX{} mode, it is specified by the
1751 variable @code{tex-run-command}, which defaults to @code{"tex"}. In
1752 @LaTeX{} mode, it is specified by @code{latex-run-command}, which
1753 defaults to @code{"latex"}. The shell command that @kbd{C-c C-v} runs
1754 to view the @file{.dvi} output is determined by the variable
1755 @code{tex-dvi-view-command}, regardless of the @TeX{} variant. The
1756 shell command that @kbd{C-c C-p} runs to print the output is
1757 determined by the variable @code{tex-dvi-print-command}. The variable
1758 @code{tex-print-file-extension} can be set to the required file
1759 extension for viewing and printing @TeX{}-compiled files. For
1760 example, you can set it to @file{.pdf}, and update
1761 @code{tex-dvi-view-command} and @code{tex-dvi-print-command}
1764 Normally, Emacs automatically appends the output file name to the
1765 shell command strings described in the preceding paragraph. For
1766 example, if @code{tex-dvi-view-command} is @code{"xdvi"}, @kbd{C-c
1767 C-v} runs @command{xdvi @var{output-file-name}}. In some cases,
1768 however, the file name needs to be embedded in the command, e.g., if
1769 you need to provide the file name as an argument to one command whose
1770 output is piped to another. You can specify where to put the file
1771 name with @samp{*} in the command string. For example,
1774 (setq tex-dvi-print-command "dvips -f * | lpr")
1777 @findex tex-kill-job
1778 @kindex C-c C-k @r{(@TeX{} mode)}
1779 @findex tex-recenter-output-buffer
1780 @kindex C-c C-l @r{(@TeX{} mode)}
1781 The terminal output from @TeX{}, including any error messages,
1782 appears in a buffer called @file{*tex-shell*}. If @TeX{} gets an
1783 error, you can switch to this buffer and feed it input (this works as
1784 in Shell mode; @pxref{Interactive Shell}). Without switching to this
1785 buffer you can scroll it so that its last line is visible by typing
1788 Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1789 you see that its output is no longer useful. Using @kbd{C-c C-b} or
1790 @kbd{C-c C-r} also kills any @TeX{} process still running.
1793 @kindex C-c C-r @r{(@TeX{} mode)}
1794 You can also pass an arbitrary region through @TeX{} by typing
1795 @kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because
1796 most files of @TeX{} input contain commands at the beginning to set
1797 parameters and define macros, without which no later part of the file
1798 will format correctly. To solve this problem, @kbd{C-c C-r} allows
1799 you to designate a part of the file as containing essential commands;
1800 it is included before the specified region as part of the input to
1801 @TeX{}. The designated part of the file is called the @dfn{header}.
1803 @cindex header (@TeX{} mode)
1804 To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1805 special strings in the file. Insert @samp{%**start of header} before the
1806 header, and @samp{%**end of header} after it. Each string must appear
1807 entirely on one line, but there may be other text on the line before or
1808 after. The lines containing the two strings are included in the header.
1809 If @samp{%**start of header} does not appear within the first 100 lines of
1810 the buffer, @kbd{C-c C-r} assumes that there is no header.
1812 In @LaTeX{} mode, the header begins with @samp{\documentclass} or
1813 @samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
1814 are commands that @LaTeX{} requires you to use in any case, so nothing
1815 special needs to be done to identify the header.
1818 @kindex C-c C-f @r{(@TeX{} mode)}
1819 The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1820 work in a temporary directory, and do not have available any of the auxiliary
1821 files needed by @TeX{} for cross-references; these commands are generally
1822 not suitable for running the final copy in which all of the cross-references
1825 When you want the auxiliary files for cross references, use @kbd{C-c
1826 C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1827 in that file's directory. Before running @TeX{}, it offers to save any
1828 modified buffers. Generally, you need to use (@code{tex-file}) twice to
1829 get the cross-references right.
1831 @vindex tex-start-options
1832 The value of the variable @code{tex-start-options} specifies
1833 options for the @TeX{} run.
1835 @vindex tex-start-commands
1836 The value of the variable @code{tex-start-commands} specifies @TeX{}
1837 commands for starting @TeX{}. The default value causes @TeX{} to run
1838 in nonstop mode. To run @TeX{} interactively, set the variable to
1841 @vindex tex-main-file
1842 Large @TeX{} documents are often split into several files---one main
1843 file, plus subfiles. Running @TeX{} on a subfile typically does not
1844 work; you have to run it on the main file. In order to make
1845 @code{tex-file} useful when you are editing a subfile, you can set the
1846 variable @code{tex-main-file} to the name of the main file. Then
1847 @code{tex-file} runs @TeX{} on that file.
1849 The most convenient way to use @code{tex-main-file} is to specify it
1850 in a local variable list in each of the subfiles. @xref{File
1853 @findex tex-bibtex-file
1854 @kindex C-c TAB @r{(@TeX{} mode)}
1855 @vindex tex-bibtex-command
1856 For @LaTeX{} files, you can use Bib@TeX{} to process the auxiliary
1857 file for the current buffer's file. Bib@TeX{} looks up bibliographic
1858 citations in a data base and prepares the cited references for the
1859 bibliography section. The command @kbd{C-c @key{TAB}}
1860 (@code{tex-bibtex-file}) runs the shell command
1861 (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1862 current buffer's file. Generally, you need to do @kbd{C-c C-f}
1863 (@code{tex-file}) once to generate the @samp{.aux} file, then do
1864 @kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1865 (@code{tex-file}) twice more to get the cross-references correct.
1868 @kindex C-c C-c @r{(@TeX{} mode)}
1869 To invoke some other compilation program on the current @TeX{}
1870 buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows
1871 how to pass arguments to many common programs, including
1872 @file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can
1873 select your desired compilation program using the standard completion
1874 keys (@pxref{Completion}).
1877 @subsection @TeX{} Mode Miscellany
1879 @vindex tex-shell-hook
1880 @vindex tex-mode-hook
1881 @vindex latex-mode-hook
1882 @vindex slitex-mode-hook
1883 @vindex plain-tex-mode-hook
1884 Entering any variant of @TeX{} mode runs the hooks
1885 @code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either
1886 @code{plain-tex-mode-hook}, @code{latex-mode-hook}, or
1887 @code{slitex-mode-hook}, whichever is appropriate. Starting the
1888 @TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}.
1892 @findex iso-iso2gtex
1893 @findex iso-gtex2iso
1894 @cindex Latin-1 @TeX{} encoding
1895 @cindex @TeX{} encoding
1896 The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1897 iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert
1898 between Latin-1 encoded files and @TeX{}-encoded equivalents.
1901 @section SGML and HTML Modes
1909 The major modes for SGML and HTML provide indentation support and
1910 commands for operating on tags.
1912 HTML consists of two modes---one, a basic mode called
1913 @code{html-mode} is a slightly customized variant of SGML mode. The
1914 other, which is used by default for HTML files, is called
1915 @code{mhtml-mode}, and attempts to properly handle Javascript enclosed
1916 in a @code{<script>} element and CSS embedded in a @code{<style>}
1921 @kindex C-c C-n @r{(SGML mode)}
1922 @findex sgml-name-char
1923 Interactively specify a special character and insert the SGML
1924 @samp{&}-command for that character (@code{sgml-name-char}).
1927 @kindex C-c C-t @r{(SGML mode)}
1929 Interactively specify a tag and its attributes (@code{sgml-tag}).
1930 This command asks you for a tag name and for the attribute values,
1931 then inserts both the opening tag and the closing tag, leaving point
1934 With a prefix argument @var{n}, the command puts the tag around the
1935 @var{n} words already present in the buffer after point. Whenever a
1936 region is active, it puts the tag around the region (when Transient
1937 Mark mode is off, it does this when a numeric argument of @minus{}1 is
1941 @kindex C-c C-a @r{(SGML mode)}
1942 @findex sgml-attributes
1943 Interactively insert attribute values for the current tag
1944 (@code{sgml-attributes}).
1947 @kindex C-c C-f @r{(SGML mode)}
1948 @findex sgml-skip-tag-forward
1949 Skip across a balanced tag group (which extends from an opening tag
1950 through its corresponding closing tag) (@code{sgml-skip-tag-forward}).
1951 A numeric argument acts as a repeat count.
1954 @kindex C-c C-b @r{(SGML mode)}
1955 @findex sgml-skip-tag-backward
1956 Skip backward across a balanced tag group (which extends from an
1957 opening tag through its corresponding closing tag)
1958 (@code{sgml-skip-tag-backward}). A numeric argument acts as a repeat
1962 @kindex C-c C-d @r{(SGML mode)}
1963 @findex sgml-delete-tag
1964 Delete the tag at or after point, and delete the matching tag too
1965 (@code{sgml-delete-tag}). If the tag at or after point is an opening
1966 tag, delete the closing tag too; if it is a closing tag, delete the
1969 @item C-c ? @var{tag} @key{RET}
1970 @kindex C-c ? @r{(SGML mode)}
1971 @findex sgml-tag-help
1972 Display a description of the meaning of tag @var{tag}
1973 (@code{sgml-tag-help}). If the argument @var{tag} is empty, describe
1977 @kindex C-c / @r{(SGML mode)}
1978 @findex sgml-close-tag
1979 Insert a close tag for the innermost unterminated tag
1980 (@code{sgml-close-tag}). If called within a tag or a comment,
1981 close it instead of inserting a close tag.
1984 @kindex C-c 8 @r{(SGML mode)}
1985 @findex sgml-name-8bit-mode
1986 Toggle a minor mode in which Latin-1 characters insert the
1987 corresponding SGML commands that stand for them, instead of the
1988 characters themselves (@code{sgml-name-8bit-mode}).
1991 @kindex C-c C-v @r{(SGML mode)}
1992 @findex sgml-validate
1993 Run a shell command (which you must specify) to validate the current
1994 buffer as SGML (@code{sgml-validate}).
1997 @kindex C-c TAB @r{(SGML mode)}
1998 @findex sgml-tags-invisible
1999 Toggle the visibility of existing tags in the buffer. This can be
2000 used as a cheap preview (@code{sgml-tags-invisible}).
2008 The major mode for editing XML documents is called nXML mode. This
2009 is a powerful major mode that can recognize many existing XML schema
2010 and use them to provide completion of XML elements via
2011 @kbd{M-@key{TAB}}, as well as on-the-fly XML
2012 validation with error highlighting. To enable nXML mode in an
2013 existing buffer, type @kbd{M-x nxml-mode}, or, equivalently, @kbd{M-x
2014 xml-mode}. Emacs uses nXML mode for files which have the extension
2015 @file{.xml}. For XHTML files, which have the extension @file{.xhtml},
2016 Emacs uses HTML mode by default; you can make it use nXML mode by
2017 customizing the variable @code{auto-mode-alist} (@pxref{Choosing
2020 nXML mode is described in its own manual: @xref{Top, nXML
2021 Mode,,nxml-mode, nXML Mode}.
2024 nXML mode is described in an Info manual, which is distributed with
2028 @vindex sgml-xml-mode
2029 You may choose to use the less powerful SGML mode for editing XML,
2030 since XML is a strict subset of SGML@. To enable SGML mode in an
2031 existing buffer, type @kbd{M-x sgml-mode}. On enabling SGML mode,
2032 Emacs examines the buffer to determine whether it is XML; if so, it
2033 sets the variable @code{sgml-xml-mode} to a non-@code{nil} value.
2034 This causes SGML mode's tag insertion commands, described above, to
2035 always insert explicit closing tags as well.
2042 @vindex nroff-mode-hook
2043 Nroff mode, a major mode derived from Text mode, is
2044 specialized for editing nroff files (e.g., Unix man pages). Type
2045 @kbd{M-x nroff-mode} to enter this mode. Entering Nroff mode runs the
2046 hook @code{text-mode-hook}, then @code{nroff-mode-hook}
2049 In Nroff mode, nroff command lines are treated as paragraph
2050 separators, pages are separated by @samp{.bp} commands, and comments
2051 start with backslash-doublequote. It also defines these commands:
2053 @findex forward-text-line
2054 @findex backward-text-line
2055 @findex count-text-lines
2056 @kindex M-n @r{(Nroff mode)}
2057 @kindex M-p @r{(Nroff mode)}
2058 @kindex M-? @r{(Nroff mode)}
2061 Move to the beginning of the next line that isn't an nroff command
2062 (@code{forward-text-line}). An argument is a repeat count.
2064 Like @kbd{M-n} but move up (@code{backward-text-line}).
2066 Displays in the echo area the number of text lines (lines that are not
2067 nroff commands) in the region (@code{count-text-lines}).
2070 @findex electric-nroff-mode
2071 Electric Nroff mode is a buffer-local minor mode that can be used
2072 with Nroff mode. To toggle this minor mode, type @kbd{M-x
2073 electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
2074 time you type @key{RET} to end a line containing an nroff command that
2075 opens a kind of grouping, the nroff command to close that grouping is
2076 automatically inserted on the following line.
2078 If you use Outline minor mode with Nroff mode (@pxref{Outline
2079 Mode}), heading lines are lines of the form @samp{.H} followed by a
2080 number (the header level).
2083 @section Enriched Text
2084 @cindex Enriched mode
2085 @cindex mode, Enriched
2086 @cindex enriched text
2088 @cindex word processing
2089 @cindex text/enriched MIME format
2091 Enriched mode is a minor mode for editing formatted text files in a
2092 WYSIWYG (What You See Is What You Get) fashion. When Enriched
2093 mode is enabled, you can apply various formatting properties to the
2094 text in the buffer, such as fonts and colors; upon saving the buffer,
2095 those properties are saved together with the text, using the MIME
2096 @samp{text/enriched} file format.
2098 Enriched mode is typically used with Text mode (@pxref{Text Mode}).
2099 It is @emph{not} compatible with Font Lock mode, which is used by many
2100 major modes, including most programming language modes, for syntax
2101 highlighting (@pxref{Font Lock}). Unlike Enriched mode, Font Lock
2102 mode assigns text properties automatically, based on the current
2103 buffer contents; those properties are not saved to disk.
2105 The file @file{enriched.txt} in Emacs's @code{data-directory}
2106 serves as an example of the features of Enriched mode.
2109 * Enriched Mode:: Entering and exiting Enriched mode.
2110 * Hard and Soft Newlines:: There are two different kinds of newlines.
2111 * Editing Format Info:: How to edit text properties.
2112 * Enriched Faces:: Bold, italic, underline, etc.
2113 * Enriched Indentation:: Changing the left and right margins.
2114 * Enriched Justification:: Centering, setting text flush with the
2115 left or right margin, etc.
2116 * Enriched Properties:: The ``special text properties'' submenu.
2120 @subsection Enriched Mode
2122 Enriched mode is a buffer-local minor mode (@pxref{Minor Modes}).
2123 When you visit a file that has been saved in the @samp{text/enriched}
2124 format, Emacs automatically enables Enriched mode, and applies the
2125 formatting information in the file to the buffer text. When you save
2126 a buffer with Enriched mode enabled, it is saved using the
2127 @samp{text/enriched} format, including the formatting information.
2129 @findex enriched-mode
2130 To create a new file of formatted text, visit the nonexistent file
2131 and type @kbd{M-x enriched-mode}. This command actually toggles
2132 Enriched mode. With a prefix argument, it enables Enriched mode if
2133 the argument is positive, and disables Enriched mode otherwise. If
2134 you disable Enriched mode, Emacs no longer saves the buffer using the
2135 @samp{text/enriched} format; any formatting properties that have been
2136 added to the buffer remain in the buffer, but they are not saved to
2139 @vindex enriched-translations
2140 Enriched mode does not save all Emacs text properties, only those
2141 specified in the variable @code{enriched-translations}. These include
2142 properties for fonts, colors, indentation, and justification.
2144 @findex format-decode-buffer
2145 If you visit a file and Emacs fails to recognize that it is in the
2146 @samp{text/enriched} format, type @kbd{M-x format-decode-buffer}.
2147 This command prompts for a file format, and re-reads the file in that
2148 format. Specifying the @samp{text/enriched} format automatically
2149 enables Enriched mode.
2151 To view a @samp{text/enriched} file in raw form (as plain text with
2152 markup tags rather than formatted text), use @kbd{M-x
2153 find-file-literally} (@pxref{Visiting}).
2155 @xref{Format Conversion,, Format Conversion, elisp, the Emacs Lisp
2156 Reference Manual}, for details of how Emacs recognizes and converts
2157 file formats like @samp{text/enriched}. @xref{Text Properties,,,
2158 elisp, the Emacs Lisp Reference Manual}, for more information about
2161 @node Hard and Soft Newlines
2162 @subsection Hard and Soft Newlines
2163 @cindex hard newline
2164 @cindex soft newline
2165 @cindex newlines, hard and soft
2167 @cindex use-hard-newlines
2168 In Enriched mode, Emacs distinguishes between two different kinds of
2169 newlines, @dfn{hard} newlines and @dfn{soft} newlines. You can also
2170 enable or disable this feature in other buffers, by typing @kbd{M-x
2173 Hard newlines are used to separate paragraphs, or anywhere there
2174 needs to be a line break regardless of how the text is filled; soft
2175 newlines are used for filling. The @key{RET} (@code{newline}) and
2176 @kbd{C-o} (@code{open-line}) commands insert hard newlines. The fill
2177 commands, including Auto Fill (@pxref{Auto Fill}), insert only soft
2178 newlines and delete only soft newlines, leaving hard newlines alone.
2180 @c FIXME: I don't see 'unfilled' in that node. --xfq
2181 Thus, when editing with Enriched mode, you should not use @key{RET}
2182 or @kbd{C-o} to break lines in the middle of filled paragraphs. Use
2183 Auto Fill mode or explicit fill commands (@pxref{Fill Commands})
2184 instead. Use @key{RET} or @kbd{C-o} where line breaks should always
2185 remain, such as in tables and lists. For such lines, you may also
2186 want to set the justification style to @code{unfilled}
2187 (@pxref{Enriched Justification}).
2189 @node Editing Format Info
2190 @subsection Editing Format Information
2192 The easiest way to alter properties is with the @samp{Text
2193 Properties} menu. You can get to this menu from the @samp{Edit} menu
2194 in the menu bar (@pxref{Menu Bar}), or with @kbd{C-mouse-2}
2195 (@pxref{Menu Mouse Clicks}). Some of the commands in the @samp{Text
2196 Properties} menu are listed below (you can also invoke them with
2200 @findex facemenu-remove-face-props
2201 @item Remove Face Properties
2202 Remove face properties from the region
2203 (@code{facemenu-remove-face-props}).
2205 @findex facemenu-remove-all
2206 @item Remove Text Properties
2207 Remove all text properties from the region, including face properties
2208 (@code{facemenu-remove-all}).
2210 @findex describe-text-properties
2211 @cindex text properties of characters
2212 @cindex overlays at character position
2213 @cindex widgets at buffer position
2214 @cindex buttons at buffer position
2215 @item Describe Properties
2216 List all text properties and other information about the character
2217 following point (@code{describe-text-properties}).
2220 Display a list of defined faces (@code{list-faces-display}).
2223 @item Display Colors
2224 Display a list of defined colors (@code{list-colors-display}).
2229 The other menu entries are described in the following sections.
2231 @node Enriched Faces
2232 @subsection Faces in Enriched Text
2234 The following commands can be used to add or remove faces
2235 (@pxref{Faces}). Each applies to the text in the region if the mark
2236 is active, and to the next self-inserting character if the mark is
2237 inactive. With a prefix argument, each command applies to the next
2238 self-inserting character even if the region is active.
2241 @kindex M-o d @r{(Enriched mode)}
2242 @findex facemenu-set-default
2244 Remove all @code{face} properties (@code{facemenu-set-default}).
2246 @kindex M-o b @r{(Enriched mode)}
2247 @findex facemenu-set-bold
2249 Apply the @code{bold} face (@code{facemenu-set-bold}).
2251 @kindex M-o i @r{(Enriched mode)}
2252 @findex facemenu-set-italic
2254 Apply the @code{italic} face (@code{facemenu-set-italic}).
2256 @kindex M-o l @r{(Enriched mode)}
2257 @findex facemenu-set-bold-italic
2259 Apply the @code{bold-italic} face (@code{facemenu-set-bold-italic}).
2261 @kindex M-o u @r{(Enriched mode)}
2262 @findex facemenu-set-underline
2264 Apply the @code{underline} face (@code{facemenu-set-underline}).
2266 @kindex M-o o @r{(Enriched mode)}
2267 @findex facemenu-set-face
2268 @item M-o o @var{face} @key{RET}
2269 Apply the face @var{face} (@code{facemenu-set-face}).
2271 @findex facemenu-set-foreground
2272 @item M-x facemenu-set-foreground
2273 Prompt for a color (@pxref{Colors}), and apply it as a foreground
2276 @findex facemenu-set-background
2277 @item M-x facemenu-set-background
2278 Prompt for a color, and apply it as a background color.
2282 These command are also available via the Text Properties menu.
2284 A self-inserting character normally inherits the face properties
2285 (and most other text properties) from the preceding character in the
2286 buffer. If you use one of the above commands to specify the face for
2287 the next self-inserting character, that character will not inherit the
2288 faces properties from the preceding character, but it will still
2289 inherit other text properties.
2291 Enriched mode defines two additional faces: @code{excerpt} and
2292 @code{fixed}. These correspond to codes used in the text/enriched
2293 file format. The @code{excerpt} face is intended for quotations; by
2294 default, it appears the same as @code{italic}. The @code{fixed} face
2295 specifies fixed-width text; by default, it appears the same as
2298 @node Enriched Indentation
2299 @subsection Indentation in Enriched Text
2301 In Enriched mode, you can specify different amounts of indentation
2302 for the right or left margin of a paragraph or a part of a paragraph.
2303 These margins also affect fill commands such as @kbd{M-q}
2306 The Indentation submenu of Text Properties offers commands
2307 for specifying indentation:
2310 @kindex C-x TAB @r{(Enriched mode)}
2311 @findex increase-left-margin
2313 Indent the region by 4 columns (@code{increase-left-margin}). In
2314 Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
2315 you supply a numeric argument, that says how many columns to add to the
2316 margin (a negative argument reduces the number of columns).
2319 Remove 4 columns of indentation from the region.
2321 @item Indent Right More
2322 Make the text narrower by indenting 4 columns at the right margin.
2324 @item Indent Right Less
2325 Remove 4 columns of indentation from the right margin.
2328 @vindex standard-indent
2329 The variable @code{standard-indent} specifies how many columns these
2330 commands should add to or subtract from the indentation. The default
2331 value is 4. The default right margin for Enriched mode is controlled
2332 by the variable @code{fill-column}, as usual.
2334 @kindex C-c [ @r{(Enriched mode)}
2335 @kindex C-c ] @r{(Enriched mode)}
2336 @findex set-left-margin
2337 @findex set-right-margin
2338 You can also type @kbd{C-c [} (@code{set-left-margin}) and @kbd{C-c
2339 ]} (@code{set-right-margin}) to set the left and right margins. You
2340 can specify the margin width with a numeric argument; otherwise these
2341 commands prompt for a value via the minibuffer.
2343 The fill prefix, if any, works in addition to the specified paragraph
2344 indentation: @kbd{C-x .} does not include the specified indentation's
2345 whitespace in the new value for the fill prefix, and the fill commands
2346 look for the fill prefix after the indentation on each line. @xref{Fill
2349 @node Enriched Justification
2350 @subsection Justification in Enriched Text
2351 @cindex justification style
2353 In Enriched mode, you can use the following commands to specify
2354 various @dfn{justification styles} for filling. These commands apply
2355 to the paragraph containing point, or, if the region is active, to all
2356 paragraphs overlapping the region.
2359 @kindex M-j l @r{(Enriched mode)}
2360 @findex set-justification-left
2362 Align lines to the left margin (@code{set-justification-left}).
2364 @kindex M-j r @r{(Enriched mode)}
2365 @findex set-justification-right
2367 Align lines to the right margin (@code{set-justification-right}).
2369 @kindex M-j b @r{(Enriched mode)}
2370 @findex set-justification-full
2372 Align lines to both margins, inserting spaces in the middle of the
2373 line to achieve this (@code{set-justification-full}).
2375 @kindex M-j c @r{(Enriched mode)}
2376 @kindex M-S @r{(Enriched mode)}
2377 @findex set-justification-center
2380 Center lines between the margins (@code{set-justification-center}).
2382 @kindex M-j u @r{(Enriched mode)}
2383 @findex set-justification-none
2385 Turn off filling entirely (@code{set-justification-none}). The fill
2386 commands do nothing on text with this setting. You can, however,
2387 still indent the left margin.
2390 @vindex default-justification
2391 You can also specify justification styles using the Justification
2392 submenu in the Text Properties menu. The default justification style
2393 is specified by the per-buffer variable @code{default-justification}.
2394 Its value should be one of the symbols @code{left}, @code{right},
2395 @code{full}, @code{center}, or @code{none}; their meanings correspond
2396 to the commands above.
2398 @node Enriched Properties
2399 @subsection Setting Other Text Properties
2401 The Special Properties submenu of Text Properties has entries for
2402 adding or removing three other text properties: @code{read-only},
2403 (which disallows alteration of the text), @code{invisible} (which
2404 hides text), and @code{intangible} (which disallows moving point
2405 within the text). The @samp{Remove Special} menu item removes all of
2406 these special properties from the text in the region.
2408 The @code{invisible} and @code{intangible} properties are not saved.
2410 @vindex enriched-allow-eval-in-display-props
2411 @cindex security, when displaying enriched text
2412 Enriched mode also supports saving and restoring @code{display}
2413 properties (@pxref{Display Property,,,elisp, the Emacs Lisp Reference
2414 Manual}), which affect how text is displayed on the screen, and also
2415 allow displaying images and strings that come from sources other than
2416 buffer text. The @code{display} properties also support execution of
2417 arbitrary Lisp forms as part of processing the property for display,
2418 thus providing a means to dynamically tailor the display to some
2419 conditions that can only be known at display time. Since execution of
2420 arbitrary Lisp opens Emacs to potential attacks, especially when the
2421 source of enriched text is outside of Emacs or even outside of your
2422 system (e.g., if it was received in an email message), such execution
2423 is by default disabled in Enriched mode. You can enable it by
2424 customizing the variable @code{enriched-allow-eval-in-display-props}
2425 to a non-@code{nil} value.
2427 @node Text Based Tables
2428 @section Editing Text-based Tables
2430 @cindex text-based tables
2432 The @code{table} package provides commands to easily edit text-based
2433 tables. Here is an example of what such a table looks like:
2437 +-----------------+--------------------------------+-----------------+
2438 | Command | Description | Key Binding |
2439 +-----------------+--------------------------------+-----------------+
2440 | forward-char |Move point right N characters | C-f |
2441 | |(left if N is negative). | |
2443 +-----------------+--------------------------------+-----------------+
2444 | backward-char |Move point left N characters | C-b |
2445 | |(right if N is negative). | |
2447 +-----------------+--------------------------------+-----------------+
2451 When Emacs recognizes such a stretch of text as a table
2452 (@pxref{Table Recognition}), editing the contents of each table cell
2453 will automatically resize the table, whenever the contents become too
2454 large to fit in the cell. You can use the commands defined in the
2455 following sections for navigating and editing the table layout.
2457 @findex table-fixed-width-mode
2458 Type @kbd{M-x table-fixed-width-mode} to toggle the automatic table
2462 * Table Definition:: What is a text based table.
2463 * Table Creation:: How to create a table.
2464 * Table Recognition:: How to activate and deactivate tables.
2465 * Cell Commands:: Cell-oriented commands in a table.
2466 * Cell Justification:: Justifying cell contents.
2467 * Table Rows and Columns:: Inserting and deleting rows and columns.
2468 * Table Conversion:: Converting between plain text and tables.
2469 * Table Misc:: Table miscellany.
2472 @node Table Definition
2473 @subsection What is a Text-based Table?
2474 @cindex cells, for text-based tables
2476 A @dfn{table} consists of a rectangular text area which is divided
2477 into @dfn{cells}. Each cell must be at least one character wide and
2478 one character high, not counting its border lines. A cell can be
2479 subdivided into more cells, but they cannot overlap.
2481 Cell border lines are drawn with three special characters, specified
2482 by the following variables:
2485 @vindex table-cell-vertical-char
2486 @item table-cell-vertical-char
2487 The character used for vertical lines. The default is @samp{|}.
2489 @vindex table-cell-horizontal-chars
2490 @item table-cell-horizontal-chars
2491 The characters used for horizontal lines. The default is @samp{"-="}.
2493 @vindex table-cell-intersection-char
2494 @item table-cell-intersection-char
2495 The character used for the intersection of horizontal and vertical
2496 lines. The default is @samp{+}.
2500 The following are examples of @emph{invalid} tables:
2503 +-----+ +--+ +-++--+
2506 +--+ | +--+--+ +-++--+
2509 +--+--+ +--+--+ +-++--+
2518 Overlapped cells or non-rectangular cells are not allowed.
2520 The border must be rectangular.
2522 Cells must have a minimum width/height of one character.
2525 @node Table Creation
2526 @subsection Creating a Table
2527 @cindex create a text-based table
2528 @cindex table creation
2530 @findex table-insert
2531 To create a text-based table from scratch, type @kbd{M-x
2532 table-insert}. This command prompts for the number of table columns,
2533 the number of table rows, cell width and cell height. The cell width
2534 and cell height do not include the cell borders; each can be specified
2535 as a single integer (which means each cell is given the same
2536 width/height), or as a sequence of integers separated by spaces or
2537 commas (which specify the width/height of the individual table
2538 columns/rows, counting from left to right for table columns and from
2539 top to bottom for table rows). The specified table is then inserted
2542 The table inserted by @kbd{M-x table-insert} contains special text
2543 properties, which tell Emacs to treat it specially as a text-based
2544 table. If you save the buffer to a file and visit it again later,
2545 those properties are lost, and the table appears to Emacs as an
2546 ordinary piece of text. See the next section, for how to convert it
2549 @node Table Recognition
2550 @subsection Table Recognition
2551 @cindex table recognition
2553 @findex table-recognize
2554 @findex table-unrecognize
2555 Existing text-based tables in a buffer, which lack the special text
2556 properties applied by @kbd{M-x table-insert}, are not treated
2557 specially as tables. To apply those text properties, type @kbd{M-x
2558 table-recognize}. This command scans the current buffer,
2559 @dfn{recognizes} valid table cells, and applies the relevant text
2560 properties. Conversely, type @kbd{M-x table-unrecognize} to
2561 @dfn{unrecognize} all tables in the current buffer, removing the
2562 special text properties and converting tables back to plain text.
2564 You can also use the following commands to selectively recognize or
2568 @findex table-recognize-region
2569 @item M-x table-recognize-region
2570 Recognize tables within the current region.
2572 @findex table-unrecognize-region
2573 @item M-x table-unrecognize-region
2574 Unrecognize tables within the current region.
2576 @findex table-recognize-table
2577 @item M-x table-recognize-table
2578 Recognize the table at point and activate it.
2580 @findex table-unrecognize-table
2581 @item M-x table-unrecognize-table
2582 Deactivate the table at point.
2584 @findex table-recognize-cell
2585 @item M-x table-recognize-cell
2586 Recognize the cell at point and activate it.
2588 @findex table-unrecognize-cell
2589 @item M-x table-unrecognize-cell
2590 Deactivate the cell at point.
2593 @xref{Table Conversion}, for another way to recognize a table.
2596 @subsection Commands for Table Cells
2598 @findex table-forward-cell
2599 @findex table-backward-cell
2600 The commands @kbd{M-x table-forward-cell} and @kbd{M-x
2601 table-backward-cell} move point from the current cell to an adjacent
2602 cell. The order is cyclic: when point is in the last cell of a table,
2603 @kbd{M-x table-forward-cell} moves to the first cell. Likewise, when
2604 point is on the first cell, @kbd{M-x table-backward-cell} moves to the
2607 @findex table-span-cell
2608 @kbd{M-x table-span-cell} prompts for a direction---right, left,
2609 above, or below---and merges the current cell with the adjacent cell
2610 in that direction. This command signals an error if the merge would
2611 result in an illegitimate cell layout.
2613 @findex table-split-cell
2614 @findex table-split-cell-vertically
2615 @findex table-split-cell-horizontally
2616 @cindex text-based tables, splitting cells
2617 @cindex splitting table cells
2618 @kbd{M-x table-split-cell} splits the current cell vertically or
2619 horizontally, prompting for the direction with the minibuffer. To
2620 split in a specific direction, use @kbd{M-x
2621 table-split-cell-vertically} and @kbd{M-x
2622 table-split-cell-horizontally}. When splitting vertically, the old
2623 cell contents are automatically split between the two new cells. When
2624 splitting horizontally, you are prompted for how to divide the cell
2625 contents, if the cell is non-empty; the options are @samp{split}
2626 (divide the contents at point), @samp{left} (put all the contents in
2627 the left cell), and @samp{right} (put all the contents in the right
2630 The following commands enlarge or shrink a cell. By default, they
2631 resize by one row or column; if a numeric argument is supplied, that
2632 specifies the number of rows or columns to resize by.
2635 @findex table-heighten-cell
2636 @item M-x table-heighten-cell
2637 Enlarge the current cell vertically.
2639 @findex table-shorten-cell
2640 @item M-x table-shorten-cell
2641 Shrink the current cell vertically.
2643 @findex table-widen-cell
2644 @item M-x table-widen-cell
2645 Enlarge the current cell horizontally.
2647 @findex table-narrow-cell
2648 @item M-x table-narrow-cell
2649 Shrink the current cell horizontally.
2652 @node Cell Justification
2653 @subsection Cell Justification
2654 @cindex justification in text-based tables
2656 The command @kbd{M-x table-justify} imposes @dfn{justification} on
2657 one or more cells in a text-based table. Justification determines how
2658 the text in the cell is aligned, relative to the edges of the cell.
2659 Each cell in a table can be separately justified.
2661 @findex table-justify
2662 @kbd{M-x table-justify} first prompts for what to justify; the
2663 options are @samp{cell} (just the current cell), @samp{column} (all
2664 cells in the current table column) and @samp{row} (all cells in the
2665 current table row). The command then prompts for the justification
2666 style; the options are @code{left}, @code{center}, @code{right},
2667 @code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no
2668 vertical justification).
2670 Horizontal and vertical justification styles are specified
2671 independently, and both types can be in effect simultaneously; for
2672 instance, you can call @kbd{M-x table-justify} twice, once to specify
2673 @code{right} justification and once to specify @code{bottom}
2674 justification, to align the contents of a cell to the bottom right.
2676 @vindex table-detect-cell-alignment
2677 The justification style is stored in the buffer as a text property,
2678 and is lost when you kill the buffer or exit Emacs. However, the
2679 table recognition commands, such as @kbd{M-x table-recognize}
2680 (@pxref{Table Recognition}), attempt to determine and re-apply each
2681 cell's justification style, by examining its contents. To disable
2682 this feature, change the variable @code{table-detect-cell-alignment}
2685 @node Table Rows and Columns
2686 @subsection Table Rows and Columns
2687 @cindex inserting rows and columns in text-based tables
2689 @findex table-insert-row
2690 @kbd{M-x table-insert-row} inserts a row of cells before the current
2691 table row. The current row, together with point, is pushed down past
2692 the new row. To insert a row after the last row at the bottom of a
2693 table, invoke this command with point below the table, just below the
2694 bottom edge. You can insert more than one row at a time by using a
2695 numeric prefix argument.
2697 @c A numeric prefix argument specifies the number of rows to insert.
2699 @findex table-insert-column
2700 Similarly, @kbd{M-x table-insert-column} inserts a column of cells
2701 to the left of the current table column. To insert a column to the
2702 right side of the rightmost column, invoke this command with point to
2703 the right of the rightmost column, outside the table. A numeric
2704 prefix argument specifies the number of columns to insert.
2706 @cindex deleting rows and column in text-based tables
2707 @kbd{M-x table-delete-column} deletes the column of cells at point.
2708 Similarly, @kbd{M-x table-delete-row} deletes the row of cells at
2709 point. A numeric prefix argument to either command specifies the
2710 number of columns or rows to delete.
2712 @node Table Conversion
2713 @subsection Converting Between Plain Text and Tables
2714 @cindex text to table
2715 @cindex table to text
2717 @findex table-capture
2718 The command @kbd{M-x table-capture} captures plain text in a region
2719 and turns it into a table. Unlike @kbd{M-x table-recognize}
2720 (@pxref{Table Recognition}), the original text does not need to have a
2721 table appearance; it only needs to have a logical table-like
2724 For example, suppose we have the following numbers, which are
2725 divided into three lines and separated horizontally by commas:
2734 Invoking @kbd{M-x table-capture} on that text produces this table:
2737 +-----+-----+-----+-----+
2739 +-----+-----+-----+-----+
2741 +-----+-----+-----+-----+
2743 +-----+-----+-----+-----+
2746 @findex table-release
2747 @kbd{M-x table-release} does the opposite: it converts a table back
2748 to plain text, removing its cell borders.
2750 One application of this pair of commands is to edit a text in
2751 layout. Look at the following three paragraphs (the latter two are
2752 indented with header lines):
2755 table-capture is a powerful command.
2756 Here are some things it can do:
2758 Parse Cell Items Using row and column delimiter regexps,
2759 it parses the specified text area and
2760 extracts cell items into a table.
2764 Applying @code{table-capture} to a region containing the above text,
2765 with empty strings for the column and row delimiter regexps, creates a
2766 table with a single cell like the following one.
2770 +----------------------------------------------------------+
2771 |table-capture is a powerful command. |
2772 |Here are some things it can do: |
2774 |Parse Cell Items Using row and column delimiter regexps,|
2775 | it parses the specified text area and |
2776 | extracts cell items into a table. |
2777 +----------------------------------------------------------+
2782 We can then use the cell splitting commands (@pxref{Cell Commands}) to
2783 subdivide the table so that each paragraph occupies a cell:
2786 +----------------------------------------------------------+
2787 |table-capture is a powerful command. |
2788 |Here are some things it can do: |
2789 +-----------------+----------------------------------------+
2790 |Parse Cell Items | Using row and column delimiter regexps,|
2791 | | it parses the specified text area and |
2792 | | extracts cell items into a table. |
2793 +-----------------+----------------------------------------+
2797 Each cell can now be edited independently without affecting the layout
2798 of other cells. When finished, we can invoke @kbd{M-x table-release}
2799 to convert the table back to plain text.
2802 @subsection Table Miscellany
2804 @cindex table dimensions
2805 @findex table-query-dimension
2806 The command @code{table-query-dimension} reports the layout of the
2807 table and table cell at point. Here is an example of its output:
2810 Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
2814 This indicates that the current cell is 21 characters wide and 6 lines
2815 high, the table is 67 characters wide and 16 lines high with 2 columns
2816 and 3 rows, and a total of 5 cells.
2818 @findex table-insert-sequence
2819 @kbd{M-x table-insert-sequence} traverses the cells of a table
2820 inserting a sequence of text strings into each cell as it goes. It
2821 asks for the base string of the sequence, and then produces the
2822 sequence by ``incrementing'' the base string, either numerically (if
2823 the base string ends in numerical characters) or in the
2824 @acronym{ASCII} order. In addition to the base string, the command
2825 prompts for the number of elements in the sequence, the increment, the
2826 cell interval, and the justification of the text in each cell.
2828 @cindex table for HTML and LaTeX
2829 @findex table-generate-source
2830 @kbd{M-x table-generate-source} generates a table formatted for a
2831 specific markup language. It asks for a language (which must be one
2832 of @code{html}, @code{latex}, or @code{cals}), a destination buffer in
2833 which to put the result, and a table caption, and then inserts the
2834 generated table into the specified buffer. The default destination
2835 buffer is @code{table.@var{lang}}, where @var{lang} is the language
2839 @section Two-Column Editing
2840 @cindex two-column editing
2841 @cindex splitting columns
2842 @cindex columns, splitting
2844 Two-column mode lets you conveniently edit two side-by-side columns
2845 of text. It uses two side-by-side windows, each showing its own
2846 buffer. There are three ways to enter two-column mode:
2849 @item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
2852 @findex 2C-two-columns
2853 Enter two-column mode with the current buffer on the left, and on the
2854 right, a buffer whose name is based on the current buffer's name
2855 (@code{2C-two-columns}). If the right-hand buffer doesn't already
2856 exist, it starts out empty; the current buffer's contents are not
2859 This command is appropriate when the current buffer is empty or contains
2860 just one column and you want to add another column.
2862 @item @kbd{@key{F2} s} or @kbd{C-x 6 s}
2866 Split the current buffer, which contains two-column text, into two
2867 buffers, and display them side by side (@code{2C-split}). The current
2868 buffer becomes the left-hand buffer, but the text in the right-hand
2869 column is moved into the right-hand buffer. The current column
2870 specifies the split point. Splitting starts with the current line and
2871 continues to the end of the buffer.
2873 This command is appropriate when you have a buffer that already contains
2874 two-column text, and you wish to separate the columns temporarily.
2876 @item @kbd{@key{F2} b @var{buffer} @key{RET}}
2877 @itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
2880 @findex 2C-associate-buffer
2881 Enter two-column mode using the current buffer as the left-hand buffer,
2882 and using buffer @var{buffer} as the right-hand buffer
2883 (@code{2C-associate-buffer}).
2886 @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
2887 is a string that appears on each line between the two columns. You can
2888 specify the width of the separator with a numeric argument to
2889 @kbd{@key{F2} s}; that many characters, before point, constitute the
2890 separator string. By default, the width is 1, so the column separator
2891 is the character before point.
2893 When a line has the separator at the proper place, @kbd{@key{F2} s}
2894 puts the text after the separator into the right-hand buffer, and
2895 deletes the separator. Lines that don't have the column separator at
2896 the proper place remain unsplit; they stay in the left-hand buffer, and
2897 the right-hand buffer gets an empty line to correspond. (This is the
2898 way to write a line that spans both columns while in two-column
2899 mode: write it in the left-hand buffer, and put an empty line in the
2905 The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}}
2906 (@code{2C-newline}) inserts a newline in each of the two buffers at
2907 corresponding positions. This is the easiest way to add a new line to
2908 the two-column text while editing it in split buffers.
2913 When you have edited both buffers as you wish, merge them with
2914 @kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the
2915 text from the right-hand buffer as a second column in the other buffer.
2916 To go back to two-column editing, use @kbd{@key{F2} s}.
2920 @findex 2C-dissociate
2921 Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
2922 leaving each as it stands (@code{2C-dissociate}). If the other buffer,
2923 the one not current when you type @kbd{@key{F2} d}, is empty,
2924 @kbd{@key{F2} d} kills it.