1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Text, Programs, Indentation, Top
6 @chapter Commands for Human Languages
8 @cindex manipulating text
10 This chapter describes Emacs commands that act on @dfn{text}, by
11 which we mean sequences of characters in a human language (as opposed
12 to, say, a computer programming language). These commands act in ways
13 that take into account the syntactic and stylistic conventions of
14 human languages: conventions involving words, sentences, paragraphs,
15 and capital letters. There are also commands for @dfn{filling}, which
16 means rearranging the lines of a paragraph to be approximately equal
17 in length. These commands, while intended primarily for editing text,
18 are also often useful for editing programs.
20 Emacs has several major modes for editing human-language text. If
21 the file contains ordinary text, use Text mode, which customizes Emacs
22 in small ways for the syntactic conventions of text. Outline mode
23 provides special commands for operating on text with an outline
33 Emacs has other major modes for text which contains ``embedded''
34 commands, such as @TeX{} and La@TeX{} (@pxref{TeX Mode}); HTML and
35 SGML (@pxref{HTML Mode}); XML (@pxref{Top, nXML Mode,,nxml-mode, nXML
36 Mode}); and Groff and Nroff (@pxref{Nroff Mode}). In addition, you
37 can edit formatted text in WYSIWYG style (``what you see is what you
38 get''), using Enriched mode (@pxref{Formatted Text}).
41 If you need to edit pictures made out of text characters (commonly
42 referred to as ``ASCII art''), use Picture mode, a special major mode
43 for editing such pictures.
45 @xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}.
55 @cindex automatic typing
56 The ``automatic typing'' features may be useful when writing text.
57 @inforef{Top,, autotype}.
60 * Words:: Moving over and killing words.
61 * Sentences:: Moving over and killing sentences.
62 * Paragraphs:: Moving over paragraphs.
63 * Pages:: Moving over pages.
64 * Filling:: Filling or justifying text.
65 * Case:: Changing the case of text.
66 * Text Mode:: The major modes for editing text files.
67 * Outline Mode:: Editing outlines.
68 * TeX Mode:: Editing input to the formatter TeX.
69 * HTML Mode:: Editing HTML and SGML files.
70 * Nroff Mode:: Editing input to the formatter nroff.
71 * Formatted Text:: Editing formatted text directly in WYSIWYG fashion.
72 * Text Based Tables:: Editing text-based tables in WYSIWYG fashion.
73 * Two-Column:: Splitting text columns into separate windows.
79 @cindex Meta commands and words
81 Emacs has commands for moving over or operating on words. By convention,
82 the keys for them are all Meta characters.
86 Move forward over a word (@code{forward-word}).
88 Move backward over a word (@code{backward-word}).
90 Kill up to the end of a word (@code{kill-word}).
92 Kill back to the beginning of a word (@code{backward-kill-word}).
94 Mark the end of the next word (@code{mark-word}).
96 Transpose two words or drag a word across others
97 (@code{transpose-words}).
100 Notice how these keys form a series that parallels the character-based
101 @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is
102 cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
107 @findex backward-word
108 The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b}
109 (@code{backward-word}) move forward and backward over words. These
110 @key{Meta}-based key sequences are analogous to the key sequences
111 @kbd{C-f} and @kbd{C-b}, which move over single characters. The
112 analogy extends to numeric arguments, which serve as repeat counts.
113 @kbd{M-f} with a negative argument moves backward, and @kbd{M-b} with
114 a negative argument moves forward. Forward motion stops right after
115 the last letter of the word, while backward motion stops right before
120 @kbd{M-d} (@code{kill-word}) kills the word after point. To be
121 precise, it kills everything from point to the place @kbd{M-f} would
122 move to. Thus, if point is in the middle of a word, @kbd{M-d} kills
123 just the part after point. If some punctuation comes between point
124 and the next word, it is killed along with the word. (If you wish to
125 kill only the next word but not the punctuation before it, simply do
126 @kbd{M-f} to get the end, and kill the word backwards with
127 @kbd{M-@key{DEL}}.) @kbd{M-d} takes arguments just like @kbd{M-f}.
129 @findex backward-kill-word
131 @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
132 point. It kills everything from point back to where @kbd{M-b} would
133 move to. For instance, if point is after the space in @w{@samp{FOO,
134 BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just
135 @samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead
136 of @kbd{M-@key{DEL}}.
138 @c Don't index M-t and transpose-words here, they are indexed in
139 @c fixit.texi, in the node "Transpose".
141 @c @findex transpose-words
142 @kbd{M-t} (@code{transpose-words}) exchanges the word before or
143 containing point with the following word. The delimiter characters between
144 the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
145 @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
146 more on transposition.
150 To operate on the next @var{n} words with an operation which acts on
151 the region, use the command @kbd{M-@@} (@code{mark-word}). This
152 command does not move point, but sets the mark where @kbd{M-f} would
153 move to. Once the mark is active, each additional @kbd{M-@@} advances
154 the mark by one additional word. @kbd{M-@@} also accepts a numeric
155 argument that says how many words to scan for the place to put the
158 The word commands' understanding of word boundaries is controlled by
159 the syntax table. Any character can, for example, be declared to be a
160 word delimiter. @xref{Syntax Tables,, Syntax Tables, elisp, The Emacs
161 Lisp Reference Manual}.
166 @cindex manipulating sentences
168 The Emacs commands for manipulating sentences and paragraphs are mostly
169 on Meta keys, so as to be like the word-handling commands.
173 Move back to the beginning of the sentence (@code{backward-sentence}).
175 Move forward to the end of the sentence (@code{forward-sentence}).
177 Kill forward to the end of the sentence (@code{kill-sentence}).
179 Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
184 @findex backward-sentence
185 @findex forward-sentence
186 The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and
187 @code{forward-sentence}) move to the beginning and end of the current
188 sentence, respectively. They were chosen to resemble @kbd{C-a} and
189 @kbd{C-e}, which move to the beginning and end of a line. Unlike
190 them, @kbd{M-a} and @kbd{M-e} move over successive sentences if
193 Moving backward over a sentence places point just before the first
194 character of the sentence; moving forward places point right after the
195 punctuation that ends the sentence. Neither one moves over the
196 whitespace at the sentence boundary.
199 @findex kill-sentence
200 Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to
201 go with them, @kbd{M-a} and @kbd{M-e} have a corresponding kill
202 command: @kbd{M-k} (@code{kill-sentence}) kills from point to the end
203 of the sentence. With a positive numeric argument @var{n}, it kills
204 the next @var{n} sentences; with a negative argument @minus{}@var{n},
205 it kills back to the beginning of the @var{n}th preceding sentence.
208 @findex backward-kill-sentence
209 The @kbd{C-x @key{DEL}} (@code{backward-kill-sentence}) kills back
210 to the beginning of a sentence.
212 The sentence commands assume that you follow the American typist's
213 convention of putting two spaces at the end of a sentence; they consider
214 a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!}
215 followed by the end of a line or two spaces, with any number of
216 @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between.
217 A sentence also begins or ends wherever a paragraph begins or ends.
218 It is useful to follow this convention, because it makes a distinction
219 between periods that end a sentence and periods that indicate
220 abbreviations; that enables the Emacs sentence commands to distinguish,
221 too. These commands do not stop for periods that indicate abbreviations.
223 @vindex sentence-end-double-space
224 If you want to use just one space between sentences, you can set the
225 variable @code{sentence-end-double-space} to @code{nil} to make the
226 sentence commands stop for single spaces. However, this has a
227 drawback: there is no way to distinguish between periods that end
228 sentences and those that indicate abbreviations. For convenient and
229 reliable editing, we therefore recommend you follow the two-space
230 convention. The variable @code{sentence-end-double-space} also
231 affects filling (@pxref{Fill Commands}) in related ways.
234 The variable @code{sentence-end} controls how to recognize the end
235 of a sentence. If non-@code{nil}, its value should be a regular
236 expression, which is used to match the last few characters of a
237 sentence, together with the whitespace following the sentence
238 (@pxref{Regexps}). If the value is @code{nil}, the default, then
239 Emacs computes sentence ends according to various criteria such as the
240 value of @code{sentence-end-double-space}.
242 @vindex sentence-end-without-period
243 Some languages do not use periods to indicate the end of a sentence.
244 For example, sentences in Thai end with a double space but without a
245 period. Set the variable @code{sentence-end-without-period} to
246 @code{t} in such cases.
251 @cindex manipulating paragraphs
254 @findex backward-paragraph
255 @findex forward-paragraph
257 The Emacs commands for manipulating paragraphs are also on Meta keys.
261 Move back to previous paragraph beginning (@code{backward-paragraph}).
263 Move forward to next paragraph end (@code{forward-paragraph}).
265 Put point and mark around this or next paragraph (@code{mark-paragraph}).
268 @kbd{M-@{} moves to the beginning of the current or previous
269 paragraph, while @kbd{M-@}} moves to the end of the current or next
270 paragraph. Blank lines and text-formatter command lines separate
271 paragraphs and are not considered part of any paragraph. If there is
272 a blank line before the paragraph, @kbd{M-@{} moves to the blank line,
273 because that is convenient in practice.
275 In Text mode, an indented line is not a paragraph break. If you
276 want indented lines to have this effect, use Paragraph-Indent Text
277 mode instead. @xref{Text Mode}.
279 In major modes for programs, paragraphs begin and end only at blank
280 lines. This makes the paragraph commands useful, even though there
281 are no paragraphs as such in a program.
283 When you have set a fill prefix, then paragraphs are delimited by
284 all lines which don't start with the fill prefix. @xref{Filling}.
287 @findex mark-paragraph
288 When you wish to operate on a paragraph, type @kbd{M-h}
289 (@code{mark-paragraph}) to set the region around it. For example,
290 @kbd{M-h C-w} kills the paragraph around or after point. @kbd{M-h}
291 puts point at the beginning and mark at the end of the paragraph point
292 was in. If point is between paragraphs (in a run of blank lines, or
293 at a boundary), the paragraph following point is surrounded by point
294 and mark. If there are blank lines preceding the first line of the
295 paragraph, one of these blank lines is included in the region. If the
296 region is already active, the command sets the mark without changing
297 point; furthermore, each subsequent @kbd{M-h} further advances the
298 mark by one paragraph.
300 @vindex paragraph-start
301 @vindex paragraph-separate
302 The precise definition of a paragraph boundary is controlled by the
303 variables @code{paragraph-separate} and @code{paragraph-start}. The
304 value of @code{paragraph-start} is a regexp that should match any line
305 that either starts or separates paragraphs. The value of
306 @code{paragraph-separate} is another regexp that should match only lines
307 that separate paragraphs without being part of any paragraph (for
308 example, blank lines). Lines that start a new paragraph and are
309 contained in it must match only @code{paragraph-start}, not
310 @code{paragraph-separate}. Each regular expression must match at the
311 left margin. For example, in Fundamental mode, @code{paragraph-start}
312 is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is
313 @w{@code{"[ \t\f]*$"}}.
315 Normally it is desirable for page boundaries to separate paragraphs.
316 The default values of these variables recognize the usual separator for
323 @cindex formfeed character
324 Within some text files, text is divided into @dfn{pages}, which are
325 delimited by the @dfn{formfeed character} (@acronym{ASCII} code 12,
326 sometimes denoted as @key{control-L}). When you print hardcopy for a
327 file, the formfeed character forces a page break: each page of the
328 file goes on a separate page on paper. Most Emacs commands treat the
329 formfeed character just like any other character: you can insert it
330 with @kbd{C-q C-l}, and delete it with @key{DEL}. However, since
331 pages are often meaningful divisions of the file, Emacs provides
332 commands to move over them and operate on them.
336 Move point to previous page boundary (@code{backward-page}).
338 Move point to next page boundary (@code{forward-page}).
340 Put point and mark around this page (or another page) (@code{mark-page}).
342 Count the lines in this page (@code{count-lines-page}).
348 @findex backward-page
349 The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
350 after the previous page delimiter. If point is already right after a page
351 delimiter, it skips that one and stops at the previous one. A numeric
352 argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
353 command moves forward past the next page delimiter.
357 The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
358 beginning of the current page and the mark at the end. The page
359 delimiter at the end is included (the mark follows it). The page
360 delimiter at the front is excluded (point follows it).
362 @kbd{C-x C-p C-w} is a handy way to kill a page to move it
363 elsewhere. If you move to another page delimiter with @kbd{C-x [} and
364 @kbd{C-x ]}, then yank the killed page, all the pages will be properly
365 delimited once again. The reason @kbd{C-x C-p} includes only the
366 following page delimiter in the region is to ensure that.
368 A numeric argument to @kbd{C-x C-p} specifies which page to go to,
369 relative to the current one. Zero means the current page. One means
370 the next page, and @minus{}1 means the previous one.
373 @findex count-lines-page
374 The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
375 where to break a page in two. It displays in the echo area the total number
376 of lines in the current page, and then divides it up into those preceding
377 the current line and those following, as in
380 Page has 96 (72+25) lines
384 Notice that the sum is off by one; this is correct if point is not at the
387 @vindex page-delimiter
388 The variable @code{page-delimiter} controls where pages begin. Its
389 value is a regular expression that matches the beginning of a line
390 that separates pages (@pxref{Regexps}). The normal value of this
391 variable is @code{"^\f"}, which matches a formfeed character at the
395 @section Filling Text
398 @dfn{Filling} text means breaking it up into lines that fit a
399 specified width. Emacs does filling in two ways. In Auto Fill mode,
400 inserting text with self-inserting characters also automatically fills
401 it. There are also explicit fill commands that you can use when editing
402 text leaves it unfilled. When you edit formatted text, you can specify
403 a style of filling for each portion of the text (@pxref{Formatted
407 * Auto Fill:: Auto Fill mode breaks long lines automatically.
408 * Fill Commands:: Commands to refill paragraphs and center lines.
409 * Fill Prefix:: Filling paragraphs that are indented or in a comment, etc.
410 * Adaptive Fill:: How Emacs can determine the fill prefix automatically.
414 @subsection Auto Fill Mode
415 @cindex Auto Fill mode
416 @cindex mode, Auto Fill
418 @dfn{Auto Fill} mode is a minor mode in which lines are broken
419 automatically when they become too wide. Breaking happens only when
420 you type a @key{SPC} or @key{RET}.
423 @item M-x auto-fill-mode
424 Enable or disable Auto Fill mode.
427 In Auto Fill mode, break lines when appropriate.
430 @findex auto-fill-mode
431 @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off
432 if it was on. With a positive numeric argument it always turns Auto
433 Fill mode on, and with a negative argument always turns it off. You can
434 see when Auto Fill mode is in effect by the presence of the word
435 @samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is
436 a minor mode which is enabled or disabled for each buffer individually.
439 In Auto Fill mode, lines are broken automatically at spaces when they
440 get longer than the desired width. Line breaking and rearrangement
441 takes place only when you type @key{SPC} or @key{RET}. If you wish to
442 insert a space or newline without permitting line-breaking, type
443 @kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a
444 control-J). Also, @kbd{C-o} inserts a newline without line breaking.
446 Auto Fill mode works well with programming-language modes, because it
447 indents new lines with @key{TAB}. If a line ending in a comment gets
448 too long, the text of the comment is split into two comment lines.
449 Optionally, new comment delimiters are inserted at the end of the first
450 line and the beginning of the second so that each line is a separate
451 comment; the variable @code{comment-multi-line} controls the choice
454 Adaptive filling (@pxref{Adaptive Fill}) works for Auto Filling as
455 well as for explicit fill commands. It takes a fill prefix
456 automatically from the second or first line of a paragraph.
458 Auto Fill mode does not refill entire paragraphs; it can break lines but
459 cannot merge lines. So editing in the middle of a paragraph can result in
460 a paragraph that is not correctly filled. The easiest way to make the
461 paragraph properly filled again is usually with the explicit fill commands.
463 @xref{Fill Commands}.
466 Many users like Auto Fill mode and want to use it in all text files.
467 The section on init files says how to arrange this permanently for yourself.
471 @subsection Explicit Fill Commands
475 Fill current paragraph (@code{fill-paragraph}).
477 Set the fill column (@code{set-fill-column}).
478 @item M-x fill-region
479 Fill each paragraph in the region (@code{fill-region}).
480 @item M-x fill-region-as-paragraph
481 Fill the region, considering it as one paragraph.
487 @findex fill-paragraph
488 To refill a paragraph, use the command @kbd{M-q}
489 (@code{fill-paragraph}). This operates on the paragraph that point is
490 inside, or the one after point if point is between paragraphs.
491 Refilling works by removing all the line-breaks, then inserting new
492 ones where necessary. When there is an active region, this command
493 operates on the text within the region like @code{fill-region}.
496 To refill many paragraphs, use @kbd{M-x fill-region}, which
497 finds the paragraphs in the region and fills each of them.
499 @findex fill-region-as-paragraph
500 @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h}
501 for finding paragraph boundaries (@pxref{Paragraphs}). For more
502 control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
503 everything between point and mark as a single paragraph. This command
504 deletes any blank lines within the region, so separate blocks of text
505 end up combined into one block.
507 @cindex justification
508 A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text
509 as well as filling it. This means that extra spaces are inserted to
510 make the right margin line up exactly at the fill column. To remove
511 the extra spaces, use @kbd{M-q} with no argument. (Likewise for
512 @code{fill-region}.) Another way to control justification, and choose
513 other styles of filling, is with the @code{justification} text
514 property; see @ref{Format Justification}.
516 @kindex M-o M-s @r{(Text mode)}
519 The command @kbd{M-o M-s} (@code{center-line}) centers the current line
520 within the current fill column. With an argument @var{n}, it centers
521 @var{n} lines individually and moves past them. This binding is
522 made by Text mode and is available only in that and related modes
527 @findex set-fill-column
528 The maximum line width for filling is in the variable
529 @code{fill-column}. Altering the value of @code{fill-column} makes it
530 local to the current buffer; until that time, the default value is in
531 effect. The default is initially 70. @xref{Locals}. The easiest way
532 to set @code{fill-column} is to use the command @kbd{C-x f}
533 (@code{set-fill-column}). With a numeric argument, it uses that as the
534 new fill column. With just @kbd{C-u} as argument, it sets
535 @code{fill-column} to the current horizontal position of point.
537 Emacs commands normally consider a period followed by two spaces or by
538 a newline as the end of a sentence; a period followed by just one space
539 indicates an abbreviation and not the end of a sentence. To preserve
540 the distinction between these two ways of using a period, the fill
541 commands do not break a line after a period followed by just one space.
543 If the variable @code{sentence-end-double-space} is @code{nil}, the
544 fill commands expect and leave just one space at the end of a sentence.
545 Ordinarily this variable is @code{t}, so the fill commands insist on
546 two spaces for the end of a sentence, as explained above. @xref{Sentences}.
548 @vindex colon-double-space
549 If the variable @code{colon-double-space} is non-@code{nil}, the
550 fill commands put two spaces after a colon.
552 @vindex fill-nobreak-predicate
553 The variable @code{fill-nobreak-predicate} is a hook (an abnormal
554 hook, @pxref{Hooks}) specifying additional conditions where
555 line-breaking is not allowed. Each function is called with no
556 arguments, with point at a place where Emacs is considering breaking
557 the line. If a function returns a non-@code{nil} value, then that's
558 a bad place to break the line. Two standard functions you can use are
559 @code{fill-single-word-nobreak-p} (don't break after the first word of
560 a sentence or before the last) and @code{fill-french-nobreak-p} (don't
561 break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}).
564 @subsection The Fill Prefix
567 To fill a paragraph in which each line starts with a special marker
568 (which might be a few spaces, giving an indented paragraph), you can use
569 the @dfn{fill prefix} feature. The fill prefix is a string that Emacs
570 expects every line to start with, and which is not included in filling.
571 You can specify a fill prefix explicitly; Emacs can also deduce the
572 fill prefix automatically (@pxref{Adaptive Fill}).
576 Set the fill prefix (@code{set-fill-prefix}).
578 Fill a paragraph using current fill prefix (@code{fill-paragraph}).
579 @item M-x fill-individual-paragraphs
580 Fill the region, considering each change of indentation as starting a
582 @item M-x fill-nonuniform-paragraphs
583 Fill the region, considering only paragraph-separator lines as starting
588 @findex set-fill-prefix
589 To specify a fill prefix for the current buffer, move to a line that
590 starts with the desired prefix, put point at the end of the prefix,
591 and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period
592 after the @kbd{C-x}.) To turn off the fill prefix, specify an empty
593 prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line.
595 When a fill prefix is in effect, the fill commands remove the fill
596 prefix from each line of the paragraph before filling and insert it on
597 each line after filling. (The beginning of the first line of the
598 paragraph is left unchanged, since often that is intentionally
599 different.) Auto Fill mode also inserts the fill prefix automatically
600 when it makes a new line. The @kbd{C-o} command inserts the fill
601 prefix on new lines it creates, when you use it at the beginning of a
602 line (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes
603 the prefix (if it occurs) after the newline that it deletes
604 (@pxref{Indentation}).
606 For example, if @code{fill-column} is 40 and you set the fill prefix
607 to @samp{;; }, then @kbd{M-q} in the following text
611 ;; example of a paragraph
612 ;; inside a Lisp-style comment.
619 ;; This is an example of a paragraph
620 ;; inside a Lisp-style comment.
623 Lines that do not start with the fill prefix are considered to start
624 paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
625 good results for paragraphs with hanging indentation (every line
626 indented except the first one). Lines which are blank or indented once
627 the prefix is removed also separate or start paragraphs; this is what
628 you want if you are writing multi-paragraph comments with a comment
629 delimiter on each line.
631 @findex fill-individual-paragraphs
632 You can use @kbd{M-x fill-individual-paragraphs} to set the fill
633 prefix for each paragraph automatically. This command divides the
634 region into paragraphs, treating every change in the amount of
635 indentation as the start of a new paragraph, and fills each of these
636 paragraphs. Thus, all the lines in one ``paragraph'' have the same
637 amount of indentation. That indentation serves as the fill prefix for
640 @findex fill-nonuniform-paragraphs
641 @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
642 the region into paragraphs in a different way. It considers only
643 paragraph-separating lines (as defined by @code{paragraph-separate}) as
644 starting a new paragraph. Since this means that the lines of one
645 paragraph may have different amounts of indentation, the fill prefix
646 used is the smallest amount of indentation of any of the lines of the
647 paragraph. This gives good results with styles that indent a paragraph's
648 first line more or less that the rest of the paragraph.
651 The fill prefix is stored in the variable @code{fill-prefix}. Its value
652 is a string, or @code{nil} when there is no fill prefix. This is a
653 per-buffer variable; altering the variable affects only the current buffer,
654 but there is a default value which you can change as well. @xref{Locals}.
656 The @code{indentation} text property provides another way to control
657 the amount of indentation paragraphs receive. @xref{Format Indentation}.
660 @subsection Adaptive Filling
662 @cindex adaptive filling
663 The fill commands can deduce the proper fill prefix for a paragraph
664 automatically in certain cases: either whitespace or certain punctuation
665 characters at the beginning of a line are propagated to all lines of the
668 If the paragraph has two or more lines, the fill prefix is taken from
669 the paragraph's second line, but only if it appears on the first line as
672 If a paragraph has just one line, fill commands @emph{may} take a
673 prefix from that line. The decision is complicated because there are
674 three reasonable things to do in such a case:
678 Use the first line's prefix on all the lines of the paragraph.
681 Indent subsequent lines with whitespace, so that they line up under the
682 text that follows the prefix on the first line, but don't actually copy
683 the prefix from the first line.
686 Don't do anything special with the second and following lines.
689 All three of these styles of formatting are commonly used. So the
690 fill commands try to determine what you would like, based on the prefix
691 that appears and on the major mode. Here is how.
693 @vindex adaptive-fill-first-line-regexp
694 If the prefix found on the first line matches
695 @code{adaptive-fill-first-line-regexp}, or if it appears to be a
696 comment-starting sequence (this depends on the major mode), then the
697 prefix found is used for filling the paragraph, provided it would not
698 act as a paragraph starter on subsequent lines.
700 Otherwise, the prefix found is converted to an equivalent number of
701 spaces, and those spaces are used as the fill prefix for the rest of the
702 lines, provided they would not act as a paragraph starter on subsequent
705 In Text mode, and other modes where only blank lines and page
706 delimiters separate paragraphs, the prefix chosen by adaptive filling
707 never acts as a paragraph starter, so it can always be used for filling.
709 @vindex adaptive-fill-mode
710 @vindex adaptive-fill-regexp
711 The variable @code{adaptive-fill-regexp} determines what kinds of line
712 beginnings can serve as a fill prefix: any characters at the start of
713 the line that match this regular expression are used. If you set the
714 variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
715 never chosen automatically.
717 @vindex adaptive-fill-function
718 You can specify more complex ways of choosing a fill prefix
719 automatically by setting the variable @code{adaptive-fill-function} to a
720 function. This function is called with point after the left margin of a
721 line, and it should return the appropriate fill prefix based on that
722 line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets
723 a chance to find a prefix.
726 @section Case Conversion Commands
727 @cindex case conversion
729 Emacs has commands for converting either a single word or any arbitrary
730 range of text to upper case or to lower case.
734 Convert following word to lower case (@code{downcase-word}).
736 Convert following word to upper case (@code{upcase-word}).
738 Capitalize the following word (@code{capitalize-word}).
740 Convert region to lower case (@code{downcase-region}).
742 Convert region to upper case (@code{upcase-region}).
748 @cindex words, case conversion
749 @cindex converting text to upper or lower case
750 @cindex capitalizing words
751 @findex downcase-word
753 @findex capitalize-word
754 The word conversion commands are the most useful. @kbd{M-l}
755 (@code{downcase-word}) converts the word after point to lower case, moving
756 past it. Thus, repeating @kbd{M-l} converts successive words.
757 @kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while
758 @kbd{M-c} (@code{capitalize-word}) puts the first letter of the word
759 into upper case and the rest into lower case. All these commands convert
760 several words at once if given an argument. They are especially convenient
761 for converting a large amount of text from all upper case to mixed case,
762 because you can move through the text using @kbd{M-l}, @kbd{M-u} or
763 @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
766 When given a negative argument, the word case conversion commands apply
767 to the appropriate number of words before point, but do not move point.
768 This is convenient when you have just typed a word in the wrong case: you
769 can give the case conversion command and continue typing.
771 If a word case conversion command is given in the middle of a word,
772 it applies only to the part of the word which follows point. (This is
773 comparable to what @kbd{M-d} (@code{kill-word}) does.) With a
774 negative argument, case conversion applies only to the part of the
779 @findex downcase-region
780 @findex upcase-region
781 The other case conversion commands are @kbd{C-x C-u}
782 (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
783 convert everything between point and mark to the specified case. Point and
786 The region case conversion commands @code{upcase-region} and
787 @code{downcase-region} are normally disabled. This means that they ask
788 for confirmation if you try to use them. When you confirm, you may
789 enable the command, which means it will not ask for confirmation again.
798 When you edit files of text in a human language, it's more convenient
799 to use Text mode rather than Fundamental mode. To enter Text mode, type
802 In Text mode, only blank lines and page delimiters separate
803 paragraphs. As a result, paragraphs can be indented, and adaptive
804 filling determines what indentation to use when filling a paragraph.
805 @xref{Adaptive Fill}.
807 @kindex TAB @r{(Text mode)}
808 Text mode defines @key{TAB} to run @code{indent-relative}
809 (@pxref{Indentation}), so that you can conveniently indent a line like
812 Text mode turns off the features concerned with comments except when
813 you explicitly invoke them. It changes the syntax table so that
814 single-quotes are considered part of words. However, if a word starts
815 with single-quotes, these are treated as a prefix for purposes such as
816 capitalization. That is, @kbd{M-c} will convert @samp{'hello'} into
817 @samp{'Hello'}, as expected.
819 @cindex Paragraph-Indent Text mode
820 @cindex mode, Paragraph-Indent Text
821 @findex paragraph-indent-text-mode
822 @findex paragraph-indent-minor-mode
823 If you indent the first lines of paragraphs, then you should use
824 Paragraph-Indent Text mode rather than Text mode. In this mode, you
825 do not need to have blank lines between paragraphs, because the
826 first-line indentation is sufficient to start a paragraph; however
827 paragraphs in which every line is indented are not supported. Use
828 @kbd{M-x paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x
829 paragraph-indent-minor-mode} to enable an equivalent minor mode in
830 situations where you can't change the major mode---in mail
831 composition, for instance.
833 @kindex M-TAB @r{(Text mode)}
834 Text mode, and all the modes based on it, define @kbd{M-@key{TAB}}
835 as the command @code{ispell-complete-word}, which performs completion
836 of the partial word in the buffer before point, using the spelling
837 dictionary as the space of possible words. @xref{Spelling}. If your
838 window manager defines @kbd{M-@key{TAB}} to switch windows, you can
839 type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.
841 @vindex text-mode-hook
842 Entering Text mode runs the hook @code{text-mode-hook}. Other major
843 modes related to Text mode also run this hook, followed by hooks of
844 their own; this includes Paragraph-Indent Text mode, Nroff mode,
845 @TeX{} mode, Outline mode, and Message mode. Hook functions on
846 @code{text-mode-hook} can look at the value of @code{major-mode} to
847 see which of these modes is actually being entered. @xref{Hooks}.
850 @section Outline Mode
852 @cindex mode, Outline
853 @cindex invisible lines
856 @findex outline-minor-mode
857 @vindex outline-minor-mode-prefix
858 Outline mode is a major mode much like Text mode but intended for
859 editing outlines. It allows you to make parts of the text temporarily
860 invisible so that you can see the outline structure. Type @kbd{M-x
861 outline-mode} to switch to Outline mode as the major mode of the current
864 When Outline mode makes a line invisible, the line does not appear
865 on the screen. The screen appears exactly as if the invisible line
866 were deleted, except that an ellipsis (three periods in a row) appears
867 at the end of the previous visible line. (Multiple consecutive
868 invisible lines produce just one ellipsis.)
870 Editing commands that operate on lines, such as @kbd{C-n} and
871 @kbd{C-p}, treat the text of the invisible line as part of the previous
872 visible line. Killing the ellipsis at the end of a visible line
873 really kills all the following invisible lines.
875 Outline minor mode provides the same commands as the major mode,
876 Outline mode, but you can use it in conjunction with other major modes.
877 Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in
878 the current buffer. You can also specify this in the text of a file,
879 with a file local variable of the form @samp{mode: outline-minor}
880 (@pxref{File Variables}).
882 @kindex C-c @@ @r{(Outline minor mode)}
883 The major mode, Outline mode, provides special key bindings on the
884 @kbd{C-c} prefix. Outline minor mode provides similar bindings with
885 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
886 major mode's special commands. (The variable
887 @code{outline-minor-mode-prefix} controls the prefix used.)
889 @vindex outline-mode-hook
890 Entering Outline mode runs the hook @code{text-mode-hook} followed by
891 the hook @code{outline-mode-hook} (@pxref{Hooks}).
894 * Format: Outline Format. What the text of an outline looks like.
895 * Motion: Outline Motion. Special commands for moving through
897 * Visibility: Outline Visibility. Commands to control what is visible.
898 * Views: Outline Views. Outlines and multiple views.
899 * Foldout:: Folding means zooming in on outlines.
903 @subsection Format of Outlines
905 @cindex heading lines (Outline mode)
906 @cindex body lines (Outline mode)
907 Outline mode assumes that the lines in the buffer are of two types:
908 @dfn{heading lines} and @dfn{body lines}. A heading line represents a
909 topic in the outline. Heading lines start with one or more stars; the
910 number of stars determines the depth of the heading in the outline
911 structure. Thus, a heading line with one star is a major topic; all the
912 heading lines with two stars between it and the next one-star heading
913 are its subtopics; and so on. Any line that is not a heading line is a
914 body line. Body lines belong with the preceding heading line. Here is
920 which says something about the topic of food.
923 This is the body of the second-level header.
933 Another first-level topic with its header line.
936 A heading line together with all following body lines is called
937 collectively an @dfn{entry}. A heading line together with all following
938 deeper heading lines and their body lines is called a @dfn{subtree}.
940 @vindex outline-regexp
941 You can customize the criterion for distinguishing heading lines by
942 setting the variable @code{outline-regexp}. (The recommended ways to
943 do this are in a major mode function or with a file local variable.)
944 Any line whose beginning has a match for this regexp is considered a
945 heading line. Matches that start within a line (not at the left
946 margin) do not count.
948 The length of the matching text determines the level of the heading;
949 longer matches make a more deeply nested level. Thus, for example, if
950 a text formatter has commands @samp{@@chapter}, @samp{@@section} and
951 @samp{@@subsection} to divide the document into chapters and sections,
952 you could make those lines count as heading lines by setting
953 @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note
954 the trick: the two words @samp{chapter} and @samp{section} are equally
955 long, but by defining the regexp to match only @samp{chap} we ensure
956 that the length of the text matched on a chapter heading is shorter,
957 so that Outline mode will know that sections are contained in
958 chapters. This works as long as no other command starts with
961 @vindex outline-level
962 You can explicitly specify a rule for calculating the level of a
963 heading line by setting the variable @code{outline-level}. The value
964 of @code{outline-level} should be a function that takes no arguments
965 and returns the level of the current heading. The recommended ways to
966 set this variable are in a major mode command or with a file local
970 @subsection Outline Motion Commands
972 Outline mode provides special motion commands that move backward and
973 forward to heading lines.
977 Move point to the next visible heading line
978 (@code{outline-next-visible-heading}).
980 Move point to the previous visible heading line
981 (@code{outline-previous-visible-heading}).
983 Move point to the next visible heading line at the same level
984 as the one point is on (@code{outline-forward-same-level}).
986 Move point to the previous visible heading line at the same level
987 (@code{outline-backward-same-level}).
989 Move point up to a lower-level (more inclusive) visible heading line
990 (@code{outline-up-heading}).
993 @findex outline-next-visible-heading
994 @findex outline-previous-visible-heading
995 @kindex C-c C-n @r{(Outline mode)}
996 @kindex C-c C-p @r{(Outline mode)}
997 @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next
998 heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves
999 similarly backward. Both accept numeric arguments as repeat counts. The
1000 names emphasize that invisible headings are skipped, but this is not really
1001 a special feature. All editing commands that look for lines ignore the
1002 invisible lines automatically.
1004 @findex outline-up-heading
1005 @findex outline-forward-same-level
1006 @findex outline-backward-same-level
1007 @kindex C-c C-f @r{(Outline mode)}
1008 @kindex C-c C-b @r{(Outline mode)}
1009 @kindex C-c C-u @r{(Outline mode)}
1010 More powerful motion commands understand the level structure of headings.
1011 @kbd{C-c C-f} (@code{outline-forward-same-level}) and
1012 @kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
1013 heading line to another visible heading at the same depth in
1014 the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves
1015 backward to another heading that is less deeply nested.
1017 @node Outline Visibility
1018 @subsection Outline Visibility Commands
1020 The other special commands of outline mode are used to make lines visible
1021 or invisible. Their names all start with @code{hide} or @code{show}.
1022 Most of them fall into pairs of opposites. They are not undoable; instead,
1023 you can undo right past them. Making lines visible or invisible is simply
1024 not recorded by the undo mechanism.
1026 Many of these commands act on the ``current'' heading line. If
1027 point is on a heading line, that is the current heading line; if point
1028 is on a body line, the current heading line is the nearest preceding
1033 Make the current heading line's body invisible (@code{hide-entry}).
1035 Make the current heading line's body visible (@code{show-entry}).
1037 Make everything under the current heading invisible, not including the
1038 heading itself (@code{hide-subtree}).
1040 Make everything under the current heading visible, including body,
1041 subheadings, and their bodies (@code{show-subtree}).
1043 Make the body of the current heading line, and of all its subheadings,
1044 invisible (@code{hide-leaves}).
1046 Make all subheadings of the current heading line, at all levels,
1047 visible (@code{show-branches}).
1049 Make immediate subheadings (one level down) of the current heading
1050 line visible (@code{show-children}).
1052 Make all body lines in the buffer invisible (@code{hide-body}).
1054 Make all lines in the buffer visible (@code{show-all}).
1056 Hide everything except the top @var{n} levels of heading lines
1057 (@code{hide-sublevels}).
1059 Hide everything except for the heading or body that point is in, plus
1060 the headings leading up from there to the top level of the outline
1061 (@code{hide-other}).
1066 @kindex C-c C-c @r{(Outline mode)}
1067 @kindex C-c C-e @r{(Outline mode)}
1068 Two commands that are exact opposites are @kbd{C-c C-c}
1069 (@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They apply
1070 to the body lines directly following the current heading line.
1071 Subheadings and their bodies are not affected.
1073 @findex hide-subtree
1074 @findex show-subtree
1075 @kindex C-c C-s @r{(Outline mode)}
1076 @kindex C-c C-d @r{(Outline mode)}
1077 @cindex subtree (Outline mode)
1078 Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree})
1079 and @kbd{C-c C-s} (@code{show-subtree}). Both apply to the current
1080 heading line's @dfn{subtree}: its body, all its subheadings, both
1081 direct and indirect, and all of their bodies. In other words, the
1082 subtree contains everything following the current heading line, up to
1083 and not including the next heading of the same or higher rank.
1086 @findex show-branches
1087 @kindex C-c C-l @r{(Outline mode)}
1088 @kindex C-c C-k @r{(Outline mode)}
1089 Intermediate between a visible subtree and an invisible one is having
1090 all the subheadings visible but none of the body. There are two
1091 commands for doing this, depending on whether you want to hide the
1092 bodies or make the subheadings visible. They are @kbd{C-c C-l}
1093 (@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}).
1095 @kindex C-c C-i @r{(Outline mode)}
1096 @findex show-children
1097 A little weaker than @code{show-branches} is @kbd{C-c C-i}
1098 (@code{show-children}). It makes just the direct subheadings
1099 visible---those one level down. Deeper subheadings remain invisible, if
1100 they were invisible.
1104 @kindex C-c C-t @r{(Outline mode)}
1105 @kindex C-c C-a @r{(Outline mode)}
1106 Two commands have a blanket effect on the whole file. @kbd{C-c C-t}
1107 (@code{hide-body}) makes all body lines invisible, so that you see just
1108 the outline structure (as a special exception, it will not hide lines
1109 at the top of the file, preceding the first header line, even though
1110 these are technically body lines). @kbd{C-c C-a} (@code{show-all})
1111 makes all lines visible. These commands can be thought of as a pair
1112 of opposites even though @kbd{C-c C-a} applies to more than just body
1115 @findex hide-sublevels
1116 @kindex C-c C-q @r{(Outline mode)}
1117 The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the
1118 top level headings. With a numeric argument @var{n}, it hides everything
1119 except the top @var{n} levels of heading lines.
1122 @kindex C-c C-o @r{(Outline mode)}
1123 The command @kbd{C-c C-o} (@code{hide-other}) hides everything except
1124 the heading and body text that point is in, plus its parents (the headers
1125 leading up from there to top level in the outline) and the top level
1129 When incremental search finds text that is hidden by Outline mode,
1130 it makes that part of the buffer visible. If you exit the search
1131 at that position, the text remains visible. You can also
1132 automatically make text visible as you navigate in it by using
1133 @kbd{M-x reveal-mode}.
1136 @subsection Viewing One Outline in Multiple Views
1138 @cindex multiple views of outline
1139 @cindex views of an outline
1140 @cindex outline with multiple views
1141 @cindex indirect buffers and outlines
1142 You can display two views of a single outline at the same time, in
1143 different windows. To do this, you must create an indirect buffer using
1144 @kbd{M-x make-indirect-buffer}. The first argument of this command is
1145 the existing outline buffer name, and its second argument is the name to
1146 use for the new indirect buffer. @xref{Indirect Buffers}.
1148 Once the indirect buffer exists, you can display it in a window in the
1149 normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline
1150 mode commands to show and hide parts of the text operate on each buffer
1151 independently; as a result, each buffer can have its own view. If you
1152 want more than two views on the same outline, create additional indirect
1156 @subsection Folding Editing
1158 @cindex folding editing
1159 The Foldout package extends Outline mode and Outline minor mode with
1160 ``folding'' commands. The idea of folding is that you zoom in on a
1161 nested portion of the outline, while hiding its relatives at higher
1164 Consider an Outline mode buffer with all the text and subheadings under
1165 level-1 headings hidden. To look at what is hidden under one of these
1166 headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose
1167 the body, or @kbd{C-c C-i} to expose the child (level-2) headings.
1170 @findex foldout-zoom-subtree
1171 With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1172 This exposes the body and child subheadings, and narrows the buffer so
1173 that only the @w{level-1} heading, the body and the level-2 headings are
1174 visible. Now to look under one of the level-2 headings, position the
1175 cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body
1176 and its level-3 child subheadings and narrows the buffer again. Zooming
1177 in on successive subheadings can be done as much as you like. A string
1178 in the mode line shows how deep you've gone.
1180 When zooming in on a heading, to see only the child subheadings specify
1181 a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children
1182 can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2
1183 C-c C-z} exposes two levels of child subheadings. Alternatively, the
1184 body can be specified with a negative argument: @kbd{M-- C-c C-z}. The
1185 whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x
1186 show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}.
1188 While you're zoomed in, you can still use Outline mode's exposure and
1189 hiding functions without disturbing Foldout. Also, since the buffer is
1190 narrowed, ``global'' editing actions will only affect text under the
1191 zoomed-in heading. This is useful for restricting changes to a
1192 particular chapter or section of your document.
1195 @findex foldout-exit-fold
1196 To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1197 This hides all the text and subheadings under the top-level heading and
1198 returns you to the previous view of the buffer. Specifying a numeric
1199 argument exits that many levels of folds. Specifying a zero argument
1202 To cancel the narrowing of a fold without hiding the text and
1203 subheadings, specify a negative argument. For example, @kbd{M--2 C-c
1204 C-x} exits two folds and leaves the text and subheadings exposed.
1206 Foldout mode also provides mouse commands for entering and exiting
1207 folds, and for showing and hiding text:
1210 @item @kbd{C-M-Mouse-1} zooms in on the heading clicked on
1213 single click: expose body.
1215 double click: expose subheadings.
1217 triple click: expose body and subheadings.
1219 quad click: expose entire subtree.
1221 @item @kbd{C-M-Mouse-2} exposes text under the heading clicked on
1224 single click: expose body.
1226 double click: expose subheadings.
1228 triple click: expose body and subheadings.
1230 quad click: expose entire subtree.
1232 @item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold
1235 single click: hide subtree.
1237 double click: exit fold and hide text.
1239 triple click: exit fold without hiding text.
1241 quad click: exit all folds and hide text.
1245 @vindex foldout-mouse-modifiers
1246 You can specify different modifier keys (instead of
1247 @kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if
1248 you have already loaded the @file{foldout.el} library, you must reload
1249 it in order for this to take effect.
1251 To use the Foldout package, you can type @kbd{M-x load-library
1252 @key{RET} foldout @key{RET}}; or you can arrange for to do that
1253 automatically by putting this in your @file{.emacs} file:
1256 (eval-after-load "outline" '(require 'foldout))
1260 @section @TeX{} Mode
1262 @cindex La@TeX{} mode
1263 @cindex Sli@TeX{} mode
1264 @cindex Doc@TeX{} mode
1265 @cindex mode, @TeX{}
1266 @cindex mode, La@TeX{}
1267 @cindex mode, Sli@TeX{}
1268 @cindex mode, Doc@TeX{}
1270 @findex plain-tex-mode
1276 Emacs provides special major modes for editing files written in
1277 @TeX{} and its related formats. @TeX{} is a powerful text formatter
1278 written by Donald Knuth; like GNU Emacs, it is free software.
1279 La@TeX{} is a simplified input format for @TeX{}, implemented using
1280 @TeX{} macros. Doc@TeX{} is a special file format in which the
1281 La@TeX{} sources are written, combining sources with documentation.
1282 Sli@TeX{} is an obsolete special form of La@TeX{}.@footnote{It has
1283 been replaced by the @samp{slides} document class, which comes with
1286 @vindex tex-default-mode
1287 @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode,
1288 Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ
1289 only slightly, and are designed for editing the four different
1290 formats. Emacs selects the appropriate mode by looking at the
1291 contents of the buffer. (This is done by the @code{tex-mode} command,
1292 which is normally called automatically when you visit a @TeX{}-like
1293 file. @xref{Choosing Modes}.) If the contents are insufficient to
1294 determine this, Emacs chooses the mode specified by the variable
1295 @code{tex-default-mode}; its default value is @code{latex-mode}. If
1296 Emacs does not guess right, you can select the correct variant of
1297 @TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x
1298 latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}.
1300 Emacs also provides Bib@TeX{} mode, a major mode for editing
1301 Bib@TeX{} files. Bib@TeX{} is a tool for storing and formatting
1302 bibliographic references, which is commonly used together with
1303 La@TeX{}. In addition, the Ref@TeX{} package provides a minor mode
1304 which can be used in conjunction with La@TeX{} mode to manage
1305 bibliographic references. @inforef{Top,, reftex}.
1308 * Editing: TeX Editing. Special commands for editing in TeX mode.
1309 * LaTeX: LaTeX Editing. Additional commands for LaTeX input files.
1310 * Printing: TeX Print. Commands for printing part of a file with TeX.
1311 * Misc: TeX Misc. Customization of TeX mode, and related features.
1315 @subsection @TeX{} Editing Commands
1319 Insert, according to context, either @samp{``} or @samp{"} or
1320 @samp{''} (@code{tex-insert-quote}).
1322 Insert a paragraph break (two newlines) and check the previous
1323 paragraph for unbalanced braces or dollar signs
1324 (@code{tex-terminate-paragraph}).
1325 @item M-x tex-validate-region
1326 Check each paragraph in the region for unbalanced braces or dollar signs.
1328 Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1330 Move forward past the next unmatched close brace (@code{up-list}).
1333 @findex tex-insert-quote
1334 @kindex " @r{(@TeX{} mode)}
1335 In @TeX{}, the character @samp{"} is not normally used; instead,
1336 quotations begin with @samp{``} and end with @samp{''}. For
1337 convenience, @TeX{} mode overrides the normal meaning of the key
1338 @kbd{"} with a command that inserts a pair of single-quotes or
1339 backquotes (@code{tex-insert-quote}). To be precise, it inserts
1340 @samp{``} after whitespace or an open brace, @samp{"} after a
1341 backslash, and @samp{''} after any other character.
1343 As a special exception, if you type @kbd{"} when the text before
1344 point is either @samp{``} or @samp{''}, Emacs replaces that preceding
1345 text with a single @samp{"} character. You can therefore type
1346 @kbd{""} to insert @samp{"}, should you ever need to do so. (You can
1347 also use @kbd{C-q "} to insert this character.)
1349 To disable the @kbd{"} expansion feature, eliminate that binding in
1350 the local map (@pxref{Key Bindings}).
1352 In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1353 understand the way @TeX{} math mode delimiters match. When you insert a
1354 @samp{$} that is meant to exit math mode, the position of the matching
1355 @samp{$} that entered math mode is displayed for a second. This is the
1356 same feature that displays the open brace that matches a close brace that
1357 is inserted. However, there is no way to tell whether a @samp{$} enters
1358 math mode or leaves it; so when you insert a @samp{$} that enters math
1359 mode, the previous @samp{$} position is shown as if it were a match, even
1360 though they are actually unrelated.
1362 @findex tex-insert-braces
1363 @kindex C-c @{ @r{(@TeX{} mode)}
1365 @kindex C-c @} @r{(@TeX{} mode)}
1366 @TeX{} uses braces as delimiters that must match. Some users prefer
1367 to keep braces balanced at all times, rather than inserting them
1368 singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1369 braces. It leaves point between the two braces so you can insert the
1370 text that belongs inside. Afterward, use the command @kbd{C-c @}}
1371 (@code{up-list}) to move forward past the close brace.
1373 @findex tex-validate-region
1374 @findex tex-terminate-paragraph
1375 @kindex C-j @r{(@TeX{} mode)}
1376 There are two commands for checking the matching of braces. @kbd{C-j}
1377 (@code{tex-terminate-paragraph}) checks the paragraph before point, and
1378 inserts two newlines to start a new paragraph. It outputs a message in
1379 the echo area if any mismatch is found. @kbd{M-x tex-validate-region}
1380 checks a region, paragraph by paragraph. The errors are listed in the
1381 @samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in
1382 that buffer to go to a particular mismatch.
1384 Note that Emacs commands count square brackets and parentheses in
1385 @TeX{} mode, not just braces. This is not strictly correct for the
1386 purpose of checking @TeX{} syntax. However, parentheses and square
1387 brackets are likely to be used in text as matching delimiters, and it
1388 is useful for the various motion commands and automatic match display
1392 @subsection La@TeX{} Editing Commands
1394 La@TeX{} mode (and its obsolete variant, Sli@TeX{} mode) provide a
1395 few extra features not applicable to plain @TeX{}:
1399 Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position
1400 point on a line between them (@code{tex-latex-block}).
1402 Close the innermost La@TeX{} block not yet closed
1403 (@code{tex-close-latex-block}).
1406 @findex tex-latex-block
1407 @kindex C-c C-o @r{(La@TeX{} mode)}
1408 @vindex latex-block-names
1409 In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to
1410 group blocks of text. To insert a @samp{\begin} and a matching
1411 @samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c
1412 C-o} (@code{tex-latex-block}). A blank line is inserted between the
1413 two, and point is left there. You can use completion when you enter the
1414 block type; to specify additional block type names beyond the standard
1415 list, set the variable @code{latex-block-names}. For example, here's
1416 how to add @samp{theorem}, @samp{corollary}, and @samp{proof}:
1419 (setq latex-block-names '("theorem" "corollary" "proof"))
1422 @findex tex-close-latex-block
1423 @kindex C-c C-e @r{(La@TeX{} mode)}
1424 In La@TeX{} input, @samp{\begin} and @samp{\end} commands must
1425 balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to
1426 insert automatically a matching @samp{\end} to match the last unmatched
1427 @samp{\begin}. It indents the @samp{\end} to match the corresponding
1428 @samp{\begin}. It inserts a newline after @samp{\end} if point is at
1429 the beginning of a line.
1432 @subsection @TeX{} Printing Commands
1434 You can invoke @TeX{} as an inferior of Emacs on either the entire
1435 contents of the buffer or just a region at a time. Running @TeX{} in
1436 this way on just one chapter is a good way to see what your changes
1437 look like without taking the time to format the entire file.
1441 Invoke @TeX{} on the current region, together with the buffer's header
1442 (@code{tex-region}).
1444 Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1446 Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1448 Invoke @TeX{} on the current file (@code{tex-file}).
1450 Recenter the window showing output from the inferior @TeX{} so that
1451 the last line can be seen (@code{tex-recenter-output-buffer}).
1453 Kill the @TeX{} subprocess (@code{tex-kill-job}).
1455 Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1456 C-f} command (@code{tex-print}).
1458 Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1459 C-f} command (@code{tex-view}).
1461 Show the printer queue (@code{tex-show-print-queue}).
1463 Invoke some other compilation command on the entire current buffer
1464 (@code{tex-compile}).
1468 @kindex C-c C-b @r{(@TeX{} mode)}
1470 @kindex C-c C-p @r{(@TeX{} mode)}
1472 @kindex C-c C-v @r{(@TeX{} mode)}
1473 @findex tex-show-print-queue
1474 @kindex C-c C-q @r{(@TeX{} mode)}
1475 You can pass the current buffer through an inferior @TeX{} by means of
1476 @kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a
1477 temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}).
1478 Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to
1479 view the progress of your output towards being printed. If your terminal
1480 has the ability to display @TeX{} output files, you can preview the
1481 output on the terminal with @kbd{C-c C-v} (@code{tex-view}).
1483 @cindex @env{TEXINPUTS} environment variable
1484 @vindex tex-directory
1485 You can specify the directory to use for running @TeX{} by setting the
1486 variable @code{tex-directory}. @code{"."} is the default value. If
1487 your environment variable @env{TEXINPUTS} contains relative directory
1488 names, or if your files contains @samp{\input} commands with relative
1489 file names, then @code{tex-directory} @emph{must} be @code{"."} or you
1490 will get the wrong results. Otherwise, it is safe to specify some other
1491 directory, such as @code{"/tmp"}.
1493 @vindex tex-run-command
1494 @vindex latex-run-command
1495 @vindex slitex-run-command
1496 @vindex tex-dvi-print-command
1497 @vindex tex-dvi-view-command
1498 @vindex tex-show-queue-command
1499 If you want to specify which shell commands are used in the inferior @TeX{},
1500 you can do so by setting the values of the variables @code{tex-run-command},
1501 @code{latex-run-command}, @code{slitex-run-command},
1502 @code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and
1503 @code{tex-show-queue-command}. The default values may
1504 (or may not) be appropriate for your system.
1506 Normally, the file name given to these commands comes at the end of
1507 the command string; for example, @samp{latex @var{filename}}. In some
1508 cases, however, the file name needs to be embedded in the command; an
1509 example is when you need to provide the file name as an argument to one
1510 command whose output is piped to another. You can specify where to put
1511 the file name with @samp{*} in the command string. For example,
1514 (setq tex-dvi-print-command "dvips -f * | lpr")
1517 @findex tex-kill-job
1518 @kindex C-c C-k @r{(@TeX{} mode)}
1519 @findex tex-recenter-output-buffer
1520 @kindex C-c C-l @r{(@TeX{} mode)}
1521 The terminal output from @TeX{}, including any error messages, appears
1522 in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can
1523 switch to this buffer and feed it input (this works as in Shell mode;
1524 @pxref{Interactive Shell}). Without switching to this buffer you can
1525 scroll it so that its last line is visible by typing @kbd{C-c
1528 Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1529 you see that its output is no longer useful. Using @kbd{C-c C-b} or
1530 @kbd{C-c C-r} also kills any @TeX{} process still running.
1533 @kindex C-c C-r @r{(@TeX{} mode)}
1534 You can also pass an arbitrary region through an inferior @TeX{} by typing
1535 @kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files
1536 of @TeX{} input contain commands at the beginning to set parameters and
1537 define macros, without which no later part of the file will format
1538 correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a
1539 part of the file as containing essential commands; it is included before
1540 the specified region as part of the input to @TeX{}. The designated part
1541 of the file is called the @dfn{header}.
1543 @cindex header (@TeX{} mode)
1544 To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1545 special strings in the file. Insert @samp{%**start of header} before the
1546 header, and @samp{%**end of header} after it. Each string must appear
1547 entirely on one line, but there may be other text on the line before or
1548 after. The lines containing the two strings are included in the header.
1549 If @samp{%**start of header} does not appear within the first 100 lines of
1550 the buffer, @kbd{C-c C-r} assumes that there is no header.
1552 In La@TeX{} mode, the header begins with @samp{\documentclass} or
1553 @samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
1554 are commands that La@TeX{} requires you to use in any case, so nothing
1555 special needs to be done to identify the header.
1558 @kindex C-c C-f @r{(@TeX{} mode)}
1559 The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1560 work in a temporary directory, and do not have available any of the auxiliary
1561 files needed by @TeX{} for cross-references; these commands are generally
1562 not suitable for running the final copy in which all of the cross-references
1565 When you want the auxiliary files for cross references, use @kbd{C-c
1566 C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1567 in that file's directory. Before running @TeX{}, it offers to save any
1568 modified buffers. Generally, you need to use (@code{tex-file}) twice to
1569 get the cross-references right.
1571 @vindex tex-start-options
1572 The value of the variable @code{tex-start-options} specifies
1573 options for the @TeX{} run.
1575 @vindex tex-start-commands
1576 The value of the variable @code{tex-start-commands} specifies @TeX{}
1577 commands for starting @TeX{}. The default value causes @TeX{} to run
1578 in nonstop mode. To run @TeX{} interactively, set the variable to
1581 @vindex tex-main-file
1582 Large @TeX{} documents are often split into several files---one main
1583 file, plus subfiles. Running @TeX{} on a subfile typically does not
1584 work; you have to run it on the main file. In order to make
1585 @code{tex-file} useful when you are editing a subfile, you can set the
1586 variable @code{tex-main-file} to the name of the main file. Then
1587 @code{tex-file} runs @TeX{} on that file.
1589 The most convenient way to use @code{tex-main-file} is to specify it
1590 in a local variable list in each of the subfiles. @xref{File
1593 @findex tex-bibtex-file
1594 @kindex C-c TAB @r{(@TeX{} mode)}
1595 @vindex tex-bibtex-command
1596 For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
1597 file for the current buffer's file. Bib@TeX{} looks up bibliographic
1598 citations in a data base and prepares the cited references for the
1599 bibliography section. The command @kbd{C-c @key{TAB}}
1600 (@code{tex-bibtex-file}) runs the shell command
1601 (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1602 current buffer's file. Generally, you need to do @kbd{C-c C-f}
1603 (@code{tex-file}) once to generate the @samp{.aux} file, then do
1604 @kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1605 (@code{tex-file}) twice more to get the cross-references correct.
1608 @kindex C-c C-c @r{(@TeX{} mode)}
1609 To invoke some other compilation program on the current @TeX{}
1610 buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows
1611 how to pass arguments to many common programs, including
1612 @file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can
1613 select your desired compilation program using the standard completion
1614 keys (@pxref{Completion}).
1617 @subsection @TeX{} Mode Miscellany
1619 @vindex tex-shell-hook
1620 @vindex tex-mode-hook
1621 @vindex latex-mode-hook
1622 @vindex slitex-mode-hook
1623 @vindex plain-tex-mode-hook
1624 Entering any variant of @TeX{} mode runs the hooks
1625 @code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either
1626 @code{plain-tex-mode-hook}, @code{latex-mode-hook}, or
1627 @code{slitex-mode-hook}, whichever is appropriate. Starting the
1628 @TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}.
1632 @findex iso-iso2gtex
1633 @findex iso-gtex2iso
1634 @cindex Latin-1 @TeX{} encoding
1635 @cindex @TeX{} encoding
1636 The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1637 iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert
1638 between Latin-1 encoded files and @TeX{}-encoded equivalents.
1640 @c Too cryptic to be useful, too cryptic for me to make it better -- rms.
1642 are included by default in the @code{format-alist} variable, so they
1643 can be used with @kbd{M-x format-find-file}, for instance.
1646 @ignore @c Not worth documenting if it is only for Czech -- rms.
1647 @findex tildify-buffer
1648 @findex tildify-region
1649 @cindex ties, @TeX{}, inserting
1650 @cindex hard spaces, @TeX{}, inserting
1651 The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region}
1652 insert @samp{~} (@dfn{tie}) characters where they are conventionally
1653 required. This is set up for Czech---customize the group
1654 @samp{tildify} for other languages or for other sorts of markup.
1657 @cindex Ref@TeX{} package
1658 @cindex references, La@TeX{}
1659 @cindex La@TeX{} references
1660 For managing all kinds of references for La@TeX{}, you can use
1661 Ref@TeX{}. @inforef{Top,, reftex}.
1664 @section SGML and HTML Modes
1672 The major modes for SGML and HTML provide indentation support and
1673 commands for operating on tags. HTML mode is a slightly customized
1674 variant of SGML mode.
1678 @kindex C-c C-n @r{(SGML mode)}
1679 @findex sgml-name-char
1680 Interactively specify a special character and insert the SGML
1681 @samp{&}-command for that character (@code{sgml-name-char}).
1684 @kindex C-c C-t @r{(SGML mode)}
1686 Interactively specify a tag and its attributes (@code{sgml-tag}).
1687 This command asks you for a tag name and for the attribute values,
1688 then inserts both the opening tag and the closing tag, leaving point
1691 With a prefix argument @var{n}, the command puts the tag around the
1692 @var{n} words already present in the buffer after point. Whenever a
1693 region is active, it puts the tag around the region (when Transient
1694 Mark mode is off, it does this when a numeric argument of @minus{}1 is
1698 @kindex C-c C-a @r{(SGML mode)}
1699 @findex sgml-attributes
1700 Interactively insert attribute values for the current tag
1701 (@code{sgml-attributes}).
1704 @kindex C-c C-f @r{(SGML mode)}
1705 @findex sgml-skip-tag-forward
1706 Skip across a balanced tag group (which extends from an opening tag
1707 through its corresponding closing tag) (@code{sgml-skip-tag-forward}).
1708 A numeric argument acts as a repeat count.
1711 @kindex C-c C-b @r{(SGML mode)}
1712 @findex sgml-skip-tag-backward
1713 Skip backward across a balanced tag group (which extends from an
1714 opening tag through its corresponding closing tag)
1715 (@code{sgml-skip-tag-backward}). A numeric argument acts as a repeat
1719 @kindex C-c C-d @r{(SGML mode)}
1720 @findex sgml-delete-tag
1721 Delete the tag at or after point, and delete the matching tag too
1722 (@code{sgml-delete-tag}). If the tag at or after point is an opening
1723 tag, delete the closing tag too; if it is a closing tag, delete the
1726 @item C-c ? @var{tag} @key{RET}
1727 @kindex C-c ? @r{(SGML mode)}
1728 @findex sgml-tag-help
1729 Display a description of the meaning of tag @var{tag}
1730 (@code{sgml-tag-help}). If the argument @var{tag} is empty, describe
1734 @kindex C-c / @r{(SGML mode)}
1735 @findex sgml-close-tag
1736 Insert a close tag for the innermost unterminated tag
1737 (@code{sgml-close-tag}). If called from within a tag or a comment,
1738 close this element instead of inserting a close tag.
1741 @kindex C-c 8 @r{(SGML mode)}
1742 @findex sgml-name-8bit-mode
1743 Toggle a minor mode in which Latin-1 characters insert the
1744 corresponding SGML commands that stand for them, instead of the
1745 characters themselves (@code{sgml-name-8bit-mode}).
1748 @kindex C-c C-v @r{(SGML mode)}
1749 @findex sgml-validate
1750 Run a shell command (which you must specify) to validate the current
1751 buffer as SGML (@code{sgml-validate}).
1754 @kindex C-c TAB @r{(SGML mode)}
1755 @findex sgml-tags-invisible
1756 Toggle the visibility of existing tags in the buffer. This can be
1757 used as a cheap preview (@code{sgml-tags-invisible}).
1764 The default mode for editing XML documents is called nXML mode
1765 (@code{xml-mode} or @code{nxml-mode}). This is a powerful major mode
1766 that can recognize many existing XML schema and use them to provide
1767 completion of XML elements via @kbd{C-@key{RET}} or @kbd{M-@key{TAB}},
1768 as well as ``on-the-fly'' XML validation with error highlighting. It
1769 is described in its own manual. @xref{Top, nXML Mode,,nxml-mode, nXML
1772 @vindex sgml-xml-mode
1773 However, you can also use SGML mode to edit XML, since XML is a
1774 strict subset of SGML. In XML, every opening tag must have an
1775 explicit closing tag. When the variable @code{sgml-xml-mode} is
1776 non-@code{nil}, the tag insertion commands described above always
1777 insert explicit closing tags as well. When you visit a file in SGML
1778 mode, Emacs determines whether it is XML by examining the file
1779 contents, and sets @code{sgml-xml-mode} accordingly.
1786 Nroff mode is a mode like Text mode but modified to handle nroff commands
1787 present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
1788 differs from Text mode in only a few ways. All nroff command lines are
1789 considered paragraph separators, so that filling will never garble the
1790 nroff commands. Pages are separated by @samp{.bp} commands. Comments
1791 start with backslash-doublequote. Also, three special commands are
1792 provided that are not in Text mode:
1794 @findex forward-text-line
1795 @findex backward-text-line
1796 @findex count-text-lines
1797 @kindex M-n @r{(Nroff mode)}
1798 @kindex M-p @r{(Nroff mode)}
1799 @kindex M-? @r{(Nroff mode)}
1802 Move to the beginning of the next line that isn't an nroff command
1803 (@code{forward-text-line}). An argument is a repeat count.
1805 Like @kbd{M-n} but move up (@code{backward-text-line}).
1807 Displays in the echo area the number of text lines (lines that are not
1808 nroff commands) in the region (@code{count-text-lines}).
1811 @findex electric-nroff-mode
1812 The other feature of Nroff mode is that you can turn on Electric Nroff
1813 mode. This is a minor mode that you can turn on or off with @kbd{M-x
1814 electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
1815 time you use @key{RET} to end a line that contains an nroff command that
1816 opens a kind of grouping, the matching nroff command to close that
1817 grouping is automatically inserted on the following line. For example,
1818 if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
1819 this inserts the matching command @samp{.)b} on a new line following
1822 If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
1823 heading lines are lines of the form @samp{.H} followed by a number (the
1826 @vindex nroff-mode-hook
1827 Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
1828 the hook @code{nroff-mode-hook} (@pxref{Hooks}).
1830 @node Formatted Text
1831 @section Editing Formatted Text
1833 @cindex Enriched mode
1834 @cindex mode, Enriched
1835 @cindex formatted text
1837 @cindex word processing
1838 @dfn{Enriched mode} is a minor mode for editing files that contain
1839 formatted text in WYSIWYG fashion, as in a word processor. Currently,
1840 formatted text in Enriched mode can specify fonts, colors, underlining,
1841 margins, and types of filling and justification. In the future, we plan
1842 to implement other formatting features as well.
1844 Enriched mode is a minor mode (@pxref{Minor Modes}). It is
1845 typically used in conjunction with Text mode (@pxref{Text Mode}), but
1846 you can also use it with other major modes such as Outline mode and
1847 Paragraph-Indent Text mode.
1849 @cindex text/enriched MIME format
1850 Potentially, Emacs can store formatted text files in various file
1851 formats. Currently, only one format is implemented: @dfn{text/enriched}
1852 format, which is defined by the MIME protocol. @xref{Format
1853 Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual},
1854 for details of how Emacs recognizes and converts file formats.
1856 The Emacs distribution contains a formatted text file that can serve as
1857 an example. Its name is @file{etc/enriched.doc}. It contains samples
1858 illustrating all the features described in this section. It also
1859 contains a list of ideas for future enhancements.
1862 * Requesting Formatted Text:: Entering and exiting Enriched mode.
1863 * Hard and Soft Newlines:: There are two different kinds of newlines.
1864 * Editing Format Info:: How to edit text properties.
1865 * Faces: Format Faces. Bold, italic, underline, etc.
1866 * Color: Format Colors. Changing the color of text.
1867 * Indent: Format Indentation. Changing the left and right margins.
1868 * Justification: Format Justification.
1869 Centering, setting text flush with the
1870 left or right margin, etc.
1871 * Special: Format Properties. The "special" text properties submenu.
1872 * Forcing Enriched Mode:: How to force use of Enriched mode.
1875 @node Requesting Formatted Text
1876 @subsection Requesting to Edit Formatted Text
1878 Whenever you visit a file that Emacs saved in the text/enriched
1879 format, Emacs automatically converts the formatting information in the
1880 file into Emacs's own internal format (known as @dfn{text
1881 properties}), and turns on Enriched mode.
1883 @findex enriched-mode
1884 To create a new file of formatted text, first visit the nonexistent
1885 file, then type @kbd{M-x enriched-mode} before you start inserting text.
1886 This command turns on Enriched mode. Do this before you begin inserting
1887 text, to ensure that the text you insert is handled properly.
1889 More generally, the command @code{enriched-mode} turns Enriched mode
1890 on if it was off, and off if it was on. With a prefix argument, this
1891 command turns Enriched mode on if the argument is positive, and turns
1892 the mode off otherwise.
1894 When you save a buffer while Enriched mode is enabled in it, Emacs
1895 automatically converts the text to text/enriched format while writing it
1896 into the file. When you visit the file again, Emacs will automatically
1897 recognize the format, reconvert the text, and turn on Enriched mode
1900 @vindex enriched-translations
1901 You can add annotations for saving additional text properties, which
1902 Emacs normally does not save, by adding to @code{enriched-translations}.
1903 Note that the text/enriched standard requires any non-standard
1904 annotations to have names starting with @samp{x-}, as in
1905 @samp{x-read-only}. This ensures that they will not conflict with
1906 standard annotations that may be added later.
1908 @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual},
1909 for more information about text properties.
1911 @node Hard and Soft Newlines
1912 @subsection Hard and Soft Newlines
1913 @cindex hard newline
1914 @cindex soft newline
1915 @cindex newlines, hard and soft
1917 @cindex use-hard-newlines
1918 In formatted text, Emacs distinguishes between two different kinds of
1919 newlines, @dfn{hard} newlines and @dfn{soft} newlines. (You can enable
1920 or disable this feature separately in any buffer with the command
1921 @code{use-hard-newlines}.)
1923 Hard newlines are used to separate paragraphs, or items in a list, or
1924 anywhere that there should always be a line break regardless of the
1925 margins. The @key{RET} command (@code{newline}) and @kbd{C-o}
1926 (@code{open-line}) insert hard newlines.
1928 Soft newlines are used to make text fit between the margins. All the
1929 fill commands, including Auto Fill, insert soft newlines---and they
1930 delete only soft newlines.
1932 Although hard and soft newlines look the same, it is important to bear
1933 the difference in mind. Do not use @key{RET} to break lines in the
1934 middle of filled paragraphs, or else you will get hard newlines that are
1935 barriers to further filling. Instead, let Auto Fill mode break lines,
1936 so that if the text or the margins change, Emacs can refill the lines
1937 properly. @xref{Auto Fill}.
1939 On the other hand, in tables and lists, where the lines should always
1940 remain as you type them, you can use @key{RET} to end lines. For these
1941 lines, you may also want to set the justification style to
1942 @code{unfilled}. @xref{Format Justification}.
1944 @node Editing Format Info
1945 @subsection Editing Format Information
1947 There are two ways to alter the formatting information for a formatted
1948 text file: with keyboard commands, and with the mouse.
1950 The easiest way to add properties to your document is with the Text
1951 Properties menu. You can get to this menu in two ways: from the Edit
1952 menu in the menu bar (use @kbd{@key{F10} e t} if you have no mouse),
1953 or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle
1954 mouse button). There are also keyboard commands described in the
1957 These items in the Text Properties menu run commands directly:
1960 @findex facemenu-remove-face-props
1961 @item Remove Face Properties
1962 Delete from the region all face and color text properties
1963 (@code{facemenu-remove-face-props}).
1965 @findex facemenu-remove-all
1966 @item Remove Text Properties
1967 Delete @emph{all} text properties from the region
1968 (@code{facemenu-remove-all}).
1970 @findex describe-text-properties
1971 @cindex text properties of characters
1972 @cindex overlays at character position
1973 @cindex widgets at buffer position
1974 @cindex buttons at buffer position
1975 @item Describe Properties
1976 List all the text properties, widgets, buttons, and overlays of the
1977 character following point (@code{describe-text-properties}).
1980 Display a list of all the defined faces (@code{list-faces-display}).
1982 @item Display Colors
1983 Display a list of all the defined colors (@code{list-colors-display}).
1987 Other items in the Text Properties menu lead to submenus:
1990 * Faces: Format Faces. Bold, italic, underline, etc.
1991 * Color: Format Colors. Changing the color of text.
1992 * Indent: Format Indentation. Changing the left and right margins.
1993 * Justification: Format Justification.
1994 Centering, setting text flush with the
1995 left or right margin, etc.
1996 * Special: Format Properties. The "special" text properties submenu.
2000 The rest lead to submenus which are described in the following sections.
2004 @subsection Faces in Formatted Text
2006 The Faces submenu under Text Properties lists various Emacs faces
2007 including @code{bold}, @code{italic}, and @code{underline}
2008 (@pxref{Faces}). These menu items operate on the region if it is
2009 active and nonempty. Otherwise, they specify to use that face for an
2010 immediately following self-inserting character. There is also an item
2011 @samp{Other} with which you can enter a face name through the
2012 minibuffer (@pxref{Standard Faces}).
2014 Instead of the Faces submenu, you can use these keyboard commands:
2017 @kindex M-o d @r{(Enriched mode)}
2018 @findex facemenu-set-default
2020 Remove all @code{face} properties from the region (which includes
2021 specified colors), or force the following inserted character to have no
2022 @code{face} property (@code{facemenu-set-default}).
2023 @kindex M-o b @r{(Enriched mode)}
2024 @findex facemenu-set-bold
2026 Add the face @code{bold} to the region or to the following inserted
2027 character (@code{facemenu-set-bold}).
2028 @kindex M-o i @r{(Enriched mode)}
2029 @findex facemenu-set-italic
2031 Add the face @code{italic} to the region or to the following inserted
2032 character (@code{facemenu-set-italic}).
2033 @kindex M-o l @r{(Enriched mode)}
2034 @findex facemenu-set-bold-italic
2036 Add the face @code{bold-italic} to the region or to the following
2037 inserted character (@code{facemenu-set-bold-italic}).
2038 @kindex M-o u @r{(Enriched mode)}
2039 @findex facemenu-set-underline
2041 Add the face @code{underline} to the region or to the following inserted
2042 character (@code{facemenu-set-underline}).
2043 @kindex M-o o @r{(Enriched mode)}
2044 @findex facemenu-set-face
2045 @item M-o o @var{face} @key{RET}
2046 Add the face @var{face} to the region or to the following inserted
2047 character (@code{facemenu-set-face}).
2050 With a prefix argument, all these commands apply to an immediately
2051 following self-inserting character, disregarding the region.
2053 A self-inserting character normally inherits the @code{face}
2054 property (and most other text properties) from the preceding character
2055 in the buffer. If you use the above commands to specify face for the
2056 next self-inserting character, or the next section's commands to
2057 specify a foreground or background color for it, then it does not
2058 inherit the @code{face} property from the preceding character; instead
2059 it uses whatever you specified. It will still inherit other text
2062 Strictly speaking, these commands apply only to the first following
2063 self-inserting character that you type. But if you insert additional
2064 characters after it, they will inherit from the first one. So it
2065 appears that these commands apply to all of them.
2067 Enriched mode defines two additional faces: @code{excerpt} and
2068 @code{fixed}. These correspond to codes used in the text/enriched file
2071 The @code{excerpt} face is intended for quotations. This face is the
2072 same as @code{italic} unless you customize it (@pxref{Face Customization}).
2074 The @code{fixed} face means, ``Use a fixed-width font for this part
2075 of the text.'' Applying the @code{fixed} face to a part of the text
2076 will cause that part of the text to appear in a fixed-width font, even
2077 if the default font is variable-width. This applies to Emacs and to
2078 other systems that display text/enriched format. So if you
2079 specifically want a certain part of the text to use a fixed-width
2080 font, you should specify the @code{fixed} face for that part.
2082 By default, the @code{fixed} face looks the same as @code{bold}.
2083 This is an attempt to distinguish it from @code{default}. You may
2084 wish to customize @code{fixed} to some other fixed-width medium font.
2085 @xref{Face Customization}.
2087 If your terminal cannot display different faces, you will not be
2088 able to see them, but you can still edit documents containing faces,
2089 and even add faces and colors to documents. The faces you specify
2090 will be visible when the file is viewed on a terminal that can display
2094 @subsection Colors in Formatted Text
2096 You can specify foreground and background colors for portions of the
2097 text. Under Text Properties, there is a submenu for specifying the
2098 foreground color, and a submenu for specifying the background color.
2099 Each one lists all the colors that you have used in Enriched mode in
2100 the current Emacs session.
2102 If the region is active, the command applies to the text in the
2103 region; otherwise, it applies to any immediately following
2104 self-inserting input. When Transient Mark mode is off
2105 (@pxref{Persistent Mark}), it always applies to the region unless a
2106 prefix argument is given, in which case it applies to the following
2109 Each of the two color submenus contains one additional item:
2110 @samp{Other}. You can use this item to specify a color that is not
2111 listed in the menu; it reads the color name with the minibuffer. To
2112 display a list of available colors and their names, use the
2113 @samp{Display Colors} menu item in the Text Properties menu
2114 (@pxref{Editing Format Info}).
2116 Any color that you specify in this way, or that is mentioned in a
2117 formatted text file that you read in, is added to the corresponding
2118 color menu for the duration of the Emacs session.
2120 @findex facemenu-set-foreground
2121 @findex facemenu-set-background
2122 There are no predefined key bindings for specifying colors, but you can do so
2123 with the extended commands @kbd{M-x facemenu-set-foreground} and
2124 @kbd{M-x facemenu-set-background}. Both of these commands read the name
2125 of the color with the minibuffer.
2127 @node Format Indentation
2128 @subsection Indentation in Formatted Text
2130 When editing formatted text, you can specify different amounts of
2131 indentation for the right or left margin of an entire paragraph or a
2132 part of a paragraph. The margins you specify automatically affect the
2133 Emacs fill commands (@pxref{Filling}) and line-breaking commands.
2135 The Indentation submenu of Text Properties provides a convenient
2136 interface for specifying these properties. The submenu contains four
2140 @kindex C-x TAB @r{(Enriched mode)}
2141 @findex increase-left-margin
2143 Indent the region by 4 columns (@code{increase-left-margin}). In
2144 Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
2145 you supply a numeric argument, that says how many columns to add to the
2146 margin (a negative argument reduces the number of columns).
2149 Remove 4 columns of indentation from the region.
2151 @item Indent Right More
2152 Make the text narrower by indenting 4 columns at the right margin.
2154 @item Indent Right Less
2155 Remove 4 columns of indentation from the right margin.
2158 You can use these commands repeatedly to increase or decrease the
2161 The most common way to use them is to change the indentation of an
2162 entire paragraph. For other uses, the effects of refilling can be
2163 hard to predict, except in some special cases like the one described
2166 The most common other use is to format paragraphs with @dfn{hanging
2167 indents}, which means that the first line is indented less than
2168 subsequent lines. To set up a hanging indent, increase the
2169 indentation of the region starting after the first word of the
2170 paragraph and running until the end of the paragraph.
2172 Indenting the first line of a paragraph is easier. Set the margin for
2173 the whole paragraph where you want it to be for the body of the
2174 paragraph, then indent the first line by inserting extra spaces or tabs.
2176 @vindex standard-indent
2177 The variable @code{standard-indent} specifies how many columns these
2178 commands should add to or subtract from the indentation. The default
2179 value is 4. The overall default right margin for Enriched mode is
2180 controlled by the variable @code{fill-column}, as usual.
2182 @kindex C-c [ @r{(Enriched mode)}
2183 @kindex C-c ] @r{(Enriched mode)}
2184 @findex set-left-margin
2185 @findex set-right-margin
2186 There are also two commands for setting the left or right margin of
2187 the region absolutely: @code{set-left-margin} and
2188 @code{set-right-margin}. Enriched mode binds these commands to
2189 @kbd{C-c [} and @kbd{C-c ]}, respectively. You can specify the
2190 margin width either with a numeric argument or in the minibuffer.
2192 Sometimes, as a result of editing, the filling of a paragraph becomes
2193 messed up---parts of the paragraph may extend past the left or right
2194 margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to
2195 refill the paragraph.
2197 The fill prefix, if any, works in addition to the specified paragraph
2198 indentation: @kbd{C-x .} does not include the specified indentation's
2199 whitespace in the new value for the fill prefix, and the fill commands
2200 look for the fill prefix after the indentation on each line. @xref{Fill
2203 @node Format Justification
2204 @subsection Justification in Formatted Text
2206 When editing formatted text, you can specify various styles of
2207 justification for a paragraph. The style you specify automatically
2208 affects the Emacs fill commands.
2210 The Justification submenu of Text Properties provides a convenient
2211 interface for specifying the style. The submenu contains five items:
2215 This is the most common style of justification (at least for English).
2216 Lines are aligned at the left margin but left uneven at the right.
2219 This aligns each line with the right margin. Spaces and tabs are added
2220 on the left, if necessary, to make lines line up on the right.
2223 This justifies the text, aligning both edges of each line. Justified
2224 text looks very nice in a printed book, where the spaces can all be
2225 adjusted equally, but it does not look as nice with a fixed-width font
2226 on the screen. Perhaps a future version of Emacs will be able to adjust
2227 the width of spaces in a line to achieve elegant justification.
2230 This centers every line between the current margins.
2233 This turns off filling entirely. Each line will remain as you wrote it;
2234 the fill and auto-fill functions will have no effect on text which has
2235 this setting. You can, however, still indent the left margin. In
2236 unfilled regions, all newlines are treated as hard newlines (@pxref{Hard
2237 and Soft Newlines}) .
2240 In Enriched mode, you can also specify justification from the keyboard
2241 using the @kbd{M-j} prefix character:
2244 @kindex M-j l @r{(Enriched mode)}
2245 @findex set-justification-left
2247 Make the region left-filled (@code{set-justification-left}).
2248 @kindex M-j r @r{(Enriched mode)}
2249 @findex set-justification-right
2251 Make the region right-filled (@code{set-justification-right}).
2252 @kindex M-j b @r{(Enriched mode)}
2253 @findex set-justification-full
2255 Make the region fully justified (@code{set-justification-full}).
2256 @kindex M-j c @r{(Enriched mode)}
2257 @kindex M-S @r{(Enriched mode)}
2258 @findex set-justification-center
2261 Make the region centered (@code{set-justification-center}).
2262 @kindex M-j u @r{(Enriched mode)}
2263 @findex set-justification-none
2265 Make the region unfilled (@code{set-justification-none}).
2268 Justification styles apply to entire paragraphs. All the
2269 justification-changing commands operate on the paragraph containing
2270 point, or, if the region is active, on all paragraphs which overlap the
2273 @vindex default-justification
2274 The default justification style is specified by the variable
2275 @code{default-justification}. Its value should be one of the symbols
2276 @code{left}, @code{right}, @code{full}, @code{center}, or @code{none}.
2277 This is a per-buffer variable. Setting the variable directly affects
2278 only the current buffer. However, customizing it in a Custom buffer
2279 sets (as always) the default value for buffers that do not override it.
2280 @xref{Locals}, and @ref{Easy Customization}.
2282 @node Format Properties
2283 @subsection Setting Other Text Properties
2285 The Special Properties submenu of Text Properties can add or remove
2286 three other useful text properties: @code{read-only}, @code{invisible}
2287 and @code{intangible}. The @code{intangible} property disallows
2288 moving point within the text, the @code{invisible} text property hides
2289 text from display, and the @code{read-only} property disallows
2290 alteration of the text.
2292 Each of these special properties has a menu item to add it to the
2293 region. The last menu item, @samp{Remove Special}, removes all of these
2294 special properties from the text in the region.
2296 Currently, the @code{invisible} and @code{intangible} properties are
2297 @emph{not} saved in the text/enriched format. The @code{read-only}
2298 property is saved, but it is not a standard part of the text/enriched
2299 format, so other editors may not respect it.
2301 @node Forcing Enriched Mode
2302 @subsection Forcing Enriched Mode
2304 Normally, Emacs knows when you are editing formatted text because it
2305 recognizes the special annotations used in the file that you visited.
2306 However, sometimes you must take special actions to convert file
2307 contents or turn on Enriched mode:
2311 When you visit a file that was created with some other editor, Emacs may
2312 not recognize the file as being in the text/enriched format. In this
2313 case, when you visit the file you will see the formatting commands
2314 rather than the formatted text. Type @kbd{M-x format-decode-buffer} to
2315 translate it. This also automatically turns on Enriched mode.
2318 When you @emph{insert} a file into a buffer, rather than visiting it,
2319 Emacs does the necessary conversions on the text which you insert, but
2320 it does not enable Enriched mode. If you wish to do that, type @kbd{M-x
2324 The command @code{format-decode-buffer} translates text in various
2325 formats into Emacs's internal format. It asks you to specify the format
2326 to translate from; however, normally you can type just @key{RET}, which
2327 tells Emacs to guess the format.
2329 @findex format-find-file
2330 If you wish to look at a text/enriched file in its raw form, as a
2331 sequence of characters rather than as formatted text, use the @kbd{M-x
2332 find-file-literally} command. This visits a file, like
2333 @code{find-file}, but does not do format conversion. It also inhibits
2334 character code conversion (@pxref{Coding Systems}) and automatic
2335 uncompression (@pxref{Compressed Files}). To disable format conversion
2336 but allow character code conversion and/or automatic uncompression if
2337 appropriate, use @code{format-find-file} with suitable arguments.
2339 @node Text Based Tables
2340 @section Editing Text-based Tables
2342 @cindex text-based tables
2344 Table mode provides an easy and intuitive way to create and edit WYSIWYG
2345 text-based tables. Here is an example of such a table:
2349 +-----------------+--------------------------------+-----------------+
2350 | Command | Description | Key Binding |
2351 +-----------------+--------------------------------+-----------------+
2352 | forward-char |Move point right N characters | C-f |
2353 | |(left if N is negative). | |
2355 | |On reaching end of buffer, stop | |
2356 | |and signal error. | |
2357 +-----------------+--------------------------------+-----------------+
2358 | backward-char |Move point left N characters | C-b |
2359 | |(right if N is negative). | |
2361 | |On attempt to pass beginning or | |
2362 | |end of buffer, stop and signal | |
2364 +-----------------+--------------------------------+-----------------+
2368 Table mode allows the contents of the table such as this one to be
2369 easily manipulated by inserting or deleting characters inside a cell.
2370 A cell is effectively a localized rectangular edit region and edits to
2371 a cell do not affect the contents of the surrounding cells. If the
2372 contents do not fit into a cell, then the cell is automatically
2373 expanded in the vertical and/or horizontal directions and the rest of
2374 the table is restructured and reformatted in accordance with the
2378 * Table Definition:: What is a text based table.
2379 * Table Creation:: How to create a table.
2380 * Table Recognition:: How to activate and deactivate tables.
2381 * Cell Commands:: Cell-oriented commands in a table.
2382 * Cell Justification:: Justifying cell contents.
2383 * Row Commands:: Manipulating rows of table cell.
2384 * Column Commands:: Manipulating columns of table cell.
2385 * Fixed Width Mode:: Fixing cell width.
2386 * Table Conversion:: Converting between plain text and tables.
2387 * Measuring Tables:: Analyzing table dimension.
2388 * Table Misc:: Table miscellany.
2391 @node Table Definition
2392 @subsection What is a Text-based Table?
2394 Keep the following examples of valid tables in mind as a reference
2395 while you read this section:
2398 +--+----+---+ +-+ +--+-----+
2400 +--+----+---+ +-+ | +--+--+
2402 +--+----+---+ +--+--+ |
2407 A table consists of a rectangular frame whose inside is divided into
2408 cells. Each cell must be at least one character wide and one
2409 character high, not counting its border lines. A cell can be
2410 subdivided into multiple rectangular cells, but cells cannot overlap.
2412 The table frame and cell border lines are made of three special
2413 characters. These variables specify those characters:
2416 @vindex table-cell-vertical-char
2417 @item table-cell-vertical-char
2418 Holds the character used for vertical lines. The default value is
2421 @vindex table-cell-horizontal-chars
2422 @item table-cell-horizontal-chars
2423 Holds the characters used for horizontal lines. The default value is
2426 @vindex table-cell-intersection-char
2427 @item table-cell-intersection-char
2428 Holds the character used at where horizontal line and vertical line
2429 meet. The default value is @samp{+}.
2433 Based on this definition, the following five tables are examples of invalid
2437 +-----+ +-----+ +--+ +-++--+ ++
2438 | | | | | | | || | ++
2439 | +-+ | | | | | | || |
2440 | | | | +--+ | +--+--+ +-++--+
2441 | +-+ | | | | | | | +-++--+
2442 | | | | | | | | | || |
2443 +-----+ +--+--+ +--+--+ +-++--+
2451 Overlapped cells or non-rectangular cells are not allowed.
2455 The border must be rectangular.
2457 Cells must have a minimum width/height of one character.
2462 @node Table Creation
2463 @subsection How to Create a Table?
2464 @cindex create a text-based table
2465 @cindex table creation
2467 @findex table-insert
2468 The command to create a table is @code{table-insert}. When called
2469 interactively, it asks for the number of columns, number of rows, cell
2470 width and cell height. The number of columns is the number of cells
2471 horizontally side by side. The number of rows is the number of cells
2472 vertically within the table's height. The cell width is a number of
2473 characters that each cell holds, left to right. The cell height is a
2474 number of lines each cell holds. The cell width and the cell height
2475 can be either an integer (when the value is constant across the table)
2476 or a series of integer, separated by spaces or commas, where each
2477 number corresponds to the next cell within a row from left to right,
2478 or the next cell within a column from top to bottom.
2480 @node Table Recognition
2481 @subsection Table Recognition
2482 @cindex table recognition
2484 @findex table-recognize
2485 @findex table-unrecognize
2486 Table mode maintains special text properties in the buffer to allow
2487 editing in a convenient fashion. When a buffer with tables is saved
2488 to its file, these text properties are lost, so when you visit this
2489 file again later, Emacs does not see a table, but just formatted text.
2490 To resurrect the table text properties, issue the @kbd{M-x
2491 table-recognize} command. It scans the current buffer, recognizes
2492 valid table cells, and attaches appropriate text properties to allow
2493 for table editing. The converse command, @code{table-unrecognize}, is
2494 used to remove the special text properties and convert the buffer back
2497 Special commands exist to enable or disable tables within a region,
2498 enable or disable individual tables, and enable/disable individual
2499 cells. These commands are:
2502 @findex table-recognize-region
2503 @item M-x table-recognize-region
2504 Recognize tables within the current region and activate them.
2505 @findex table-unrecognize-region
2506 @item M-x table-unrecognize-region
2507 Deactivate tables within the current region.
2508 @findex table-recognize-table
2509 @item M-x table-recognize-table
2510 Recognize the table at point and activate it.
2511 @findex table-unrecognize-table
2512 @item M-x table-unrecognize-table
2513 Deactivate the table at point.
2514 @findex table-recognize-cell
2515 @item M-x table-recognize-cell
2516 Recognize the cell at point and activate it.
2517 @findex table-unrecognize-cell
2518 @item M-x table-unrecognize-cell
2519 Deactivate the cell at point.
2522 For another way of converting text into tables, see @ref{Table
2526 @subsection Commands for Table Cells
2528 @findex table-forward-cell
2529 @findex table-backward-cell
2530 The commands @code{table-forward-cell} and
2531 @code{table-backward-cell} move point from the current cell to an
2532 adjacent cell forward and backward respectively. The order of the
2533 cells is cyclic: when point is in the last cell of a table, typing
2534 @kbd{M-x table-forward-cell} moves to the first cell in the table.
2535 Likewise @kbd{M-x table-backward-cell} from the first cell in a table
2536 moves to the last cell.
2538 @findex table-span-cell
2539 The command @code{table-span-cell} merges the current cell with the
2540 adjacent cell in a specified direction---right, left, above or below.
2541 You specify the direction with the minibuffer. It does not allow
2542 merges which don't result in a legitimate cell layout.
2544 @findex table-split-cell
2545 @cindex text-based tables, split a cell
2546 @cindex split table cell
2547 The command @code{table-split-cell} splits the current cell
2548 vertically or horizontally. This command is a wrapper to the
2549 direction specific commands @code{table-split-cell-vertically} and
2550 @code{table-split-cell-horizontally}. You specify the direction with
2551 a minibuffer argument.
2553 @findex table-split-cell-vertically
2554 The command @code{table-split-cell-vertically} splits the current
2555 cell vertically and creates a pair of cells above and below where
2556 point is located. The content in the original cell is split as well.
2558 @findex table-split-cell-horizontally
2559 The command @code{table-split-cell-horizontally} splits the current
2560 cell horizontally and creates a pair of cells right and left of where
2561 point is located. If the cell being split is not empty, this asks you
2562 how to handle the cell contents. The three options are: @code{split},
2563 @code{left}, or @code{right}. @code{split} splits the contents at
2564 point literally, while the @code{left} and @code{right} options move
2565 the entire contents into the left or right cell respectively.
2567 @cindex enlarge a table cell
2568 @cindex shrink a table cell
2569 The next four commands enlarge or shrink a cell. They use numeric
2570 arguments (@pxref{Arguments}) to specify how many columns or rows to
2571 enlarge or shrink a particular table.
2574 @findex table-heighten-cell
2575 @item M-x table-heighten-cell
2576 Enlarge the current cell vertically.
2577 @findex table-shorten-cell
2578 @item M-x table-shorten-cell
2579 Shrink the current cell vertically.
2580 @findex table-widen-cell
2581 @item M-x table-widen-cell
2582 Enlarge the current cell horizontally.
2583 @findex table-narrow-cell
2584 @item M-x table-narrow-cell
2585 Shrink the current cell horizontally.
2588 @node Cell Justification
2589 @subsection Cell Justification
2590 @cindex cell text justification
2592 You can specify text justification for each cell. The justification
2593 is remembered independently for each cell and the subsequent editing
2594 of cell contents is subject to the specified justification.
2596 @findex table-justify
2597 The command @code{table-justify} ask you to specify what to justify:
2598 a cell, a column, or a row. If you select cell justification, this
2599 command sets the justification only for the current cell. Selecting
2600 column or row justification sets the justification for all the cells
2601 within a column or row respectively. The command then ask you which
2602 kind of justification to apply: @code{left}, @code{center},
2603 @code{right}, @code{top}, @code{middle}, @code{bottom}, or
2604 @code{none}. Horizontal justification and vertical justification are
2605 specified independently. The options @code{left}, @code{center}, and
2606 @code{right} specify horizontal justification while the options
2607 @code{top}, @code{middle}, @code{bottom}, and @code{none} specify
2608 vertical justification. The vertical justification @code{none}
2609 effectively removes vertical justification. Horizontal justification
2610 must be one of @code{left}, @code{center}, or @code{right}.
2612 @vindex table-detect-cell-alignment
2613 Justification information is stored in the buffer as a part of text
2614 property. Therefore, this information is ephemeral and does not
2615 survive through the loss of the buffer (closing the buffer and
2616 revisiting the buffer erase any previous text properties). To
2617 countermand for this, the command @code{table-recognize} and other
2618 recognition commands (@pxref{Table Recognition}) are equipped with a
2619 convenience feature (turned on by default). During table recognition,
2620 the contents of a cell are examined to determine which justification
2621 was originally applied to the cell and then applies this justification
2622 to the cell. This is a speculative algorithm and is therefore not
2623 perfect, however, the justification is deduced correctly most of the
2624 time. To disable this feature, customize the variable
2625 @code{table-detect-cell-alignment} and set it to @code{nil}.
2628 @subsection Commands for Table Rows
2629 @cindex table row commands
2631 @cindex insert row in table
2632 @findex table-insert-row
2633 The command @code{table-insert-row} inserts a row of cells before
2634 the current row in a table. The current row where point is located is
2635 pushed down after the newly inserted row. A numeric prefix argument
2636 specifies the number of rows to insert. Note that in order to insert
2637 rows @emph{after} the last row at the bottom of a table, you must
2638 place point below the table---that is, outside the table---prior to
2639 invoking this command.
2641 @cindex delete row in table
2642 @findex table-delete-row
2643 The command @code{table-delete-row} deletes a row of cells at point.
2644 A numeric prefix argument specifies the number of rows to delete.
2646 @node Column Commands
2647 @subsection Commands for Table Columns
2648 @cindex table column commands
2650 @cindex insert column in table
2651 @findex table-insert-column
2652 The command @code{table-insert-column} inserts a column of cells to
2653 the left of the current row in a table. This pushes the current
2654 column to the right. To insert a column to the right side of the
2655 rightmost column, place point to the right of the rightmost column,
2656 which is outside of the table, prior to invoking this command. A
2657 numeric prefix argument specifies the number of columns to insert.
2659 @cindex delete column in table
2660 A command @code{table-delete-column} deletes a column of cells at
2661 point. A numeric prefix argument specifies the number of columns to
2664 @node Fixed Width Mode
2665 @subsection Fix Width of Cells
2666 @cindex fix width of table cells
2668 @findex table-fixed-width-mode
2669 The command @code{table-fixed-width-mode} toggles fixed width mode
2670 on and off. When fixed width mode is turned on, editing inside a
2671 cell never changes the cell width; when it is off, the cell width
2672 expands automatically in order to prevent a word from being folded
2673 into multiple lines. By default, fixed width mode is disabled.
2675 @node Table Conversion
2676 @subsection Conversion Between Plain Text and Tables
2677 @cindex text to table
2678 @cindex table to text
2680 @findex table-capture
2681 The command @code{table-capture} captures plain text in a region and
2682 turns it into a table. Unlike @code{table-recognize} (@pxref{Table
2683 Recognition}), the original text does not have a table appearance but
2684 may hold a logical table structure. For example, some elements
2685 separated by known patterns form a two dimensional structure which can
2686 be turned into a table.
2688 Here's an example of data that @code{table-capture} can operate on.
2689 The numbers are horizontally separated by a comma and vertically
2690 separated by a newline character.
2699 Invoking @kbd{M-x table-capture} on that text produces this table:
2702 +-----+-----+-----+-----+
2704 +-----+-----+-----+-----+
2706 +-----+-----+-----+-----+
2708 +-----+-----+-----+-----+
2712 The conversion uses @samp{,} for the column delimiter and newline for
2713 a row delimiter, cells are left justified, and minimum cell width is
2716 @findex table-release
2717 The command @code{table-release} does the opposite of
2718 @code{table-capture}. It releases a table by removing the table frame
2719 and cell borders. This leaves the table contents as plain text. One
2720 of the useful applications of @code{table-capture} and
2721 @code{table-release} is to edit a text in layout. Look at the
2722 following three paragraphs (the latter two are indented with header
2726 table-capture is a powerful command.
2727 Here are some things it can do:
2729 Parse Cell Items By using column delimiter regular
2730 expression and raw delimiter regular
2731 expression, it parses the specified text
2732 area and extracts cell items from
2733 non-table text and then forms a table out
2736 Capture Text Area When no delimiters are specified it
2737 creates a single cell table. The text in
2738 the specified region is placed in that
2743 Applying @code{table-capture} to a region containing the above three
2744 paragraphs, with empty strings for column delimiter regexp and row
2745 delimiter regexp, creates a table with a single cell like the
2748 @c The first line's right-hand frame in the following two examples
2749 @c sticks out to accommodate for the removal of @samp in the
2750 @c produced output!!
2753 +-------------------------------------------------------------+
2754 |table-capture is a powerful command. |
2755 |Here are some things it can do: |
2757 |Parse Cell Items By using column delimiter regular |
2758 | expression and raw delimiter regular |
2759 | expression, it parses the specified text |
2760 | area and extracts cell items from |
2761 | non-table text and then forms a table out |
2764 |Capture Text Area When no delimiters are specified it |
2765 | creates a single cell table. The text in |
2766 | the specified region is placed in that |
2768 +-------------------------------------------------------------+
2773 By splitting the cell appropriately we now have a table consisting of
2774 paragraphs occupying its own cell. Each cell can now be edited
2775 independently without affecting the layout of other cells.
2778 +--------------------------------------------------------------+
2779 |table-capture is a powerful command. |
2780 |Here are some things it can do: |
2781 +------------------+-------------------------------------------+
2782 |Parse Cell Items |By using column delimiter regular |
2783 | |expression and raw delimiter regular |
2784 | |expression, it parses the specified text |
2785 | |area and extracts cell items from |
2786 | |non-table text and then forms a table out |
2788 +------------------+-------------------------------------------+
2789 |Capture Text Area |When no delimiters are specified it |
2790 | |creates a single cell table. The text in |
2791 | |the specified region is placed in that |
2793 +------------------+-------------------------------------------+
2797 By applying @code{table-release}, which does the opposite process, the
2798 contents become once again plain text. @code{table-release} works as
2799 a companion command to @code{table-capture}.
2801 @node Measuring Tables
2802 @subsection Analyzing Table Dimensions
2803 @cindex table dimensions
2805 @findex table-query-dimension
2806 The command @code{table-query-dimension} analyzes a table structure
2807 and reports information regarding its dimensions. In case of the
2808 above example table, the @code{table-query-dimension} command displays
2812 Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
2816 This indicates that the current cell is 21 character wide and 6 lines
2817 high, the entire table is 67 characters wide and 16 lines high. The
2818 table has 2 columns and 3 rows. It has a total of 5 cells, since the
2819 first row has a spanned cell.
2822 @subsection Table Miscellany
2824 @cindex insert string into table cells
2825 @findex table-insert-sequence
2826 The command @code{table-insert-sequence} inserts a string into each
2827 cell. Each string is a part of a sequence i.e.@: a series of
2828 increasing integer numbers.
2830 @cindex table in language format
2831 @cindex table for HTML and LaTeX
2832 @findex table-generate-source
2833 The command @code{table-generate-source} generates a table formatted
2834 for a specific markup language. It asks for a language (which must be
2835 one of @code{html}, @code{latex}, or @code{cals}), a destination
2836 buffer where to put the result, and the table caption (a string), and
2837 then inserts the generated table in the proper syntax into the
2838 destination buffer. The default destination buffer is
2839 @code{table.@var{lang}}, where @var{lang} is the language you
2843 @section Two-Column Editing
2844 @cindex two-column editing
2845 @cindex splitting columns
2846 @cindex columns, splitting
2848 Two-column mode lets you conveniently edit two side-by-side columns of
2849 text. It uses two side-by-side windows, each showing its own
2852 There are three ways to enter two-column mode:
2855 @item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
2858 @findex 2C-two-columns
2859 Enter two-column mode with the current buffer on the left, and on the
2860 right, a buffer whose name is based on the current buffer's name
2861 (@code{2C-two-columns}). If the right-hand buffer doesn't already
2862 exist, it starts out empty; the current buffer's contents are not
2865 This command is appropriate when the current buffer is empty or contains
2866 just one column and you want to add another column.
2868 @item @kbd{@key{F2} s} or @kbd{C-x 6 s}
2872 Split the current buffer, which contains two-column text, into two
2873 buffers, and display them side by side (@code{2C-split}). The current
2874 buffer becomes the left-hand buffer, but the text in the right-hand
2875 column is moved into the right-hand buffer. The current column
2876 specifies the split point. Splitting starts with the current line and
2877 continues to the end of the buffer.
2879 This command is appropriate when you have a buffer that already contains
2880 two-column text, and you wish to separate the columns temporarily.
2882 @item @kbd{@key{F2} b @var{buffer} @key{RET}}
2883 @itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
2886 @findex 2C-associate-buffer
2887 Enter two-column mode using the current buffer as the left-hand buffer,
2888 and using buffer @var{buffer} as the right-hand buffer
2889 (@code{2C-associate-buffer}).
2892 @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
2893 is a string that appears on each line between the two columns. You can
2894 specify the width of the separator with a numeric argument to
2895 @kbd{@key{F2} s}; that many characters, before point, constitute the
2896 separator string. By default, the width is 1, so the column separator
2897 is the character before point.
2899 When a line has the separator at the proper place, @kbd{@key{F2} s}
2900 puts the text after the separator into the right-hand buffer, and
2901 deletes the separator. Lines that don't have the column separator at
2902 the proper place remain unsplit; they stay in the left-hand buffer, and
2903 the right-hand buffer gets an empty line to correspond. (This is the
2904 way to write a line that ``spans both columns while in two-column
2905 mode'': write it in the left-hand buffer, and put an empty line in the
2911 The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}}
2912 (@code{2C-newline}) inserts a newline in each of the two buffers at
2913 corresponding positions. This is the easiest way to add a new line to
2914 the two-column text while editing it in split buffers.
2919 When you have edited both buffers as you wish, merge them with
2920 @kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the
2921 text from the right-hand buffer as a second column in the other buffer.
2922 To go back to two-column editing, use @kbd{@key{F2} s}.
2926 @findex 2C-dissociate
2927 Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
2928 leaving each as it stands (@code{2C-dissociate}). If the other buffer,
2929 the one not current when you type @kbd{@key{F2} d}, is empty,
2930 @kbd{@key{F2} d} kills it.