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
416 @findex electric-quote-mode
417 One common way to quote is the typewriter convention, which quotes
418 using straight apostrophes @t{'like this'} or double-quotes @t{"like
419 this"}. Another common way is the curved quote convention, which uses
420 left and right single or double quotation marks @t{‘like this’} or
421 @t{“like this”}. In text files, typewriter quotes are simple and
422 portable; curved quotes are less ambiguous and typically look nicer.
424 @vindex electric-quote-chars
425 Electric Quote mode makes it easier to type curved quotes. As you
426 type characters it optionally converts @t{`} to @t{‘}, @t{'} to @t{’},
427 @t{``} to @t{“}, and @t{''} to @t{”}. It's possible to change the
428 default quotes listed above, by customizing the variable
429 @code{electric-quote-chars}, a list of four characters, where the
430 items correspond to the left single quote, the right single quote, the
431 left double quote and the right double quote, respectively, whose
432 default value is @code{'(?‘ ?’ ?“ ?”)}.
434 @vindex electric-quote-paragraph
435 @vindex electric-quote-comment
436 @vindex electric-quote-string
437 You can customize the behavior of Electric Quote mode by customizing
438 variables that control where it is active. It is active in text
439 paragraphs if @code{electric-quote-paragraph} is non-@code{nil}, in
440 programming-language comments if @code{electric-quote-comment} is
441 non-@code{nil}, and in programming-language strings if
442 @code{electric-quote-string} is non-@code{nil}. The default is
443 @code{nil} for @code{electric-quote-string} and @code{t} for the other
446 Electric Quote mode is disabled by default. To toggle it, type
447 @kbd{M-x electric-quote-mode}. To toggle it in a single buffer, use
448 @kbd{M-x electric-quote-local-mode}. To suppress it for a single use,
449 type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}. To
450 insert a curved quote even when Electric Quote is disabled or
451 inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for
452 @t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}.
453 @xref{Inserting Text}. Note that the value of
454 @code{electric-quote-chars} does not affect these keybindings, they
455 are not keybindings of @code{electric-quote-mode} but bound in
459 @section Filling Text
462 @dfn{Filling} text means breaking it up into lines that fit a
463 specified width. Emacs does filling in two ways. In Auto Fill mode,
464 inserting text with self-inserting characters also automatically fills
465 it. There are also explicit fill commands that you can use when editing
469 * Auto Fill:: Auto Fill mode breaks long lines automatically.
470 * Fill Commands:: Commands to refill paragraphs and center lines.
471 * Fill Prefix:: Filling paragraphs that are indented or in a comment, etc.
472 * Adaptive Fill:: How Emacs can determine the fill prefix automatically.
476 @subsection Auto Fill Mode
477 @cindex Auto Fill mode
478 @cindex mode, Auto Fill
480 @dfn{Auto Fill} mode is a buffer-local minor mode (@pxref{Minor
481 Modes}) in which lines are broken automatically when they become too
482 wide. Breaking happens only when you type a @key{SPC} or @key{RET}.
485 @item M-x auto-fill-mode
486 Enable or disable Auto Fill mode.
489 In Auto Fill mode, break lines when appropriate.
492 @findex auto-fill-mode
493 The mode command @kbd{M-x auto-fill-mode} toggles Auto Fill mode in
494 the current buffer. With a positive numeric argument, it enables Auto
495 Fill mode, and with a negative argument it disables it. If
496 @code{auto-fill-mode} is called from Lisp with an omitted or
497 @code{nil} argument, it enables Auto Fill mode. To enable Auto Fill
498 mode automatically in certain major modes, add @code{auto-fill-mode}
499 to the mode hooks (@pxref{Major Modes}). When Auto Fill mode is
500 enabled, the mode indicator @samp{Fill} appears in the mode line
503 Auto Fill mode breaks lines automatically at spaces whenever they
504 get longer than the desired width. This line breaking occurs only
505 when you type @key{SPC} or @key{RET}. If you wish to insert a space
506 or newline without permitting line-breaking, type @kbd{C-q @key{SPC}}
507 or @kbd{C-q C-j} respectively. Also, @kbd{C-o} inserts a newline
508 without line breaking.
510 When Auto Fill mode breaks a line, it tries to obey the
511 @dfn{adaptive fill prefix}: if a fill prefix can be deduced from the
512 first and/or second line of the current paragraph, it is inserted into
513 the new line (@pxref{Adaptive Fill}). Otherwise the new line is
514 indented, as though you had typed @key{TAB} on it
515 (@pxref{Indentation}). In a programming language mode, if a line is
516 broken in the middle of a comment, the comment is split by inserting
517 new comment delimiters as appropriate.
519 Auto Fill mode does not refill entire paragraphs; it breaks lines
520 but does not merge lines. Therefore, editing in the middle of a
521 paragraph can result in a paragraph that is not correctly filled. To
522 fill it, call the explicit fill commands
524 described in the next section.
527 (@pxref{Fill Commands}).
531 @subsection Explicit Fill Commands
535 Fill current paragraph (@code{fill-paragraph}).
537 Set the fill column (@code{set-fill-column}).
538 @item M-x fill-region
539 Fill each paragraph in the region (@code{fill-region}).
540 @item M-x fill-region-as-paragraph
541 Fill the region, considering it as one paragraph.
547 @findex fill-paragraph
548 The command @kbd{M-q} (@code{fill-paragraph}) @dfn{fills} the
549 current paragraph. It redistributes the line breaks within the
550 paragraph, and deletes any excess space and tab characters occurring
551 within the paragraph, in such a way that the lines end up fitting
552 within a certain maximum width.
555 Normally, @kbd{M-q} acts on the paragraph where point is, but if
556 point is between paragraphs, it acts on the paragraph after point. If
557 the region is active, it acts instead on the text in the region. You
558 can also call @kbd{M-x fill-region} to specifically fill the text in
561 @findex fill-region-as-paragraph
562 @kbd{M-q} and @code{fill-region} use the usual Emacs criteria for
563 finding paragraph boundaries (@pxref{Paragraphs}). For more control,
564 you can use @kbd{M-x fill-region-as-paragraph}, which refills
565 everything between point and mark as a single paragraph. This command
566 deletes any blank lines within the region, so separate blocks of text
567 end up combined into one block.
569 @cindex justification
570 A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text
571 as well as filling it. This means that extra spaces are inserted to
572 make the right margin line up exactly at the fill column. To remove
573 the extra spaces, use @kbd{M-q} with no argument. (Likewise for
578 @findex set-fill-column
579 The maximum line width for filling is specified by the buffer-local
580 variable @code{fill-column}. The default value (@pxref{Locals}) is
581 70. The easiest way to set @code{fill-column} in the current buffer
582 is to use the command @kbd{C-x f} (@code{set-fill-column}). With a
583 numeric argument, it uses that as the new fill column. With just
584 @kbd{C-u} as argument, it sets @code{fill-column} to the current
585 horizontal position of point.
587 @kindex M-o M-s @r{(Text mode)}
590 The command @kbd{M-o M-s} (@code{center-line}) centers the current line
591 within the current fill column. With an argument @var{n}, it centers
592 @var{n} lines individually and moves past them. This binding is
593 made by Text mode and is available only in that and related modes
596 By default, Emacs considers a period followed by two spaces or by a
597 newline as the end of a sentence; a period followed by just one space
598 indicates an abbreviation, not the end of a sentence. Accordingly,
599 the fill commands will not break a line after a period followed by
600 just one space. If you set the variable
601 @code{sentence-end-double-space} to @code{nil}, the fill commands will
602 break a line after a period followed by one space, and put just one
603 space after each period. @xref{Sentences}, for other effects and
604 possible drawbacks of this.
606 @vindex colon-double-space
607 If the variable @code{colon-double-space} is non-@code{nil}, the
608 fill commands put two spaces after a colon.
610 @vindex fill-nobreak-predicate
611 To specify additional conditions where line-breaking is not allowed,
612 customize the abnormal hook variable @code{fill-nobreak-predicate}
613 (@pxref{Hooks}). Each function in this hook is called with no
614 arguments, with point positioned where Emacs is considering breaking a
615 line. If a function returns a non-@code{nil} value, Emacs will not
616 break the line there. Functions you can use there include:
617 @code{fill-single-word-nobreak-p} (don't break after the first word of
618 a sentence or before the last); @code{fill-single-char-nobreak-p}
619 (don't break after a one-letter word); and @code{fill-french-nobreak-p}
620 (don't break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}).
623 @subsection The Fill Prefix
626 The @dfn{fill prefix} feature allows paragraphs to be filled so that
627 each line starts with a special string of characters (such as a
628 sequence of spaces, giving an indented paragraph). You can specify a
629 fill prefix explicitly; otherwise, Emacs tries to deduce one
630 automatically (@pxref{Adaptive Fill}).
634 Set the fill prefix (@code{set-fill-prefix}).
636 Fill a paragraph using current fill prefix (@code{fill-paragraph}).
637 @item M-x fill-individual-paragraphs
638 Fill the region, considering each change of indentation as starting a
640 @item M-x fill-nonuniform-paragraphs
641 Fill the region, considering only paragraph-separator lines as starting
646 @findex set-fill-prefix
647 To specify a fill prefix for the current buffer, move to a line that
648 starts with the desired prefix, put point at the end of the prefix,
649 and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period
650 after the @kbd{C-x}.) To turn off the fill prefix, specify an empty
651 prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line.
653 When a fill prefix is in effect, the fill commands remove the fill
654 prefix from each line of the paragraph before filling, and insert it
655 on each line after filling. (The beginning of the first line of the
656 paragraph is left unchanged, since often that is intentionally
657 different.) Auto Fill mode also inserts the fill prefix automatically
658 when it makes a new line (@pxref{Auto Fill}). The @kbd{C-o} command
659 inserts the fill prefix on new lines it creates, when you use it at
660 the beginning of a line (@pxref{Blank Lines}). Conversely, the
661 command @kbd{M-^} deletes the prefix (if it occurs) after the newline
662 that it deletes (@pxref{Indentation}).
664 For example, if @code{fill-column} is 40 and you set the fill prefix
665 to @samp{;; }, then @kbd{M-q} in the following text
669 ;; example of a paragraph
670 ;; inside a Lisp-style comment.
677 ;; This is an example of a paragraph
678 ;; inside a Lisp-style comment.
681 Lines that do not start with the fill prefix are considered to start
682 paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
683 good results for paragraphs with hanging indentation (every line
684 indented except the first one). Lines which are blank or indented once
685 the prefix is removed also separate or start paragraphs; this is what
686 you want if you are writing multi-paragraph comments with a comment
687 delimiter on each line.
689 @findex fill-individual-paragraphs
690 You can use @kbd{M-x fill-individual-paragraphs} to set the fill
691 prefix for each paragraph automatically. This command divides the
692 region into paragraphs, treating every change in the amount of
693 indentation as the start of a new paragraph, and fills each of these
694 paragraphs. Thus, all the lines in one paragraph have the same
695 amount of indentation. That indentation serves as the fill prefix for
698 @findex fill-nonuniform-paragraphs
699 @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
700 the region into paragraphs in a different way. It considers only
701 paragraph-separating lines (as defined by @code{paragraph-separate}) as
702 starting a new paragraph. Since this means that the lines of one
703 paragraph may have different amounts of indentation, the fill prefix
704 used is the smallest amount of indentation of any of the lines of the
705 paragraph. This gives good results with styles that indent a paragraph's
706 first line more or less that the rest of the paragraph.
709 The fill prefix is stored in the variable @code{fill-prefix}. Its value
710 is a string, or @code{nil} when there is no fill prefix. This is a
711 per-buffer variable; altering the variable affects only the current buffer,
712 but there is a default value which you can change as well. @xref{Locals}.
714 The @code{indentation} text property provides another way to control
715 the amount of indentation paragraphs receive. @xref{Enriched
719 @subsection Adaptive Filling
721 @cindex adaptive filling
722 The fill commands can deduce the proper fill prefix for a paragraph
723 automatically in certain cases: either whitespace or certain punctuation
724 characters at the beginning of a line are propagated to all lines of the
727 If the paragraph has two or more lines, the fill prefix is taken from
728 the paragraph's second line, but only if it appears on the first line as
731 If a paragraph has just one line, fill commands @emph{may} take a
732 prefix from that line. The decision is complicated because there are
733 three reasonable things to do in such a case:
737 Use the first line's prefix on all the lines of the paragraph.
740 Indent subsequent lines with whitespace, so that they line up under the
741 text that follows the prefix on the first line, but don't actually copy
742 the prefix from the first line.
745 Don't do anything special with the second and following lines.
748 All three of these styles of formatting are commonly used. So the
749 fill commands try to determine what you would like, based on the prefix
750 that appears and on the major mode. Here is how.
752 @vindex adaptive-fill-first-line-regexp
753 If the prefix found on the first line matches
754 @code{adaptive-fill-first-line-regexp}, or if it appears to be a
755 comment-starting sequence (this depends on the major mode), then the
756 prefix found is used for filling the paragraph, provided it would not
757 act as a paragraph starter on subsequent lines.
759 Otherwise, the prefix found is converted to an equivalent number of
760 spaces, and those spaces are used as the fill prefix for the rest of the
761 lines, provided they would not act as a paragraph starter on subsequent
764 In Text mode, and other modes where only blank lines and page
765 delimiters separate paragraphs, the prefix chosen by adaptive filling
766 never acts as a paragraph starter, so it can always be used for filling.
768 @vindex adaptive-fill-mode
769 @vindex adaptive-fill-regexp
770 The variable @code{adaptive-fill-regexp} determines what kinds of line
771 beginnings can serve as a fill prefix: any characters at the start of
772 the line that match this regular expression are used. If you set the
773 variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
774 never chosen automatically.
776 @vindex adaptive-fill-function
777 You can specify more complex ways of choosing a fill prefix
778 automatically by setting the variable @code{adaptive-fill-function} to a
779 function. This function is called with point after the left margin of a
780 line, and it should return the appropriate fill prefix based on that
781 line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets
782 a chance to find a prefix.
785 @section Case Conversion Commands
786 @cindex case conversion
788 Emacs has commands for converting either a single word or any arbitrary
789 range of text to upper case or to lower case.
793 Convert following word to lower case (@code{downcase-word}).
795 Convert following word to upper case (@code{upcase-word}).
797 Capitalize the following word (@code{capitalize-word}).
799 Convert region to lower case (@code{downcase-region}).
801 Convert region to upper case (@code{upcase-region}).
807 @cindex words, case conversion
808 @cindex converting text to upper or lower case
809 @cindex capitalizing words
810 @findex downcase-word
812 @findex capitalize-word
813 @kbd{M-l} (@code{downcase-word}) converts the word after point to
814 lower case, moving past it. Thus, repeating @kbd{M-l} converts
815 successive words. @kbd{M-u} (@code{upcase-word}) converts to all
816 capitals instead, while @kbd{M-c} (@code{capitalize-word}) puts the
817 first letter of the word into upper case and the rest into lower case.
818 All these commands convert several words at once if given an argument.
819 They are especially convenient for converting a large amount of text
820 from all upper case to mixed case, because you can move through the
821 text using @kbd{M-l}, @kbd{M-u} or @kbd{M-c} on each word as
822 appropriate, occasionally using @kbd{M-f} instead to skip a word.
824 When given a negative argument, the word case conversion commands apply
825 to the appropriate number of words before point, but do not move point.
826 This is convenient when you have just typed a word in the wrong case: you
827 can give the case conversion command and continue typing.
829 If a word case conversion command is given in the middle of a word,
830 it applies only to the part of the word which follows point. (This is
831 comparable to what @kbd{M-d} (@code{kill-word}) does.) With a
832 negative argument, case conversion applies only to the part of the
837 @findex downcase-region
838 @findex upcase-region
839 The other case conversion commands are @kbd{C-x C-u}
840 (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
841 convert everything between point and mark to the specified case. Point and
844 The region case conversion commands @code{upcase-region} and
845 @code{downcase-region} are normally disabled. This means that they ask
846 for confirmation if you try to use them. When you confirm, you may
847 enable the command, which means it will not ask for confirmation again.
856 Text mode is a major mode for editing files of text in a human
857 language. Files which have names ending in the extension @file{.txt}
858 are usually opened in Text mode (@pxref{Choosing Modes}). To
859 explicitly switch to Text mode, type @kbd{M-x text-mode}.
861 In Text mode, only blank lines and page delimiters separate
862 paragraphs. As a result, paragraphs can be indented, and adaptive
863 filling determines what indentation to use when filling a paragraph.
864 @xref{Adaptive Fill}.
866 @kindex TAB @r{(Text mode)}
867 In Text mode, the @key{TAB} (@code{indent-for-tab-command}) command
868 usually inserts whitespace up to the next tab stop, instead of
869 indenting the current line. @xref{Indentation}, for details.
871 Text mode turns off the features concerned with comments except when
872 you explicitly invoke them. It changes the syntax table so that
873 apostrophes are considered part of words (e.g., @samp{don't} is
874 considered one word). However, if a word starts with an apostrophe,
875 it is treated as a prefix for the purposes of capitalization
876 (e.g., @kbd{M-c} converts @samp{'hello'} into @samp{'Hello'}, as
879 @cindex Paragraph-Indent Text mode
880 @cindex mode, Paragraph-Indent Text
881 @findex paragraph-indent-text-mode
882 @findex paragraph-indent-minor-mode
883 If you indent the first lines of paragraphs, then you should use
884 Paragraph-Indent Text mode (@kbd{M-x paragraph-indent-text-mode})
885 rather than Text mode. In that mode, you do not need to have blank
886 lines between paragraphs, because the first-line indentation is
887 sufficient to start a paragraph; however paragraphs in which every
888 line is indented are not supported. Use @kbd{M-x
889 paragraph-indent-minor-mode} to enable an equivalent minor mode for
890 situations where you shouldn't change the major mode---in mail
891 composition, for instance.
893 @kindex M-TAB @r{(Text mode)}
894 Text mode binds @kbd{M-@key{TAB}} to @code{ispell-complete-word}.
895 This command performs completion of the partial word in the buffer
896 before point, using the spelling dictionary as the space of possible
897 words. @xref{Spelling}. If your window manager defines
898 @kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC}
899 @key{TAB}} or @kbd{C-M-i} instead.
901 @vindex text-mode-hook
902 Entering Text mode runs the mode hook @code{text-mode-hook}
903 (@pxref{Major Modes}).
905 The following sections describe several major modes that are
906 @dfn{derived} from Text mode. These derivatives share most of the
907 features of Text mode described above. In particular, derivatives of
908 Text mode run @code{text-mode-hook} prior to running their own mode
912 @section Outline Mode
914 @cindex mode, Outline
915 @cindex invisible lines
918 @findex outline-minor-mode
919 @vindex outline-minor-mode-prefix
920 @vindex outline-mode-hook
921 Outline mode is a major mode derived from Text mode, which is
922 specialized for editing outlines. It provides commands to navigate
923 between entries in the outline structure, and commands to make parts
924 of a buffer temporarily invisible, so that the outline structure may
925 be more easily viewed. Type @kbd{M-x outline-mode} to switch to
926 Outline mode. Entering Outline mode runs the hook
927 @code{text-mode-hook} followed by the hook @code{outline-mode-hook}
930 When you use an Outline mode command to make a line invisible
931 (@pxref{Outline Visibility}), the line disappears from the screen. An
932 ellipsis (three periods in a row) is displayed at the end of the
933 previous visible line, to indicate the hidden text. Multiple
934 consecutive invisible lines produce just one ellipsis.
936 Editing commands that operate on lines, such as @kbd{C-n} and
937 @kbd{C-p}, treat the text of the invisible line as part of the
938 previous visible line. Killing the ellipsis at the end of a visible
939 line really kills all the following invisible text associated with the
942 Outline minor mode is a buffer-local minor mode which provides the
943 same commands as the major mode, Outline mode, but can be used in
944 conjunction with other major modes. You can type @kbd{M-x
945 outline-minor-mode} to toggle Outline minor mode in the current
946 buffer, or use a file-local variable setting to enable it in a
947 specific file (@pxref{File Variables}).
949 @kindex C-c @@ @r{(Outline minor mode)}
950 The major mode, Outline mode, provides special key bindings on the
951 @kbd{C-c} prefix. Outline minor mode provides similar bindings with
952 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
953 major mode's special commands. (The variable
954 @code{outline-minor-mode-prefix} controls the prefix used.)
957 * Outline Format:: What the text of an outline looks like.
958 * Outline Motion:: Special commands for moving through outlines.
959 * Outline Visibility:: Commands to control what is visible.
960 * Outline Views:: Outlines and multiple views.
961 * Foldout:: Folding means zooming in on outlines.
965 @subsection Format of Outlines
967 @cindex heading lines (Outline mode)
968 @cindex body lines (Outline mode)
969 Outline mode assumes that the lines in the buffer are of two types:
970 @dfn{heading lines} and @dfn{body lines}. A heading line represents a
971 topic in the outline. Heading lines start with one or more asterisk
972 (@samp{*}) characters; the number of asterisks determines the depth of
973 the heading in the outline structure. Thus, a heading line with one
974 @samp{*} is a major topic; all the heading lines with two @samp{*}s
975 between it and the next one-@samp{*} heading are its subtopics; and so
976 on. Any line that is not a heading line is a body line. Body lines
977 belong with the preceding heading line. Here is an example:
982 which says something about the topic of food.
985 This is the body of the second-level header.
995 Another first-level topic with its header line.
998 A heading line together with all following body lines is called
999 collectively an @dfn{entry}. A heading line together with all following
1000 deeper heading lines and their body lines is called a @dfn{subtree}.
1002 @vindex outline-regexp
1003 You can customize the criterion for distinguishing heading lines by
1004 setting the variable @code{outline-regexp}. (The recommended ways to
1005 do this are in a major mode function or with a file local variable.)
1006 Any line whose beginning has a match for this regexp is considered a
1007 heading line. Matches that start within a line (not at the left
1008 margin) do not count.
1010 The length of the matching text determines the level of the heading;
1011 longer matches make a more deeply nested level. Thus, for example, if
1012 a text formatter has commands @samp{@@chapter}, @samp{@@section} and
1013 @samp{@@subsection} to divide the document into chapters and sections,
1014 you could make those lines count as heading lines by setting
1015 @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note
1016 the trick: the two words @samp{chapter} and @samp{section} are equally
1017 long, but by defining the regexp to match only @samp{chap} we ensure
1018 that the length of the text matched on a chapter heading is shorter,
1019 so that Outline mode will know that sections are contained in
1020 chapters. This works as long as no other command starts with
1023 @vindex outline-level
1024 You can explicitly specify a rule for calculating the level of a
1025 heading line by setting the variable @code{outline-level}. The value
1026 of @code{outline-level} should be a function that takes no arguments
1027 and returns the level of the current heading. The recommended ways to
1028 set this variable are in a major mode command or with a file local
1031 @node Outline Motion
1032 @subsection Outline Motion Commands
1034 Outline mode provides special motion commands that move backward and
1035 forward to heading lines.
1039 Move point to the next visible heading line
1040 (@code{outline-next-visible-heading}).
1042 Move point to the previous visible heading line
1043 (@code{outline-previous-visible-heading}).
1045 Move point to the next visible heading line at the same level
1046 as the one point is on (@code{outline-forward-same-level}).
1048 Move point to the previous visible heading line at the same level
1049 (@code{outline-backward-same-level}).
1051 Move point up to a lower-level (more inclusive) visible heading line
1052 (@code{outline-up-heading}).
1055 @findex outline-next-visible-heading
1056 @findex outline-previous-visible-heading
1057 @kindex C-c C-n @r{(Outline mode)}
1058 @kindex C-c C-p @r{(Outline mode)}
1059 @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to
1060 the next heading line. @kbd{C-c C-p}
1061 (@code{outline-previous-visible-heading}) moves similarly backward.
1062 Both accept numeric arguments as repeat counts.
1064 @findex outline-up-heading
1065 @findex outline-forward-same-level
1066 @findex outline-backward-same-level
1067 @kindex C-c C-f @r{(Outline mode)}
1068 @kindex C-c C-b @r{(Outline mode)}
1069 @kindex C-c C-u @r{(Outline mode)}
1070 @kbd{C-c C-f} (@code{outline-forward-same-level}) and @kbd{C-c C-b}
1071 (@code{outline-backward-same-level}) move from one heading line to
1072 another visible heading at the same depth in the outline. @kbd{C-c
1073 C-u} (@code{outline-up-heading}) moves backward to another heading
1074 that is less deeply nested.
1076 @node Outline Visibility
1077 @subsection Outline Visibility Commands
1079 Outline mode provides several commands for temporarily hiding or
1080 revealing parts of the buffer, based on the outline structure. These
1081 commands are not undoable; their effects are simply not recorded by
1082 the undo mechanism, so you can undo right past them (@pxref{Undo}).
1084 Many of these commands act on the current heading line. If
1085 point is on a heading line, that is the current heading line; if point
1086 is on a body line, the current heading line is the nearest preceding
1091 Make the current heading line's body invisible
1092 (@code{outline-hide-entry}).
1094 Make the current heading line's body visible
1095 (@code{outline-show-entry}).
1097 Make everything under the current heading invisible, not including the
1098 heading itself (@code{outline-hide-subtree}).
1100 Make everything under the current heading visible, including body,
1101 subheadings, and their bodies (@code{outline-show-subtree}).
1103 Make the body of the current heading line, and of all its subheadings,
1104 invisible (@code{outline-hide-leaves}).
1106 Make all subheadings of the current heading line, at all levels,
1107 visible (@code{outline-show-branches}).
1109 Make immediate subheadings (one level down) of the current heading
1110 line visible (@code{outline-show-children}).
1112 Make all body lines in the buffer invisible
1113 (@code{outline-hide-body}).
1115 Make all lines in the buffer visible (@code{outline-show-all}).
1117 Hide everything except the top @var{n} levels of heading lines
1118 (@code{outline-hide-sublevels}).
1120 Hide everything except for the heading or body that point is in, plus
1121 the headings leading up from there to the top level of the outline
1122 (@code{outline-hide-other}).
1125 @findex outline-hide-entry
1126 @findex outline-show-entry
1127 @kindex C-c C-c @r{(Outline mode)}
1128 @kindex C-c C-e @r{(Outline mode)}
1129 The simplest of these commands are @kbd{C-c C-c}
1130 (@code{outline-hide-entry}), which hides the body lines directly
1131 following the current heading line, and @kbd{C-c C-e}
1132 (@code{outline-show-entry}), which reveals them. Subheadings and
1133 their bodies are not affected.
1135 @findex outline-hide-subtree
1136 @findex outline-show-subtree
1137 @kindex C-c C-s @r{(Outline mode)}
1138 @kindex C-c C-d @r{(Outline mode)}
1139 @cindex subtree (Outline mode)
1140 The commands @kbd{C-c C-d} (@code{outline-hide-subtree}) and
1141 @kbd{C-c C-s} (@code{outline-show-subtree}) are more powerful. They
1142 apply to the current heading line's @dfn{subtree}: its body, all of
1143 its subheadings, both direct and indirect, and all of their bodies.
1145 @findex outline-hide-leaves
1146 @findex outline-show-branches
1147 @findex outline-show-children
1148 @kindex C-c C-l @r{(Outline mode)}
1149 @kindex C-c C-k @r{(Outline mode)}
1150 @kindex C-c C-i @r{(Outline mode)}
1151 The command @kbd{C-c C-l} (@code{outline-hide-leaves}) hides the
1152 body of the current heading line as well as all the bodies in its
1153 subtree; the subheadings themselves are left visible. The command
1154 @kbd{C-c C-k} (@code{outline-show-branches}) reveals the subheadings,
1155 if they had previously been hidden (e.g., by @kbd{C-c C-d}). The
1156 command @kbd{C-c C-i} (@code{outline-show-children}) is a weaker
1157 version of this; it reveals just the direct subheadings, i.e., those
1160 @findex outline-hide-other
1161 @kindex C-c C-o @r{(Outline mode)}
1162 The command @kbd{C-c C-o} (@code{outline-hide-other}) hides
1163 everything except the entry that point is in, plus its parents (the
1164 headers leading up from there to top level in the outline) and the top
1165 level headings. It also reveals body lines preceding the first
1166 heading in the buffer.
1168 @findex outline-hide-body
1169 @findex outline-show-all
1170 @kindex C-c C-t @r{(Outline mode)}
1171 @kindex C-c C-a @r{(Outline mode)}
1172 @findex hide-sublevels
1173 @kindex C-c C-q @r{(Outline mode)}
1174 The remaining commands affect the whole buffer. @kbd{C-c C-t}
1175 (@code{outline-hide-body}) makes all body lines invisible, so that you
1176 see just the outline structure (as a special exception, it will not
1177 hide lines at the top of the file, preceding the first header line,
1178 even though these are technically body lines). @kbd{C-c C-a}
1179 (@code{outline-show-all}) makes all lines visible. @kbd{C-c C-q}
1180 (@code{outline-hide-sublevels}) hides all but the top level headings
1181 at and above the level of the current heading line (defaulting to 1 if
1182 point is not on a heading); with a numeric argument @var{n}, it hides
1183 everything except the top @var{n} levels of heading lines. Note that
1184 it completely reveals all the @var{n} top levels and the body lines
1185 before the first heading.
1187 @anchor{Outline Search}
1189 @vindex search-invisible
1190 When incremental search finds text that is hidden by Outline mode,
1191 it makes that part of the buffer visible. If you exit the search at
1192 that position, the text remains visible. To toggle whether or not
1193 an active incremental search can match hidden text, type @kbd{M-s i}.
1194 To change the default for future searches, customize the option
1195 @code{search-invisible}. (This option also affects how @code{query-replace}
1196 and related functions treat hidden text, @pxref{Query Replace}.)
1197 You can also automatically make text visible as you navigate in it by
1198 using Reveal mode (@kbd{M-x reveal-mode}), a buffer-local minor mode.
1201 @subsection Viewing One Outline in Multiple Views
1203 @cindex multiple views of outline
1204 @cindex views of an outline
1205 @cindex outline with multiple views
1206 @cindex indirect buffers and outlines
1207 You can display two views of a single outline at the same time, in
1208 different windows. To do this, you must create an indirect buffer using
1209 @kbd{M-x make-indirect-buffer}. The first argument of this command is
1210 the existing outline buffer name, and its second argument is the name to
1211 use for the new indirect buffer. @xref{Indirect Buffers}.
1213 Once the indirect buffer exists, you can display it in a window in the
1214 normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline
1215 mode commands to show and hide parts of the text operate on each buffer
1216 independently; as a result, each buffer can have its own view. If you
1217 want more than two views on the same outline, create additional indirect
1221 @subsection Folding Editing
1223 @cindex folding editing
1224 The Foldout package extends Outline mode and Outline minor mode with
1225 folding commands. The idea of folding is that you zoom in on a
1226 nested portion of the outline, while hiding its relatives at higher
1229 Consider an Outline mode buffer with all the text and subheadings under
1230 level-1 headings hidden. To look at what is hidden under one of these
1231 headings, you could use @kbd{C-c C-e} (@kbd{M-x outline-show-entry})
1232 to expose the body, or @kbd{C-c C-i} to expose the child (level-2)
1236 @findex foldout-zoom-subtree
1237 With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1238 This exposes the body and child subheadings, and narrows the buffer so
1239 that only the @w{level-1} heading, the body and the level-2 headings are
1240 visible. Now to look under one of the level-2 headings, position the
1241 cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body
1242 and its level-3 child subheadings and narrows the buffer again. Zooming
1243 in on successive subheadings can be done as much as you like. A string
1244 in the mode line shows how deep you've gone.
1246 When zooming in on a heading, to see only the child subheadings specify
1247 a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children
1248 can be specified too (compare @kbd{M-x outline-show-children}), e.g.,
1249 @w{@kbd{M-2 C-c C-z}} exposes two levels of child subheadings.
1250 Alternatively, the body can be specified with a negative argument:
1251 @w{@kbd{M-- C-c C-z}}. The whole subtree can be expanded, similarly to
1252 @kbd{C-c C-s} (@kbd{M-x outline-show-subtree}), by specifying a zero
1253 argument: @w{@kbd{M-0 C-c C-z}}.
1255 While you're zoomed in, you can still use Outline mode's exposure and
1256 hiding functions without disturbing Foldout. Also, since the buffer is
1257 narrowed, global editing actions will only affect text under the
1258 zoomed-in heading. This is useful for restricting changes to a
1259 particular chapter or section of your document.
1262 @findex foldout-exit-fold
1263 To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1264 This hides all the text and subheadings under the top-level heading and
1265 returns you to the previous view of the buffer. Specifying a numeric
1266 argument exits that many levels of folds. Specifying a zero argument
1269 To cancel the narrowing of a fold without hiding the text and
1270 subheadings, specify a negative argument. For example, @w{@kbd{M--2 C-c
1271 C-x}} exits two folds and leaves the text and subheadings exposed.
1273 Foldout mode also provides mouse commands for entering and exiting
1274 folds, and for showing and hiding text:
1277 @item @kbd{C-M-mouse-1} zooms in on the heading clicked on
1280 single click: expose body.
1282 double click: expose subheadings.
1284 triple click: expose body and subheadings.
1286 quad click: expose entire subtree.
1288 @item @kbd{C-M-mouse-2} exposes text under the heading clicked on
1291 single click: expose body.
1293 double click: expose subheadings.
1295 triple click: expose body and subheadings.
1297 quad click: expose entire subtree.
1299 @item @kbd{C-M-mouse-3} hides text under the heading clicked on or exits fold
1302 single click: hide subtree.
1304 double click: exit fold and hide text.
1306 triple click: exit fold without hiding text.
1308 quad click: exit all folds and hide text.
1312 @c FIXME not marked as a user variable
1313 @vindex foldout-mouse-modifiers
1314 You can specify different modifier keys (instead of
1315 @kbd{@key{Ctrl}-@key{META}-}) by setting @code{foldout-mouse-modifiers}; but if
1316 you have already loaded the @file{foldout.el} library, you must reload
1317 it in order for this to take effect.
1319 To use the Foldout package, you can type @kbd{M-x load-library
1320 @key{RET} foldout @key{RET}}; or you can arrange for to do that
1321 automatically by putting the following in your init file:
1324 (with-eval-after-load "outline"
1336 Org mode is a variant of Outline mode for using Emacs as an
1337 organizer and/or authoring system. Files with names ending in the
1338 extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}).
1339 To explicitly switch to Org mode, type @kbd{M-x org-mode}.
1341 In Org mode, as in Outline mode, each entry has a heading line that
1342 starts with one or more @samp{*} characters. @xref{Outline Format}.
1343 In addition, any line that begins with the @samp{#} character is
1344 treated as a comment.
1346 @kindex TAB @r{(Org Mode)}
1348 Org mode provides commands for easily viewing and manipulating the
1349 outline structure. The simplest of these commands is @key{TAB}
1350 (@code{org-cycle}). If invoked on a heading line, it cycles through
1351 the different visibility states of the subtree: (i) showing only that
1352 heading line, (ii) showing only the heading line and the heading lines
1353 of its direct children, if any, and (iii) showing the entire subtree.
1354 If invoked in a body line, the global binding for @key{TAB} is
1357 @kindex S-TAB @r{(Org Mode)}
1358 @findex org-shifttab
1359 Typing @kbd{S-@key{TAB}} (@code{org-shifttab}) anywhere in an Org mode
1360 buffer cycles the visibility of the entire outline structure, between
1361 (i) showing only top-level heading lines, (ii) showing all heading
1362 lines but no body lines, and (iii) showing everything.
1364 @kindex M-<up> @r{(Org Mode)}
1365 @kindex M-<down> @r{(Org Mode)}
1366 @kindex M-<left> @r{(Org Mode)}
1367 @kindex M-<right> @r{(Org Mode)}
1369 @findex org-metadown
1370 @findex org-metaleft
1371 @findex org-metaright
1372 You can move an entire entry up or down in the buffer, including its
1373 body lines and subtree (if any), by typing @kbd{M-<up>}
1374 (@code{org-metaup}) or @kbd{M-<down>} (@code{org-metadown}) on the
1375 heading line. Similarly, you can promote or demote a heading line
1376 with @kbd{M-<left>} (@code{org-metaleft}) and @kbd{M-<right>}
1377 (@code{org-metaright}). These commands execute their global bindings
1378 if invoked on a body line.
1380 The following subsections give basic instructions for using Org mode
1381 as an organizer and as an authoring system. For details, @pxref{Top,
1382 The Org Mode Manual, Introduction, org, The Org Manual}.
1385 * Org Organizer:: Managing TODO lists and agendas.
1386 * Org Authoring:: Exporting Org buffers to various formats.
1390 @subsection Org as an organizer
1394 @kindex C-c C-t @r{(Org Mode)}
1396 @vindex org-todo-keywords
1397 You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c
1398 C-t} (@code{org-todo}) anywhere in the entry. This adds the keyword
1399 @samp{TODO} to the heading line. Typing @kbd{C-c C-t} again switches
1400 the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword
1401 entirely, and so forth. You can customize the keywords used by
1402 @kbd{C-c C-t} via the variable @code{org-todo-keywords}.
1404 @kindex C-c C-s @r{(Org Mode)}
1405 @kindex C-c C-d @r{(Org Mode)}
1406 @findex org-schedule
1407 @findex org-deadline
1408 Apart from marking an entry as TODO, you can attach a date to it, by
1409 typing @kbd{C-c C-s} (@code{org-schedule}) in the entry. This prompts
1410 for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}),
1411 and then adds the tag @samp{SCHEDULED}, together with the selected
1412 date, beneath the heading line. The command @kbd{C-c C-d}
1413 (@code{org-deadline}) has the same effect, except that it uses the tag
1416 @kindex C-c [ @r{(Org Mode)}
1417 @findex org-agenda-file-to-front
1418 @vindex org-agenda-files
1419 Once you have some TODO items planned in an Org file, you can add
1420 that file to the list of @dfn{agenda files} by typing @kbd{C-c [}
1421 (@code{org-agenda-file-to-front}). Org mode is designed to let you
1422 easily maintain multiple agenda files, e.g., for organizing different
1423 aspects of your life. The list of agenda files is stored in the
1424 variable @code{org-agenda-files}.
1427 To view items coming from your agenda files, type @kbd{M-x
1428 org-agenda}. This command prompts for what you want to see: a list of
1429 things to do this week, a list of TODO items with specific keywords,
1432 @xref{Agenda Views,,,org, The Org Manual}, for details.
1436 @subsection Org as an authoring system
1437 @cindex Org exporting
1440 @kindex C-c C-e @r{(Org mode)}
1441 You may want to format your Org notes nicely and to prepare them for
1442 export and publication. To export the current buffer, type @kbd{C-c
1443 C-e} (@code{org-export}) anywhere in an Org buffer. This command
1444 prompts for an export format; currently supported formats include
1445 HTML, @LaTeX{}, OpenDocument (@file{.odt}), and PDF@. Some formats,
1446 such as PDF, require certain system tools to be installed.
1448 @vindex org-publish-project-alist
1449 To export several files at once to a specific directory, either
1450 locally or over the network, you must define a list of projects
1451 through the variable @code{org-publish-project-alist}. See its
1452 documentation for details.
1454 Org supports a simple markup scheme for applying text formatting to
1458 - This text is /emphasized/
1459 - This text is *in bold*
1460 - This text is _underlined_
1461 - This text uses =a teletype font=
1464 ``This is a quote.''
1472 For further details, @ref{Exporting,,,org, The Org Manual}, and
1473 @ref{Publishing,,,org, The Org Manual}.
1476 @section @TeX{} Mode
1478 @cindex @LaTeX{} mode
1479 @cindex Sli@TeX{} mode
1480 @cindex Doc@TeX{} mode
1481 @cindex mode, @TeX{}
1482 @cindex mode, @LaTeX{}
1483 @cindex mode, Sli@TeX{}
1484 @cindex mode, Doc@TeX{}
1486 @findex plain-tex-mode
1492 Emacs provides special major modes for editing files written in
1493 @TeX{} and its related formats. @TeX{} is a powerful text formatter
1494 written by Donald Knuth; like GNU Emacs, it is free software.
1495 @LaTeX{} is a simplified input format for @TeX{}, implemented using
1496 @TeX{} macros. Doc@TeX{} is a special file format in which the
1497 @LaTeX{} sources are written, combining sources with documentation.
1498 Sli@TeX{} is an obsolete special form of @LaTeX{}.@footnote{It has
1499 been replaced by the @samp{slides} document class, which comes with
1502 @vindex tex-default-mode
1503 @TeX{} mode has four variants: Plain @TeX{} mode, @LaTeX{} mode,
1504 Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ
1505 only slightly, and are designed for editing the four different
1506 formats. Emacs selects the appropriate mode by looking at the
1507 contents of the buffer. (This is done by the @code{tex-mode} command,
1508 which is normally called automatically when you visit a @TeX{}-like
1509 file. @xref{Choosing Modes}.) If the contents are insufficient to
1510 determine this, Emacs chooses the mode specified by the variable
1511 @code{tex-default-mode}; its default value is @code{latex-mode}. If
1512 Emacs does not guess right, you can select the correct variant of
1513 @TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x
1514 latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}.
1516 The following sections document the features of @TeX{} mode and its
1517 variants. There are several other @TeX{}-related Emacs packages,
1518 which are not documented in this manual:
1522 Bib@TeX{} mode is a major mode for Bib@TeX{} files, which are commonly
1523 used for keeping bibliographic references for @LaTeX{} documents. For
1524 more information, see the documentation string for the command
1528 The Ref@TeX{} package provides a minor mode which can be used with
1529 @LaTeX{} mode to manage bibliographic references.
1531 @xref{Top,The Ref@TeX{} Manual,,reftex}.
1534 For more information, see the Ref@TeX{} Info manual, which is
1535 distributed with Emacs.
1539 The AUC@TeX{} package provides more advanced features for editing
1540 @TeX{} and its related formats, including the ability to preview
1541 @TeX{} equations within Emacs buffers. Unlike Bib@TeX{} mode and the
1542 Ref@TeX{} package, AUC@TeX{} is not distributed with Emacs by default.
1543 It can be downloaded via the Package Menu (@pxref{Packages}); once
1546 @ref{Top,The AUC@TeX{} Manual,,auctex}.
1549 the AUC@TeX{} manual, which is included with the package.
1554 * TeX Editing:: Special commands for editing in TeX mode.
1555 * LaTeX Editing:: Additional commands for LaTeX input files.
1556 * TeX Print:: Commands for printing part of a file with TeX.
1557 * TeX Misc:: Customization of TeX mode, and related features.
1561 @subsection @TeX{} Editing Commands
1565 Insert, according to context, either @samp{``} or @samp{"} or
1566 @samp{''} (@code{tex-insert-quote}).
1568 Insert a paragraph break (two newlines) and check the previous
1569 paragraph for unbalanced braces or dollar signs
1570 (@code{tex-terminate-paragraph}).
1571 @item M-x tex-validate-region
1572 Check each paragraph in the region for unbalanced braces or dollar signs.
1574 Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1576 Move forward past the next unmatched close brace (@code{up-list}).
1579 @findex tex-insert-quote
1580 @kindex " @r{(@TeX{} mode)}
1581 In @TeX{}, the character @samp{"} is not normally used; instead,
1582 quotations begin with @samp{``} and end with @samp{''}. @TeX{} mode
1583 therefore binds the @kbd{"} key to the @code{tex-insert-quote}
1584 command. This inserts @samp{``} after whitespace or an open brace,
1585 @samp{"} after a backslash, and @samp{''} after any other character.
1587 As a special exception, if you type @kbd{"} when the text before
1588 point is either @samp{``} or @samp{''}, Emacs replaces that preceding
1589 text with a single @samp{"} character. You can therefore type
1590 @kbd{""} to insert @samp{"}, should you ever need to do so. (You can
1591 also use @kbd{C-q "} to insert this character.)
1593 In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1594 understand the way @TeX{} math mode delimiters match. When you insert a
1595 @samp{$} that is meant to exit math mode, the position of the matching
1596 @samp{$} that entered math mode is displayed for a second. This is the
1597 same feature that displays the open brace that matches a close brace that
1598 is inserted. However, there is no way to tell whether a @samp{$} enters
1599 math mode or leaves it; so when you insert a @samp{$} that enters math
1600 mode, the previous @samp{$} position is shown as if it were a match, even
1601 though they are actually unrelated.
1603 @findex tex-insert-braces
1604 @kindex C-c @{ @r{(@TeX{} mode)}
1606 @kindex C-c @} @r{(@TeX{} mode)}
1607 @TeX{} uses braces as delimiters that must match. Some users prefer
1608 to keep braces balanced at all times, rather than inserting them
1609 singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1610 braces. It leaves point between the two braces so you can insert the
1611 text that belongs inside. Afterward, use the command @kbd{C-c @}}
1612 (@code{up-list}) to move forward past the close brace.
1614 @findex tex-validate-region
1615 @findex tex-terminate-paragraph
1616 @kindex C-j @r{(@TeX{} mode)}
1617 There are two commands for checking the matching of braces.
1618 @kbd{C-j} (@code{tex-terminate-paragraph}) checks the paragraph before
1619 point, and inserts two newlines to start a new paragraph. It outputs
1620 a message in the echo area if any mismatch is found. @kbd{M-x
1621 tex-validate-region} checks a region, paragraph by paragraph. The
1622 errors are listed in an @file{*Occur*} buffer; you can use the usual
1623 Occur mode commands in that buffer, such as @kbd{C-c C-c}, to visit a
1624 particular mismatch (@pxref{Other Repeating Search}).
1626 Note that Emacs commands count square brackets and parentheses in
1627 @TeX{} mode, not just braces. This is not strictly correct for the
1628 purpose of checking @TeX{} syntax. However, parentheses and square
1629 brackets are likely to be used in text as matching delimiters, and it
1630 is useful for the various motion commands and automatic match display
1634 @subsection @LaTeX{} Editing Commands
1636 @LaTeX{} mode provides a few extra features not applicable to plain
1641 Insert @samp{\begin} and @samp{\end} for @LaTeX{} block and position
1642 point on a line between them (@code{tex-latex-block}).
1644 Close the innermost @LaTeX{} block not yet closed
1645 (@code{tex-close-latex-block}).
1648 @findex tex-latex-block
1649 @kindex C-c C-o @r{(@LaTeX{} mode)}
1650 In @LaTeX{} input, @samp{\begin} and @samp{\end} tags are used to
1651 group blocks of text. To insert a block, type @kbd{C-c C-o}
1652 (@code{tex-latex-block}). This prompts for a block type, and inserts
1653 the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a
1654 blank line between the two and moving point there.
1656 @vindex latex-block-names
1657 When entering the block type argument to @kbd{C-c C-o}, you can use
1658 the usual completion commands (@pxref{Completion}). The default
1659 completion list contains the standard @LaTeX{} block types. If you
1660 want additional block types for completion, customize the list
1661 variable @code{latex-block-names}.
1663 @findex tex-close-latex-block
1664 @kindex C-c C-e @r{(@LaTeX{} mode)}
1665 @findex latex-electric-env-pair-mode
1666 In @LaTeX{} input, @samp{\begin} and @samp{\end} tags must balance.
1667 You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an
1668 @samp{\end} tag which matches the last unmatched @samp{\begin}. It
1669 also indents the @samp{\end} to match the corresponding @samp{\begin},
1670 and inserts a newline after the @samp{\end} tag if point is at the
1671 beginning of a line. The minor mode @code{latex-electric-env-pair-mode}
1672 automatically inserts an @samp{\end} or @samp{\begin} tag for you
1673 when you type the corresponding one.
1676 @subsection @TeX{} Printing Commands
1678 You can invoke @TeX{} as an subprocess of Emacs, supplying either
1679 the entire contents of the buffer or just part of it (e.g., one
1680 chapter of a larger document).
1684 Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1686 Invoke @TeX{} on the current region, together with the buffer's header
1687 (@code{tex-region}).
1689 Invoke @TeX{} on the current file (@code{tex-file}).
1692 Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1693 C-f} command (@code{tex-view}).
1696 Print the output from the last @kbd{C-c C-b}, @kbd{C-c C-r}, or
1697 @kbd{C-c C-f} command (@code{tex-print}).
1700 Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1702 Recenter the window showing output from @TeX{} so that the last line
1703 can be seen (@code{tex-recenter-output-buffer}).
1705 Kill the @TeX{} subprocess (@code{tex-kill-job}).
1707 Invoke some other compilation command on the entire current buffer
1708 (@code{tex-compile}).
1712 @kindex C-c C-b @r{(@TeX{} mode)}
1714 @kindex C-c C-v @r{(@TeX{} mode)}
1716 @kindex C-c C-p @r{(@TeX{} mode)}
1717 To pass the current buffer through @TeX{}, type @kbd{C-c C-b}
1718 (@code{tex-buffer}). The formatted output goes in a temporary file,
1719 normally a @file{.dvi} file. Afterwards, you can type @kbd{C-c C-v}
1720 (@code{tex-view}) to launch an external program, such as
1721 @command{xdvi}, to view this output file. You can also type @kbd{C-c
1722 C-p} (@code{tex-print}) to print a hardcopy of the output file.
1724 @cindex @env{TEXINPUTS} environment variable
1725 @vindex tex-directory
1726 By default, @kbd{C-c C-b} runs @TeX{} in the current directory. The
1727 output of @TeX{} also goes in this directory. To run @TeX{} in a
1728 different directory, change the variable @code{tex-directory} to the
1729 desired directory name. If your environment variable @env{TEXINPUTS}
1730 contains relative directory names, or if your files contains
1731 @samp{\input} commands with relative file names, then
1732 @code{tex-directory} @emph{must} be @code{"."} or you will get the
1733 wrong results. Otherwise, it is safe to specify some other directory,
1734 such as @code{"/tmp"}.
1736 @vindex tex-run-command
1737 @vindex latex-run-command
1738 @vindex tex-dvi-view-command
1739 @vindex tex-dvi-print-command
1740 @vindex tex-print-file-extension
1741 The buffer's @TeX{} variant determines what shell command @kbd{C-c
1742 C-b} actually runs. In Plain @TeX{} mode, it is specified by the
1743 variable @code{tex-run-command}, which defaults to @code{"tex"}. In
1744 @LaTeX{} mode, it is specified by @code{latex-run-command}, which
1745 defaults to @code{"latex"}. The shell command that @kbd{C-c C-v} runs
1746 to view the @file{.dvi} output is determined by the variable
1747 @code{tex-dvi-view-command}, regardless of the @TeX{} variant. The
1748 shell command that @kbd{C-c C-p} runs to print the output is
1749 determined by the variable @code{tex-dvi-print-command}. The variable
1750 @code{tex-print-file-extension} can be set to the required file
1751 extension for viewing and printing @TeX{}-compiled files. For
1752 example, you can set it to @file{.pdf}, and update
1753 @code{tex-dvi-view-command} and @code{tex-dvi-print-command}
1756 Normally, Emacs automatically appends the output file name to the
1757 shell command strings described in the preceding paragraph. For
1758 example, if @code{tex-dvi-view-command} is @code{"xdvi"}, @kbd{C-c
1759 C-v} runs @command{xdvi @var{output-file-name}}. In some cases,
1760 however, the file name needs to be embedded in the command, e.g., if
1761 you need to provide the file name as an argument to one command whose
1762 output is piped to another. You can specify where to put the file
1763 name with @samp{*} in the command string. For example,
1766 (setq tex-dvi-print-command "dvips -f * | lpr")
1769 @findex tex-kill-job
1770 @kindex C-c C-k @r{(@TeX{} mode)}
1771 @findex tex-recenter-output-buffer
1772 @kindex C-c C-l @r{(@TeX{} mode)}
1773 The terminal output from @TeX{}, including any error messages,
1774 appears in a buffer called @file{*tex-shell*}. If @TeX{} gets an
1775 error, you can switch to this buffer and feed it input (this works as
1776 in Shell mode; @pxref{Interactive Shell}). Without switching to this
1777 buffer you can scroll it so that its last line is visible by typing
1780 Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1781 you see that its output is no longer useful. Using @kbd{C-c C-b} or
1782 @kbd{C-c C-r} also kills any @TeX{} process still running.
1785 @kindex C-c C-r @r{(@TeX{} mode)}
1786 You can also pass an arbitrary region through @TeX{} by typing
1787 @kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because
1788 most files of @TeX{} input contain commands at the beginning to set
1789 parameters and define macros, without which no later part of the file
1790 will format correctly. To solve this problem, @kbd{C-c C-r} allows
1791 you to designate a part of the file as containing essential commands;
1792 it is included before the specified region as part of the input to
1793 @TeX{}. The designated part of the file is called the @dfn{header}.
1795 @cindex header (@TeX{} mode)
1796 To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1797 special strings in the file. Insert @samp{%**start of header} before the
1798 header, and @samp{%**end of header} after it. Each string must appear
1799 entirely on one line, but there may be other text on the line before or
1800 after. The lines containing the two strings are included in the header.
1801 If @samp{%**start of header} does not appear within the first 100 lines of
1802 the buffer, @kbd{C-c C-r} assumes that there is no header.
1804 In @LaTeX{} mode, the header begins with @samp{\documentclass} or
1805 @samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
1806 are commands that @LaTeX{} requires you to use in any case, so nothing
1807 special needs to be done to identify the header.
1810 @kindex C-c C-f @r{(@TeX{} mode)}
1811 The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1812 work in a temporary directory, and do not have available any of the auxiliary
1813 files needed by @TeX{} for cross-references; these commands are generally
1814 not suitable for running the final copy in which all of the cross-references
1817 When you want the auxiliary files for cross references, use @kbd{C-c
1818 C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1819 in that file's directory. Before running @TeX{}, it offers to save any
1820 modified buffers. Generally, you need to use (@code{tex-file}) twice to
1821 get the cross-references right.
1823 @vindex tex-start-options
1824 The value of the variable @code{tex-start-options} specifies
1825 options for the @TeX{} run.
1827 @vindex tex-start-commands
1828 The value of the variable @code{tex-start-commands} specifies @TeX{}
1829 commands for starting @TeX{}. The default value causes @TeX{} to run
1830 in nonstop mode. To run @TeX{} interactively, set the variable to
1833 @vindex tex-main-file
1834 Large @TeX{} documents are often split into several files---one main
1835 file, plus subfiles. Running @TeX{} on a subfile typically does not
1836 work; you have to run it on the main file. In order to make
1837 @code{tex-file} useful when you are editing a subfile, you can set the
1838 variable @code{tex-main-file} to the name of the main file. Then
1839 @code{tex-file} runs @TeX{} on that file.
1841 The most convenient way to use @code{tex-main-file} is to specify it
1842 in a local variable list in each of the subfiles. @xref{File
1845 @findex tex-bibtex-file
1846 @kindex C-c TAB @r{(@TeX{} mode)}
1847 @vindex tex-bibtex-command
1848 For @LaTeX{} files, you can use Bib@TeX{} to process the auxiliary
1849 file for the current buffer's file. Bib@TeX{} looks up bibliographic
1850 citations in a data base and prepares the cited references for the
1851 bibliography section. The command @kbd{C-c @key{TAB}}
1852 (@code{tex-bibtex-file}) runs the shell command
1853 (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1854 current buffer's file. Generally, you need to do @kbd{C-c C-f}
1855 (@code{tex-file}) once to generate the @samp{.aux} file, then do
1856 @kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1857 (@code{tex-file}) twice more to get the cross-references correct.
1860 @kindex C-c C-c @r{(@TeX{} mode)}
1861 To invoke some other compilation program on the current @TeX{}
1862 buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows
1863 how to pass arguments to many common programs, including
1864 @file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can
1865 select your desired compilation program using the standard completion
1866 keys (@pxref{Completion}).
1869 @subsection @TeX{} Mode Miscellany
1871 @vindex tex-shell-hook
1872 @vindex tex-mode-hook
1873 @vindex latex-mode-hook
1874 @vindex slitex-mode-hook
1875 @vindex plain-tex-mode-hook
1876 Entering any variant of @TeX{} mode runs the hooks
1877 @code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either
1878 @code{plain-tex-mode-hook}, @code{latex-mode-hook}, or
1879 @code{slitex-mode-hook}, whichever is appropriate. Starting the
1880 @TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}.
1884 @findex iso-iso2gtex
1885 @findex iso-gtex2iso
1886 @cindex Latin-1 @TeX{} encoding
1887 @cindex @TeX{} encoding
1888 The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1889 iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert
1890 between Latin-1 encoded files and @TeX{}-encoded equivalents.
1893 @section SGML and HTML Modes
1901 The major modes for SGML and HTML provide indentation support and
1902 commands for operating on tags. HTML mode is a slightly customized
1903 variant of SGML mode.
1907 @kindex C-c C-n @r{(SGML mode)}
1908 @findex sgml-name-char
1909 Interactively specify a special character and insert the SGML
1910 @samp{&}-command for that character (@code{sgml-name-char}).
1913 @kindex C-c C-t @r{(SGML mode)}
1915 Interactively specify a tag and its attributes (@code{sgml-tag}).
1916 This command asks you for a tag name and for the attribute values,
1917 then inserts both the opening tag and the closing tag, leaving point
1920 With a prefix argument @var{n}, the command puts the tag around the
1921 @var{n} words already present in the buffer after point. Whenever a
1922 region is active, it puts the tag around the region (when Transient
1923 Mark mode is off, it does this when a numeric argument of @minus{}1 is
1927 @kindex C-c C-a @r{(SGML mode)}
1928 @findex sgml-attributes
1929 Interactively insert attribute values for the current tag
1930 (@code{sgml-attributes}).
1933 @kindex C-c C-f @r{(SGML mode)}
1934 @findex sgml-skip-tag-forward
1935 Skip across a balanced tag group (which extends from an opening tag
1936 through its corresponding closing tag) (@code{sgml-skip-tag-forward}).
1937 A numeric argument acts as a repeat count.
1940 @kindex C-c C-b @r{(SGML mode)}
1941 @findex sgml-skip-tag-backward
1942 Skip backward across a balanced tag group (which extends from an
1943 opening tag through its corresponding closing tag)
1944 (@code{sgml-skip-tag-backward}). A numeric argument acts as a repeat
1948 @kindex C-c C-d @r{(SGML mode)}
1949 @findex sgml-delete-tag
1950 Delete the tag at or after point, and delete the matching tag too
1951 (@code{sgml-delete-tag}). If the tag at or after point is an opening
1952 tag, delete the closing tag too; if it is a closing tag, delete the
1955 @item C-c ? @var{tag} @key{RET}
1956 @kindex C-c ? @r{(SGML mode)}
1957 @findex sgml-tag-help
1958 Display a description of the meaning of tag @var{tag}
1959 (@code{sgml-tag-help}). If the argument @var{tag} is empty, describe
1963 @kindex C-c / @r{(SGML mode)}
1964 @findex sgml-close-tag
1965 Insert a close tag for the innermost unterminated tag
1966 (@code{sgml-close-tag}). If called within a tag or a comment,
1967 close it instead of inserting a close tag.
1970 @kindex C-c 8 @r{(SGML mode)}
1971 @findex sgml-name-8bit-mode
1972 Toggle a minor mode in which Latin-1 characters insert the
1973 corresponding SGML commands that stand for them, instead of the
1974 characters themselves (@code{sgml-name-8bit-mode}).
1977 @kindex C-c C-v @r{(SGML mode)}
1978 @findex sgml-validate
1979 Run a shell command (which you must specify) to validate the current
1980 buffer as SGML (@code{sgml-validate}).
1983 @kindex C-c TAB @r{(SGML mode)}
1984 @findex sgml-tags-invisible
1985 Toggle the visibility of existing tags in the buffer. This can be
1986 used as a cheap preview (@code{sgml-tags-invisible}).
1993 The major mode for editing XML documents is called nXML mode. This
1994 is a powerful major mode that can recognize many existing XML schema
1995 and use them to provide completion of XML elements via
1996 @kbd{M-@key{TAB}}, as well as on-the-fly XML
1997 validation with error highlighting. To enable nXML mode in an
1998 existing buffer, type @kbd{M-x nxml-mode}, or, equivalently, @kbd{M-x
1999 xml-mode}. Emacs uses nXML mode for files which have the extension
2000 @file{.xml}. For XHTML files, which have the extension @file{.xhtml},
2001 Emacs uses HTML mode by default; you can make it use nXML mode by
2002 customizing the variable @code{auto-mode-alist} (@pxref{Choosing
2005 nXML mode is described in its own manual: @xref{Top, nXML
2006 Mode,,nxml-mode, nXML Mode}.
2009 nXML mode is described in an Info manual, which is distributed with
2013 @vindex sgml-xml-mode
2014 You may choose to use the less powerful SGML mode for editing XML,
2015 since XML is a strict subset of SGML@. To enable SGML mode in an
2016 existing buffer, type @kbd{M-x sgml-mode}. On enabling SGML mode,
2017 Emacs examines the buffer to determine whether it is XML; if so, it
2018 sets the variable @code{sgml-xml-mode} to a non-@code{nil} value.
2019 This causes SGML mode's tag insertion commands, described above, to
2020 always insert explicit closing tags as well.
2027 @vindex nroff-mode-hook
2028 Nroff mode, a major mode derived from Text mode, is
2029 specialized for editing nroff files (e.g., Unix man pages). Type
2030 @kbd{M-x nroff-mode} to enter this mode. Entering Nroff mode runs the
2031 hook @code{text-mode-hook}, then @code{nroff-mode-hook}
2034 In Nroff mode, nroff command lines are treated as paragraph
2035 separators, pages are separated by @samp{.bp} commands, and comments
2036 start with backslash-doublequote. It also defines these commands:
2038 @findex forward-text-line
2039 @findex backward-text-line
2040 @findex count-text-lines
2041 @kindex M-n @r{(Nroff mode)}
2042 @kindex M-p @r{(Nroff mode)}
2043 @kindex M-? @r{(Nroff mode)}
2046 Move to the beginning of the next line that isn't an nroff command
2047 (@code{forward-text-line}). An argument is a repeat count.
2049 Like @kbd{M-n} but move up (@code{backward-text-line}).
2051 Displays in the echo area the number of text lines (lines that are not
2052 nroff commands) in the region (@code{count-text-lines}).
2055 @findex electric-nroff-mode
2056 Electric Nroff mode is a buffer-local minor mode that can be used
2057 with Nroff mode. To toggle this minor mode, type @kbd{M-x
2058 electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
2059 time you type @key{RET} to end a line containing an nroff command that
2060 opens a kind of grouping, the nroff command to close that grouping is
2061 automatically inserted on the following line.
2063 If you use Outline minor mode with Nroff mode (@pxref{Outline
2064 Mode}), heading lines are lines of the form @samp{.H} followed by a
2065 number (the header level).
2068 @section Enriched Text
2069 @cindex Enriched mode
2070 @cindex mode, Enriched
2071 @cindex enriched text
2073 @cindex word processing
2074 @cindex text/enriched MIME format
2076 Enriched mode is a minor mode for editing formatted text files in a
2077 WYSIWYG (What You See Is What You Get) fashion. When Enriched
2078 mode is enabled, you can apply various formatting properties to the
2079 text in the buffer, such as fonts and colors; upon saving the buffer,
2080 those properties are saved together with the text, using the MIME
2081 @samp{text/enriched} file format.
2083 Enriched mode is typically used with Text mode (@pxref{Text Mode}).
2084 It is @emph{not} compatible with Font Lock mode, which is used by many
2085 major modes, including most programming language modes, for syntax
2086 highlighting (@pxref{Font Lock}). Unlike Enriched mode, Font Lock
2087 mode assigns text properties automatically, based on the current
2088 buffer contents; those properties are not saved to disk.
2090 The file @file{enriched.txt} in Emacs's @code{data-directory}
2091 serves as an example of the features of Enriched mode.
2094 * Enriched Mode:: Entering and exiting Enriched mode.
2095 * Hard and Soft Newlines:: There are two different kinds of newlines.
2096 * Editing Format Info:: How to edit text properties.
2097 * Enriched Faces:: Bold, italic, underline, etc.
2098 * Enriched Indentation:: Changing the left and right margins.
2099 * Enriched Justification:: Centering, setting text flush with the
2100 left or right margin, etc.
2101 * Enriched Properties:: The ``special text properties'' submenu.
2105 @subsection Enriched Mode
2107 Enriched mode is a buffer-local minor mode (@pxref{Minor Modes}).
2108 When you visit a file that has been saved in the @samp{text/enriched}
2109 format, Emacs automatically enables Enriched mode, and applies the
2110 formatting information in the file to the buffer text. When you save
2111 a buffer with Enriched mode enabled, it is saved using the
2112 @samp{text/enriched} format, including the formatting information.
2114 @findex enriched-mode
2115 To create a new file of formatted text, visit the nonexistent file
2116 and type @kbd{M-x enriched-mode}. This command actually toggles
2117 Enriched mode. With a prefix argument, it enables Enriched mode if
2118 the argument is positive, and disables Enriched mode otherwise. If
2119 you disable Enriched mode, Emacs no longer saves the buffer using the
2120 @samp{text/enriched} format; any formatting properties that have been
2121 added to the buffer remain in the buffer, but they are not saved to
2124 @vindex enriched-translations
2125 Enriched mode does not save all Emacs text properties, only those
2126 specified in the variable @code{enriched-translations}. These include
2127 properties for fonts, colors, indentation, and justification.
2129 @findex format-decode-buffer
2130 If you visit a file and Emacs fails to recognize that it is in the
2131 @samp{text/enriched} format, type @kbd{M-x format-decode-buffer}.
2132 This command prompts for a file format, and re-reads the file in that
2133 format. Specifying the @samp{text/enriched} format automatically
2134 enables Enriched mode.
2136 To view a @samp{text/enriched} file in raw form (as plain text with
2137 markup tags rather than formatted text), use @kbd{M-x
2138 find-file-literally} (@pxref{Visiting}).
2140 @xref{Format Conversion,, Format Conversion, elisp, the Emacs Lisp
2141 Reference Manual}, for details of how Emacs recognizes and converts
2142 file formats like @samp{text/enriched}. @xref{Text Properties,,,
2143 elisp, the Emacs Lisp Reference Manual}, for more information about
2146 @node Hard and Soft Newlines
2147 @subsection Hard and Soft Newlines
2148 @cindex hard newline
2149 @cindex soft newline
2150 @cindex newlines, hard and soft
2152 @cindex use-hard-newlines
2153 In Enriched mode, Emacs distinguishes between two different kinds of
2154 newlines, @dfn{hard} newlines and @dfn{soft} newlines. You can also
2155 enable or disable this feature in other buffers, by typing @kbd{M-x
2158 Hard newlines are used to separate paragraphs, or anywhere there
2159 needs to be a line break regardless of how the text is filled; soft
2160 newlines are used for filling. The @key{RET} (@code{newline}) and
2161 @kbd{C-o} (@code{open-line}) commands insert hard newlines. The fill
2162 commands, including Auto Fill (@pxref{Auto Fill}), insert only soft
2163 newlines and delete only soft newlines, leaving hard newlines alone.
2165 @c FIXME: I don't see 'unfilled' in that node. --xfq
2166 Thus, when editing with Enriched mode, you should not use @key{RET}
2167 or @kbd{C-o} to break lines in the middle of filled paragraphs. Use
2168 Auto Fill mode or explicit fill commands (@pxref{Fill Commands})
2169 instead. Use @key{RET} or @kbd{C-o} where line breaks should always
2170 remain, such as in tables and lists. For such lines, you may also
2171 want to set the justification style to @code{unfilled}
2172 (@pxref{Enriched Justification}).
2174 @node Editing Format Info
2175 @subsection Editing Format Information
2177 The easiest way to alter properties is with the @samp{Text
2178 Properties} menu. You can get to this menu from the @samp{Edit} menu
2179 in the menu bar (@pxref{Menu Bar}), or with @kbd{C-mouse-2}
2180 (@pxref{Menu Mouse Clicks}). Some of the commands in the @samp{Text
2181 Properties} menu are listed below (you can also invoke them with
2185 @findex facemenu-remove-face-props
2186 @item Remove Face Properties
2187 Remove face properties from the region
2188 (@code{facemenu-remove-face-props}).
2190 @findex facemenu-remove-all
2191 @item Remove Text Properties
2192 Remove all text properties from the region, including face properties
2193 (@code{facemenu-remove-all}).
2195 @findex describe-text-properties
2196 @cindex text properties of characters
2197 @cindex overlays at character position
2198 @cindex widgets at buffer position
2199 @cindex buttons at buffer position
2200 @item Describe Properties
2201 List all text properties and other information about the character
2202 following point (@code{describe-text-properties}).
2205 Display a list of defined faces (@code{list-faces-display}).
2208 @item Display Colors
2209 Display a list of defined colors (@code{list-colors-display}).
2214 The other menu entries are described in the following sections.
2216 @node Enriched Faces
2217 @subsection Faces in Enriched Text
2219 The following commands can be used to add or remove faces
2220 (@pxref{Faces}). Each applies to the text in the region if the mark
2221 is active, and to the next self-inserting character if the mark is
2222 inactive. With a prefix argument, each command applies to the next
2223 self-inserting character even if the region is active.
2226 @kindex M-o d @r{(Enriched mode)}
2227 @findex facemenu-set-default
2229 Remove all @code{face} properties (@code{facemenu-set-default}).
2231 @kindex M-o b @r{(Enriched mode)}
2232 @findex facemenu-set-bold
2234 Apply the @code{bold} face (@code{facemenu-set-bold}).
2236 @kindex M-o i @r{(Enriched mode)}
2237 @findex facemenu-set-italic
2239 Apply the @code{italic} face (@code{facemenu-set-italic}).
2241 @kindex M-o l @r{(Enriched mode)}
2242 @findex facemenu-set-bold-italic
2244 Apply the @code{bold-italic} face (@code{facemenu-set-bold-italic}).
2246 @kindex M-o u @r{(Enriched mode)}
2247 @findex facemenu-set-underline
2249 Apply the @code{underline} face (@code{facemenu-set-underline}).
2251 @kindex M-o o @r{(Enriched mode)}
2252 @findex facemenu-set-face
2253 @item M-o o @var{face} @key{RET}
2254 Apply the face @var{face} (@code{facemenu-set-face}).
2256 @findex facemenu-set-foreground
2257 @item M-x facemenu-set-foreground
2258 Prompt for a color (@pxref{Colors}), and apply it as a foreground
2261 @findex facemenu-set-background
2262 @item M-x facemenu-set-background
2263 Prompt for a color, and apply it as a background color.
2267 These command are also available via the Text Properties menu.
2269 A self-inserting character normally inherits the face properties
2270 (and most other text properties) from the preceding character in the
2271 buffer. If you use one of the above commands to specify the face for
2272 the next self-inserting character, that character will not inherit the
2273 faces properties from the preceding character, but it will still
2274 inherit other text properties.
2276 Enriched mode defines two additional faces: @code{excerpt} and
2277 @code{fixed}. These correspond to codes used in the text/enriched
2278 file format. The @code{excerpt} face is intended for quotations; by
2279 default, it appears the same as @code{italic}. The @code{fixed} face
2280 specifies fixed-width text; by default, it appears the same as
2283 @node Enriched Indentation
2284 @subsection Indentation in Enriched Text
2286 In Enriched mode, you can specify different amounts of indentation
2287 for the right or left margin of a paragraph or a part of a paragraph.
2288 These margins also affect fill commands such as @kbd{M-q}
2291 The Indentation submenu of Text Properties offers commands
2292 for specifying indentation:
2295 @kindex C-x TAB @r{(Enriched mode)}
2296 @findex increase-left-margin
2298 Indent the region by 4 columns (@code{increase-left-margin}). In
2299 Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
2300 you supply a numeric argument, that says how many columns to add to the
2301 margin (a negative argument reduces the number of columns).
2304 Remove 4 columns of indentation from the region.
2306 @item Indent Right More
2307 Make the text narrower by indenting 4 columns at the right margin.
2309 @item Indent Right Less
2310 Remove 4 columns of indentation from the right margin.
2313 @vindex standard-indent
2314 The variable @code{standard-indent} specifies how many columns these
2315 commands should add to or subtract from the indentation. The default
2316 value is 4. The default right margin for Enriched mode is controlled
2317 by the variable @code{fill-column}, as usual.
2319 @kindex C-c [ @r{(Enriched mode)}
2320 @kindex C-c ] @r{(Enriched mode)}
2321 @findex set-left-margin
2322 @findex set-right-margin
2323 You can also type @kbd{C-c [} (@code{set-left-margin}) and @kbd{C-c
2324 ]} (@code{set-right-margin}) to set the left and right margins. You
2325 can specify the margin width with a numeric argument; otherwise these
2326 commands prompt for a value via the minibuffer.
2328 The fill prefix, if any, works in addition to the specified paragraph
2329 indentation: @kbd{C-x .} does not include the specified indentation's
2330 whitespace in the new value for the fill prefix, and the fill commands
2331 look for the fill prefix after the indentation on each line. @xref{Fill
2334 @node Enriched Justification
2335 @subsection Justification in Enriched Text
2336 @cindex justification style
2338 In Enriched mode, you can use the following commands to specify
2339 various @dfn{justification styles} for filling. These commands apply
2340 to the paragraph containing point, or, if the region is active, to all
2341 paragraphs overlapping the region.
2344 @kindex M-j l @r{(Enriched mode)}
2345 @findex set-justification-left
2347 Align lines to the left margin (@code{set-justification-left}).
2349 @kindex M-j r @r{(Enriched mode)}
2350 @findex set-justification-right
2352 Align lines to the right margin (@code{set-justification-right}).
2354 @kindex M-j b @r{(Enriched mode)}
2355 @findex set-justification-full
2357 Align lines to both margins, inserting spaces in the middle of the
2358 line to achieve this (@code{set-justification-full}).
2360 @kindex M-j c @r{(Enriched mode)}
2361 @kindex M-S @r{(Enriched mode)}
2362 @findex set-justification-center
2365 Center lines between the margins (@code{set-justification-center}).
2367 @kindex M-j u @r{(Enriched mode)}
2368 @findex set-justification-none
2370 Turn off filling entirely (@code{set-justification-none}). The fill
2371 commands do nothing on text with this setting. You can, however,
2372 still indent the left margin.
2375 @vindex default-justification
2376 You can also specify justification styles using the Justification
2377 submenu in the Text Properties menu. The default justification style
2378 is specified by the per-buffer variable @code{default-justification}.
2379 Its value should be one of the symbols @code{left}, @code{right},
2380 @code{full}, @code{center}, or @code{none}; their meanings correspond
2381 to the commands above.
2383 @node Enriched Properties
2384 @subsection Setting Other Text Properties
2386 The Special Properties submenu of Text Properties has entries for
2387 adding or removing three other text properties: @code{read-only},
2388 (which disallows alteration of the text), @code{invisible} (which
2389 hides text), and @code{intangible} (which disallows moving point
2390 within the text). The @samp{Remove Special} menu item removes all of
2391 these special properties from the text in the region.
2393 The @code{invisible} and @code{intangible} properties are not saved.
2395 @node Text Based Tables
2396 @section Editing Text-based Tables
2398 @cindex text-based tables
2400 The @code{table} package provides commands to easily edit text-based
2401 tables. Here is an example of what such a table looks like:
2405 +-----------------+--------------------------------+-----------------+
2406 | Command | Description | Key Binding |
2407 +-----------------+--------------------------------+-----------------+
2408 | forward-char |Move point right N characters | C-f |
2409 | |(left if N is negative). | |
2411 +-----------------+--------------------------------+-----------------+
2412 | backward-char |Move point left N characters | C-b |
2413 | |(right if N is negative). | |
2415 +-----------------+--------------------------------+-----------------+
2419 When Emacs recognizes such a stretch of text as a table
2420 (@pxref{Table Recognition}), editing the contents of each table cell
2421 will automatically resize the table, whenever the contents become too
2422 large to fit in the cell. You can use the commands defined in the
2423 following sections for navigating and editing the table layout.
2425 @findex table-fixed-width-mode
2426 Type @kbd{M-x table-fixed-width-mode} to toggle the automatic table
2430 * Table Definition:: What is a text based table.
2431 * Table Creation:: How to create a table.
2432 * Table Recognition:: How to activate and deactivate tables.
2433 * Cell Commands:: Cell-oriented commands in a table.
2434 * Cell Justification:: Justifying cell contents.
2435 * Table Rows and Columns:: Inserting and deleting rows and columns.
2436 * Table Conversion:: Converting between plain text and tables.
2437 * Table Misc:: Table miscellany.
2440 @node Table Definition
2441 @subsection What is a Text-based Table?
2442 @cindex cells, for text-based tables
2444 A @dfn{table} consists of a rectangular text area which is divided
2445 into @dfn{cells}. Each cell must be at least one character wide and
2446 one character high, not counting its border lines. A cell can be
2447 subdivided into more cells, but they cannot overlap.
2449 Cell border lines are drawn with three special characters, specified
2450 by the following variables:
2453 @vindex table-cell-vertical-char
2454 @item table-cell-vertical-char
2455 The character used for vertical lines. The default is @samp{|}.
2457 @vindex table-cell-horizontal-chars
2458 @item table-cell-horizontal-chars
2459 The characters used for horizontal lines. The default is @samp{"-="}.
2461 @vindex table-cell-intersection-char
2462 @item table-cell-intersection-char
2463 The character used for the intersection of horizontal and vertical
2464 lines. The default is @samp{+}.
2468 The following are examples of @emph{invalid} tables:
2471 +-----+ +--+ +-++--+
2474 +--+ | +--+--+ +-++--+
2477 +--+--+ +--+--+ +-++--+
2486 Overlapped cells or non-rectangular cells are not allowed.
2488 The border must be rectangular.
2490 Cells must have a minimum width/height of one character.
2493 @node Table Creation
2494 @subsection Creating a Table
2495 @cindex create a text-based table
2496 @cindex table creation
2498 @findex table-insert
2499 To create a text-based table from scratch, type @kbd{M-x
2500 table-insert}. This command prompts for the number of table columns,
2501 the number of table rows, cell width and cell height. The cell width
2502 and cell height do not include the cell borders; each can be specified
2503 as a single integer (which means each cell is given the same
2504 width/height), or as a sequence of integers separated by spaces or
2505 commas (which specify the width/height of the individual table
2506 columns/rows, counting from left to right for table columns and from
2507 top to bottom for table rows). The specified table is then inserted
2510 The table inserted by @kbd{M-x table-insert} contains special text
2511 properties, which tell Emacs to treat it specially as a text-based
2512 table. If you save the buffer to a file and visit it again later,
2513 those properties are lost, and the table appears to Emacs as an
2514 ordinary piece of text. See the next section, for how to convert it
2517 @node Table Recognition
2518 @subsection Table Recognition
2519 @cindex table recognition
2521 @findex table-recognize
2522 @findex table-unrecognize
2523 Existing text-based tables in a buffer, which lack the special text
2524 properties applied by @kbd{M-x table-insert}, are not treated
2525 specially as tables. To apply those text properties, type @kbd{M-x
2526 table-recognize}. This command scans the current buffer,
2527 @dfn{recognizes} valid table cells, and applies the relevant text
2528 properties. Conversely, type @kbd{M-x table-unrecognize} to
2529 @dfn{unrecognize} all tables in the current buffer, removing the
2530 special text properties and converting tables back to plain text.
2532 You can also use the following commands to selectively recognize or
2536 @findex table-recognize-region
2537 @item M-x table-recognize-region
2538 Recognize tables within the current region.
2540 @findex table-unrecognize-region
2541 @item M-x table-unrecognize-region
2542 Unrecognize tables within the current region.
2544 @findex table-recognize-table
2545 @item M-x table-recognize-table
2546 Recognize the table at point and activate it.
2548 @findex table-unrecognize-table
2549 @item M-x table-unrecognize-table
2550 Deactivate the table at point.
2552 @findex table-recognize-cell
2553 @item M-x table-recognize-cell
2554 Recognize the cell at point and activate it.
2556 @findex table-unrecognize-cell
2557 @item M-x table-unrecognize-cell
2558 Deactivate the cell at point.
2561 @xref{Table Conversion}, for another way to recognize a table.
2564 @subsection Commands for Table Cells
2566 @findex table-forward-cell
2567 @findex table-backward-cell
2568 The commands @kbd{M-x table-forward-cell} and @kbd{M-x
2569 table-backward-cell} move point from the current cell to an adjacent
2570 cell. The order is cyclic: when point is in the last cell of a table,
2571 @kbd{M-x table-forward-cell} moves to the first cell. Likewise, when
2572 point is on the first cell, @kbd{M-x table-backward-cell} moves to the
2575 @findex table-span-cell
2576 @kbd{M-x table-span-cell} prompts for a direction---right, left,
2577 above, or below---and merges the current cell with the adjacent cell
2578 in that direction. This command signals an error if the merge would
2579 result in an illegitimate cell layout.
2581 @findex table-split-cell
2582 @findex table-split-cell-vertically
2583 @findex table-split-cell-horizontally
2584 @cindex text-based tables, splitting cells
2585 @cindex splitting table cells
2586 @kbd{M-x table-split-cell} splits the current cell vertically or
2587 horizontally, prompting for the direction with the minibuffer. To
2588 split in a specific direction, use @kbd{M-x
2589 table-split-cell-vertically} and @kbd{M-x
2590 table-split-cell-horizontally}. When splitting vertically, the old
2591 cell contents are automatically split between the two new cells. When
2592 splitting horizontally, you are prompted for how to divide the cell
2593 contents, if the cell is non-empty; the options are @samp{split}
2594 (divide the contents at point), @samp{left} (put all the contents in
2595 the left cell), and @samp{right} (put all the contents in the right
2598 The following commands enlarge or shrink a cell. By default, they
2599 resize by one row or column; if a numeric argument is supplied, that
2600 specifies the number of rows or columns to resize by.
2603 @findex table-heighten-cell
2604 @item M-x table-heighten-cell
2605 Enlarge the current cell vertically.
2607 @findex table-shorten-cell
2608 @item M-x table-shorten-cell
2609 Shrink the current cell vertically.
2611 @findex table-widen-cell
2612 @item M-x table-widen-cell
2613 Enlarge the current cell horizontally.
2615 @findex table-narrow-cell
2616 @item M-x table-narrow-cell
2617 Shrink the current cell horizontally.
2620 @node Cell Justification
2621 @subsection Cell Justification
2622 @cindex justification in text-based tables
2624 The command @kbd{M-x table-justify} imposes @dfn{justification} on
2625 one or more cells in a text-based table. Justification determines how
2626 the text in the cell is aligned, relative to the edges of the cell.
2627 Each cell in a table can be separately justified.
2629 @findex table-justify
2630 @kbd{M-x table-justify} first prompts for what to justify; the
2631 options are @samp{cell} (just the current cell), @samp{column} (all
2632 cells in the current table column) and @samp{row} (all cells in the
2633 current table row). The command then prompts for the justification
2634 style; the options are @code{left}, @code{center}, @code{right},
2635 @code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no
2636 vertical justification).
2638 Horizontal and vertical justification styles are specified
2639 independently, and both types can be in effect simultaneously; for
2640 instance, you can call @kbd{M-x table-justify} twice, once to specify
2641 @code{right} justification and once to specify @code{bottom}
2642 justification, to align the contents of a cell to the bottom right.
2644 @vindex table-detect-cell-alignment
2645 The justification style is stored in the buffer as a text property,
2646 and is lost when you kill the buffer or exit Emacs. However, the
2647 table recognition commands, such as @kbd{M-x table-recognize}
2648 (@pxref{Table Recognition}), attempt to determine and re-apply each
2649 cell's justification style, by examining its contents. To disable
2650 this feature, change the variable @code{table-detect-cell-alignment}
2653 @node Table Rows and Columns
2654 @subsection Table Rows and Columns
2655 @cindex inserting rows and columns in text-based tables
2657 @findex table-insert-row
2658 @kbd{M-x table-insert-row} inserts a row of cells before the current
2659 table row. The current row, together with point, is pushed down past
2660 the new row. To insert a row after the last row at the bottom of a
2661 table, invoke this command with point below the table, just below the
2662 bottom edge. You can insert more than one row at a time by using a
2663 numeric prefix argument.
2665 @c A numeric prefix argument specifies the number of rows to insert.
2667 @findex table-insert-column
2668 Similarly, @kbd{M-x table-insert-column} inserts a column of cells
2669 to the left of the current table column. To insert a column to the
2670 right side of the rightmost column, invoke this command with point to
2671 the right of the rightmost column, outside the table. A numeric
2672 prefix argument specifies the number of columns to insert.
2674 @cindex deleting rows and column in text-based tables
2675 @kbd{M-x table-delete-column} deletes the column of cells at point.
2676 Similarly, @kbd{M-x table-delete-row} deletes the row of cells at
2677 point. A numeric prefix argument to either command specifies the
2678 number of columns or rows to delete.
2680 @node Table Conversion
2681 @subsection Converting Between Plain Text and Tables
2682 @cindex text to table
2683 @cindex table to text
2685 @findex table-capture
2686 The command @kbd{M-x table-capture} captures plain text in a region
2687 and turns it into a table. Unlike @kbd{M-x table-recognize}
2688 (@pxref{Table Recognition}), the original text does not need to have a
2689 table appearance; it only needs to have a logical table-like
2692 For example, suppose we have the following numbers, which are
2693 divided into three lines and separated horizontally by commas:
2702 Invoking @kbd{M-x table-capture} on that text produces this table:
2705 +-----+-----+-----+-----+
2707 +-----+-----+-----+-----+
2709 +-----+-----+-----+-----+
2711 +-----+-----+-----+-----+
2714 @findex table-release
2715 @kbd{M-x table-release} does the opposite: it converts a table back
2716 to plain text, removing its cell borders.
2718 One application of this pair of commands is to edit a text in
2719 layout. Look at the following three paragraphs (the latter two are
2720 indented with header lines):
2723 table-capture is a powerful command.
2724 Here are some things it can do:
2726 Parse Cell Items Using row and column delimiter regexps,
2727 it parses the specified text area and
2728 extracts cell items into a table.
2732 Applying @code{table-capture} to a region containing the above text,
2733 with empty strings for the column and row delimiter regexps, creates a
2734 table with a single cell like the following one.
2738 +----------------------------------------------------------+
2739 |table-capture is a powerful command. |
2740 |Here are some things it can do: |
2742 |Parse Cell Items Using row and column delimiter regexps,|
2743 | it parses the specified text area and |
2744 | extracts cell items into a table. |
2745 +----------------------------------------------------------+
2750 We can then use the cell splitting commands (@pxref{Cell Commands}) to
2751 subdivide the table so that each paragraph occupies a cell:
2754 +----------------------------------------------------------+
2755 |table-capture is a powerful command. |
2756 |Here are some things it can do: |
2757 +-----------------+----------------------------------------+
2758 |Parse Cell Items | Using row and column delimiter regexps,|
2759 | | it parses the specified text area and |
2760 | | extracts cell items into a table. |
2761 +-----------------+----------------------------------------+
2765 Each cell can now be edited independently without affecting the layout
2766 of other cells. When finished, we can invoke @kbd{M-x table-release}
2767 to convert the table back to plain text.
2770 @subsection Table Miscellany
2772 @cindex table dimensions
2773 @findex table-query-dimension
2774 The command @code{table-query-dimension} reports the layout of the
2775 table and table cell at point. Here is an example of its output:
2778 Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
2782 This indicates that the current cell is 21 characters wide and 6 lines
2783 high, the table is 67 characters wide and 16 lines high with 2 columns
2784 and 3 rows, and a total of 5 cells.
2786 @findex table-insert-sequence
2787 @kbd{M-x table-insert-sequence} inserts a string into each cell.
2788 Each string is a part of a sequence i.e., a series of increasing
2791 @cindex table for HTML and LaTeX
2792 @findex table-generate-source
2793 @kbd{M-x table-generate-source} generates a table formatted for a
2794 specific markup language. It asks for a language (which must be one
2795 of @code{html}, @code{latex}, or @code{cals}), a destination buffer in
2796 which to put the result, and a table caption, and then inserts the
2797 generated table into the specified buffer. The default destination
2798 buffer is @code{table.@var{lang}}, where @var{lang} is the language
2802 @section Two-Column Editing
2803 @cindex two-column editing
2804 @cindex splitting columns
2805 @cindex columns, splitting
2807 Two-column mode lets you conveniently edit two side-by-side columns
2808 of text. It uses two side-by-side windows, each showing its own
2809 buffer. There are three ways to enter two-column mode:
2812 @item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
2815 @findex 2C-two-columns
2816 Enter two-column mode with the current buffer on the left, and on the
2817 right, a buffer whose name is based on the current buffer's name
2818 (@code{2C-two-columns}). If the right-hand buffer doesn't already
2819 exist, it starts out empty; the current buffer's contents are not
2822 This command is appropriate when the current buffer is empty or contains
2823 just one column and you want to add another column.
2825 @item @kbd{@key{F2} s} or @kbd{C-x 6 s}
2829 Split the current buffer, which contains two-column text, into two
2830 buffers, and display them side by side (@code{2C-split}). The current
2831 buffer becomes the left-hand buffer, but the text in the right-hand
2832 column is moved into the right-hand buffer. The current column
2833 specifies the split point. Splitting starts with the current line and
2834 continues to the end of the buffer.
2836 This command is appropriate when you have a buffer that already contains
2837 two-column text, and you wish to separate the columns temporarily.
2839 @item @kbd{@key{F2} b @var{buffer} @key{RET}}
2840 @itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
2843 @findex 2C-associate-buffer
2844 Enter two-column mode using the current buffer as the left-hand buffer,
2845 and using buffer @var{buffer} as the right-hand buffer
2846 (@code{2C-associate-buffer}).
2849 @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
2850 is a string that appears on each line between the two columns. You can
2851 specify the width of the separator with a numeric argument to
2852 @kbd{@key{F2} s}; that many characters, before point, constitute the
2853 separator string. By default, the width is 1, so the column separator
2854 is the character before point.
2856 When a line has the separator at the proper place, @kbd{@key{F2} s}
2857 puts the text after the separator into the right-hand buffer, and
2858 deletes the separator. Lines that don't have the column separator at
2859 the proper place remain unsplit; they stay in the left-hand buffer, and
2860 the right-hand buffer gets an empty line to correspond. (This is the
2861 way to write a line that spans both columns while in two-column
2862 mode: write it in the left-hand buffer, and put an empty line in the
2868 The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}}
2869 (@code{2C-newline}) inserts a newline in each of the two buffers at
2870 corresponding positions. This is the easiest way to add a new line to
2871 the two-column text while editing it in split buffers.
2876 When you have edited both buffers as you wish, merge them with
2877 @kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the
2878 text from the right-hand buffer as a second column in the other buffer.
2879 To go back to two-column editing, use @kbd{@key{F2} s}.
2883 @findex 2C-dissociate
2884 Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
2885 leaving each as it stands (@code{2C-dissociate}). If the other buffer,
2886 the one not current when you type @kbd{@key{F2} d}, is empty,
2887 @kbd{@key{F2} d} kills it.