1 @c -*- coding: utf-8 -*-
2 @c This is part of the Emacs manual.
3 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 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. Org mode extends Outline mode and turn Emacs into a
26 full-fledged organizer: you can manage TODO lists, store notes and
27 publish them in many formats.
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 Mark 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.
160 To operate on words with an operation which acts on the region, use
161 the command @kbd{M-@@} (@code{mark-word}). This command sets the mark
162 where @kbd{M-f} would move to. @xref{Marking Objects}, for more
163 information about this command.
165 The word commands' understanding of word boundaries is controlled by
166 the syntax table. Any character can, for example, be declared to be a
167 word delimiter. @xref{Syntax Tables,, Syntax Tables, elisp, The Emacs
168 Lisp Reference Manual}.
170 In addition, see @ref{Position Info} for the @kbd{M-=}
171 (@code{count-words-region}) and @kbd{M-x count-words} commands, which
172 count and report the number of words in the region or buffer.
177 @cindex manipulating sentences
179 The Emacs commands for manipulating sentences and paragraphs are
180 mostly on Meta keys, like the word-handling commands.
184 Move back to the beginning of the sentence (@code{backward-sentence}).
186 Move forward to the end of the sentence (@code{forward-sentence}).
188 Kill forward to the end of the sentence (@code{kill-sentence}).
190 Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
195 @findex backward-sentence
196 @findex forward-sentence
197 The commands @kbd{M-a} (@code{backward-sentence}) and @kbd{M-e}
198 (@code{forward-sentence}) move to the beginning and end of the current
199 sentence, respectively. Their bindings were chosen to resemble
200 @kbd{C-a} and @kbd{C-e}, which move to the beginning and end of a
201 line. Unlike them, @kbd{M-a} and @kbd{M-e} move over successive
202 sentences if repeated.
204 Moving backward over a sentence places point just before the first
205 character of the sentence; moving forward places point right after the
206 punctuation that ends the sentence. Neither one moves over the
207 whitespace at the sentence boundary.
210 @findex kill-sentence
211 Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to
212 go with them, @kbd{M-a} and @kbd{M-e} have a corresponding kill
213 command: @kbd{M-k} (@code{kill-sentence}) kills from point to the end
214 of the sentence. With a positive numeric argument @var{n}, it kills
215 the next @var{n} sentences; with a negative argument @minus{}@var{n},
216 it kills back to the beginning of the @var{n}th preceding sentence.
219 @findex backward-kill-sentence
220 The @kbd{C-x @key{DEL}} (@code{backward-kill-sentence}) kills back
221 to the beginning of a sentence.
223 The sentence commands assume that you follow the American typist's
224 convention of putting two spaces at the end of a sentence. That is, a
225 sentence ends wherever there is a @samp{.}, @samp{?} or @samp{!}
226 followed by the end of a line or two spaces, with any number of
227 @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in
228 between. A sentence also begins or ends wherever a paragraph begins
229 or ends. It is useful to follow this convention, because it allows
230 the Emacs sentence commands to distinguish between periods that end a
231 sentence and periods that indicate abbreviations.
233 @vindex sentence-end-double-space
234 If you want to use just one space between sentences, you can set the
235 variable @code{sentence-end-double-space} to @code{nil} to make the
236 sentence commands stop for single spaces. However, this has a
237 drawback: there is no way to distinguish between periods that end
238 sentences and those that indicate abbreviations. For convenient and
239 reliable editing, we therefore recommend you follow the two-space
240 convention. The variable @code{sentence-end-double-space} also
241 affects filling (@pxref{Fill Commands}).
244 The variable @code{sentence-end} controls how to recognize the end
245 of a sentence. If non-@code{nil}, its value should be a regular
246 expression, which is used to match the last few characters of a
247 sentence, together with the whitespace following the sentence
248 (@pxref{Regexps}). If the value is @code{nil}, the default, then
249 Emacs computes sentence ends according to various criteria such as the
250 value of @code{sentence-end-double-space}.
252 @vindex sentence-end-without-period
253 Some languages, such as Thai, do not use periods to indicate the end
254 of a sentence. Set the variable @code{sentence-end-without-period} to
255 @code{t} in such cases.
260 @cindex manipulating paragraphs
262 The Emacs commands for manipulating paragraphs are also on Meta keys.
266 Move back to previous paragraph beginning (@code{backward-paragraph}).
268 Move forward to next paragraph end (@code{forward-paragraph}).
270 Put point and mark around this or next paragraph (@code{mark-paragraph}).
275 @findex backward-paragraph
276 @findex forward-paragraph
277 @kbd{M-@{} (@code{backward-paragraph}) moves to the beginning of the
278 current or previous paragraph (see below for the definition of a
279 paragraph). @kbd{M-@}} (@code{forward-paragraph}) moves to the end of
280 the current or next paragraph. If there is a blank line before the
281 paragraph, @kbd{M-@{} moves to the blank line.
284 @findex mark-paragraph
285 When you wish to operate on a paragraph, type @kbd{M-h}
286 (@code{mark-paragraph}) to set the region around it. For example,
287 @kbd{M-h C-w} kills the paragraph around or after point. @kbd{M-h}
288 puts point at the beginning and mark at the end of the paragraph point
289 was in. If point is between paragraphs (in a run of blank lines, or
290 at a boundary), @kbd{M-h} sets the region around the paragraph
291 following point. If there are blank lines preceding the first line of
292 the paragraph, one of these blank lines is included in the region. If
293 the region is already active, the command sets the mark without
294 changing point, and each subsequent @kbd{M-h} further advances the
295 mark by one paragraph.
297 The definition of a paragraph depends on the major mode. In
298 Fundamental mode, as well as Text mode and related modes, a paragraph
299 is separated each neighboring paragraph another by one or more
300 @dfn{blank lines}---lines that are either empty, or consist solely of
301 space, tab and/or formfeed characters. In programming language modes,
302 paragraphs are usually defined in a similar way, so that you can use
303 the paragraph commands even though there are no paragraphs as such in
306 Note that an indented line is @emph{not} itself a paragraph break in
307 Text mode. If you want indented lines to separate paragraphs, use
308 Paragraph-Indent Text mode instead. @xref{Text Mode}.
310 If you set a fill prefix, then paragraphs are delimited by all lines
311 which don't start with the fill prefix. @xref{Filling}.
313 @vindex paragraph-start
314 @vindex paragraph-separate
315 The precise definition of a paragraph boundary is controlled by the
316 variables @code{paragraph-separate} and @code{paragraph-start}. The
317 value of @code{paragraph-start} is a regular expression that should
318 match lines that either start or separate paragraphs
319 (@pxref{Regexps}). The value of @code{paragraph-separate} is another
320 regular expression that should match lines that separate paragraphs
321 without being part of any paragraph (for example, blank lines). Lines
322 that start a new paragraph and are contained in it must match only
323 @code{paragraph-start}, not @code{paragraph-separate}. For example,
324 in Fundamental mode, @code{paragraph-start} is @w{@code{"\f\\|[
325 \t]*$"}}, and @code{paragraph-separate} is @w{@code{"[ \t\f]*$"}}.
331 @cindex formfeed character
332 Within some text files, text is divided into @dfn{pages} delimited
333 by the @dfn{formfeed character} (@acronym{ASCII} code 12, also denoted
334 as @samp{control-L}), which is displayed in Emacs as the escape
335 sequence @samp{^L} (@pxref{Text Display}). Traditionally, when such
336 text files are printed to hardcopy, each formfeed character forces a
337 page break. Most Emacs commands treat it just like any other
338 character, so you can insert it with @kbd{C-q C-l}, delete it with
339 @key{DEL}, etc. In addition, Emacs provides commands to move over
340 pages and operate on them.
344 Display the page number of point, and the line number within that page.
346 Move point to previous page boundary (@code{backward-page}).
348 Move point to next page boundary (@code{forward-page}).
350 Put point and mark around this page (or another page) (@code{mark-page}).
352 Count the lines in this page (@code{count-lines-page}).
356 @kbd{M-x what-page} counts pages from the beginning of the file, and
357 counts lines within the page, showing both numbers in the echo area.
362 @findex backward-page
363 The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
364 after the previous page delimiter. If point is already right after a page
365 delimiter, it skips that one and stops at the previous one. A numeric
366 argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
367 command moves forward past the next page delimiter.
371 The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
372 beginning of the current page (after that page delimiter at the
373 front), and the mark at the end of the page (after the page delimiter
376 @kbd{C-x C-p C-w} is a handy way to kill a page to move it
377 elsewhere. If you move to another page delimiter with @kbd{C-x [} and
378 @kbd{C-x ]}, then yank the killed page, all the pages will be properly
379 delimited once again. The reason @kbd{C-x C-p} includes only the
380 following page delimiter in the region is to ensure that.
382 A numeric argument to @kbd{C-x C-p} specifies which page to go to,
383 relative to the current one. Zero means the current page, one
384 the next page, and @minus{}1 the previous one.
387 @findex count-lines-page
388 The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
389 where to break a page in two. It displays in the echo area the total number
390 of lines in the current page, and then divides it up into those preceding
391 the current line and those following, as in
394 Page has 96 (72+25) lines
398 Notice that the sum is off by one; this is correct if point is not at the
401 @vindex page-delimiter
402 The variable @code{page-delimiter} controls where pages begin. Its
403 value is a regular expression that matches the beginning of a line
404 that separates pages (@pxref{Regexps}). The normal value of this
405 variable is @code{"^\f"}, which matches a formfeed character at the
408 @node Quotation Marks
409 @section Quotation Marks
410 @cindex Quotation marks
411 @cindex Electric Quote mode
412 @cindex mode, Electric Quote
414 @cindex curved quotes
415 @findex electric-quote-mode
416 One common way to quote is the typewriter convention, which quotes
417 using straight apostrophes @t{'like this'} or double-quotes @t{"like
418 this"}. Another common way is the curved quote convention, which uses
419 left and right single or double quotation marks @t{‘like this’} or
420 @t{“like this”}. In text files, typewriter quotes are simple and
421 portable; curved quotes are less ambiguous and typically look nicer.
423 Electric Quote mode makes it easier to type curved quotes. As you
424 type characters it optionally converts @t{`} to @t{‘}, @t{'} to @t{’},
425 @t{``} to @t{“}, and @t{''} to @t{”}.
427 @vindex electric-quote-paragraph
428 @vindex electric-quote-comment
429 @vindex electric-quote-string
430 You can customize the behavior of Electric Quote mode by customizing
431 variables that control where it is active. It is active in text
432 paragraphs if @code{electric-quote-paragraph} is non-@code{nil}, in
433 programming-language comments if @code{electric-quote-comment} is
434 non-@code{nil}, and in programming-language strings if
435 @code{electric-quote-string} is non-@code{nil}. The default is
436 @code{nil} for @code{electric-quote-string} and @code{t} for the other
439 Electric Quote mode is disabled by default. To toggle it, type
440 @kbd{M-x electric-quote-mode}. To toggle it in a single buffer, use
441 @kbd{M-x electric-quote-local-mode}. To suppress it for a single use,
442 type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}. To
443 insert a curved quote even when Electric Quote is disabled or
444 inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for
445 @t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}.
446 @xref{Inserting Text}.
449 @section Filling Text
452 @dfn{Filling} text means breaking it up into lines that fit a
453 specified width. Emacs does filling in two ways. In Auto Fill mode,
454 inserting text with self-inserting characters also automatically fills
455 it. There are also explicit fill commands that you can use when editing
459 * Auto Fill:: Auto Fill mode breaks long lines automatically.
460 * Fill Commands:: Commands to refill paragraphs and center lines.
461 * Fill Prefix:: Filling paragraphs that are indented or in a comment, etc.
462 * Adaptive Fill:: How Emacs can determine the fill prefix automatically.
466 @subsection Auto Fill Mode
467 @cindex Auto Fill mode
468 @cindex mode, Auto Fill
470 @dfn{Auto Fill} mode is a buffer-local minor mode (@pxref{Minor
471 Modes}) in which lines are broken automatically when they become too
472 wide. Breaking happens only when you type a @key{SPC} or @key{RET}.
475 @item M-x auto-fill-mode
476 Enable or disable Auto Fill mode.
479 In Auto Fill mode, break lines when appropriate.
482 @findex auto-fill-mode
483 The mode command @kbd{M-x auto-fill-mode} toggles Auto Fill mode in
484 the current buffer. With a positive numeric argument, it enables Auto
485 Fill mode, and with a negative argument it disables it. If
486 @code{auto-fill-mode} is called from Lisp with an omitted or
487 @code{nil} argument, it enables Auto Fill mode. To enable Auto Fill
488 mode automatically in certain major modes, add @code{auto-fill-mode}
489 to the mode hooks (@pxref{Major Modes}). When Auto Fill mode is
490 enabled, the mode indicator @samp{Fill} appears in the mode line
493 Auto Fill mode breaks lines automatically at spaces whenever they
494 get longer than the desired width. This line breaking occurs only
495 when you type @key{SPC} or @key{RET}. If you wish to insert a space
496 or newline without permitting line-breaking, type @kbd{C-q @key{SPC}}
497 or @kbd{C-q C-j} respectively. Also, @kbd{C-o} inserts a newline
498 without line breaking.
500 When Auto Fill mode breaks a line, it tries to obey the
501 @dfn{adaptive fill prefix}: if a fill prefix can be deduced from the
502 first and/or second line of the current paragraph, it is inserted into
503 the new line (@pxref{Adaptive Fill}). Otherwise the new line is
504 indented, as though you had typed @key{TAB} on it
505 (@pxref{Indentation}). In a programming language mode, if a line is
506 broken in the middle of a comment, the comment is split by inserting
507 new comment delimiters as appropriate.
509 Auto Fill mode does not refill entire paragraphs; it breaks lines
510 but does not merge lines. Therefore, editing in the middle of a
511 paragraph can result in a paragraph that is not correctly filled. To
512 fill it, call the explicit fill commands
514 described in the next section.
517 (@pxref{Fill Commands}).
521 @subsection Explicit Fill Commands
525 Fill current paragraph (@code{fill-paragraph}).
527 Set the fill column (@code{set-fill-column}).
528 @item M-x fill-region
529 Fill each paragraph in the region (@code{fill-region}).
530 @item M-x fill-region-as-paragraph
531 Fill the region, considering it as one paragraph.
537 @findex fill-paragraph
538 The command @kbd{M-q} (@code{fill-paragraph}) @dfn{fills} the
539 current paragraph. It redistributes the line breaks within the
540 paragraph, and deletes any excess space and tab characters occurring
541 within the paragraph, in such a way that the lines end up fitting
542 within a certain maximum width.
545 Normally, @kbd{M-q} acts on the paragraph where point is, but if
546 point is between paragraphs, it acts on the paragraph after point. If
547 the region is active, it acts instead on the text in the region. You
548 can also call @kbd{M-x fill-region} to specifically fill the text in
551 @findex fill-region-as-paragraph
552 @kbd{M-q} and @code{fill-region} use the usual Emacs criteria for
553 finding paragraph boundaries (@pxref{Paragraphs}). For more control,
554 you can use @kbd{M-x fill-region-as-paragraph}, which refills
555 everything between point and mark as a single paragraph. This command
556 deletes any blank lines within the region, so separate blocks of text
557 end up combined into one block.
559 @cindex justification
560 A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text
561 as well as filling it. This means that extra spaces are inserted to
562 make the right margin line up exactly at the fill column. To remove
563 the extra spaces, use @kbd{M-q} with no argument. (Likewise for
568 @findex set-fill-column
569 The maximum line width for filling is specified by the buffer-local
570 variable @code{fill-column}. The default value (@pxref{Locals}) is
571 70. The easiest way to set @code{fill-column} in the current buffer
572 is to use the command @kbd{C-x f} (@code{set-fill-column}). With a
573 numeric argument, it uses that as the new fill column. With just
574 @kbd{C-u} as argument, it sets @code{fill-column} to the current
575 horizontal position of point.
577 @kindex M-o M-s @r{(Text mode)}
580 The command @kbd{M-o M-s} (@code{center-line}) centers the current line
581 within the current fill column. With an argument @var{n}, it centers
582 @var{n} lines individually and moves past them. This binding is
583 made by Text mode and is available only in that and related modes
586 By default, Emacs considers a period followed by two spaces or by a
587 newline as the end of a sentence; a period followed by just one space
588 indicates an abbreviation, not the end of a sentence. Accordingly,
589 the fill commands will not break a line after a period followed by
590 just one space. If you set the variable
591 @code{sentence-end-double-space} to @code{nil}, the fill commands will
592 break a line after a period followed by one space, and put just one
593 space after each period. @xref{Sentences}, for other effects and
594 possible drawbacks of this.
596 @vindex colon-double-space
597 If the variable @code{colon-double-space} is non-@code{nil}, the
598 fill commands put two spaces after a colon.
600 @vindex fill-nobreak-predicate
601 To specify additional conditions where line-breaking is not allowed,
602 customize the abnormal hook variable @code{fill-nobreak-predicate}
603 (@pxref{Hooks}). Each function in this hook is called with no
604 arguments, with point positioned where Emacs is considering breaking a
605 line. If a function returns a non-@code{nil} value, Emacs will not
606 break the line there. Functions you can use there include:
607 @code{fill-single-word-nobreak-p} (don't break after the first word of
608 a sentence or before the last); @code{fill-single-char-nobreak-p}
609 (don't break after a one-letter word); and @code{fill-french-nobreak-p}
610 (don't break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}).
613 @subsection The Fill Prefix
616 The @dfn{fill prefix} feature allows paragraphs to be filled so that
617 each line starts with a special string of characters (such as a
618 sequence of spaces, giving an indented paragraph). You can specify a
619 fill prefix explicitly; otherwise, Emacs tries to deduce one
620 automatically (@pxref{Adaptive Fill}).
624 Set the fill prefix (@code{set-fill-prefix}).
626 Fill a paragraph using current fill prefix (@code{fill-paragraph}).
627 @item M-x fill-individual-paragraphs
628 Fill the region, considering each change of indentation as starting a
630 @item M-x fill-nonuniform-paragraphs
631 Fill the region, considering only paragraph-separator lines as starting
636 @findex set-fill-prefix
637 To specify a fill prefix for the current buffer, move to a line that
638 starts with the desired prefix, put point at the end of the prefix,
639 and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period
640 after the @kbd{C-x}.) To turn off the fill prefix, specify an empty
641 prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line.
643 When a fill prefix is in effect, the fill commands remove the fill
644 prefix from each line of the paragraph before filling, and insert it
645 on each line after filling. (The beginning of the first line of the
646 paragraph is left unchanged, since often that is intentionally
647 different.) Auto Fill mode also inserts the fill prefix automatically
648 when it makes a new line (@pxref{Auto Fill}). The @kbd{C-o} command
649 inserts the fill prefix on new lines it creates, when you use it at
650 the beginning of a line (@pxref{Blank Lines}). Conversely, the
651 command @kbd{M-^} deletes the prefix (if it occurs) after the newline
652 that it deletes (@pxref{Indentation}).
654 For example, if @code{fill-column} is 40 and you set the fill prefix
655 to @samp{;; }, then @kbd{M-q} in the following text
659 ;; example of a paragraph
660 ;; inside a Lisp-style comment.
667 ;; This is an example of a paragraph
668 ;; inside a Lisp-style comment.
671 Lines that do not start with the fill prefix are considered to start
672 paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
673 good results for paragraphs with hanging indentation (every line
674 indented except the first one). Lines which are blank or indented once
675 the prefix is removed also separate or start paragraphs; this is what
676 you want if you are writing multi-paragraph comments with a comment
677 delimiter on each line.
679 @findex fill-individual-paragraphs
680 You can use @kbd{M-x fill-individual-paragraphs} to set the fill
681 prefix for each paragraph automatically. This command divides the
682 region into paragraphs, treating every change in the amount of
683 indentation as the start of a new paragraph, and fills each of these
684 paragraphs. Thus, all the lines in one paragraph have the same
685 amount of indentation. That indentation serves as the fill prefix for
688 @findex fill-nonuniform-paragraphs
689 @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
690 the region into paragraphs in a different way. It considers only
691 paragraph-separating lines (as defined by @code{paragraph-separate}) as
692 starting a new paragraph. Since this means that the lines of one
693 paragraph may have different amounts of indentation, the fill prefix
694 used is the smallest amount of indentation of any of the lines of the
695 paragraph. This gives good results with styles that indent a paragraph's
696 first line more or less that the rest of the paragraph.
699 The fill prefix is stored in the variable @code{fill-prefix}. Its value
700 is a string, or @code{nil} when there is no fill prefix. This is a
701 per-buffer variable; altering the variable affects only the current buffer,
702 but there is a default value which you can change as well. @xref{Locals}.
704 The @code{indentation} text property provides another way to control
705 the amount of indentation paragraphs receive. @xref{Enriched
709 @subsection Adaptive Filling
711 @cindex adaptive filling
712 The fill commands can deduce the proper fill prefix for a paragraph
713 automatically in certain cases: either whitespace or certain punctuation
714 characters at the beginning of a line are propagated to all lines of the
717 If the paragraph has two or more lines, the fill prefix is taken from
718 the paragraph's second line, but only if it appears on the first line as
721 If a paragraph has just one line, fill commands @emph{may} take a
722 prefix from that line. The decision is complicated because there are
723 three reasonable things to do in such a case:
727 Use the first line's prefix on all the lines of the paragraph.
730 Indent subsequent lines with whitespace, so that they line up under the
731 text that follows the prefix on the first line, but don't actually copy
732 the prefix from the first line.
735 Don't do anything special with the second and following lines.
738 All three of these styles of formatting are commonly used. So the
739 fill commands try to determine what you would like, based on the prefix
740 that appears and on the major mode. Here is how.
742 @vindex adaptive-fill-first-line-regexp
743 If the prefix found on the first line matches
744 @code{adaptive-fill-first-line-regexp}, or if it appears to be a
745 comment-starting sequence (this depends on the major mode), then the
746 prefix found is used for filling the paragraph, provided it would not
747 act as a paragraph starter on subsequent lines.
749 Otherwise, the prefix found is converted to an equivalent number of
750 spaces, and those spaces are used as the fill prefix for the rest of the
751 lines, provided they would not act as a paragraph starter on subsequent
754 In Text mode, and other modes where only blank lines and page
755 delimiters separate paragraphs, the prefix chosen by adaptive filling
756 never acts as a paragraph starter, so it can always be used for filling.
758 @vindex adaptive-fill-mode
759 @vindex adaptive-fill-regexp
760 The variable @code{adaptive-fill-regexp} determines what kinds of line
761 beginnings can serve as a fill prefix: any characters at the start of
762 the line that match this regular expression are used. If you set the
763 variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
764 never chosen automatically.
766 @vindex adaptive-fill-function
767 You can specify more complex ways of choosing a fill prefix
768 automatically by setting the variable @code{adaptive-fill-function} to a
769 function. This function is called with point after the left margin of a
770 line, and it should return the appropriate fill prefix based on that
771 line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets
772 a chance to find a prefix.
775 @section Case Conversion Commands
776 @cindex case conversion
778 Emacs has commands for converting either a single word or any arbitrary
779 range of text to upper case or to lower case.
783 Convert following word to lower case (@code{downcase-word}).
785 Convert following word to upper case (@code{upcase-word}).
787 Capitalize the following word (@code{capitalize-word}).
789 Convert region to lower case (@code{downcase-region}).
791 Convert region to upper case (@code{upcase-region}).
797 @cindex words, case conversion
798 @cindex converting text to upper or lower case
799 @cindex capitalizing words
800 @findex downcase-word
802 @findex capitalize-word
803 @kbd{M-l} (@code{downcase-word}) converts the word after point to
804 lower case, moving past it. Thus, repeating @kbd{M-l} converts
805 successive words. @kbd{M-u} (@code{upcase-word}) converts to all
806 capitals instead, while @kbd{M-c} (@code{capitalize-word}) puts the
807 first letter of the word into upper case and the rest into lower case.
808 All these commands convert several words at once if given an argument.
809 They are especially convenient for converting a large amount of text
810 from all upper case to mixed case, because you can move through the
811 text using @kbd{M-l}, @kbd{M-u} or @kbd{M-c} on each word as
812 appropriate, occasionally using @kbd{M-f} instead to skip a word.
814 When given a negative argument, the word case conversion commands apply
815 to the appropriate number of words before point, but do not move point.
816 This is convenient when you have just typed a word in the wrong case: you
817 can give the case conversion command and continue typing.
819 If a word case conversion command is given in the middle of a word,
820 it applies only to the part of the word which follows point. (This is
821 comparable to what @kbd{M-d} (@code{kill-word}) does.) With a
822 negative argument, case conversion applies only to the part of the
827 @findex downcase-region
828 @findex upcase-region
829 The other case conversion commands are @kbd{C-x C-u}
830 (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
831 convert everything between point and mark to the specified case. Point and
834 The region case conversion commands @code{upcase-region} and
835 @code{downcase-region} are normally disabled. This means that they ask
836 for confirmation if you try to use them. When you confirm, you may
837 enable the command, which means it will not ask for confirmation again.
846 Text mode is a major mode for editing files of text in a human
847 language. Files which have names ending in the extension @file{.txt}
848 are usually opened in Text mode (@pxref{Choosing Modes}). To
849 explicitly switch to Text mode, type @kbd{M-x text-mode}.
851 In Text mode, only blank lines and page delimiters separate
852 paragraphs. As a result, paragraphs can be indented, and adaptive
853 filling determines what indentation to use when filling a paragraph.
854 @xref{Adaptive Fill}.
856 @kindex TAB @r{(Text mode)}
857 In Text mode, the @key{TAB} (@code{indent-for-tab-command}) command
858 usually inserts whitespace up to the next tab stop, instead of
859 indenting the current line. @xref{Indentation}, for details.
861 Text mode turns off the features concerned with comments except when
862 you explicitly invoke them. It changes the syntax table so that
863 apostrophes are considered part of words (e.g., @samp{don't} is
864 considered one word). However, if a word starts with an apostrophe,
865 it is treated as a prefix for the purposes of capitalization
866 (e.g., @kbd{M-c} converts @samp{'hello'} into @samp{'Hello'}, as
869 @cindex Paragraph-Indent Text mode
870 @cindex mode, Paragraph-Indent Text
871 @findex paragraph-indent-text-mode
872 @findex paragraph-indent-minor-mode
873 If you indent the first lines of paragraphs, then you should use
874 Paragraph-Indent Text mode (@kbd{M-x paragraph-indent-text-mode})
875 rather than Text mode. In that mode, you do not need to have blank
876 lines between paragraphs, because the first-line indentation is
877 sufficient to start a paragraph; however paragraphs in which every
878 line is indented are not supported. Use @kbd{M-x
879 paragraph-indent-minor-mode} to enable an equivalent minor mode for
880 situations where you shouldn't change the major mode---in mail
881 composition, for instance.
883 @kindex M-TAB @r{(Text mode)}
884 Text mode binds @kbd{M-@key{TAB}} to @code{ispell-complete-word}.
885 This command performs completion of the partial word in the buffer
886 before point, using the spelling dictionary as the space of possible
887 words. @xref{Spelling}. If your window manager defines
888 @kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC}
889 @key{TAB}} or @kbd{C-M-i} instead.
891 @vindex text-mode-hook
892 Entering Text mode runs the mode hook @code{text-mode-hook}
893 (@pxref{Major Modes}).
895 The following sections describe several major modes that are
896 @dfn{derived} from Text mode. These derivatives share most of the
897 features of Text mode described above. In particular, derivatives of
898 Text mode run @code{text-mode-hook} prior to running their own mode
902 @section Outline Mode
904 @cindex mode, Outline
905 @cindex invisible lines
908 @findex outline-minor-mode
909 @vindex outline-minor-mode-prefix
910 @vindex outline-mode-hook
911 Outline mode is a major mode derived from Text mode, which is
912 specialized for editing outlines. It provides commands to navigate
913 between entries in the outline structure, and commands to make parts
914 of a buffer temporarily invisible, so that the outline structure may
915 be more easily viewed. Type @kbd{M-x outline-mode} to switch to
916 Outline mode. Entering Outline mode runs the hook
917 @code{text-mode-hook} followed by the hook @code{outline-mode-hook}
920 When you use an Outline mode command to make a line invisible
921 (@pxref{Outline Visibility}), the line disappears from the screen. An
922 ellipsis (three periods in a row) is displayed at the end of the
923 previous visible line, to indicate the hidden text. Multiple
924 consecutive invisible lines produce just one ellipsis.
926 Editing commands that operate on lines, such as @kbd{C-n} and
927 @kbd{C-p}, treat the text of the invisible line as part of the
928 previous visible line. Killing the ellipsis at the end of a visible
929 line really kills all the following invisible text associated with the
932 Outline minor mode is a buffer-local minor mode which provides the
933 same commands as the major mode, Outline mode, but can be used in
934 conjunction with other major modes. You can type @kbd{M-x
935 outline-minor-mode} to toggle Outline minor mode in the current
936 buffer, or use a file-local variable setting to enable it in a
937 specific file (@pxref{File Variables}).
939 @kindex C-c @@ @r{(Outline minor mode)}
940 The major mode, Outline mode, provides special key bindings on the
941 @kbd{C-c} prefix. Outline minor mode provides similar bindings with
942 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
943 major mode's special commands. (The variable
944 @code{outline-minor-mode-prefix} controls the prefix used.)
947 * Outline Format:: What the text of an outline looks like.
948 * Outline Motion:: Special commands for moving through outlines.
949 * Outline Visibility:: Commands to control what is visible.
950 * Outline Views:: Outlines and multiple views.
951 * Foldout:: Folding means zooming in on outlines.
955 @subsection Format of Outlines
957 @cindex heading lines (Outline mode)
958 @cindex body lines (Outline mode)
959 Outline mode assumes that the lines in the buffer are of two types:
960 @dfn{heading lines} and @dfn{body lines}. A heading line represents a
961 topic in the outline. Heading lines start with one or more asterisk
962 (@samp{*}) characters; the number of asterisks determines the depth of
963 the heading in the outline structure. Thus, a heading line with one
964 @samp{*} is a major topic; all the heading lines with two @samp{*}s
965 between it and the next one-@samp{*} heading are its subtopics; and so
966 on. Any line that is not a heading line is a body line. Body lines
967 belong with the preceding heading line. Here is an example:
972 which says something about the topic of food.
975 This is the body of the second-level header.
985 Another first-level topic with its header line.
988 A heading line together with all following body lines is called
989 collectively an @dfn{entry}. A heading line together with all following
990 deeper heading lines and their body lines is called a @dfn{subtree}.
992 @vindex outline-regexp
993 You can customize the criterion for distinguishing heading lines by
994 setting the variable @code{outline-regexp}. (The recommended ways to
995 do this are in a major mode function or with a file local variable.)
996 Any line whose beginning has a match for this regexp is considered a
997 heading line. Matches that start within a line (not at the left
998 margin) do not count.
1000 The length of the matching text determines the level of the heading;
1001 longer matches make a more deeply nested level. Thus, for example, if
1002 a text formatter has commands @samp{@@chapter}, @samp{@@section} and
1003 @samp{@@subsection} to divide the document into chapters and sections,
1004 you could make those lines count as heading lines by setting
1005 @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note
1006 the trick: the two words @samp{chapter} and @samp{section} are equally
1007 long, but by defining the regexp to match only @samp{chap} we ensure
1008 that the length of the text matched on a chapter heading is shorter,
1009 so that Outline mode will know that sections are contained in
1010 chapters. This works as long as no other command starts with
1013 @vindex outline-level
1014 You can explicitly specify a rule for calculating the level of a
1015 heading line by setting the variable @code{outline-level}. The value
1016 of @code{outline-level} should be a function that takes no arguments
1017 and returns the level of the current heading. The recommended ways to
1018 set this variable are in a major mode command or with a file local
1021 @node Outline Motion
1022 @subsection Outline Motion Commands
1024 Outline mode provides special motion commands that move backward and
1025 forward to heading lines.
1029 Move point to the next visible heading line
1030 (@code{outline-next-visible-heading}).
1032 Move point to the previous visible heading line
1033 (@code{outline-previous-visible-heading}).
1035 Move point to the next visible heading line at the same level
1036 as the one point is on (@code{outline-forward-same-level}).
1038 Move point to the previous visible heading line at the same level
1039 (@code{outline-backward-same-level}).
1041 Move point up to a lower-level (more inclusive) visible heading line
1042 (@code{outline-up-heading}).
1045 @findex outline-next-visible-heading
1046 @findex outline-previous-visible-heading
1047 @kindex C-c C-n @r{(Outline mode)}
1048 @kindex C-c C-p @r{(Outline mode)}
1049 @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to
1050 the next heading line. @kbd{C-c C-p}
1051 (@code{outline-previous-visible-heading}) moves similarly backward.
1052 Both accept numeric arguments as repeat counts.
1054 @findex outline-up-heading
1055 @findex outline-forward-same-level
1056 @findex outline-backward-same-level
1057 @kindex C-c C-f @r{(Outline mode)}
1058 @kindex C-c C-b @r{(Outline mode)}
1059 @kindex C-c C-u @r{(Outline mode)}
1060 @kbd{C-c C-f} (@code{outline-forward-same-level}) and @kbd{C-c C-b}
1061 (@code{outline-backward-same-level}) move from one heading line to
1062 another visible heading at the same depth in the outline. @kbd{C-c
1063 C-u} (@code{outline-up-heading}) moves backward to another heading
1064 that is less deeply nested.
1066 @node Outline Visibility
1067 @subsection Outline Visibility Commands
1069 Outline mode provides several commands for temporarily hiding or
1070 revealing parts of the buffer, based on the outline structure. These
1071 commands are not undoable; their effects are simply not recorded by
1072 the undo mechanism, so you can undo right past them (@pxref{Undo}).
1074 Many of these commands act on the current heading line. If
1075 point is on a heading line, that is the current heading line; if point
1076 is on a body line, the current heading line is the nearest preceding
1081 Make the current heading line's body invisible
1082 (@code{outline-hide-entry}).
1084 Make the current heading line's body visible
1085 (@code{outline-show-entry}).
1087 Make everything under the current heading invisible, not including the
1088 heading itself (@code{outline-hide-subtree}).
1090 Make everything under the current heading visible, including body,
1091 subheadings, and their bodies (@code{outline-show-subtree}).
1093 Make the body of the current heading line, and of all its subheadings,
1094 invisible (@code{outline-hide-leaves}).
1096 Make all subheadings of the current heading line, at all levels,
1097 visible (@code{outline-show-branches}).
1099 Make immediate subheadings (one level down) of the current heading
1100 line visible (@code{outline-show-children}).
1102 Make all body lines in the buffer invisible
1103 (@code{outline-hide-body}).
1105 Make all lines in the buffer visible (@code{outline-show-all}).
1107 Hide everything except the top @var{n} levels of heading lines
1108 (@code{outline-hide-sublevels}).
1110 Hide everything except for the heading or body that point is in, plus
1111 the headings leading up from there to the top level of the outline
1112 (@code{outline-hide-other}).
1115 @findex outline-hide-entry
1116 @findex outline-show-entry
1117 @kindex C-c C-c @r{(Outline mode)}
1118 @kindex C-c C-e @r{(Outline mode)}
1119 The simplest of these commands are @kbd{C-c C-c}
1120 (@code{outline-hide-entry}), which hides the body lines directly
1121 following the current heading line, and @kbd{C-c C-e}
1122 (@code{outline-show-entry}), which reveals them. Subheadings and
1123 their bodies are not affected.
1125 @findex outline-hide-subtree
1126 @findex outline-show-subtree
1127 @kindex C-c C-s @r{(Outline mode)}
1128 @kindex C-c C-d @r{(Outline mode)}
1129 @cindex subtree (Outline mode)
1130 The commands @kbd{C-c C-d} (@code{outline-hide-subtree}) and
1131 @kbd{C-c C-s} (@code{outline-show-subtree}) are more powerful. They
1132 apply to the current heading line's @dfn{subtree}: its body, all of
1133 its subheadings, both direct and indirect, and all of their bodies.
1135 @findex outline-hide-leaves
1136 @findex outline-show-branches
1137 @findex outline-show-children
1138 @kindex C-c C-l @r{(Outline mode)}
1139 @kindex C-c C-k @r{(Outline mode)}
1140 @kindex C-c C-i @r{(Outline mode)}
1141 The command @kbd{C-c C-l} (@code{outline-hide-leaves}) hides the
1142 body of the current heading line as well as all the bodies in its
1143 subtree; the subheadings themselves are left visible. The command
1144 @kbd{C-c C-k} (@code{outline-show-branches}) reveals the subheadings,
1145 if they had previously been hidden (e.g., by @kbd{C-c C-d}). The
1146 command @kbd{C-c C-i} (@code{outline-show-children}) is a weaker
1147 version of this; it reveals just the direct subheadings, i.e., those
1150 @findex outline-hide-other
1151 @kindex C-c C-o @r{(Outline mode)}
1152 The command @kbd{C-c C-o} (@code{outline-hide-other}) hides
1153 everything except the entry that point is in, plus its parents (the
1154 headers leading up from there to top level in the outline) and the top
1155 level headings. It also reveals body lines preceding the first
1156 heading in the buffer.
1158 @findex outline-hide-body
1159 @findex outline-show-all
1160 @kindex C-c C-t @r{(Outline mode)}
1161 @kindex C-c C-a @r{(Outline mode)}
1162 @findex hide-sublevels
1163 @kindex C-c C-q @r{(Outline mode)}
1164 The remaining commands affect the whole buffer. @kbd{C-c C-t}
1165 (@code{outline-hide-body}) makes all body lines invisible, so that you
1166 see just the outline structure (as a special exception, it will not
1167 hide lines at the top of the file, preceding the first header line,
1168 even though these are technically body lines). @kbd{C-c C-a}
1169 (@code{outline-show-all}) makes all lines visible. @kbd{C-c C-q}
1170 (@code{outline-hide-sublevels}) hides all but the top level headings
1171 at and above the level of the current heading line (defaulting to 1 if
1172 point is not on a heading); with a numeric argument @var{n}, it hides
1173 everything except the top @var{n} levels of heading lines. Note that
1174 it completely reveals all the @var{n} top levels and the body lines
1175 before the first heading.
1177 @anchor{Outline Search}
1179 @vindex search-invisible
1180 When incremental search finds text that is hidden by Outline mode,
1181 it makes that part of the buffer visible. If you exit the search at
1182 that position, the text remains visible. To toggle whether or not
1183 an active incremental search can match hidden text, type @kbd{M-s i}.
1184 To change the default for future searches, customize the option
1185 @code{search-invisible}. (This option also affects how @code{query-replace}
1186 and related functions treat hidden text, @pxref{Query Replace}.)
1187 You can also automatically make text visible as you navigate in it by
1188 using Reveal mode (@kbd{M-x reveal-mode}), a buffer-local minor mode.
1191 @subsection Viewing One Outline in Multiple Views
1193 @cindex multiple views of outline
1194 @cindex views of an outline
1195 @cindex outline with multiple views
1196 @cindex indirect buffers and outlines
1197 You can display two views of a single outline at the same time, in
1198 different windows. To do this, you must create an indirect buffer using
1199 @kbd{M-x make-indirect-buffer}. The first argument of this command is
1200 the existing outline buffer name, and its second argument is the name to
1201 use for the new indirect buffer. @xref{Indirect Buffers}.
1203 Once the indirect buffer exists, you can display it in a window in the
1204 normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline
1205 mode commands to show and hide parts of the text operate on each buffer
1206 independently; as a result, each buffer can have its own view. If you
1207 want more than two views on the same outline, create additional indirect
1211 @subsection Folding Editing
1213 @cindex folding editing
1214 The Foldout package extends Outline mode and Outline minor mode with
1215 folding commands. The idea of folding is that you zoom in on a
1216 nested portion of the outline, while hiding its relatives at higher
1219 Consider an Outline mode buffer with all the text and subheadings under
1220 level-1 headings hidden. To look at what is hidden under one of these
1221 headings, you could use @kbd{C-c C-e} (@kbd{M-x outline-show-entry})
1222 to expose the body, or @kbd{C-c C-i} to expose the child (level-2)
1226 @findex foldout-zoom-subtree
1227 With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1228 This exposes the body and child subheadings, and narrows the buffer so
1229 that only the @w{level-1} heading, the body and the level-2 headings are
1230 visible. Now to look under one of the level-2 headings, position the
1231 cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body
1232 and its level-3 child subheadings and narrows the buffer again. Zooming
1233 in on successive subheadings can be done as much as you like. A string
1234 in the mode line shows how deep you've gone.
1236 When zooming in on a heading, to see only the child subheadings specify
1237 a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children
1238 can be specified too (compare @kbd{M-x outline-show-children}), e.g.,
1239 @w{@kbd{M-2 C-c C-z}} exposes two levels of child subheadings.
1240 Alternatively, the body can be specified with a negative argument:
1241 @w{@kbd{M-- C-c C-z}}. The whole subtree can be expanded, similarly to
1242 @kbd{C-c C-s} (@kbd{M-x outline-show-subtree}), by specifying a zero
1243 argument: @w{@kbd{M-0 C-c C-z}}.
1245 While you're zoomed in, you can still use Outline mode's exposure and
1246 hiding functions without disturbing Foldout. Also, since the buffer is
1247 narrowed, global editing actions will only affect text under the
1248 zoomed-in heading. This is useful for restricting changes to a
1249 particular chapter or section of your document.
1252 @findex foldout-exit-fold
1253 To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1254 This hides all the text and subheadings under the top-level heading and
1255 returns you to the previous view of the buffer. Specifying a numeric
1256 argument exits that many levels of folds. Specifying a zero argument
1259 To cancel the narrowing of a fold without hiding the text and
1260 subheadings, specify a negative argument. For example, @w{@kbd{M--2 C-c
1261 C-x}} exits two folds and leaves the text and subheadings exposed.
1263 Foldout mode also provides mouse commands for entering and exiting
1264 folds, and for showing and hiding text:
1267 @item @kbd{C-M-mouse-1} zooms in on the heading clicked on
1270 single click: expose body.
1272 double click: expose subheadings.
1274 triple click: expose body and subheadings.
1276 quad click: expose entire subtree.
1278 @item @kbd{C-M-mouse-2} exposes text under the heading clicked on
1281 single click: expose body.
1283 double click: expose subheadings.
1285 triple click: expose body and subheadings.
1287 quad click: expose entire subtree.
1289 @item @kbd{C-M-mouse-3} hides text under the heading clicked on or exits fold
1292 single click: hide subtree.
1294 double click: exit fold and hide text.
1296 triple click: exit fold without hiding text.
1298 quad click: exit all folds and hide text.
1302 @c FIXME not marked as a user variable
1303 @vindex foldout-mouse-modifiers
1304 You can specify different modifier keys (instead of
1305 @kbd{@key{Ctrl}-@key{META}-}) by setting @code{foldout-mouse-modifiers}; but if
1306 you have already loaded the @file{foldout.el} library, you must reload
1307 it in order for this to take effect.
1309 To use the Foldout package, you can type @kbd{M-x load-library
1310 @key{RET} foldout @key{RET}}; or you can arrange for to do that
1311 automatically by putting the following in your init file:
1314 (with-eval-after-load "outline"
1326 Org mode is a variant of Outline mode for using Emacs as an
1327 organizer and/or authoring system. Files with names ending in the
1328 extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}).
1329 To explicitly switch to Org mode, type @kbd{M-x org-mode}.
1331 In Org mode, as in Outline mode, each entry has a heading line that
1332 starts with one or more @samp{*} characters. @xref{Outline Format}.
1333 In addition, any line that begins with the @samp{#} character is
1334 treated as a comment.
1336 @kindex TAB @r{(Org Mode)}
1338 Org mode provides commands for easily viewing and manipulating the
1339 outline structure. The simplest of these commands is @key{TAB}
1340 (@code{org-cycle}). If invoked on a heading line, it cycles through
1341 the different visibility states of the subtree: (i) showing only that
1342 heading line, (ii) showing only the heading line and the heading lines
1343 of its direct children, if any, and (iii) showing the entire subtree.
1344 If invoked in a body line, the global binding for @key{TAB} is
1347 @kindex S-TAB @r{(Org Mode)}
1348 @findex org-shifttab
1349 Typing @kbd{S-@key{TAB}} (@code{org-shifttab}) anywhere in an Org mode
1350 buffer cycles the visibility of the entire outline structure, between
1351 (i) showing only top-level heading lines, (ii) showing all heading
1352 lines but no body lines, and (iii) showing everything.
1354 @kindex M-<up> @r{(Org Mode)}
1355 @kindex M-<down> @r{(Org Mode)}
1356 @kindex M-<left> @r{(Org Mode)}
1357 @kindex M-<right> @r{(Org Mode)}
1359 @findex org-metadown
1360 @findex org-metaleft
1361 @findex org-metaright
1362 You can move an entire entry up or down in the buffer, including its
1363 body lines and subtree (if any), by typing @kbd{M-<up>}
1364 (@code{org-metaup}) or @kbd{M-<down>} (@code{org-metadown}) on the
1365 heading line. Similarly, you can promote or demote a heading line
1366 with @kbd{M-<left>} (@code{org-metaleft}) and @kbd{M-<right>}
1367 (@code{org-metaright}). These commands execute their global bindings
1368 if invoked on a body line.
1370 The following subsections give basic instructions for using Org mode
1371 as an organizer and as an authoring system. For details, @pxref{Top,
1372 The Org Mode Manual, Introduction, org, The Org Manual}.
1375 * Org Organizer:: Managing TODO lists and agendas.
1376 * Org Authoring:: Exporting Org buffers to various formats.
1380 @subsection Org as an organizer
1384 @kindex C-c C-t @r{(Org Mode)}
1386 @vindex org-todo-keywords
1387 You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c
1388 C-t} (@code{org-todo}) anywhere in the entry. This adds the keyword
1389 @samp{TODO} to the heading line. Typing @kbd{C-c C-t} again switches
1390 the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword
1391 entirely, and so forth. You can customize the keywords used by
1392 @kbd{C-c C-t} via the variable @code{org-todo-keywords}.
1394 @kindex C-c C-s @r{(Org Mode)}
1395 @kindex C-c C-d @r{(Org Mode)}
1396 @findex org-schedule
1397 @findex org-deadline
1398 Apart from marking an entry as TODO, you can attach a date to it, by
1399 typing @kbd{C-c C-s} (@code{org-schedule}) in the entry. This prompts
1400 for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}),
1401 and then adds the tag @samp{SCHEDULED}, together with the selected
1402 date, beneath the heading line. The command @kbd{C-c C-d}
1403 (@code{org-deadline}) has the same effect, except that it uses the tag
1406 @kindex C-c [ @r{(Org Mode)}
1407 @findex org-agenda-file-to-front
1408 @vindex org-agenda-files
1409 Once you have some TODO items planned in an Org file, you can add
1410 that file to the list of @dfn{agenda files} by typing @kbd{C-c [}
1411 (@code{org-agenda-file-to-front}). Org mode is designed to let you
1412 easily maintain multiple agenda files, e.g., for organizing different
1413 aspects of your life. The list of agenda files is stored in the
1414 variable @code{org-agenda-files}.
1417 To view items coming from your agenda files, type @kbd{M-x
1418 org-agenda}. This command prompts for what you want to see: a list of
1419 things to do this week, a list of TODO items with specific keywords,
1422 @xref{Agenda Views,,,org, The Org Manual}, for details.
1426 @subsection Org as an authoring system
1427 @cindex Org exporting
1430 @kindex C-c C-e @r{(Org mode)}
1431 You may want to format your Org notes nicely and to prepare them for
1432 export and publication. To export the current buffer, type @kbd{C-c
1433 C-e} (@code{org-export}) anywhere in an Org buffer. This command
1434 prompts for an export format; currently supported formats include
1435 HTML, @LaTeX{}, OpenDocument (@file{.odt}), and PDF@. Some formats,
1436 such as PDF, require certain system tools to be installed.
1438 @vindex org-publish-project-alist
1439 To export several files at once to a specific directory, either
1440 locally or over the network, you must define a list of projects
1441 through the variable @code{org-publish-project-alist}. See its
1442 documentation for details.
1444 Org supports a simple markup scheme for applying text formatting to
1448 - This text is /emphasized/
1449 - This text is *in bold*
1450 - This text is _underlined_
1451 - This text uses =a teletype font=
1454 ``This is a quote.''
1462 For further details, @ref{Exporting,,,org, The Org Manual}, and
1463 @ref{Publishing,,,org, The Org Manual}.
1466 @section @TeX{} Mode
1468 @cindex @LaTeX{} mode
1469 @cindex Sli@TeX{} mode
1470 @cindex Doc@TeX{} mode
1471 @cindex mode, @TeX{}
1472 @cindex mode, @LaTeX{}
1473 @cindex mode, Sli@TeX{}
1474 @cindex mode, Doc@TeX{}
1476 @findex plain-tex-mode
1482 Emacs provides special major modes for editing files written in
1483 @TeX{} and its related formats. @TeX{} is a powerful text formatter
1484 written by Donald Knuth; like GNU Emacs, it is free software.
1485 @LaTeX{} is a simplified input format for @TeX{}, implemented using
1486 @TeX{} macros. Doc@TeX{} is a special file format in which the
1487 @LaTeX{} sources are written, combining sources with documentation.
1488 Sli@TeX{} is an obsolete special form of @LaTeX{}.@footnote{It has
1489 been replaced by the @samp{slides} document class, which comes with
1492 @vindex tex-default-mode
1493 @TeX{} mode has four variants: Plain @TeX{} mode, @LaTeX{} mode,
1494 Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ
1495 only slightly, and are designed for editing the four different
1496 formats. Emacs selects the appropriate mode by looking at the
1497 contents of the buffer. (This is done by the @code{tex-mode} command,
1498 which is normally called automatically when you visit a @TeX{}-like
1499 file. @xref{Choosing Modes}.) If the contents are insufficient to
1500 determine this, Emacs chooses the mode specified by the variable
1501 @code{tex-default-mode}; its default value is @code{latex-mode}. If
1502 Emacs does not guess right, you can select the correct variant of
1503 @TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x
1504 latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}.
1506 The following sections document the features of @TeX{} mode and its
1507 variants. There are several other @TeX{}-related Emacs packages,
1508 which are not documented in this manual:
1512 Bib@TeX{} mode is a major mode for Bib@TeX{} files, which are commonly
1513 used for keeping bibliographic references for @LaTeX{} documents. For
1514 more information, see the documentation string for the command
1518 The Ref@TeX{} package provides a minor mode which can be used with
1519 @LaTeX{} mode to manage bibliographic references.
1521 @xref{Top,The Ref@TeX{} Manual,,reftex}.
1524 For more information, see the Ref@TeX{} Info manual, which is
1525 distributed with Emacs.
1529 The AUC@TeX{} package provides more advanced features for editing
1530 @TeX{} and its related formats, including the ability to preview
1531 @TeX{} equations within Emacs buffers. Unlike Bib@TeX{} mode and the
1532 Ref@TeX{} package, AUC@TeX{} is not distributed with Emacs by default.
1533 It can be downloaded via the Package Menu (@pxref{Packages}); once
1536 @ref{Top,The AUC@TeX{} Manual,,auctex}.
1539 the AUC@TeX{} manual, which is included with the package.
1544 * TeX Editing:: Special commands for editing in TeX mode.
1545 * LaTeX Editing:: Additional commands for LaTeX input files.
1546 * TeX Print:: Commands for printing part of a file with TeX.
1547 * TeX Misc:: Customization of TeX mode, and related features.
1551 @subsection @TeX{} Editing Commands
1555 Insert, according to context, either @samp{``} or @samp{"} or
1556 @samp{''} (@code{tex-insert-quote}).
1558 Insert a paragraph break (two newlines) and check the previous
1559 paragraph for unbalanced braces or dollar signs
1560 (@code{tex-terminate-paragraph}).
1561 @item M-x tex-validate-region
1562 Check each paragraph in the region for unbalanced braces or dollar signs.
1564 Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1566 Move forward past the next unmatched close brace (@code{up-list}).
1569 @findex tex-insert-quote
1570 @kindex " @r{(@TeX{} mode)}
1571 In @TeX{}, the character @samp{"} is not normally used; instead,
1572 quotations begin with @samp{``} and end with @samp{''}. @TeX{} mode
1573 therefore binds the @kbd{"} key to the @code{tex-insert-quote}
1574 command. This inserts @samp{``} after whitespace or an open brace,
1575 @samp{"} after a backslash, and @samp{''} after any other character.
1577 As a special exception, if you type @kbd{"} when the text before
1578 point is either @samp{``} or @samp{''}, Emacs replaces that preceding
1579 text with a single @samp{"} character. You can therefore type
1580 @kbd{""} to insert @samp{"}, should you ever need to do so. (You can
1581 also use @kbd{C-q "} to insert this character.)
1583 In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1584 understand the way @TeX{} math mode delimiters match. When you insert a
1585 @samp{$} that is meant to exit math mode, the position of the matching
1586 @samp{$} that entered math mode is displayed for a second. This is the
1587 same feature that displays the open brace that matches a close brace that
1588 is inserted. However, there is no way to tell whether a @samp{$} enters
1589 math mode or leaves it; so when you insert a @samp{$} that enters math
1590 mode, the previous @samp{$} position is shown as if it were a match, even
1591 though they are actually unrelated.
1593 @findex tex-insert-braces
1594 @kindex C-c @{ @r{(@TeX{} mode)}
1596 @kindex C-c @} @r{(@TeX{} mode)}
1597 @TeX{} uses braces as delimiters that must match. Some users prefer
1598 to keep braces balanced at all times, rather than inserting them
1599 singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1600 braces. It leaves point between the two braces so you can insert the
1601 text that belongs inside. Afterward, use the command @kbd{C-c @}}
1602 (@code{up-list}) to move forward past the close brace.
1604 @findex tex-validate-region
1605 @findex tex-terminate-paragraph
1606 @kindex C-j @r{(@TeX{} mode)}
1607 There are two commands for checking the matching of braces.
1608 @kbd{C-j} (@code{tex-terminate-paragraph}) checks the paragraph before
1609 point, and inserts two newlines to start a new paragraph. It outputs
1610 a message in the echo area if any mismatch is found. @kbd{M-x
1611 tex-validate-region} checks a region, paragraph by paragraph. The
1612 errors are listed in an @file{*Occur*} buffer; you can use the usual
1613 Occur mode commands in that buffer, such as @kbd{C-c C-c}, to visit a
1614 particular mismatch (@pxref{Other Repeating Search}).
1616 Note that Emacs commands count square brackets and parentheses in
1617 @TeX{} mode, not just braces. This is not strictly correct for the
1618 purpose of checking @TeX{} syntax. However, parentheses and square
1619 brackets are likely to be used in text as matching delimiters, and it
1620 is useful for the various motion commands and automatic match display
1624 @subsection @LaTeX{} Editing Commands
1626 @LaTeX{} mode provides a few extra features not applicable to plain
1631 Insert @samp{\begin} and @samp{\end} for @LaTeX{} block and position
1632 point on a line between them (@code{tex-latex-block}).
1634 Close the innermost @LaTeX{} block not yet closed
1635 (@code{tex-close-latex-block}).
1638 @findex tex-latex-block
1639 @kindex C-c C-o @r{(@LaTeX{} mode)}
1640 In @LaTeX{} input, @samp{\begin} and @samp{\end} tags are used to
1641 group blocks of text. To insert a block, type @kbd{C-c C-o}
1642 (@code{tex-latex-block}). This prompts for a block type, and inserts
1643 the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a
1644 blank line between the two and moving point there.
1646 @vindex latex-block-names
1647 When entering the block type argument to @kbd{C-c C-o}, you can use
1648 the usual completion commands (@pxref{Completion}). The default
1649 completion list contains the standard @LaTeX{} block types. If you
1650 want additional block types for completion, customize the list
1651 variable @code{latex-block-names}.
1653 @findex tex-close-latex-block
1654 @kindex C-c C-e @r{(@LaTeX{} mode)}
1655 @findex latex-electric-env-pair-mode
1656 In @LaTeX{} input, @samp{\begin} and @samp{\end} tags must balance.
1657 You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an
1658 @samp{\end} tag which matches the last unmatched @samp{\begin}. It
1659 also indents the @samp{\end} to match the corresponding @samp{\begin},
1660 and inserts a newline after the @samp{\end} tag if point is at the
1661 beginning of a line. The minor mode @code{latex-electric-env-pair-mode}
1662 automatically inserts an @samp{\end} or @samp{\begin} tag for you
1663 when you type the corresponding one.
1666 @subsection @TeX{} Printing Commands
1668 You can invoke @TeX{} as an subprocess of Emacs, supplying either
1669 the entire contents of the buffer or just part of it (e.g., one
1670 chapter of a larger document).
1674 Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1676 Invoke @TeX{} on the current region, together with the buffer's header
1677 (@code{tex-region}).
1679 Invoke @TeX{} on the current file (@code{tex-file}).
1682 Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1683 C-f} command (@code{tex-view}).
1686 Print the output from the last @kbd{C-c C-b}, @kbd{C-c C-r}, or
1687 @kbd{C-c C-f} command (@code{tex-print}).
1690 Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1692 Recenter the window showing output from @TeX{} so that the last line
1693 can be seen (@code{tex-recenter-output-buffer}).
1695 Kill the @TeX{} subprocess (@code{tex-kill-job}).
1697 Invoke some other compilation command on the entire current buffer
1698 (@code{tex-compile}).
1702 @kindex C-c C-b @r{(@TeX{} mode)}
1704 @kindex C-c C-v @r{(@TeX{} mode)}
1706 @kindex C-c C-p @r{(@TeX{} mode)}
1707 To pass the current buffer through @TeX{}, type @kbd{C-c C-b}
1708 (@code{tex-buffer}). The formatted output goes in a temporary file,
1709 normally a @file{.dvi} file. Afterwards, you can type @kbd{C-c C-v}
1710 (@code{tex-view}) to launch an external program, such as
1711 @command{xdvi}, to view this output file. You can also type @kbd{C-c
1712 C-p} (@code{tex-print}) to print a hardcopy of the output file.
1714 @cindex @env{TEXINPUTS} environment variable
1715 @vindex tex-directory
1716 By default, @kbd{C-c C-b} runs @TeX{} in the current directory. The
1717 output of @TeX{} also goes in this directory. To run @TeX{} in a
1718 different directory, change the variable @code{tex-directory} to the
1719 desired directory name. If your environment variable @env{TEXINPUTS}
1720 contains relative directory names, or if your files contains
1721 @samp{\input} commands with relative file names, then
1722 @code{tex-directory} @emph{must} be @code{"."} or you will get the
1723 wrong results. Otherwise, it is safe to specify some other directory,
1724 such as @code{"/tmp"}.
1726 @vindex tex-run-command
1727 @vindex latex-run-command
1728 @vindex tex-dvi-view-command
1729 @vindex tex-dvi-print-command
1730 @vindex tex-print-file-extension
1731 The buffer's @TeX{} variant determines what shell command @kbd{C-c
1732 C-b} actually runs. In Plain @TeX{} mode, it is specified by the
1733 variable @code{tex-run-command}, which defaults to @code{"tex"}. In
1734 @LaTeX{} mode, it is specified by @code{latex-run-command}, which
1735 defaults to @code{"latex"}. The shell command that @kbd{C-c C-v} runs
1736 to view the @file{.dvi} output is determined by the variable
1737 @code{tex-dvi-view-command}, regardless of the @TeX{} variant. The
1738 shell command that @kbd{C-c C-p} runs to print the output is
1739 determined by the variable @code{tex-dvi-print-command}. The variable
1740 @code{tex-print-file-extension} can be set to the required file
1741 extension for viewing and printing @TeX{}-compiled files. For
1742 example, you can set it to @file{.pdf}, and update
1743 @code{tex-dvi-view-command} and @code{tex-dvi-print-command}
1746 Normally, Emacs automatically appends the output file name to the
1747 shell command strings described in the preceding paragraph. For
1748 example, if @code{tex-dvi-view-command} is @code{"xdvi"}, @kbd{C-c
1749 C-v} runs @command{xdvi @var{output-file-name}}. In some cases,
1750 however, the file name needs to be embedded in the command, e.g., if
1751 you need to provide the file name as an argument to one command whose
1752 output is piped to another. You can specify where to put the file
1753 name with @samp{*} in the command string. For example,
1756 (setq tex-dvi-print-command "dvips -f * | lpr")
1759 @findex tex-kill-job
1760 @kindex C-c C-k @r{(@TeX{} mode)}
1761 @findex tex-recenter-output-buffer
1762 @kindex C-c C-l @r{(@TeX{} mode)}
1763 The terminal output from @TeX{}, including any error messages,
1764 appears in a buffer called @file{*tex-shell*}. If @TeX{} gets an
1765 error, you can switch to this buffer and feed it input (this works as
1766 in Shell mode; @pxref{Interactive Shell}). Without switching to this
1767 buffer you can scroll it so that its last line is visible by typing
1770 Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1771 you see that its output is no longer useful. Using @kbd{C-c C-b} or
1772 @kbd{C-c C-r} also kills any @TeX{} process still running.
1775 @kindex C-c C-r @r{(@TeX{} mode)}
1776 You can also pass an arbitrary region through @TeX{} by typing
1777 @kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because
1778 most files of @TeX{} input contain commands at the beginning to set
1779 parameters and define macros, without which no later part of the file
1780 will format correctly. To solve this problem, @kbd{C-c C-r} allows
1781 you to designate a part of the file as containing essential commands;
1782 it is included before the specified region as part of the input to
1783 @TeX{}. The designated part of the file is called the @dfn{header}.
1785 @cindex header (@TeX{} mode)
1786 To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1787 special strings in the file. Insert @samp{%**start of header} before the
1788 header, and @samp{%**end of header} after it. Each string must appear
1789 entirely on one line, but there may be other text on the line before or
1790 after. The lines containing the two strings are included in the header.
1791 If @samp{%**start of header} does not appear within the first 100 lines of
1792 the buffer, @kbd{C-c C-r} assumes that there is no header.
1794 In @LaTeX{} mode, the header begins with @samp{\documentclass} or
1795 @samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
1796 are commands that @LaTeX{} requires you to use in any case, so nothing
1797 special needs to be done to identify the header.
1800 @kindex C-c C-f @r{(@TeX{} mode)}
1801 The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1802 work in a temporary directory, and do not have available any of the auxiliary
1803 files needed by @TeX{} for cross-references; these commands are generally
1804 not suitable for running the final copy in which all of the cross-references
1807 When you want the auxiliary files for cross references, use @kbd{C-c
1808 C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1809 in that file's directory. Before running @TeX{}, it offers to save any
1810 modified buffers. Generally, you need to use (@code{tex-file}) twice to
1811 get the cross-references right.
1813 @vindex tex-start-options
1814 The value of the variable @code{tex-start-options} specifies
1815 options for the @TeX{} run.
1817 @vindex tex-start-commands
1818 The value of the variable @code{tex-start-commands} specifies @TeX{}
1819 commands for starting @TeX{}. The default value causes @TeX{} to run
1820 in nonstop mode. To run @TeX{} interactively, set the variable to
1823 @vindex tex-main-file
1824 Large @TeX{} documents are often split into several files---one main
1825 file, plus subfiles. Running @TeX{} on a subfile typically does not
1826 work; you have to run it on the main file. In order to make
1827 @code{tex-file} useful when you are editing a subfile, you can set the
1828 variable @code{tex-main-file} to the name of the main file. Then
1829 @code{tex-file} runs @TeX{} on that file.
1831 The most convenient way to use @code{tex-main-file} is to specify it
1832 in a local variable list in each of the subfiles. @xref{File
1835 @findex tex-bibtex-file
1836 @kindex C-c TAB @r{(@TeX{} mode)}
1837 @vindex tex-bibtex-command
1838 For @LaTeX{} files, you can use Bib@TeX{} to process the auxiliary
1839 file for the current buffer's file. Bib@TeX{} looks up bibliographic
1840 citations in a data base and prepares the cited references for the
1841 bibliography section. The command @kbd{C-c @key{TAB}}
1842 (@code{tex-bibtex-file}) runs the shell command
1843 (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1844 current buffer's file. Generally, you need to do @kbd{C-c C-f}
1845 (@code{tex-file}) once to generate the @samp{.aux} file, then do
1846 @kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1847 (@code{tex-file}) twice more to get the cross-references correct.
1850 @kindex C-c C-c @r{(@TeX{} mode)}
1851 To invoke some other compilation program on the current @TeX{}
1852 buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows
1853 how to pass arguments to many common programs, including
1854 @file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can
1855 select your desired compilation program using the standard completion
1856 keys (@pxref{Completion}).
1859 @subsection @TeX{} Mode Miscellany
1861 @vindex tex-shell-hook
1862 @vindex tex-mode-hook
1863 @vindex latex-mode-hook
1864 @vindex slitex-mode-hook
1865 @vindex plain-tex-mode-hook
1866 Entering any variant of @TeX{} mode runs the hooks
1867 @code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either
1868 @code{plain-tex-mode-hook}, @code{latex-mode-hook}, or
1869 @code{slitex-mode-hook}, whichever is appropriate. Starting the
1870 @TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}.
1874 @findex iso-iso2gtex
1875 @findex iso-gtex2iso
1876 @cindex Latin-1 @TeX{} encoding
1877 @cindex @TeX{} encoding
1878 The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1879 iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert
1880 between Latin-1 encoded files and @TeX{}-encoded equivalents.
1883 @section SGML and HTML Modes
1891 The major modes for SGML and HTML provide indentation support and
1892 commands for operating on tags. HTML mode is a slightly customized
1893 variant of SGML mode.
1897 @kindex C-c C-n @r{(SGML mode)}
1898 @findex sgml-name-char
1899 Interactively specify a special character and insert the SGML
1900 @samp{&}-command for that character (@code{sgml-name-char}).
1903 @kindex C-c C-t @r{(SGML mode)}
1905 Interactively specify a tag and its attributes (@code{sgml-tag}).
1906 This command asks you for a tag name and for the attribute values,
1907 then inserts both the opening tag and the closing tag, leaving point
1910 With a prefix argument @var{n}, the command puts the tag around the
1911 @var{n} words already present in the buffer after point. Whenever a
1912 region is active, it puts the tag around the region (when Transient
1913 Mark mode is off, it does this when a numeric argument of @minus{}1 is
1917 @kindex C-c C-a @r{(SGML mode)}
1918 @findex sgml-attributes
1919 Interactively insert attribute values for the current tag
1920 (@code{sgml-attributes}).
1923 @kindex C-c C-f @r{(SGML mode)}
1924 @findex sgml-skip-tag-forward
1925 Skip across a balanced tag group (which extends from an opening tag
1926 through its corresponding closing tag) (@code{sgml-skip-tag-forward}).
1927 A numeric argument acts as a repeat count.
1930 @kindex C-c C-b @r{(SGML mode)}
1931 @findex sgml-skip-tag-backward
1932 Skip backward across a balanced tag group (which extends from an
1933 opening tag through its corresponding closing tag)
1934 (@code{sgml-skip-tag-backward}). A numeric argument acts as a repeat
1938 @kindex C-c C-d @r{(SGML mode)}
1939 @findex sgml-delete-tag
1940 Delete the tag at or after point, and delete the matching tag too
1941 (@code{sgml-delete-tag}). If the tag at or after point is an opening
1942 tag, delete the closing tag too; if it is a closing tag, delete the
1945 @item C-c ? @var{tag} @key{RET}
1946 @kindex C-c ? @r{(SGML mode)}
1947 @findex sgml-tag-help
1948 Display a description of the meaning of tag @var{tag}
1949 (@code{sgml-tag-help}). If the argument @var{tag} is empty, describe
1953 @kindex C-c / @r{(SGML mode)}
1954 @findex sgml-close-tag
1955 Insert a close tag for the innermost unterminated tag
1956 (@code{sgml-close-tag}). If called within a tag or a comment,
1957 close it instead of inserting a close tag.
1960 @kindex C-c 8 @r{(SGML mode)}
1961 @findex sgml-name-8bit-mode
1962 Toggle a minor mode in which Latin-1 characters insert the
1963 corresponding SGML commands that stand for them, instead of the
1964 characters themselves (@code{sgml-name-8bit-mode}).
1967 @kindex C-c C-v @r{(SGML mode)}
1968 @findex sgml-validate
1969 Run a shell command (which you must specify) to validate the current
1970 buffer as SGML (@code{sgml-validate}).
1973 @kindex C-c TAB @r{(SGML mode)}
1974 @findex sgml-tags-invisible
1975 Toggle the visibility of existing tags in the buffer. This can be
1976 used as a cheap preview (@code{sgml-tags-invisible}).
1983 The major mode for editing XML documents is called nXML mode. This
1984 is a powerful major mode that can recognize many existing XML schema
1985 and use them to provide completion of XML elements via
1986 @kbd{M-@key{TAB}}, as well as on-the-fly XML
1987 validation with error highlighting. To enable nXML mode in an
1988 existing buffer, type @kbd{M-x nxml-mode}, or, equivalently, @kbd{M-x
1989 xml-mode}. Emacs uses nXML mode for files which have the extension
1990 @file{.xml}. For XHTML files, which have the extension @file{.xhtml},
1991 Emacs uses HTML mode by default; you can make it use nXML mode by
1992 customizing the variable @code{auto-mode-alist} (@pxref{Choosing
1995 nXML mode is described in its own manual: @xref{Top, nXML
1996 Mode,,nxml-mode, nXML Mode}.
1999 nXML mode is described in an Info manual, which is distributed with
2003 @vindex sgml-xml-mode
2004 You may choose to use the less powerful SGML mode for editing XML,
2005 since XML is a strict subset of SGML@. To enable SGML mode in an
2006 existing buffer, type @kbd{M-x sgml-mode}. On enabling SGML mode,
2007 Emacs examines the buffer to determine whether it is XML; if so, it
2008 sets the variable @code{sgml-xml-mode} to a non-@code{nil} value.
2009 This causes SGML mode's tag insertion commands, described above, to
2010 always insert explicit closing tags as well.
2017 @vindex nroff-mode-hook
2018 Nroff mode, a major mode derived from Text mode, is
2019 specialized for editing nroff files (e.g., Unix man pages). Type
2020 @kbd{M-x nroff-mode} to enter this mode. Entering Nroff mode runs the
2021 hook @code{text-mode-hook}, then @code{nroff-mode-hook}
2024 In Nroff mode, nroff command lines are treated as paragraph
2025 separators, pages are separated by @samp{.bp} commands, and comments
2026 start with backslash-doublequote. It also defines these commands:
2028 @findex forward-text-line
2029 @findex backward-text-line
2030 @findex count-text-lines
2031 @kindex M-n @r{(Nroff mode)}
2032 @kindex M-p @r{(Nroff mode)}
2033 @kindex M-? @r{(Nroff mode)}
2036 Move to the beginning of the next line that isn't an nroff command
2037 (@code{forward-text-line}). An argument is a repeat count.
2039 Like @kbd{M-n} but move up (@code{backward-text-line}).
2041 Displays in the echo area the number of text lines (lines that are not
2042 nroff commands) in the region (@code{count-text-lines}).
2045 @findex electric-nroff-mode
2046 Electric Nroff mode is a buffer-local minor mode that can be used
2047 with Nroff mode. To toggle this minor mode, type @kbd{M-x
2048 electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
2049 time you type @key{RET} to end a line containing an nroff command that
2050 opens a kind of grouping, the nroff command to close that grouping is
2051 automatically inserted on the following line.
2053 If you use Outline minor mode with Nroff mode (@pxref{Outline
2054 Mode}), heading lines are lines of the form @samp{.H} followed by a
2055 number (the header level).
2058 @section Enriched Text
2059 @cindex Enriched mode
2060 @cindex mode, Enriched
2061 @cindex enriched text
2063 @cindex word processing
2064 @cindex text/enriched MIME format
2066 Enriched mode is a minor mode for editing formatted text files in a
2067 WYSIWYG (What You See Is What You Get) fashion. When Enriched
2068 mode is enabled, you can apply various formatting properties to the
2069 text in the buffer, such as fonts and colors; upon saving the buffer,
2070 those properties are saved together with the text, using the MIME
2071 @samp{text/enriched} file format.
2073 Enriched mode is typically used with Text mode (@pxref{Text Mode}).
2074 It is @emph{not} compatible with Font Lock mode, which is used by many
2075 major modes, including most programming language modes, for syntax
2076 highlighting (@pxref{Font Lock}). Unlike Enriched mode, Font Lock
2077 mode assigns text properties automatically, based on the current
2078 buffer contents; those properties are not saved to disk.
2080 The file @file{enriched.txt} in Emacs's @code{data-directory}
2081 serves as an example of the features of Enriched mode.
2084 * Enriched Mode:: Entering and exiting Enriched mode.
2085 * Hard and Soft Newlines:: There are two different kinds of newlines.
2086 * Editing Format Info:: How to edit text properties.
2087 * Enriched Faces:: Bold, italic, underline, etc.
2088 * Enriched Indentation:: Changing the left and right margins.
2089 * Enriched Justification:: Centering, setting text flush with the
2090 left or right margin, etc.
2091 * Enriched Properties:: The ``special text properties'' submenu.
2095 @subsection Enriched Mode
2097 Enriched mode is a buffer-local minor mode (@pxref{Minor Modes}).
2098 When you visit a file that has been saved in the @samp{text/enriched}
2099 format, Emacs automatically enables Enriched mode, and applies the
2100 formatting information in the file to the buffer text. When you save
2101 a buffer with Enriched mode enabled, it is saved using the
2102 @samp{text/enriched} format, including the formatting information.
2104 @findex enriched-mode
2105 To create a new file of formatted text, visit the nonexistent file
2106 and type @kbd{M-x enriched-mode}. This command actually toggles
2107 Enriched mode. With a prefix argument, it enables Enriched mode if
2108 the argument is positive, and disables Enriched mode otherwise. If
2109 you disable Enriched mode, Emacs no longer saves the buffer using the
2110 @samp{text/enriched} format; any formatting properties that have been
2111 added to the buffer remain in the buffer, but they are not saved to
2114 @vindex enriched-translations
2115 Enriched mode does not save all Emacs text properties, only those
2116 specified in the variable @code{enriched-translations}. These include
2117 properties for fonts, colors, indentation, and justification.
2119 @findex format-decode-buffer
2120 If you visit a file and Emacs fails to recognize that it is in the
2121 @samp{text/enriched} format, type @kbd{M-x format-decode-buffer}.
2122 This command prompts for a file format, and re-reads the file in that
2123 format. Specifying the @samp{text/enriched} format automatically
2124 enables Enriched mode.
2126 To view a @samp{text/enriched} file in raw form (as plain text with
2127 markup tags rather than formatted text), use @kbd{M-x
2128 find-file-literally} (@pxref{Visiting}).
2130 @xref{Format Conversion,, Format Conversion, elisp, the Emacs Lisp
2131 Reference Manual}, for details of how Emacs recognizes and converts
2132 file formats like @samp{text/enriched}. @xref{Text Properties,,,
2133 elisp, the Emacs Lisp Reference Manual}, for more information about
2136 @node Hard and Soft Newlines
2137 @subsection Hard and Soft Newlines
2138 @cindex hard newline
2139 @cindex soft newline
2140 @cindex newlines, hard and soft
2142 @cindex use-hard-newlines
2143 In Enriched mode, Emacs distinguishes between two different kinds of
2144 newlines, @dfn{hard} newlines and @dfn{soft} newlines. You can also
2145 enable or disable this feature in other buffers, by typing @kbd{M-x
2148 Hard newlines are used to separate paragraphs, or anywhere there
2149 needs to be a line break regardless of how the text is filled; soft
2150 newlines are used for filling. The @key{RET} (@code{newline}) and
2151 @kbd{C-o} (@code{open-line}) commands insert hard newlines. The fill
2152 commands, including Auto Fill (@pxref{Auto Fill}), insert only soft
2153 newlines and delete only soft newlines, leaving hard newlines alone.
2155 @c FIXME: I don't see 'unfilled' in that node. --xfq
2156 Thus, when editing with Enriched mode, you should not use @key{RET}
2157 or @kbd{C-o} to break lines in the middle of filled paragraphs. Use
2158 Auto Fill mode or explicit fill commands (@pxref{Fill Commands})
2159 instead. Use @key{RET} or @kbd{C-o} where line breaks should always
2160 remain, such as in tables and lists. For such lines, you may also
2161 want to set the justification style to @code{unfilled}
2162 (@pxref{Enriched Justification}).
2164 @node Editing Format Info
2165 @subsection Editing Format Information
2167 The easiest way to alter properties is with the @samp{Text
2168 Properties} menu. You can get to this menu from the @samp{Edit} menu
2169 in the menu bar (@pxref{Menu Bar}), or with @kbd{C-mouse-2}
2170 (@pxref{Menu Mouse Clicks}). Some of the commands in the @samp{Text
2171 Properties} menu are listed below (you can also invoke them with
2175 @findex facemenu-remove-face-props
2176 @item Remove Face Properties
2177 Remove face properties from the region
2178 (@code{facemenu-remove-face-props}).
2180 @findex facemenu-remove-all
2181 @item Remove Text Properties
2182 Remove all text properties from the region, including face properties
2183 (@code{facemenu-remove-all}).
2185 @findex describe-text-properties
2186 @cindex text properties of characters
2187 @cindex overlays at character position
2188 @cindex widgets at buffer position
2189 @cindex buttons at buffer position
2190 @item Describe Properties
2191 List all text properties and other information about the character
2192 following point (@code{describe-text-properties}).
2195 Display a list of defined faces (@code{list-faces-display}).
2198 @item Display Colors
2199 Display a list of defined colors (@code{list-colors-display}).
2204 The other menu entries are described in the following sections.
2206 @node Enriched Faces
2207 @subsection Faces in Enriched Text
2209 The following commands can be used to add or remove faces
2210 (@pxref{Faces}). Each applies to the text in the region if the mark
2211 is active, and to the next self-inserting character if the mark is
2212 inactive. With a prefix argument, each command applies to the next
2213 self-inserting character even if the region is active.
2216 @kindex M-o d @r{(Enriched mode)}
2217 @findex facemenu-set-default
2219 Remove all @code{face} properties (@code{facemenu-set-default}).
2221 @kindex M-o b @r{(Enriched mode)}
2222 @findex facemenu-set-bold
2224 Apply the @code{bold} face (@code{facemenu-set-bold}).
2226 @kindex M-o i @r{(Enriched mode)}
2227 @findex facemenu-set-italic
2229 Apply the @code{italic} face (@code{facemenu-set-italic}).
2231 @kindex M-o l @r{(Enriched mode)}
2232 @findex facemenu-set-bold-italic
2234 Apply the @code{bold-italic} face (@code{facemenu-set-bold-italic}).
2236 @kindex M-o u @r{(Enriched mode)}
2237 @findex facemenu-set-underline
2239 Apply the @code{underline} face (@code{facemenu-set-underline}).
2241 @kindex M-o o @r{(Enriched mode)}
2242 @findex facemenu-set-face
2243 @item M-o o @var{face} @key{RET}
2244 Apply the face @var{face} (@code{facemenu-set-face}).
2246 @findex facemenu-set-foreground
2247 @item M-x facemenu-set-foreground
2248 Prompt for a color (@pxref{Colors}), and apply it as a foreground
2251 @findex facemenu-set-background
2252 @item M-x facemenu-set-background
2253 Prompt for a color, and apply it as a background color.
2257 These command are also available via the Text Properties menu.
2259 A self-inserting character normally inherits the face properties
2260 (and most other text properties) from the preceding character in the
2261 buffer. If you use one of the above commands to specify the face for
2262 the next self-inserting character, that character will not inherit the
2263 faces properties from the preceding character, but it will still
2264 inherit other text properties.
2266 Enriched mode defines two additional faces: @code{excerpt} and
2267 @code{fixed}. These correspond to codes used in the text/enriched
2268 file format. The @code{excerpt} face is intended for quotations; by
2269 default, it appears the same as @code{italic}. The @code{fixed} face
2270 specifies fixed-width text; by default, it appears the same as
2273 @node Enriched Indentation
2274 @subsection Indentation in Enriched Text
2276 In Enriched mode, you can specify different amounts of indentation
2277 for the right or left margin of a paragraph or a part of a paragraph.
2278 These margins also affect fill commands such as @kbd{M-q}
2281 The Indentation submenu of Text Properties offers commands
2282 for specifying indentation:
2285 @kindex C-x TAB @r{(Enriched mode)}
2286 @findex increase-left-margin
2288 Indent the region by 4 columns (@code{increase-left-margin}). In
2289 Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
2290 you supply a numeric argument, that says how many columns to add to the
2291 margin (a negative argument reduces the number of columns).
2294 Remove 4 columns of indentation from the region.
2296 @item Indent Right More
2297 Make the text narrower by indenting 4 columns at the right margin.
2299 @item Indent Right Less
2300 Remove 4 columns of indentation from the right margin.
2303 @vindex standard-indent
2304 The variable @code{standard-indent} specifies how many columns these
2305 commands should add to or subtract from the indentation. The default
2306 value is 4. The default right margin for Enriched mode is controlled
2307 by the variable @code{fill-column}, as usual.
2309 @kindex C-c [ @r{(Enriched mode)}
2310 @kindex C-c ] @r{(Enriched mode)}
2311 @findex set-left-margin
2312 @findex set-right-margin
2313 You can also type @kbd{C-c [} (@code{set-left-margin}) and @kbd{C-c
2314 ]} (@code{set-right-margin}) to set the left and right margins. You
2315 can specify the margin width with a numeric argument; otherwise these
2316 commands prompt for a value via the minibuffer.
2318 The fill prefix, if any, works in addition to the specified paragraph
2319 indentation: @kbd{C-x .} does not include the specified indentation's
2320 whitespace in the new value for the fill prefix, and the fill commands
2321 look for the fill prefix after the indentation on each line. @xref{Fill
2324 @node Enriched Justification
2325 @subsection Justification in Enriched Text
2326 @cindex justification style
2328 In Enriched mode, you can use the following commands to specify
2329 various @dfn{justification styles} for filling. These commands apply
2330 to the paragraph containing point, or, if the region is active, to all
2331 paragraphs overlapping the region.
2334 @kindex M-j l @r{(Enriched mode)}
2335 @findex set-justification-left
2337 Align lines to the left margin (@code{set-justification-left}).
2339 @kindex M-j r @r{(Enriched mode)}
2340 @findex set-justification-right
2342 Align lines to the right margin (@code{set-justification-right}).
2344 @kindex M-j b @r{(Enriched mode)}
2345 @findex set-justification-full
2347 Align lines to both margins, inserting spaces in the middle of the
2348 line to achieve this (@code{set-justification-full}).
2350 @kindex M-j c @r{(Enriched mode)}
2351 @kindex M-S @r{(Enriched mode)}
2352 @findex set-justification-center
2355 Center lines between the margins (@code{set-justification-center}).
2357 @kindex M-j u @r{(Enriched mode)}
2358 @findex set-justification-none
2360 Turn off filling entirely (@code{set-justification-none}). The fill
2361 commands do nothing on text with this setting. You can, however,
2362 still indent the left margin.
2365 @vindex default-justification
2366 You can also specify justification styles using the Justification
2367 submenu in the Text Properties menu. The default justification style
2368 is specified by the per-buffer variable @code{default-justification}.
2369 Its value should be one of the symbols @code{left}, @code{right},
2370 @code{full}, @code{center}, or @code{none}; their meanings correspond
2371 to the commands above.
2373 @node Enriched Properties
2374 @subsection Setting Other Text Properties
2376 The Special Properties submenu of Text Properties has entries for
2377 adding or removing three other text properties: @code{read-only},
2378 (which disallows alteration of the text), @code{invisible} (which
2379 hides text), and @code{intangible} (which disallows moving point
2380 within the text). The @samp{Remove Special} menu item removes all of
2381 these special properties from the text in the region.
2383 The @code{invisible} and @code{intangible} properties are not saved.
2385 @node Text Based Tables
2386 @section Editing Text-based Tables
2388 @cindex text-based tables
2390 The @code{table} package provides commands to easily edit text-based
2391 tables. Here is an example of what such a table looks like:
2395 +-----------------+--------------------------------+-----------------+
2396 | Command | Description | Key Binding |
2397 +-----------------+--------------------------------+-----------------+
2398 | forward-char |Move point right N characters | C-f |
2399 | |(left if N is negative). | |
2401 +-----------------+--------------------------------+-----------------+
2402 | backward-char |Move point left N characters | C-b |
2403 | |(right if N is negative). | |
2405 +-----------------+--------------------------------+-----------------+
2409 When Emacs recognizes such a stretch of text as a table
2410 (@pxref{Table Recognition}), editing the contents of each table cell
2411 will automatically resize the table, whenever the contents become too
2412 large to fit in the cell. You can use the commands defined in the
2413 following sections for navigating and editing the table layout.
2415 @findex table-fixed-width-mode
2416 Type @kbd{M-x table-fixed-width-mode} to toggle the automatic table
2420 * Table Definition:: What is a text based table.
2421 * Table Creation:: How to create a table.
2422 * Table Recognition:: How to activate and deactivate tables.
2423 * Cell Commands:: Cell-oriented commands in a table.
2424 * Cell Justification:: Justifying cell contents.
2425 * Table Rows and Columns:: Inserting and deleting rows and columns.
2426 * Table Conversion:: Converting between plain text and tables.
2427 * Table Misc:: Table miscellany.
2430 @node Table Definition
2431 @subsection What is a Text-based Table?
2432 @cindex cells, for text-based tables
2434 A @dfn{table} consists of a rectangular text area which is divided
2435 into @dfn{cells}. Each cell must be at least one character wide and
2436 one character high, not counting its border lines. A cell can be
2437 subdivided into more cells, but they cannot overlap.
2439 Cell border lines are drawn with three special characters, specified
2440 by the following variables:
2443 @vindex table-cell-vertical-char
2444 @item table-cell-vertical-char
2445 The character used for vertical lines. The default is @samp{|}.
2447 @vindex table-cell-horizontal-chars
2448 @item table-cell-horizontal-chars
2449 The characters used for horizontal lines. The default is @samp{"-="}.
2451 @vindex table-cell-intersection-char
2452 @item table-cell-intersection-char
2453 The character used for the intersection of horizontal and vertical
2454 lines. The default is @samp{+}.
2458 The following are examples of @emph{invalid} tables:
2461 +-----+ +--+ +-++--+
2464 +--+ | +--+--+ +-++--+
2467 +--+--+ +--+--+ +-++--+
2476 Overlapped cells or non-rectangular cells are not allowed.
2478 The border must be rectangular.
2480 Cells must have a minimum width/height of one character.
2483 @node Table Creation
2484 @subsection Creating a Table
2485 @cindex create a text-based table
2486 @cindex table creation
2488 @findex table-insert
2489 To create a text-based table from scratch, type @kbd{M-x
2490 table-insert}. This command prompts for the number of table columns,
2491 the number of table rows, cell width and cell height. The cell width
2492 and cell height do not include the cell borders; each can be specified
2493 as a single integer (which means each cell is given the same
2494 width/height), or as a sequence of integers separated by spaces or
2495 commas (which specify the width/height of the individual table
2496 columns/rows, counting from left to right for table columns and from
2497 top to bottom for table rows). The specified table is then inserted
2500 The table inserted by @kbd{M-x table-insert} contains special text
2501 properties, which tell Emacs to treat it specially as a text-based
2502 table. If you save the buffer to a file and visit it again later,
2503 those properties are lost, and the table appears to Emacs as an
2504 ordinary piece of text. See the next section, for how to convert it
2507 @node Table Recognition
2508 @subsection Table Recognition
2509 @cindex table recognition
2511 @findex table-recognize
2512 @findex table-unrecognize
2513 Existing text-based tables in a buffer, which lack the special text
2514 properties applied by @kbd{M-x table-insert}, are not treated
2515 specially as tables. To apply those text properties, type @kbd{M-x
2516 table-recognize}. This command scans the current buffer,
2517 @dfn{recognizes} valid table cells, and applies the relevant text
2518 properties. Conversely, type @kbd{M-x table-unrecognize} to
2519 @dfn{unrecognize} all tables in the current buffer, removing the
2520 special text properties and converting tables back to plain text.
2522 You can also use the following commands to selectively recognize or
2526 @findex table-recognize-region
2527 @item M-x table-recognize-region
2528 Recognize tables within the current region.
2530 @findex table-unrecognize-region
2531 @item M-x table-unrecognize-region
2532 Unrecognize tables within the current region.
2534 @findex table-recognize-table
2535 @item M-x table-recognize-table
2536 Recognize the table at point and activate it.
2538 @findex table-unrecognize-table
2539 @item M-x table-unrecognize-table
2540 Deactivate the table at point.
2542 @findex table-recognize-cell
2543 @item M-x table-recognize-cell
2544 Recognize the cell at point and activate it.
2546 @findex table-unrecognize-cell
2547 @item M-x table-unrecognize-cell
2548 Deactivate the cell at point.
2551 @xref{Table Conversion}, for another way to recognize a table.
2554 @subsection Commands for Table Cells
2556 @findex table-forward-cell
2557 @findex table-backward-cell
2558 The commands @kbd{M-x table-forward-cell} and @kbd{M-x
2559 table-backward-cell} move point from the current cell to an adjacent
2560 cell. The order is cyclic: when point is in the last cell of a table,
2561 @kbd{M-x table-forward-cell} moves to the first cell. Likewise, when
2562 point is on the first cell, @kbd{M-x table-backward-cell} moves to the
2565 @findex table-span-cell
2566 @kbd{M-x table-span-cell} prompts for a direction---right, left,
2567 above, or below---and merges the current cell with the adjacent cell
2568 in that direction. This command signals an error if the merge would
2569 result in an illegitimate cell layout.
2571 @findex table-split-cell
2572 @findex table-split-cell-vertically
2573 @findex table-split-cell-horizontally
2574 @cindex text-based tables, splitting cells
2575 @cindex splitting table cells
2576 @kbd{M-x table-split-cell} splits the current cell vertically or
2577 horizontally, prompting for the direction with the minibuffer. To
2578 split in a specific direction, use @kbd{M-x
2579 table-split-cell-vertically} and @kbd{M-x
2580 table-split-cell-horizontally}. When splitting vertically, the old
2581 cell contents are automatically split between the two new cells. When
2582 splitting horizontally, you are prompted for how to divide the cell
2583 contents, if the cell is non-empty; the options are @samp{split}
2584 (divide the contents at point), @samp{left} (put all the contents in
2585 the left cell), and @samp{right} (put all the contents in the right
2588 The following commands enlarge or shrink a cell. By default, they
2589 resize by one row or column; if a numeric argument is supplied, that
2590 specifies the number of rows or columns to resize by.
2593 @findex table-heighten-cell
2594 @item M-x table-heighten-cell
2595 Enlarge the current cell vertically.
2597 @findex table-shorten-cell
2598 @item M-x table-shorten-cell
2599 Shrink the current cell vertically.
2601 @findex table-widen-cell
2602 @item M-x table-widen-cell
2603 Enlarge the current cell horizontally.
2605 @findex table-narrow-cell
2606 @item M-x table-narrow-cell
2607 Shrink the current cell horizontally.
2610 @node Cell Justification
2611 @subsection Cell Justification
2612 @cindex justification in text-based tables
2614 The command @kbd{M-x table-justify} imposes @dfn{justification} on
2615 one or more cells in a text-based table. Justification determines how
2616 the text in the cell is aligned, relative to the edges of the cell.
2617 Each cell in a table can be separately justified.
2619 @findex table-justify
2620 @kbd{M-x table-justify} first prompts for what to justify; the
2621 options are @samp{cell} (just the current cell), @samp{column} (all
2622 cells in the current table column) and @samp{row} (all cells in the
2623 current table row). The command then prompts for the justification
2624 style; the options are @code{left}, @code{center}, @code{right},
2625 @code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no
2626 vertical justification).
2628 Horizontal and vertical justification styles are specified
2629 independently, and both types can be in effect simultaneously; for
2630 instance, you can call @kbd{M-x table-justify} twice, once to specify
2631 @code{right} justification and once to specify @code{bottom}
2632 justification, to align the contents of a cell to the bottom right.
2634 @vindex table-detect-cell-alignment
2635 The justification style is stored in the buffer as a text property,
2636 and is lost when you kill the buffer or exit Emacs. However, the
2637 table recognition commands, such as @kbd{M-x table-recognize}
2638 (@pxref{Table Recognition}), attempt to determine and re-apply each
2639 cell's justification style, by examining its contents. To disable
2640 this feature, change the variable @code{table-detect-cell-alignment}
2643 @node Table Rows and Columns
2644 @subsection Table Rows and Columns
2645 @cindex inserting rows and columns in text-based tables
2647 @findex table-insert-row
2648 @kbd{M-x table-insert-row} inserts a row of cells before the current
2649 table row. The current row, together with point, is pushed down past
2650 the new row. To insert a row after the last row at the bottom of a
2651 table, invoke this command with point below the table, just below the
2652 bottom edge. You can insert more than one row at a time by using a
2653 numeric prefix argument.
2655 @c A numeric prefix argument specifies the number of rows to insert.
2657 @findex table-insert-column
2658 Similarly, @kbd{M-x table-insert-column} inserts a column of cells
2659 to the left of the current table column. To insert a column to the
2660 right side of the rightmost column, invoke this command with point to
2661 the right of the rightmost column, outside the table. A numeric
2662 prefix argument specifies the number of columns to insert.
2664 @cindex deleting rows and column in text-based tables
2665 @kbd{M-x table-delete-column} deletes the column of cells at point.
2666 Similarly, @kbd{M-x table-delete-row} deletes the row of cells at
2667 point. A numeric prefix argument to either command specifies the
2668 number of columns or rows to delete.
2670 @node Table Conversion
2671 @subsection Converting Between Plain Text and Tables
2672 @cindex text to table
2673 @cindex table to text
2675 @findex table-capture
2676 The command @kbd{M-x table-capture} captures plain text in a region
2677 and turns it into a table. Unlike @kbd{M-x table-recognize}
2678 (@pxref{Table Recognition}), the original text does not need to have a
2679 table appearance; it only needs to have a logical table-like
2682 For example, suppose we have the following numbers, which are
2683 divided into three lines and separated horizontally by commas:
2692 Invoking @kbd{M-x table-capture} on that text produces this table:
2695 +-----+-----+-----+-----+
2697 +-----+-----+-----+-----+
2699 +-----+-----+-----+-----+
2701 +-----+-----+-----+-----+
2704 @findex table-release
2705 @kbd{M-x table-release} does the opposite: it converts a table back
2706 to plain text, removing its cell borders.
2708 One application of this pair of commands is to edit a text in
2709 layout. Look at the following three paragraphs (the latter two are
2710 indented with header lines):
2713 table-capture is a powerful command.
2714 Here are some things it can do:
2716 Parse Cell Items Using row and column delimiter regexps,
2717 it parses the specified text area and
2718 extracts cell items into a table.
2722 Applying @code{table-capture} to a region containing the above text,
2723 with empty strings for the column and row delimiter regexps, creates a
2724 table with a single cell like the following one.
2728 +----------------------------------------------------------+
2729 |table-capture is a powerful command. |
2730 |Here are some things it can do: |
2732 |Parse Cell Items Using row and column delimiter regexps,|
2733 | it parses the specified text area and |
2734 | extracts cell items into a table. |
2735 +----------------------------------------------------------+
2740 We can then use the cell splitting commands (@pxref{Cell Commands}) to
2741 subdivide the table so that each paragraph occupies a cell:
2744 +----------------------------------------------------------+
2745 |table-capture is a powerful command. |
2746 |Here are some things it can do: |
2747 +-----------------+----------------------------------------+
2748 |Parse Cell Items | Using row and column delimiter regexps,|
2749 | | it parses the specified text area and |
2750 | | extracts cell items into a table. |
2751 +-----------------+----------------------------------------+
2755 Each cell can now be edited independently without affecting the layout
2756 of other cells. When finished, we can invoke @kbd{M-x table-release}
2757 to convert the table back to plain text.
2760 @subsection Table Miscellany
2762 @cindex table dimensions
2763 @findex table-query-dimension
2764 The command @code{table-query-dimension} reports the layout of the
2765 table and table cell at point. Here is an example of its output:
2768 Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
2772 This indicates that the current cell is 21 characters wide and 6 lines
2773 high, the table is 67 characters wide and 16 lines high with 2 columns
2774 and 3 rows, and a total of 5 cells.
2776 @findex table-insert-sequence
2777 @kbd{M-x table-insert-sequence} inserts a string into each cell.
2778 Each string is a part of a sequence i.e., a series of increasing
2781 @cindex table for HTML and LaTeX
2782 @findex table-generate-source
2783 @kbd{M-x table-generate-source} generates a table formatted for a
2784 specific markup language. It asks for a language (which must be one
2785 of @code{html}, @code{latex}, or @code{cals}), a destination buffer in
2786 which to put the result, and a table caption, and then inserts the
2787 generated table into the specified buffer. The default destination
2788 buffer is @code{table.@var{lang}}, where @var{lang} is the language
2792 @section Two-Column Editing
2793 @cindex two-column editing
2794 @cindex splitting columns
2795 @cindex columns, splitting
2797 Two-column mode lets you conveniently edit two side-by-side columns
2798 of text. It uses two side-by-side windows, each showing its own
2799 buffer. There are three ways to enter two-column mode:
2802 @item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
2805 @findex 2C-two-columns
2806 Enter two-column mode with the current buffer on the left, and on the
2807 right, a buffer whose name is based on the current buffer's name
2808 (@code{2C-two-columns}). If the right-hand buffer doesn't already
2809 exist, it starts out empty; the current buffer's contents are not
2812 This command is appropriate when the current buffer is empty or contains
2813 just one column and you want to add another column.
2815 @item @kbd{@key{F2} s} or @kbd{C-x 6 s}
2819 Split the current buffer, which contains two-column text, into two
2820 buffers, and display them side by side (@code{2C-split}). The current
2821 buffer becomes the left-hand buffer, but the text in the right-hand
2822 column is moved into the right-hand buffer. The current column
2823 specifies the split point. Splitting starts with the current line and
2824 continues to the end of the buffer.
2826 This command is appropriate when you have a buffer that already contains
2827 two-column text, and you wish to separate the columns temporarily.
2829 @item @kbd{@key{F2} b @var{buffer} @key{RET}}
2830 @itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
2833 @findex 2C-associate-buffer
2834 Enter two-column mode using the current buffer as the left-hand buffer,
2835 and using buffer @var{buffer} as the right-hand buffer
2836 (@code{2C-associate-buffer}).
2839 @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
2840 is a string that appears on each line between the two columns. You can
2841 specify the width of the separator with a numeric argument to
2842 @kbd{@key{F2} s}; that many characters, before point, constitute the
2843 separator string. By default, the width is 1, so the column separator
2844 is the character before point.
2846 When a line has the separator at the proper place, @kbd{@key{F2} s}
2847 puts the text after the separator into the right-hand buffer, and
2848 deletes the separator. Lines that don't have the column separator at
2849 the proper place remain unsplit; they stay in the left-hand buffer, and
2850 the right-hand buffer gets an empty line to correspond. (This is the
2851 way to write a line that spans both columns while in two-column
2852 mode: write it in the left-hand buffer, and put an empty line in the
2858 The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}}
2859 (@code{2C-newline}) inserts a newline in each of the two buffers at
2860 corresponding positions. This is the easiest way to add a new line to
2861 the two-column text while editing it in split buffers.
2866 When you have edited both buffers as you wish, merge them with
2867 @kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the
2868 text from the right-hand buffer as a second column in the other buffer.
2869 To go back to two-column editing, use @kbd{@key{F2} s}.
2873 @findex 2C-dissociate
2874 Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
2875 leaving each as it stands (@code{2C-dissociate}). If the other buffer,
2876 the one not current when you type @kbd{@key{F2} d}, is empty,
2877 @kbd{@key{F2} d} kills it.