1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001, 2002, 2004
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 The term @dfn{text} has two widespread meanings in our area of the
11 computer field. One is data that is a sequence of characters. Any file
12 that you edit with Emacs is text, in this sense of the word. The other
13 meaning is more restrictive: a sequence of characters in a human language
14 for humans to read (possibly after processing by a text formatter), as
15 opposed to a program or commands for a program.
17 Human languages have syntactic/stylistic conventions that can be
18 supported or used to advantage by editor commands: conventions involving
19 words, sentences, paragraphs, and capital letters. This chapter
20 describes Emacs commands for all of these things. There are also
21 commands for @dfn{filling}, which means rearranging the lines of a
22 paragraph to be approximately equal in length. The commands for moving
23 over and killing words, sentences and paragraphs, while intended
24 primarily for editing text, are also often useful for editing programs.
26 Emacs has several major modes for editing human-language text. If the
27 file contains text pure and simple, use Text mode, which customizes
28 Emacs in small ways for the syntactic conventions of text. Outline mode
29 provides special commands for operating on text with an outline
35 For text which contains embedded commands for text formatters, Emacs
36 has other major modes, each for a particular text formatter. Thus, for
37 input to @TeX{}, you would use @TeX{}
39 mode (@pxref{TeX Mode}).
44 For input to nroff, use Nroff mode.
46 Instead of using a text formatter, you can edit formatted text in
47 WYSIWYG style (``what you see is what you get''), with Enriched mode.
48 Then the formatting appears on the screen in Emacs while you edit.
50 @xref{Formatted Text}.
56 @cindex automatic typing
57 The ``automatic typing'' features may be useful when writing text.
58 @inforef{Top,, autotype}.
61 * Words:: Moving over and killing words.
62 * Sentences:: Moving over and killing sentences.
63 * Paragraphs:: Moving over paragraphs.
64 * Pages:: Moving over pages.
65 * Filling:: Filling or justifying text.
66 * Case:: Changing the case of text.
67 * Text Mode:: The major modes for editing text files.
68 * Outline Mode:: Editing outlines.
69 * TeX Mode:: Editing input to the formatter TeX.
70 * HTML Mode:: Editing HTML, SGML, and XML files.
71 * Nroff Mode:: Editing input to the formatter nroff.
72 * Formatted Text:: Editing formatted text directly in WYSIWYG fashion.
78 @cindex Meta commands and words
80 Emacs has commands for moving over or operating on words. By convention,
81 the keys for them are all Meta characters.
85 Move forward over a word (@code{forward-word}).
87 Move backward over a word (@code{backward-word}).
89 Kill up to the end of a word (@code{kill-word}).
91 Kill back to the beginning of a word (@code{backward-kill-word}).
93 Mark the end of the next word (@code{mark-word}).
95 Transpose two words or drag a word across other words
96 (@code{transpose-words}).
99 Notice how these keys form a series that parallels the character-based
100 @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is
101 cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
106 @findex backward-word
107 The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b}
108 (@code{backward-word}) move forward and backward over words. These
109 Meta characters are thus analogous to the corresponding control
110 characters, @kbd{C-f} and @kbd{C-b}, which move over single characters
111 in the text. The analogy extends to numeric arguments, which serve as
112 repeat counts. @kbd{M-f} with a negative argument moves backward, and
113 @kbd{M-b} with a negative argument moves forward. Forward motion
114 stops right after the last letter of the word, while backward motion
115 stops right before the first letter.@refill
119 @kbd{M-d} (@code{kill-word}) kills the word after point. To be
120 precise, it kills everything from point to the place @kbd{M-f} would
121 move to. Thus, if point is in the middle of a word, @kbd{M-d} kills
122 just the part after point. If some punctuation comes between point and the
123 next word, it is killed along with the word. (If you wish to kill only the
124 next word but not the punctuation before it, simply do @kbd{M-f} to get
125 the end, and kill the word backwards with @kbd{M-@key{DEL}}.)
126 @kbd{M-d} takes arguments just like @kbd{M-f}.
128 @findex backward-kill-word
130 @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
131 point. It kills everything from point back to where @kbd{M-b} would
132 move to. If point is after the space in @w{@samp{FOO, BAR}}, then
133 @w{@samp{FOO, }} is killed. (If you wish to kill just @samp{FOO}, and
134 not the comma and the space, use @kbd{M-b M-d} instead of
137 @c Don't index M-t and transpose-words here, they are indexed in
138 @c fixit.texi, in the node "Transpose".
140 @c @findex transpose-words
141 @kbd{M-t} (@code{transpose-words}) exchanges the word before or
142 containing point with the following word. The delimiter characters between
143 the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
144 @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
145 more on transposition and on arguments to transposition commands.
149 To operate on the next @var{n} words with an operation which applies
150 between point and mark, you can either set the mark at point and then move
151 over the words, or you can use the command @kbd{M-@@} (@code{mark-word})
152 which does not move point, but sets the mark where @kbd{M-f} would move
153 to. @kbd{M-@@} accepts a numeric argument that says how many words to
154 scan for the place to put the mark. In Transient Mark mode, this command
157 The word commands' understanding of syntax is completely controlled by
158 the syntax table. Any character can, for example, be declared to be a word
159 delimiter. @xref{Syntax}.
164 @cindex manipulating sentences
166 The Emacs commands for manipulating sentences and paragraphs are mostly
167 on Meta keys, so as to be like the word-handling commands.
171 Move back to the beginning of the sentence (@code{backward-sentence}).
173 Move forward to the end of the sentence (@code{forward-sentence}).
175 Kill forward to the end of the sentence (@code{kill-sentence}).
177 Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
182 @findex backward-sentence
183 @findex forward-sentence
184 The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and
185 @code{forward-sentence}) move to the beginning and end of the current
186 sentence, respectively. They were chosen to resemble @kbd{C-a} and
187 @kbd{C-e}, which move to the beginning and end of a line. Unlike them,
188 @kbd{M-a} and @kbd{M-e} if repeated or given numeric arguments move over
189 successive sentences.
191 Moving backward over a sentence places point just before the first
192 character of the sentence; moving forward places point right after the
193 punctuation that ends the sentence. Neither one moves over the
194 whitespace at the sentence boundary.
198 @findex kill-sentence
199 @findex backward-kill-sentence
200 Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
201 with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
202 @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of
203 the sentence. With minus one as an argument it kills back to the
204 beginning of the sentence. Larger arguments serve as a repeat count.
205 There is also a command, @kbd{C-x @key{DEL}}
206 (@code{backward-kill-sentence}), for killing back to the beginning of a
207 sentence. This command is useful when you change your mind in the
208 middle of composing text.@refill
210 The sentence commands assume that you follow the American typist's
211 convention of putting two spaces at the end of a sentence; they consider
212 a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!}
213 followed by the end of a line or two spaces, with any number of
214 @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between.
215 A sentence also begins or ends wherever a paragraph begins or ends.
218 The variable @code{sentence-end} controls recognition of the end of
219 a sentence. If non-@code{nil}, it is a regexp that matches the last
220 few characters of a sentence, together with the whitespace following
221 the sentence. If the value is @code{nil}, the default, then Emacs
222 computes the regexp according to various criteria. The result is
223 normally similar to the following regexp:
226 "[.?!][]\"')]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
230 This example is explained in the section on regexps. @xref{Regexps}.
232 If you want to use just one space between sentences, you should
233 set @code{sentence-end} to this value:
236 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
240 You should also set the variable @code{sentence-end-double-space} to
241 @code{nil} so that the fill commands expect and leave just one space at
242 the end of a sentence. Note that this makes it impossible to
243 distinguish between periods that end sentences and those that indicate
249 @cindex manipulating paragraphs
252 @findex backward-paragraph
253 @findex forward-paragraph
255 The Emacs commands for manipulating paragraphs are also Meta keys.
259 Move back to previous paragraph beginning (@code{backward-paragraph}).
261 Move forward to next paragraph end (@code{forward-paragraph}).
263 Put point and mark around this or next paragraph (@code{mark-paragraph}).
266 @kbd{M-@{} moves to the beginning of the current or previous
267 paragraph, while @kbd{M-@}} moves to the end of the current or next
268 paragraph. Blank lines and text-formatter command lines separate
269 paragraphs and are not considered part of any paragraph. In Indented
270 Text mode, but not in Text mode, an indented line also starts a new
271 paragraph. (If a paragraph is preceded by a blank line, these
272 commands treat that blank line as the beginning of the paragraph.)
274 In major modes for programs, paragraphs begin and end only at blank
275 lines. This makes the paragraph commands continue to be useful even
276 though there are no paragraphs per se.
278 When there is a fill prefix, then paragraphs are delimited by all lines
279 which don't start with the fill prefix. @xref{Filling}.
282 @findex mark-paragraph
283 When you wish to operate on a paragraph, you can use the command
284 @kbd{M-h} (@code{mark-paragraph}) to set the region around it. Thus,
285 for example, @kbd{M-h C-w} kills the paragraph around or after point.
286 The @kbd{M-h} command puts point at the beginning and mark at the end of
287 the paragraph point was in. In Transient Mark mode, it activates the
288 mark. If point is between paragraphs (in a run of blank lines, or at a
289 boundary), the paragraph following point is surrounded by point and
290 mark. If there are blank lines preceding the first line of the
291 paragraph, one of these blank lines is included in the region.
293 @vindex paragraph-start
294 @vindex paragraph-separate
295 The precise definition of a paragraph boundary is controlled by the
296 variables @code{paragraph-separate} and @code{paragraph-start}. The
297 value of @code{paragraph-start} is a regexp that should match any line
298 that either starts or separates paragraphs. The value of
299 @code{paragraph-separate} is another regexp that should match only lines
300 that separate paragraphs without being part of any paragraph (for
301 example, blank lines). Lines that start a new paragraph and are
302 contained in it must match only @code{paragraph-start}, not
303 @code{paragraph-separate}. Each regular expression must match at the
304 left margin. For example, in Fundamental mode, @code{paragraph-start}
305 is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is
306 @w{@code{"[ \t\f]*$"}}.
308 Normally it is desirable for page boundaries to separate paragraphs.
309 The default values of these variables recognize the usual separator for
317 Files are often thought of as divided into @dfn{pages} by the
318 @dfn{formfeed} character (@acronym{ASCII} control-L, octal code 014).
319 When you print hardcopy for a file, this character forces a page break;
320 thus, each page of the file goes on a separate page on paper. Most Emacs
321 commands treat the page-separator character just like any other
322 character: you can insert it with @kbd{C-q C-l}, and delete it with
323 @key{DEL}. Thus, you are free to paginate your file or not. However,
324 since pages are often meaningful divisions of the file, Emacs provides
325 commands to move over them and operate on them.
329 Move point to previous page boundary (@code{backward-page}).
331 Move point to next page boundary (@code{forward-page}).
333 Put point and mark around this page (or another page) (@code{mark-page}).
335 Count the lines in this page (@code{count-lines-page}).
341 @findex backward-page
342 The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
343 after the previous page delimiter. If point is already right after a page
344 delimiter, it skips that one and stops at the previous one. A numeric
345 argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
346 command moves forward past the next page delimiter.
350 The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
351 beginning of the current page and the mark at the end. The page
352 delimiter at the end is included (the mark follows it). The page
353 delimiter at the front is excluded (point follows it). In Transient
354 Mark mode, this command activates the mark.
356 @kbd{C-x C-p C-w} is a handy way to kill a page to move it
357 elsewhere. If you move to another page delimiter with @kbd{C-x [} and
358 @kbd{C-x ]}, then yank the killed page, all the pages will be properly
359 delimited once again. The reason @kbd{C-x C-p} includes only the
360 following page delimiter in the region is to ensure that.
362 A numeric argument to @kbd{C-x C-p} is used to specify which page to go
363 to, relative to the current one. Zero means the current page. One means
364 the next page, and @minus{}1 means the previous one.
367 @findex count-lines-page
368 The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
369 where to break a page in two. It displays in the echo area the total number
370 of lines in the current page, and then divides it up into those preceding
371 the current line and those following, as in
374 Page has 96 (72+25) lines
378 Notice that the sum is off by one; this is correct if point is not at the
381 @vindex page-delimiter
382 The variable @code{page-delimiter} controls where pages begin. Its
383 value is a regexp that matches the beginning of a line that separates
384 pages. The normal value of this variable is @code{"^\f"}, which
385 matches a formfeed character at the beginning of a line.
388 @section Filling Text
391 @dfn{Filling} text means breaking it up into lines that fit a
392 specified width. Emacs does filling in two ways. In Auto Fill mode,
393 inserting text with self-inserting characters also automatically fills
394 it. There are also explicit fill commands that you can use when editing
395 text leaves it unfilled. When you edit formatted text, you can specify
396 a style of filling for each portion of the text (@pxref{Formatted
400 * Auto Fill:: Auto Fill mode breaks long lines automatically.
401 * Refill:: Keeping paragraphs filled.
402 * Fill Commands:: Commands to refill paragraphs and center lines.
403 * Fill Prefix:: Filling paragraphs that are indented
404 or in a comment, etc.
405 * Adaptive Fill:: How Emacs can determine the fill prefix automatically.
409 @subsection Auto Fill Mode
410 @cindex Auto Fill mode
411 @cindex mode, Auto Fill
414 @dfn{Auto Fill} mode is a minor mode in which lines are broken
415 automatically when they become too wide. Breaking happens only when
416 you type a @key{SPC} or @key{RET}.
419 @item M-x auto-fill-mode
420 Enable or disable Auto Fill mode.
423 In Auto Fill mode, break lines when appropriate.
426 @findex auto-fill-mode
427 @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off
428 if it was on. With a positive numeric argument it always turns Auto
429 Fill mode on, and with a negative argument always turns it off. You can
430 see when Auto Fill mode is in effect by the presence of the word
431 @samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is
432 a minor mode which is enabled or disabled for each buffer individually.
435 In Auto Fill mode, lines are broken automatically at spaces when they
436 get longer than the desired width. Line breaking and rearrangement
437 takes place only when you type @key{SPC} or @key{RET}. If you wish to
438 insert a space or newline without permitting line-breaking, type
439 @kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a
440 control-J). Also, @kbd{C-o} inserts a newline without line breaking.
442 Auto Fill mode works well with programming-language modes, because it
443 indents new lines with @key{TAB}. If a line ending in a comment gets
444 too long, the text of the comment is split into two comment lines.
445 Optionally, new comment delimiters are inserted at the end of the first
446 line and the beginning of the second so that each line is a separate
447 comment; the variable @code{comment-multi-line} controls the choice
450 Adaptive filling (@pxref{Adaptive Fill}) works for Auto Filling as
451 well as for explicit fill commands. It takes a fill prefix
452 automatically from the second or first line of a paragraph.
454 Auto Fill mode does not refill entire paragraphs; it can break lines but
455 cannot merge lines. So editing in the middle of a paragraph can result in
456 a paragraph that is not correctly filled. The easiest way to make the
457 paragraph properly filled again is usually with the explicit fill commands.
459 @xref{Fill Commands}.
462 Many users like Auto Fill mode and want to use it in all text files.
463 The section on init files says how to arrange this permanently for yourself.
467 @subsection Refill Mode
468 @cindex refilling text, word processor style
469 @cindex modes, Refill
470 @cindex Refill minor mode
472 Refill minor mode provides support for keeping paragraphs filled as
473 you type or modify them in other ways. It provides an effect similar
474 to typical word processor behavior. This works by running a
475 paragraph-filling command at suitable times.
477 When you are typing text, only characters which normally trigger
478 auto filling, like the space character, will trigger refilling. This
479 is to avoid making it too slow. Apart from self-inserting characters,
480 other commands which modify the text cause refilling.
482 The current implementation is preliminary and probably not robust.
483 We expect to improve on it.
485 To toggle the use of Refill mode in the current buffer, type
486 @kbd{M-x refill-mode}.
489 @subsection Explicit Fill Commands
493 Fill current paragraph (@code{fill-paragraph}).
495 Set the fill column (@code{set-fill-column}).
496 @item M-x fill-region
497 Fill each paragraph in the region (@code{fill-region}).
498 @item M-x fill-region-as-paragraph
499 Fill the region, considering it as one paragraph.
505 @findex fill-paragraph
506 To refill a paragraph, use the command @kbd{M-q}
507 (@code{fill-paragraph}). This operates on the paragraph that point is
508 inside, or the one after point if point is between paragraphs.
509 Refilling works by removing all the line-breaks, then inserting new ones
513 To refill many paragraphs, use @kbd{M-x fill-region}, which
514 divides the region into paragraphs and fills each of them.
516 @findex fill-region-as-paragraph
517 @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h}
518 for finding paragraph boundaries (@pxref{Paragraphs}). For more
519 control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
520 everything between point and mark. This command deletes any blank lines
521 within the region, so separate blocks of text end up combined into one
524 @cindex justification
525 A numeric argument to @kbd{M-q} causes it to @dfn{justify} the text as
526 well as filling it. This means that extra spaces are inserted to make
527 the right margin line up exactly at the fill column. To remove the
528 extra spaces, use @kbd{M-q} with no argument. (Likewise for
529 @code{fill-region}.) Another way to control justification, and choose
530 other styles of filling, is with the @code{justification} text property;
531 see @ref{Format Justification}.
533 @kindex M-s @r{(Text mode)}
536 The command @kbd{M-s} (@code{center-line}) centers the current line
537 within the current fill column. With an argument @var{n}, it centers
538 @var{n} lines individually and moves past them. This binding is
539 made by Text mode and is available only in that and related modes
544 @findex set-fill-column
545 The maximum line width for filling is in the variable
546 @code{fill-column}. Altering the value of @code{fill-column} makes it
547 local to the current buffer; until that time, the default value is in
548 effect. The default is initially 70. @xref{Locals}. The easiest way
549 to set @code{fill-column} is to use the command @kbd{C-x f}
550 (@code{set-fill-column}). With a numeric argument, it uses that as the
551 new fill column. With just @kbd{C-u} as argument, it sets
552 @code{fill-column} to the current horizontal position of point.
554 Emacs commands normally consider a period followed by two spaces or by
555 a newline as the end of a sentence; a period followed by just one space
556 indicates an abbreviation and not the end of a sentence. To preserve
557 the distinction between these two ways of using a period, the fill
558 commands do not break a line after a period followed by just one space.
560 @vindex sentence-end-double-space
561 If the variable @code{sentence-end-double-space} is @code{nil}, the
562 fill commands expect and leave just one space at the end of a sentence.
563 Ordinarily this variable is @code{t}, so the fill commands insist on
564 two spaces for the end of a sentence, as explained above. @xref{Sentences}.
566 @vindex colon-double-space
567 If the variable @code{colon-double-space} is non-@code{nil}, the
568 fill commands put two spaces after a colon.
570 @vindex sentence-end-without-period
571 Some languages do not use period to indicate end of sentence. For
572 example, a sentence in Thai text ends with double space but without a
573 period. Set the variable @code{sentence-end-without-period} to
574 @code{t} to tell the sentence commands that a period is not necessary.
576 @vindex fill-nobreak-predicate
577 The variable @code{fill-nobreak-predicate} specifies additional
578 conditions for where line-breaking is allowed. Its value is either
579 @code{nil} or a Lisp function; the function is called with no
580 arguments, and if it returns a non-@code{nil} value, then point is not
581 a good place to break the line. Two standard functions you can use are
582 @code{fill-single-word-nobreak-p} (don't break after the first word of
583 a sentence or before the last) and @code{fill-french-nobreak-p} (don't
584 break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}).
587 @subsection The Fill Prefix
590 To fill a paragraph in which each line starts with a special marker
591 (which might be a few spaces, giving an indented paragraph), you can use
592 the @dfn{fill prefix} feature. The fill prefix is a string that Emacs
593 expects every line to start with, and which is not included in filling.
594 You can specify a fill prefix explicitly; Emacs can also deduce the
595 fill prefix automatically (@pxref{Adaptive Fill}).
599 Set the fill prefix (@code{set-fill-prefix}).
601 Fill a paragraph using current fill prefix (@code{fill-paragraph}).
602 @item M-x fill-individual-paragraphs
603 Fill the region, considering each change of indentation as starting a
605 @item M-x fill-nonuniform-paragraphs
606 Fill the region, considering only paragraph-separator lines as starting
611 @findex set-fill-prefix
612 To specify a fill prefix for the current buffer, move to a line that
613 starts with the desired prefix, put point at the end of the prefix,
614 and give the command @w{@kbd{C-x .}}@: (@code{set-fill-prefix}).
615 That's a period after the @kbd{C-x}. To turn off the fill prefix,
616 specify an empty prefix: type @w{@kbd{C-x .}}@: with point at the
617 beginning of a line.@refill
619 When a fill prefix is in effect, the fill commands remove the fill
620 prefix from each line before filling and insert it on each line after
621 filling. Auto Fill mode also inserts the fill prefix automatically when
622 it makes a new line. The @kbd{C-o} command inserts the fill prefix on
623 new lines it creates, when you use it at the beginning of a line
624 (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes the
625 prefix (if it occurs) after the newline that it deletes
626 (@pxref{Indentation}).
628 For example, if @code{fill-column} is 40 and you set the fill prefix
629 to @samp{;; }, then @kbd{M-q} in the following text
633 ;; example of a paragraph
634 ;; inside a Lisp-style comment.
641 ;; This is an example of a paragraph
642 ;; inside a Lisp-style comment.
645 Lines that do not start with the fill prefix are considered to start
646 paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
647 good results for paragraphs with hanging indentation (every line
648 indented except the first one). Lines which are blank or indented once
649 the prefix is removed also separate or start paragraphs; this is what
650 you want if you are writing multi-paragraph comments with a comment
651 delimiter on each line.
653 @findex fill-individual-paragraphs
654 You can use @kbd{M-x fill-individual-paragraphs} to set the fill
655 prefix for each paragraph automatically. This command divides the
656 region into paragraphs, treating every change in the amount of
657 indentation as the start of a new paragraph, and fills each of these
658 paragraphs. Thus, all the lines in one ``paragraph'' have the same
659 amount of indentation. That indentation serves as the fill prefix for
662 @findex fill-nonuniform-paragraphs
663 @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
664 the region into paragraphs in a different way. It considers only
665 paragraph-separating lines (as defined by @code{paragraph-separate}) as
666 starting a new paragraph. Since this means that the lines of one
667 paragraph may have different amounts of indentation, the fill prefix
668 used is the smallest amount of indentation of any of the lines of the
669 paragraph. This gives good results with styles that indent a paragraph's
670 first line more or less that the rest of the paragraph.
673 The fill prefix is stored in the variable @code{fill-prefix}. Its value
674 is a string, or @code{nil} when there is no fill prefix. This is a
675 per-buffer variable; altering the variable affects only the current buffer,
676 but there is a default value which you can change as well. @xref{Locals}.
678 The @code{indentation} text property provides another way to control
679 the amount of indentation paragraphs receive. @xref{Format Indentation}.
682 @subsection Adaptive Filling
684 @cindex adaptive filling
685 The fill commands can deduce the proper fill prefix for a paragraph
686 automatically in certain cases: either whitespace or certain punctuation
687 characters at the beginning of a line are propagated to all lines of the
690 If the paragraph has two or more lines, the fill prefix is taken from
691 the paragraph's second line, but only if it appears on the first line as
694 If a paragraph has just one line, fill commands @emph{may} take a
695 prefix from that line. The decision is complicated because there are
696 three reasonable things to do in such a case:
700 Use the first line's prefix on all the lines of the paragraph.
703 Indent subsequent lines with whitespace, so that they line up under the
704 text that follows the prefix on the first line, but don't actually copy
705 the prefix from the first line.
708 Don't do anything special with the second and following lines.
711 All three of these styles of formatting are commonly used. So the
712 fill commands try to determine what you would like, based on the prefix
713 that appears and on the major mode. Here is how.
715 @vindex adaptive-fill-first-line-regexp
716 If the prefix found on the first line matches
717 @code{adaptive-fill-first-line-regexp}, or if it appears to be a
718 comment-starting sequence (this depends on the major mode), then the
719 prefix found is used for filling the paragraph, provided it would not
720 act as a paragraph starter on subsequent lines.
722 Otherwise, the prefix found is converted to an equivalent number of
723 spaces, and those spaces are used as the fill prefix for the rest of the
724 lines, provided they would not act as a paragraph starter on subsequent
727 In Text mode, and other modes where only blank lines and page
728 delimiters separate paragraphs, the prefix chosen by adaptive filling
729 never acts as a paragraph starter, so it can always be used for filling.
731 @vindex adaptive-fill-mode
732 @vindex adaptive-fill-regexp
733 The variable @code{adaptive-fill-regexp} determines what kinds of line
734 beginnings can serve as a fill prefix: any characters at the start of
735 the line that match this regular expression are used. If you set the
736 variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
737 never chosen automatically.
739 @vindex adaptive-fill-function
740 You can specify more complex ways of choosing a fill prefix
741 automatically by setting the variable @code{adaptive-fill-function} to a
742 function. This function is called with point after the left margin of a
743 line, and it should return the appropriate fill prefix based on that
744 line. If it returns @code{nil}, that means it sees no fill prefix in
748 @section Case Conversion Commands
749 @cindex case conversion
751 Emacs has commands for converting either a single word or any arbitrary
752 range of text to upper case or to lower case.
756 Convert following word to lower case (@code{downcase-word}).
758 Convert following word to upper case (@code{upcase-word}).
760 Capitalize the following word (@code{capitalize-word}).
762 Convert region to lower case (@code{downcase-region}).
764 Convert region to upper case (@code{upcase-region}).
770 @cindex words, case conversion
771 @cindex converting text to upper or lower case
772 @cindex capitalizing words
773 @findex downcase-word
775 @findex capitalize-word
776 The word conversion commands are the most useful. @kbd{M-l}
777 (@code{downcase-word}) converts the word after point to lower case, moving
778 past it. Thus, repeating @kbd{M-l} converts successive words.
779 @kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while
780 @kbd{M-c} (@code{capitalize-word}) puts the first letter of the word
781 into upper case and the rest into lower case. All these commands convert
782 several words at once if given an argument. They are especially convenient
783 for converting a large amount of text from all upper case to mixed case,
784 because you can move through the text using @kbd{M-l}, @kbd{M-u} or
785 @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
788 When given a negative argument, the word case conversion commands apply
789 to the appropriate number of words before point, but do not move point.
790 This is convenient when you have just typed a word in the wrong case: you
791 can give the case conversion command and continue typing.
793 If a word case conversion command is given in the middle of a word, it
794 applies only to the part of the word which follows point. This is just
795 like what @kbd{M-d} (@code{kill-word}) does. With a negative argument,
796 case conversion applies only to the part of the word before point.
800 @findex downcase-region
801 @findex upcase-region
802 The other case conversion commands are @kbd{C-x C-u}
803 (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
804 convert everything between point and mark to the specified case. Point and
807 The region case conversion commands @code{upcase-region} and
808 @code{downcase-region} are normally disabled. This means that they ask
809 for confirmation if you try to use them. When you confirm, you may
810 enable the command, which means it will not ask for confirmation again.
819 When you edit files of text in a human language, it's more convenient
820 to use Text mode rather than Fundamental mode. To enter Text mode, type
823 In Text mode, only blank lines and page delimiters separate
824 paragraphs. As a result, paragraphs can be indented, and adaptive
825 filling determines what indentation to use when filling a paragraph.
826 @xref{Adaptive Fill}.
828 @kindex TAB @r{(Text mode)}
829 Text mode defines @key{TAB} to run @code{indent-relative}
830 (@pxref{Indentation}), so that you can conveniently indent a line like
833 Text mode turns off the features concerned with comments except when
834 you explicitly invoke them. It changes the syntax table so that
835 single-quotes are considered part of words. However, if a word starts
836 with single-quotes, then these are treated as a prefix for purposes
837 such as capitalization. That is, @kbd{M-c} will convert
838 @samp{'hello'} into @samp{'Hello'}, as expected.
840 @cindex Paragraph-Indent Text mode
841 @cindex mode, Paragraph-Indent Text
842 @findex paragraph-indent-text-mode
843 @findex paragraph-indent-minor-mode
844 If you indent the first lines of paragraphs, then you should use
845 Paragraph-Indent Text mode rather than Text mode. In this mode, you do
846 not need to have blank lines between paragraphs, because the first-line
847 indentation is sufficient to start a paragraph; however paragraphs in
848 which every line is indented are not supported. Use @kbd{M-x
849 paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x
850 paragraph-indent-minor-mode} to enter an equivalent minor mode, for
851 instance during mail composition.
853 @kindex M-TAB @r{(Text mode)}
854 Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} as
855 the command @code{ispell-complete-word}, which performs completion of
856 the partial word in the buffer before point, using the spelling
857 dictionary as the space of possible words. @xref{Spelling}.
859 @vindex text-mode-hook
860 Entering Text mode runs the hook @code{text-mode-hook}. Other major
861 modes related to Text mode also run this hook, followed by hooks of
862 their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{}
863 mode, Outline mode, and Mail mode. Hook functions on
864 @code{text-mode-hook} can look at the value of @code{major-mode} to see
865 which of these modes is actually being entered. @xref{Hooks}.
868 Emacs provides two other modes for editing text that is to be passed
869 through a text formatter to produce fancy formatted printed output.
870 @xref{Nroff Mode}, for editing input to the formatter nroff.
871 @xref{TeX Mode}, for editing input to the formatter TeX.
873 Another mode is used for editing outlines. It allows you to view the
874 text at various levels of detail. You can view either the outline
875 headings alone or both headings and text; you can also hide some of the
876 headings at lower levels from view to make the high level structure more
877 visible. @xref{Outline Mode}.
881 @section Outline Mode
883 @cindex mode, Outline
884 @cindex invisible lines
887 @findex outline-minor-mode
888 @vindex outline-minor-mode-prefix
889 Outline mode is a major mode much like Text mode but intended for
890 editing outlines. It allows you to make parts of the text temporarily
891 invisible so that you can see the outline structure. Type @kbd{M-x
892 outline-mode} to switch to Outline mode as the major mode of the current
895 When Outline mode makes a line invisible, the line does not appear on
896 the screen. The screen appears exactly as if the invisible line were
897 deleted, except that an ellipsis (three periods in a row) appears at the
898 end of the previous visible line (only one ellipsis no matter how many
899 invisible lines follow).
901 Editing commands that operate on lines, such as @kbd{C-n} and
902 @kbd{C-p}, treat the text of the invisible line as part of the previous
903 visible line. Killing the ellipsis at the end of a visible line
904 really kills all the following invisible lines.
906 Outline minor mode provides the same commands as the major mode,
907 Outline mode, but you can use it in conjunction with other major modes.
908 Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in
909 the current buffer. You can also specify this in the text of a file,
910 with a file local variable of the form @samp{mode: outline-minor}
911 (@pxref{File Variables}).
913 @kindex C-c @@ @r{(Outline minor mode)}
914 The major mode, Outline mode, provides special key bindings on the
915 @kbd{C-c} prefix. Outline minor mode provides similar bindings with
916 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
917 major mode's special commands. (The variable
918 @code{outline-minor-mode-prefix} controls the prefix used.)
920 @vindex outline-mode-hook
921 Entering Outline mode runs the hook @code{text-mode-hook} followed by
922 the hook @code{outline-mode-hook} (@pxref{Hooks}).
925 * Format: Outline Format. What the text of an outline looks like.
926 * Motion: Outline Motion. Special commands for moving through
928 * Visibility: Outline Visibility. Commands to control what is visible.
929 * Views: Outline Views. Outlines and multiple views.
930 * Foldout:: Folding editing.
934 @subsection Format of Outlines
936 @cindex heading lines (Outline mode)
937 @cindex body lines (Outline mode)
938 Outline mode assumes that the lines in the buffer are of two types:
939 @dfn{heading lines} and @dfn{body lines}. A heading line represents a
940 topic in the outline. Heading lines start with one or more stars; the
941 number of stars determines the depth of the heading in the outline
942 structure. Thus, a heading line with one star is a major topic; all the
943 heading lines with two stars between it and the next one-star heading
944 are its subtopics; and so on. Any line that is not a heading line is a
945 body line. Body lines belong with the preceding heading line. Here is
951 which says something about the topic of food.
954 This is the body of the second-level header.
964 Another first-level topic with its header line.
967 A heading line together with all following body lines is called
968 collectively an @dfn{entry}. A heading line together with all following
969 deeper heading lines and their body lines is called a @dfn{subtree}.
971 @vindex outline-regexp
972 You can customize the criterion for distinguishing heading lines
973 by setting the variable @code{outline-regexp}. Any line whose
974 beginning has a match for this regexp is considered a heading line.
975 Matches that start within a line (not at the left margin) do not count.
976 The length of the matching text determines the level of the heading;
977 longer matches make a more deeply nested level. Thus, for example,
978 if a text formatter has commands @samp{@@chapter}, @samp{@@section}
979 and @samp{@@subsection} to divide the document into chapters and
980 sections, you could make those lines count as heading lines by
981 setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}.
982 Note the trick: the two words @samp{chapter} and @samp{section} are equally
983 long, but by defining the regexp to match only @samp{chap} we ensure
984 that the length of the text matched on a chapter heading is shorter,
985 so that Outline mode will know that sections are contained in chapters.
986 This works as long as no other command starts with @samp{@@chap}.
988 @vindex outline-level
989 You can change the rule for calculating the level of a heading line
990 by setting the variable @code{outline-level}. The value of
991 @code{outline-level} should be a function that takes no arguments and
992 returns the level of the current heading. Some major modes such as C,
993 Nroff, and Emacs Lisp mode set this variable and @code{outline-regexp}
994 in order to work with Outline minor mode.
997 @subsection Outline Motion Commands
999 Outline mode provides special motion commands that move backward and
1000 forward to heading lines.
1004 Move point to the next visible heading line
1005 (@code{outline-next-visible-heading}).
1007 Move point to the previous visible heading line
1008 (@code{outline-previous-visible-heading}).
1010 Move point to the next visible heading line at the same level
1011 as the one point is on (@code{outline-forward-same-level}).
1013 Move point to the previous visible heading line at the same level
1014 (@code{outline-backward-same-level}).
1016 Move point up to a lower-level (more inclusive) visible heading line
1017 (@code{outline-up-heading}).
1020 @findex outline-next-visible-heading
1021 @findex outline-previous-visible-heading
1022 @kindex C-c C-n @r{(Outline mode)}
1023 @kindex C-c C-p @r{(Outline mode)}
1024 @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next
1025 heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves
1026 similarly backward. Both accept numeric arguments as repeat counts. The
1027 names emphasize that invisible headings are skipped, but this is not really
1028 a special feature. All editing commands that look for lines ignore the
1029 invisible lines automatically.@refill
1031 @findex outline-up-heading
1032 @findex outline-forward-same-level
1033 @findex outline-backward-same-level
1034 @kindex C-c C-f @r{(Outline mode)}
1035 @kindex C-c C-b @r{(Outline mode)}
1036 @kindex C-c C-u @r{(Outline mode)}
1037 More powerful motion commands understand the level structure of headings.
1038 @kbd{C-c C-f} (@code{outline-forward-same-level}) and
1039 @kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
1040 heading line to another visible heading at the same depth in
1041 the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves
1042 backward to another heading that is less deeply nested.
1044 @node Outline Visibility
1045 @subsection Outline Visibility Commands
1047 The other special commands of outline mode are used to make lines visible
1048 or invisible. Their names all start with @code{hide} or @code{show}.
1049 Most of them fall into pairs of opposites. They are not undoable; instead,
1050 you can undo right past them. Making lines visible or invisible is simply
1051 not recorded by the undo mechanism.
1055 Make all body lines in the buffer invisible (@code{hide-body}).
1057 Make all lines in the buffer visible (@code{show-all}).
1059 Make everything under this heading invisible, not including this
1060 heading itself (@code{hide-subtree}).
1062 Make everything under this heading visible, including body,
1063 subheadings, and their bodies (@code{show-subtree}).
1065 Make the body of this heading line, and of all its subheadings,
1066 invisible (@code{hide-leaves}).
1068 Make all subheadings of this heading line, at all levels, visible
1069 (@code{show-branches}).
1071 Make immediate subheadings (one level down) of this heading line
1072 visible (@code{show-children}).
1074 Make this heading line's body invisible (@code{hide-entry}).
1076 Make this heading line's body visible (@code{show-entry}).
1078 Hide everything except the top @var{n} levels of heading lines
1079 (@code{hide-sublevels}).
1081 Hide everything except for the heading or body that point is in, plus
1082 the headings leading up from there to the top level of the outline
1083 (@code{hide-other}).
1088 @kindex C-c C-c @r{(Outline mode)}
1089 @kindex C-c C-e @r{(Outline mode)}
1090 Two commands that are exact opposites are @kbd{C-c C-c}
1091 (@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They are
1092 used with point on a heading line, and apply only to the body lines of
1093 that heading. Subheadings and their bodies are not affected.
1095 @findex hide-subtree
1096 @findex show-subtree
1097 @kindex C-c C-s @r{(Outline mode)}
1098 @kindex C-c C-d @r{(Outline mode)}
1099 @cindex subtree (Outline mode)
1100 Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) and
1101 @kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is
1102 on a heading line, and both apply to all the lines of that heading's
1103 @dfn{subtree}: its body, all its subheadings, both direct and indirect, and
1104 all of their bodies. In other words, the subtree contains everything
1105 following this heading line, up to and not including the next heading of
1106 the same or higher rank.@refill
1109 @findex show-branches
1110 @kindex C-c C-l @r{(Outline mode)}
1111 @kindex C-c C-k @r{(Outline mode)}
1112 Intermediate between a visible subtree and an invisible one is having
1113 all the subheadings visible but none of the body. There are two
1114 commands for doing this, depending on whether you want to hide the
1115 bodies or make the subheadings visible. They are @kbd{C-c C-l}
1116 (@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}).
1118 @kindex C-c C-i @r{(Outline mode)}
1119 @findex show-children
1120 A little weaker than @code{show-branches} is @kbd{C-c C-i}
1121 (@code{show-children}). It makes just the direct subheadings
1122 visible---those one level down. Deeper subheadings remain invisible, if
1123 they were invisible.@refill
1127 @kindex C-c C-t @r{(Outline mode)}
1128 @kindex C-c C-a @r{(Outline mode)}
1129 Two commands have a blanket effect on the whole file. @kbd{C-c C-t}
1130 (@code{hide-body}) makes all body lines invisible, so that you see just
1131 the outline structure. @kbd{C-c C-a} (@code{show-all}) makes all lines
1132 visible. These commands can be thought of as a pair of opposites even
1133 though @kbd{C-c C-a} applies to more than just body lines.
1135 @findex hide-sublevels
1136 @kindex C-c C-q @r{(Outline mode)}
1137 The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the
1138 top level headings. With a numeric argument @var{n}, it hides everything
1139 except the top @var{n} levels of heading lines.
1142 @kindex C-c C-o @r{(Outline mode)}
1143 The command @kbd{C-c C-o} (@code{hide-other}) hides everything except
1144 the heading and body text that point is in, plus its parents (the headers
1145 leading up from there to top level in the outline) and the top level
1149 When incremental search finds text that is hidden by Outline mode,
1150 it makes that part of the buffer visible. If you exit the search
1151 at that position, the text remains visible. You can also
1152 automatically make text visible as you navigate in it by using
1153 @kbd{M-x reveal-mode}.
1156 @subsection Viewing One Outline in Multiple Views
1158 @cindex multiple views of outline
1159 @cindex views of an outline
1160 @cindex outline with multiple views
1161 @cindex indirect buffers and outlines
1162 You can display two views of a single outline at the same time, in
1163 different windows. To do this, you must create an indirect buffer using
1164 @kbd{M-x make-indirect-buffer}. The first argument of this command is
1165 the existing outline buffer name, and its second argument is the name to
1166 use for the new indirect buffer. @xref{Indirect Buffers}.
1168 Once the indirect buffer exists, you can display it in a window in the
1169 normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline
1170 mode commands to show and hide parts of the text operate on each buffer
1171 independently; as a result, each buffer can have its own view. If you
1172 want more than two views on the same outline, create additional indirect
1176 @subsection Folding Editing
1178 @cindex folding editing
1179 The Foldout package extends Outline mode and Outline minor mode with
1180 ``folding'' commands. The idea of folding is that you zoom in on a
1181 nested portion of the outline, while hiding its relatives at higher
1184 Consider an Outline mode buffer with all the text and subheadings under
1185 level-1 headings hidden. To look at what is hidden under one of these
1186 headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose
1187 the body, or @kbd{C-c C-i} to expose the child (level-2) headings.
1190 @findex foldout-zoom-subtree
1191 With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1192 This exposes the body and child subheadings, and narrows the buffer so
1193 that only the @w{level-1} heading, the body and the level-2 headings are
1194 visible. Now to look under one of the level-2 headings, position the
1195 cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body
1196 and its level-3 child subheadings and narrows the buffer again. Zooming
1197 in on successive subheadings can be done as much as you like. A string
1198 in the mode line shows how deep you've gone.
1200 When zooming in on a heading, to see only the child subheadings specify
1201 a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children
1202 can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2
1203 C-c C-z} exposes two levels of child subheadings. Alternatively, the
1204 body can be specified with a negative argument: @kbd{M-- C-c C-z}. The
1205 whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x
1206 show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}.
1208 While you're zoomed in, you can still use Outline mode's exposure and
1209 hiding functions without disturbing Foldout. Also, since the buffer is
1210 narrowed, ``global'' editing actions will only affect text under the
1211 zoomed-in heading. This is useful for restricting changes to a
1212 particular chapter or section of your document.
1215 @findex foldout-exit-fold
1216 To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1217 This hides all the text and subheadings under the top-level heading and
1218 returns you to the previous view of the buffer. Specifying a numeric
1219 argument exits that many levels of folds. Specifying a zero argument
1222 To cancel the narrowing of a fold without hiding the text and
1223 subheadings, specify a negative argument. For example, @kbd{M--2 C-c
1224 C-x} exits two folds and leaves the text and subheadings exposed.
1226 Foldout mode also provides mouse commands for entering and exiting
1227 folds, and for showing and hiding text:
1230 @item @kbd{C-M-Mouse-1} zooms in on the heading clicked on
1233 single click: expose body.
1235 double click: expose subheadings.
1237 triple click: expose body and subheadings.
1239 quad click: expose entire subtree.
1241 @item @kbd{C-M-Mouse-2} exposes text under the heading clicked on
1244 single click: expose body.
1246 double click: expose subheadings.
1248 triple click: expose body and subheadings.
1250 quad click: expose entire subtree.
1252 @item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold
1255 single click: hide subtree.
1257 double click: exit fold and hide text.
1259 triple click: exit fold without hiding text.
1261 quad click: exit all folds and hide text.
1265 @vindex foldout-mouse-modifiers
1266 You can specify different modifier keys (instead of
1267 @kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if
1268 you have already loaded the @file{foldout.el} library, you must reload
1269 it in order for this to take effect.
1271 To use the Foldout package, you can type @kbd{M-x load-library
1272 @key{RET} foldout @key{RET}}; or you can arrange for to do that
1273 automatically by putting this in your @file{.emacs} file:
1276 (eval-after-load "outline" '(require 'foldout))
1280 @section @TeX{} Mode
1282 @cindex La@TeX{} mode
1283 @cindex Sli@TeX{} mode
1284 @cindex mode, @TeX{}
1285 @cindex mode, La@TeX{}
1286 @cindex mode, Sli@TeX{}
1288 @findex plain-tex-mode
1292 @TeX{} is a powerful text formatter written by Donald Knuth; it is also
1293 free, like GNU Emacs. La@TeX{} is a simplified input format for @TeX{},
1294 implemented by @TeX{} macros; it comes with @TeX{}. Sli@TeX{} is a special
1295 form of La@TeX{}.@footnote{Sli@TeX{} is obsoleted by the @samp{slides}
1296 document class in recent La@TeX{} versions.}
1298 Emacs has a special @TeX{} mode for editing @TeX{} input files.
1299 It provides facilities for checking the balance of delimiters and for
1300 invoking @TeX{} on all or part of the file.
1302 @vindex tex-default-mode
1303 @TeX{} mode has three variants, Plain @TeX{} mode, La@TeX{} mode, and
1304 Sli@TeX{} mode (these three distinct major modes differ only slightly).
1305 They are designed for editing the three different formats. The command
1306 @kbd{M-x tex-mode} looks at the contents of the buffer to determine
1307 whether the contents appear to be either La@TeX{} input or Sli@TeX{}
1308 input; if so, it selects the appropriate mode. If the file contents do
1309 not appear to be La@TeX{} or Sli@TeX{}, it selects Plain @TeX{} mode.
1310 If the contents are insufficient to determine this, the variable
1311 @code{tex-default-mode} controls which mode is used.
1313 When @kbd{M-x tex-mode} does not guess right, you can use the commands
1314 @kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, and @kbd{M-x
1315 slitex-mode} to select explicitly the particular variants of @TeX{}
1319 * Editing: TeX Editing. Special commands for editing in TeX mode.
1320 * LaTeX: LaTeX Editing. Additional commands for LaTeX input files.
1321 * Printing: TeX Print. Commands for printing part of a file with TeX.
1322 * Misc: TeX Misc. Customization of TeX mode, and related features.
1326 @subsection @TeX{} Editing Commands
1328 Here are the special commands provided in @TeX{} mode for editing the
1333 Insert, according to context, either @samp{``} or @samp{"} or
1334 @samp{''} (@code{tex-insert-quote}).
1336 Insert a paragraph break (two newlines) and check the previous
1337 paragraph for unbalanced braces or dollar signs
1338 (@code{tex-terminate-paragraph}).
1339 @item M-x tex-validate-region
1340 Check each paragraph in the region for unbalanced braces or dollar signs.
1342 Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1344 Move forward past the next unmatched close brace (@code{up-list}).
1347 @findex tex-insert-quote
1348 @kindex " @r{(@TeX{} mode)}
1349 In @TeX{}, the character @samp{"} is not normally used; we use
1350 @samp{``} to start a quotation and @samp{''} to end one. To make
1351 editing easier under this formatting convention, @TeX{} mode overrides
1352 the normal meaning of the key @kbd{"} with a command that inserts a pair
1353 of single-quotes or backquotes (@code{tex-insert-quote}). To be
1354 precise, this command inserts @samp{``} after whitespace or an open
1355 brace, @samp{"} after a backslash, and @samp{''} after any other
1358 If you need the character @samp{"} itself in unusual contexts, use
1359 @kbd{C-q} to insert it. Also, @kbd{"} with a numeric argument always
1360 inserts that number of @samp{"} characters. You can turn off the
1361 feature of @kbd{"} expansion by eliminating that binding in the local
1362 map (@pxref{Key Bindings}).
1364 In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1365 understand the way @TeX{} math mode delimiters match. When you insert a
1366 @samp{$} that is meant to exit math mode, the position of the matching
1367 @samp{$} that entered math mode is displayed for a second. This is the
1368 same feature that displays the open brace that matches a close brace that
1369 is inserted. However, there is no way to tell whether a @samp{$} enters
1370 math mode or leaves it; so when you insert a @samp{$} that enters math
1371 mode, the previous @samp{$} position is shown as if it were a match, even
1372 though they are actually unrelated.
1374 @findex tex-insert-braces
1375 @kindex C-c @{ @r{(@TeX{} mode)}
1377 @kindex C-c @} @r{(@TeX{} mode)}
1378 @TeX{} uses braces as delimiters that must match. Some users prefer
1379 to keep braces balanced at all times, rather than inserting them
1380 singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1381 braces. It leaves point between the two braces so you can insert the
1382 text that belongs inside. Afterward, use the command @kbd{C-c @}}
1383 (@code{up-list}) to move forward past the close brace.
1385 @findex tex-validate-region
1386 @findex tex-terminate-paragraph
1387 @kindex C-j @r{(@TeX{} mode)}
1388 There are two commands for checking the matching of braces. @kbd{C-j}
1389 (@code{tex-terminate-paragraph}) checks the paragraph before point, and
1390 inserts two newlines to start a new paragraph. It outputs a message in
1391 the echo area if any mismatch is found. @kbd{M-x tex-validate-region}
1392 checks a region, paragraph by paragraph. The errors are listed in the
1393 @samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in
1394 that buffer to go to a particular mismatch.
1396 Note that Emacs commands count square brackets and parentheses in
1397 @TeX{} mode, not just braces. This is not strictly correct for the
1398 purpose of checking @TeX{} syntax. However, parentheses and square
1399 brackets are likely to be used in text as matching delimiters and it is
1400 useful for the various motion commands and automatic match display to
1404 @subsection La@TeX{} Editing Commands
1406 La@TeX{} mode, and its variant, Sli@TeX{} mode, provide a few extra
1407 features not applicable to plain @TeX{}.
1411 Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position
1412 point on a line between them (@code{tex-latex-block}).
1414 Close the innermost La@TeX{} block not yet closed
1415 (@code{tex-close-latex-block}).
1418 @findex tex-latex-block
1419 @kindex C-c C-o @r{(La@TeX{} mode)}
1420 @vindex latex-block-names
1421 In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to
1422 group blocks of text. To insert a @samp{\begin} and a matching
1423 @samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c
1424 C-o} (@code{tex-latex-block}). A blank line is inserted between the
1425 two, and point is left there. You can use completion when you enter the
1426 block type; to specify additional block type names beyond the standard
1427 list, set the variable @code{latex-block-names}. For example, here's
1428 how to add @samp{theorem}, @samp{corollary}, and @samp{proof}:
1431 (setq latex-block-names '("theorem" "corollary" "proof"))
1434 @findex tex-close-latex-block
1435 @kindex C-c C-e @r{(La@TeX{} mode)}
1436 In La@TeX{} input, @samp{\begin} and @samp{\end} commands must
1437 balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to
1438 insert automatically a matching @samp{\end} to match the last unmatched
1439 @samp{\begin}. It indents the @samp{\end} to match the corresponding
1440 @samp{\begin}. It inserts a newline after @samp{\end} if point is at
1441 the beginning of a line.
1444 @subsection @TeX{} Printing Commands
1446 You can invoke @TeX{} as an inferior of Emacs on either the entire
1447 contents of the buffer or just a region at a time. Running @TeX{} in
1448 this way on just one chapter is a good way to see what your changes
1449 look like without taking the time to format the entire file.
1453 Invoke @TeX{} on the current region, together with the buffer's header
1454 (@code{tex-region}).
1456 Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1458 Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1460 Invoke @TeX{} on the current file (@code{tex-file}).
1462 Recenter the window showing output from the inferior @TeX{} so that
1463 the last line can be seen (@code{tex-recenter-output-buffer}).
1465 Kill the @TeX{} subprocess (@code{tex-kill-job}).
1467 Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1468 C-f} command (@code{tex-print}).
1470 Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1471 C-f} command (@code{tex-view}).
1473 Show the printer queue (@code{tex-show-print-queue}).
1477 @kindex C-c C-b @r{(@TeX{} mode)}
1479 @kindex C-c C-p @r{(@TeX{} mode)}
1481 @kindex C-c C-v @r{(@TeX{} mode)}
1482 @findex tex-show-print-queue
1483 @kindex C-c C-q @r{(@TeX{} mode)}
1484 You can pass the current buffer through an inferior @TeX{} by means of
1485 @kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a
1486 temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}).
1487 Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to
1488 view the progress of your output towards being printed. If your terminal
1489 has the ability to display @TeX{} output files, you can preview the
1490 output on the terminal with @kbd{C-c C-v} (@code{tex-view}).
1492 @cindex @env{TEXINPUTS} environment variable
1493 @vindex tex-directory
1494 You can specify the directory to use for running @TeX{} by setting the
1495 variable @code{tex-directory}. @code{"."} is the default value. If
1496 your environment variable @env{TEXINPUTS} contains relative directory
1497 names, or if your files contains @samp{\input} commands with relative
1498 file names, then @code{tex-directory} @emph{must} be @code{"."} or you
1499 will get the wrong results. Otherwise, it is safe to specify some other
1500 directory, such as @code{"/tmp"}.
1502 @vindex tex-run-command
1503 @vindex latex-run-command
1504 @vindex slitex-run-command
1505 @vindex tex-dvi-print-command
1506 @vindex tex-dvi-view-command
1507 @vindex tex-show-queue-command
1508 If you want to specify which shell commands are used in the inferior @TeX{},
1509 you can do so by setting the values of the variables @code{tex-run-command},
1510 @code{latex-run-command}, @code{slitex-run-command},
1511 @code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and
1512 @code{tex-show-queue-command}. You @emph{must} set the value of
1513 @code{tex-dvi-view-command} for your particular terminal; this variable
1514 has no default value. The other variables have default values that may
1515 (or may not) be appropriate for your system.
1517 Normally, the file name given to these commands comes at the end of
1518 the command string; for example, @samp{latex @var{filename}}. In some
1519 cases, however, the file name needs to be embedded in the command; an
1520 example is when you need to provide the file name as an argument to one
1521 command whose output is piped to another. You can specify where to put
1522 the file name with @samp{*} in the command string. For example,
1525 (setq tex-dvi-print-command "dvips -f * | lpr")
1528 @findex tex-kill-job
1529 @kindex C-c C-k @r{(@TeX{} mode)}
1530 @findex tex-recenter-output-buffer
1531 @kindex C-c C-l @r{(@TeX{} mode)}
1532 The terminal output from @TeX{}, including any error messages, appears
1533 in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can
1534 switch to this buffer and feed it input (this works as in Shell mode;
1535 @pxref{Interactive Shell}). Without switching to this buffer you can
1536 scroll it so that its last line is visible by typing @kbd{C-c
1539 Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1540 you see that its output is no longer useful. Using @kbd{C-c C-b} or
1541 @kbd{C-c C-r} also kills any @TeX{} process still running.@refill
1544 @kindex C-c C-r @r{(@TeX{} mode)}
1545 You can also pass an arbitrary region through an inferior @TeX{} by typing
1546 @kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files
1547 of @TeX{} input contain commands at the beginning to set parameters and
1548 define macros, without which no later part of the file will format
1549 correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a
1550 part of the file as containing essential commands; it is included before
1551 the specified region as part of the input to @TeX{}. The designated part
1552 of the file is called the @dfn{header}.
1554 @cindex header (@TeX{} mode)
1555 To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1556 special strings in the file. Insert @samp{%**start of header} before the
1557 header, and @samp{%**end of header} after it. Each string must appear
1558 entirely on one line, but there may be other text on the line before or
1559 after. The lines containing the two strings are included in the header.
1560 If @samp{%**start of header} does not appear within the first 100 lines of
1561 the buffer, @kbd{C-c C-r} assumes that there is no header.
1563 In La@TeX{} mode, the header begins with @samp{\documentclass} or
1564 @samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
1565 are commands that La@TeX{} requires you to use in any case, so nothing
1566 special needs to be done to identify the header.
1569 @kindex C-c C-f @r{(@TeX{} mode)}
1570 The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1571 work in a temporary directory, and do not have available any of the auxiliary
1572 files needed by @TeX{} for cross-references; these commands are generally
1573 not suitable for running the final copy in which all of the cross-references
1576 When you want the auxiliary files for cross references, use @kbd{C-c
1577 C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1578 in that file's directory. Before running @TeX{}, it offers to save any
1579 modified buffers. Generally, you need to use (@code{tex-file}) twice to
1580 get the cross-references right.
1582 @vindex tex-start-options
1583 The value of the variable @code{tex-start-options} specifies
1584 options for the @TeX{} run.
1586 @vindex tex-start-commands
1587 The value of the variable @code{tex-start-commands} specifies @TeX{}
1588 commands for starting @TeX{}. The default value causes @TeX{} to run
1589 in nonstop mode. To run @TeX{} interactively, set the variable to
1592 @vindex tex-main-file
1593 Large @TeX{} documents are often split into several files---one main
1594 file, plus subfiles. Running @TeX{} on a subfile typically does not
1595 work; you have to run it on the main file. In order to make
1596 @code{tex-file} useful when you are editing a subfile, you can set the
1597 variable @code{tex-main-file} to the name of the main file. Then
1598 @code{tex-file} runs @TeX{} on that file.
1600 The most convenient way to use @code{tex-main-file} is to specify it
1601 in a local variable list in each of the subfiles. @xref{File
1604 @findex tex-bibtex-file
1605 @kindex C-c TAB @r{(@TeX{} mode)}
1606 @vindex tex-bibtex-command
1607 For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
1608 file for the current buffer's file. Bib@TeX{} looks up bibliographic
1609 citations in a data base and prepares the cited references for the
1610 bibliography section. The command @kbd{C-c TAB}
1611 (@code{tex-bibtex-file}) runs the shell command
1612 (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1613 current buffer's file. Generally, you need to do @kbd{C-c C-f}
1614 (@code{tex-file}) once to generate the @samp{.aux} file, then do
1615 @kbd{C-c TAB} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1616 (@code{tex-file}) twice more to get the cross-references correct.
1619 @subsection @TeX{} Mode Miscellany
1621 @vindex tex-shell-hook
1622 @vindex tex-mode-hook
1623 @vindex latex-mode-hook
1624 @vindex slitex-mode-hook
1625 @vindex plain-tex-mode-hook
1626 Entering any variant of @TeX{} mode runs the hooks
1627 @code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either
1628 @code{plain-tex-mode-hook}, @code{latex-mode-hook}, or
1629 @code{slitex-mode-hook}, whichever is appropriate. Starting the
1630 @TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}.
1634 @findex iso-iso2gtex
1635 @findex iso-gtex2iso
1636 @cindex Latin-1 @TeX{} encoding
1637 @cindex @TeX{} encoding
1638 The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1639 iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert
1640 between Latin-1 encoded files and @TeX{}-encoded equivalents.
1642 @c Too cryptic to be useful, too cryptic for me to make it better -- rms.
1644 are included by default in the @code{format-alist} variable, so they
1645 can be used with @kbd{M-x format-find-file}, for instance.
1648 @ignore @c Not worth documenting if it is only for Czech -- rms.
1649 @findex tildify-buffer
1650 @findex tildify-region
1651 @cindex ties, @TeX{}, inserting
1652 @cindex hard spaces, @TeX{}, inserting
1653 The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region}
1654 insert @samp{~} (@dfn{tie}) characters where they are conventionally
1655 required. This is set up for Czech---customize the group
1656 @samp{tildify} for other languages or for other sorts of markup.
1659 @cindex Ref@TeX{} package
1660 @cindex references, La@TeX{}
1661 @cindex La@TeX{} references
1662 For managing all kinds of references for La@TeX{}, you can use
1663 Ref@TeX{}. @inforef{Top,, reftex}.
1666 @section SGML, XML, and HTML Modes
1668 The major modes for SGML and HTML include indentation support and
1669 commands to operate on tags. This section describes the special
1670 commands of these modes. (HTML mode is a slightly customized variant
1675 @kindex C-c C-n @r{(SGML mode)}
1676 @findex sgml-name-char
1677 Interactively specify a special character and insert the SGML
1678 @samp{&}-command for that character.
1681 @kindex C-c C-t @r{(SGML mode)}
1683 Interactively specify a tag and its attributes (@code{sgml-tag}).
1684 This command asks you for a tag name and for the attribute values,
1685 then inserts both the opening tag and the closing tag, leaving point
1688 With a prefix argument @var{n}, the command puts the tag around the
1689 @var{n} words already present in the buffer after point. With
1690 @minus{}1 as argument, it puts the tag around the region. (In
1691 Transient Mark mode, it does this whenever a region is active.)
1694 @kindex C-c C-a @r{(SGML mode)}
1695 @findex sgml-attributes
1696 Interactively insert attribute values for the current tag
1697 (@code{sgml-attributes}).
1700 @kindex C-c C-f @r{(SGML mode)}
1701 @findex sgml-skip-tag-forward
1702 Skip across a balanced tag group (which extends from an opening tag
1703 through its corresponding closing tag) (@code{sgml-skip-tag-forward}).
1704 A numeric argument acts as a repeat count.
1707 @kindex C-c C-b @r{(SGML mode)}
1708 @findex sgml-skip-tag-backward
1709 Skip backward across a balanced tag group (which extends from an
1710 opening tag through its corresponding closing tag)
1711 (@code{sgml-skip-tag-forward}). A numeric argument acts as a repeat
1715 @kindex C-c C-d @r{(SGML mode)}
1716 @findex sgml-delete-tag
1717 Delete the tag at or after point, and delete the matching tag too
1718 (@code{sgml-delete-tag}). If the tag at or after point is an opening
1719 tag, delete the closing tag too; if it is a closing tag, delete the
1722 @item C-c ? @var{tag} @key{RET}
1723 @kindex C-c ? @r{(SGML mode)}
1724 @findex sgml-tag-help
1725 Display a description of the meaning of tag @var{tag}
1726 (@code{sgml-tag-help}). If the argument @var{tag} is empty, describe
1730 @kindex C-c / @r{(SGML mode)}
1731 @findex sgml-close-tag
1732 Insert a close tag for the innermost unterminated tag
1733 (@code{sgml-close-tag}). If called from within a tag or a comment,
1734 close this element instead of inserting a close tag.
1737 @kindex C-c 8 @r{(SGML mode)}
1738 @findex sgml-name-8bit-mode
1739 Toggle a minor mode in which Latin-1 characters insert the
1740 corresponding SGML commands that stand for them, instead of the
1741 characters themselves (@code{sgml-name-8bit-mode}).
1744 @kindex C-c C-v @r{(SGML mode)}
1745 @findex sgml-validate
1746 Run a shell command (which you must specify) to validate the current
1747 buffer as SGML (@code{sgml-validate}).
1750 @kindex C-c TAB @r{(SGML mode)}
1751 @findex sgml-tags-invisible
1752 Toggle the visibility of existing tags in the buffer. This can be
1753 used as a cheap preview.
1756 @vindex sgml-xml-mode
1757 SGML mode and HTML mode support XML also. In XML, every opening tag
1758 must have an explicit closing tag. When @code{sgml-xml-mode} is
1759 non-@code{nil}, SGML mode (and HTML mode) always insert explicit
1760 closing tags. When you visit a file, these modes determine from the
1761 file contents whether it is XML or not, and set @code{sgml-xml-mode}
1762 accordingly, so that they do the right thing for the file in either
1770 Nroff mode is a mode like Text mode but modified to handle nroff commands
1771 present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
1772 differs from Text mode in only a few ways. All nroff command lines are
1773 considered paragraph separators, so that filling will never garble the
1774 nroff commands. Pages are separated by @samp{.bp} commands. Comments
1775 start with backslash-doublequote. Also, three special commands are
1776 provided that are not in Text mode:
1778 @findex forward-text-line
1779 @findex backward-text-line
1780 @findex count-text-lines
1781 @kindex M-n @r{(Nroff mode)}
1782 @kindex M-p @r{(Nroff mode)}
1783 @kindex M-? @r{(Nroff mode)}
1786 Move to the beginning of the next line that isn't an nroff command
1787 (@code{forward-text-line}). An argument is a repeat count.
1789 Like @kbd{M-n} but move up (@code{backward-text-line}).
1791 Displays in the echo area the number of text lines (lines that are not
1792 nroff commands) in the region (@code{count-text-lines}).
1795 @findex electric-nroff-mode
1796 The other feature of Nroff mode is that you can turn on Electric Nroff
1797 mode. This is a minor mode that you can turn on or off with @kbd{M-x
1798 electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
1799 time you use @key{RET} to end a line that contains an nroff command that
1800 opens a kind of grouping, the matching nroff command to close that
1801 grouping is automatically inserted on the following line. For example,
1802 if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
1803 this inserts the matching command @samp{.)b} on a new line following
1806 If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
1807 heading lines are lines of the form @samp{.H} followed by a number (the
1810 @vindex nroff-mode-hook
1811 Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
1812 the hook @code{nroff-mode-hook} (@pxref{Hooks}).
1814 @node Formatted Text
1815 @section Editing Formatted Text
1817 @cindex Enriched mode
1818 @cindex mode, Enriched
1819 @cindex formatted text
1821 @cindex word processing
1822 @dfn{Enriched mode} is a minor mode for editing files that contain
1823 formatted text in WYSIWYG fashion, as in a word processor. Currently,
1824 formatted text in Enriched mode can specify fonts, colors, underlining,
1825 margins, and types of filling and justification. In the future, we plan
1826 to implement other formatting features as well.
1828 Enriched mode is a minor mode (@pxref{Minor Modes}). It is
1829 typically used in conjunction with Text mode (@pxref{Text Mode}), but
1830 you can also use it with other major modes such as Outline mode and
1831 Paragraph-Indent Text mode.
1833 @cindex text/enriched MIME format
1834 Potentially, Emacs can store formatted text files in various file
1835 formats. Currently, only one format is implemented: @dfn{text/enriched}
1836 format, which is defined by the MIME protocol. @xref{Format
1837 Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual},
1838 for details of how Emacs recognizes and converts file formats.
1840 The Emacs distribution contains a formatted text file that can serve as
1841 an example. Its name is @file{etc/enriched.doc}. It contains samples
1842 illustrating all the features described in this section. It also
1843 contains a list of ideas for future enhancements.
1846 * Requesting Formatted Text:: Entering and exiting Enriched mode.
1847 * Hard and Soft Newlines:: There are two different kinds of newlines.
1848 * Editing Format Info:: How to edit text properties.
1849 * Faces: Format Faces. Bold, italic, underline, etc.
1850 * Color: Format Colors. Changing the color of text.
1851 * Indent: Format Indentation. Changing the left and right margins.
1852 * Justification: Format Justification.
1853 Centering, setting text flush with the
1854 left or right margin, etc.
1855 * Other: Format Properties. The "special" text properties submenu.
1856 * Forcing Enriched Mode:: How to force use of Enriched mode.
1859 @node Requesting Formatted Text
1860 @subsection Requesting to Edit Formatted Text
1862 Whenever you visit a file that Emacs saved in the text/enriched
1863 format, Emacs automatically converts the formatting information in the
1864 file into Emacs's own internal format (known as @dfn{text
1865 properties}), and turns on Enriched mode.
1867 @findex enriched-mode
1868 To create a new file of formatted text, first visit the nonexistent
1869 file, then type @kbd{M-x enriched-mode} before you start inserting text.
1870 This command turns on Enriched mode. Do this before you begin inserting
1871 text, to ensure that the text you insert is handled properly.
1873 More generally, the command @code{enriched-mode} turns Enriched mode
1874 on if it was off, and off if it was on. With a prefix argument, this
1875 command turns Enriched mode on if the argument is positive, and turns
1876 the mode off otherwise.
1878 When you save a buffer while Enriched mode is enabled in it, Emacs
1879 automatically converts the text to text/enriched format while writing it
1880 into the file. When you visit the file again, Emacs will automatically
1881 recognize the format, reconvert the text, and turn on Enriched mode
1884 @vindex enriched-translations
1885 You can add annotations for saving additional text properties, which
1886 Emacs normally does not save, by adding to @code{enriched-translations}.
1887 Note that the text/enriched standard requires any non-standard
1888 annotations to have names starting with @samp{x-}, as in
1889 @samp{x-read-only}. This ensures that they will not conflict with
1890 standard annotations that may be added later.
1892 @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual},
1893 for more information about text properties.
1895 @node Hard and Soft Newlines
1896 @subsection Hard and Soft Newlines
1897 @cindex hard newline
1898 @cindex soft newline
1899 @cindex newlines, hard and soft
1901 In formatted text, Emacs distinguishes between two different kinds of
1902 newlines, @dfn{hard} newlines and @dfn{soft} newlines.
1904 Hard newlines are used to separate paragraphs, or items in a list, or
1905 anywhere that there should always be a line break regardless of the
1906 margins. The @key{RET} command (@code{newline}) and @kbd{C-o}
1907 (@code{open-line}) insert hard newlines.
1909 Soft newlines are used to make text fit between the margins. All the
1910 fill commands, including Auto Fill, insert soft newlines---and they
1911 delete only soft newlines.
1913 Although hard and soft newlines look the same, it is important to bear
1914 the difference in mind. Do not use @key{RET} to break lines in the
1915 middle of filled paragraphs, or else you will get hard newlines that are
1916 barriers to further filling. Instead, let Auto Fill mode break lines,
1917 so that if the text or the margins change, Emacs can refill the lines
1918 properly. @xref{Auto Fill}.
1920 On the other hand, in tables and lists, where the lines should always
1921 remain as you type them, you can use @key{RET} to end lines. For these
1922 lines, you may also want to set the justification style to
1923 @code{unfilled}. @xref{Format Justification}.
1925 @node Editing Format Info
1926 @subsection Editing Format Information
1928 There are two ways to alter the formatting information for a formatted
1929 text file: with keyboard commands, and with the mouse.
1931 The easiest way to add properties to your document is with the Text
1932 Properties menu. You can get to this menu in two ways: from the Edit
1933 menu in the menu bar (use @kbd{@key{F10} e t} if you have no mouse),
1934 or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle
1935 mouse button). There are also keyboard commands described in the
1938 Most of the items in the Text Properties menu lead to other submenus.
1939 These are described in the sections that follow. Some items run
1943 @findex facemenu-remove-face-props
1944 @item Remove Face Properties
1945 Delete from the region all face and color text properties
1946 (@code{facemenu-remove-face-props}).
1948 @findex facemenu-remove-all
1949 @item Remove Text Properties
1950 Delete @emph{all} text properties from the region
1951 (@code{facemenu-remove-all}).
1953 @findex describe-text-properties
1954 @cindex text properties of characters
1955 @cindex overlays at character position
1956 @cindex widgets at buffer position
1957 @cindex buttons at buffer position
1958 @item Describe Properties
1959 List all the text properties, widgets, buttons, and overlays of the
1960 character following point (@code{describe-text-properties}).
1963 Display a list of all the defined faces (@code{list-faces-display}).
1965 @item Display Colors
1966 Display a list of all the defined colors (@code{list-colors-display}).
1970 @subsection Faces in Formatted Text
1972 The Faces submenu lists various Emacs faces including @code{bold},
1973 @code{italic}, and @code{underline}. Selecting one of these adds the
1974 chosen face to the region. @xref{Faces}. You can also specify a face
1975 with these keyboard commands:
1978 @kindex M-g d @r{(Enriched mode)}
1979 @findex facemenu-set-default
1981 Set the region, or the next inserted character, to the @code{default} face
1982 (@code{facemenu-set-default}).
1983 @kindex M-g b @r{(Enriched mode)}
1984 @findex facemenu-set-bold
1986 Set the region, or the next inserted character, to the @code{bold} face
1987 (@code{facemenu-set-bold}).
1988 @kindex M-g i @r{(Enriched mode)}
1989 @findex facemenu-set-italic
1991 Set the region, or the next inserted character, to the @code{italic} face
1992 (@code{facemenu-set-italic}).
1993 @kindex M-g l @r{(Enriched mode)}
1994 @findex facemenu-set-bold-italic
1996 Set the region, or the next inserted character, to the @code{bold-italic} face
1997 (@code{facemenu-set-bold-italic}).
1998 @kindex M-g u @r{(Enriched mode)}
1999 @findex facemenu-set-underline
2001 Set the region, or the next inserted character, to the @code{underline} face
2002 (@code{facemenu-set-underline}).
2003 @kindex M-g o @r{(Enriched mode)}
2004 @findex facemenu-set-face
2005 @item M-g o @var{face} @key{RET}
2006 Set the region, or the next inserted character, to the face @var{face}
2007 (@code{facemenu-set-face}).
2010 If you use these commands with a prefix argument---or, in Transient Mark
2011 mode, if the region is not active---then these commands specify a face
2012 to use for any immediately following self-inserting input.
2013 @xref{Transient Mark}. This applies to both the keyboard commands and
2016 Specifying the @code{default} face also resets foreground and
2017 background color to their defaults.(@pxref{Format Colors}).
2019 Any self-inserting character you type inherits, by default, the face
2020 properties (as well as most other text properties) of the preceding
2021 character. Specifying any face property, including foreground or
2022 background color, for your next self-inserting character will prevent
2023 it from inheriting any face properties from the preceding character,
2024 although it will still inherit other text properties. Characters
2025 inserted by yanking do not inherit text properties.
2027 Enriched mode defines two additional faces: @code{excerpt} and
2028 @code{fixed}. These correspond to codes used in the text/enriched file
2031 The @code{excerpt} face is intended for quotations. This face is the
2032 same as @code{italic} unless you customize it (@pxref{Face Customization}).
2034 The @code{fixed} face means, ``Use a fixed-width font for this part
2035 of the text.'' Applying the @code{fixed} face to a part of the text
2036 will cause that part of the text to appear in a fixed-width font, even
2037 if the default font is variable-width. This applies to Emacs and to
2038 other systems that display text/enriched format. So if you
2039 specifically want a certain part of the text to use a fixed-width
2040 font, you should specify the @code{fixed} face for that part.
2042 By default, the @code{fixed} face looks the same as @code{bold}.
2043 This is an attempt to distinguish it from @code{default}. You may
2044 wish to customize @code{fixed} to some other fixed-width medium font.
2045 @xref{Face Customization}.
2047 If your terminal cannot display different faces, you will not be
2048 able to see them, but you can still edit documents containing faces,
2049 and even add faces and colors to documents. The faces you specify
2050 will be visible when the file is viewed on a terminal that can display
2054 @subsection Colors in Formatted Text
2056 You can specify foreground and background colors for portions of the
2057 text. There is a menu for specifying the foreground color and a menu
2058 for specifying the background color. Each color menu lists all the
2059 colors that you have used in Enriched mode in the current Emacs session.
2061 If you specify a color with a prefix argument---or, in Transient
2062 Mark mode, if the region is not active---then it applies to any
2063 immediately following self-inserting input. @xref{Transient Mark}.
2064 Otherwise, the command applies to the region.
2066 Each color menu contains one additional item: @samp{Other}. You can use
2067 this item to specify a color that is not listed in the menu; it reads
2068 the color name with the minibuffer. To display a list of available colors
2069 and their names, use the @samp{Display Colors} menu item in the Text
2070 Properties menu (@pxref{Editing Format Info}).
2072 Any color that you specify in this way, or that is mentioned in a
2073 formatted text file that you read in, is added to the corresponding
2074 color menu for the duration of the Emacs session.
2076 @findex facemenu-set-foreground
2077 @findex facemenu-set-background
2078 There are no key bindings for specifying colors, but you can do so
2079 with the extended commands @kbd{M-x facemenu-set-foreground} and
2080 @kbd{M-x facemenu-set-background}. Both of these commands read the name
2081 of the color with the minibuffer.
2083 @node Format Indentation
2084 @subsection Indentation in Formatted Text
2086 When editing formatted text, you can specify different amounts of
2087 indentation for the right or left margin of an entire paragraph or a
2088 part of a paragraph. The margins you specify automatically affect the
2089 Emacs fill commands (@pxref{Filling}) and line-breaking commands.
2091 The Indentation submenu provides a convenient interface for specifying
2092 these properties. The submenu contains four items:
2095 @kindex C-x TAB @r{(Enriched mode)}
2096 @findex increase-left-margin
2098 Indent the region by 4 columns (@code{increase-left-margin}). In
2099 Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
2100 you supply a numeric argument, that says how many columns to add to the
2101 margin (a negative argument reduces the number of columns).
2104 Remove 4 columns of indentation from the region.
2106 @item Indent Right More
2107 Make the text narrower by indenting 4 columns at the right margin.
2109 @item Indent Right Less
2110 Remove 4 columns of indentation from the right margin.
2113 You can use these commands repeatedly to increase or decrease the
2116 The most common way to use them is to change the indentation of an
2117 entire paragraph. For other uses, the effects of refilling can be
2118 hard to predict, except in some special cases like the one described
2121 The most common other use is to format paragraphs with @dfn{hanging
2122 indents}, which means that the first line is indented less than
2123 subsequent lines. To set up a hanging indent, increase the
2124 indentation of the region starting after the first word of the
2125 paragraph and running until the end of the paragraph.
2127 Indenting the first line of a paragraph is easier. Set the margin for
2128 the whole paragraph where you want it to be for the body of the
2129 paragraph, then indent the first line by inserting extra spaces or tabs.
2131 @vindex standard-indent
2132 The variable @code{standard-indent} specifies how many columns these
2133 commands should add to or subtract from the indentation. The default
2134 value is 4. The overall default right margin for Enriched mode is
2135 controlled by the variable @code{fill-column}, as usual.
2137 @kindex C-c [ @r{(Enriched mode)}
2138 @kindex C-c ] @r{(Enriched mode)}
2139 @findex set-left-margin
2140 @findex set-right-margin
2141 There are also two commands for setting the left or right margin of
2142 the region absolutely: @code{set-left-margin} and
2143 @code{set-right-margin}. Enriched mode binds these commands to
2144 @kbd{C-c [} and @kbd{C-c ]}, respectively. You can specify the
2145 margin width either with a numeric argument or in the minibuffer.
2147 Sometimes, as a result of editing, the filling of a paragraph becomes
2148 messed up---parts of the paragraph may extend past the left or right
2149 margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to
2150 refill the paragraph.
2152 The fill prefix, if any, works in addition to the specified paragraph
2153 indentation: @kbd{C-x .} does not include the specified indentation's
2154 whitespace in the new value for the fill prefix, and the fill commands
2155 look for the fill prefix after the indentation on each line. @xref{Fill
2158 @node Format Justification
2159 @subsection Justification in Formatted Text
2161 When editing formatted text, you can specify various styles of
2162 justification for a paragraph. The style you specify automatically
2163 affects the Emacs fill commands.
2165 The Justification submenu provides a convenient interface for specifying
2166 the style. The submenu contains five items:
2170 This is the most common style of justification (at least for English).
2171 Lines are aligned at the left margin but left uneven at the right.
2174 This aligns each line with the right margin. Spaces and tabs are added
2175 on the left, if necessary, to make lines line up on the right.
2178 This justifies the text, aligning both edges of each line. Justified
2179 text looks very nice in a printed book, where the spaces can all be
2180 adjusted equally, but it does not look as nice with a fixed-width font
2181 on the screen. Perhaps a future version of Emacs will be able to adjust
2182 the width of spaces in a line to achieve elegant justification.
2185 This centers every line between the current margins.
2188 This turns off filling entirely. Each line will remain as you wrote it;
2189 the fill and auto-fill functions will have no effect on text which has
2190 this setting. You can, however, still indent the left margin. In
2191 unfilled regions, all newlines are treated as hard newlines (@pxref{Hard
2192 and Soft Newlines}) .
2195 In Enriched mode, you can also specify justification from the keyboard
2196 using the @kbd{M-j} prefix character:
2199 @kindex M-j l @r{(Enriched mode)}
2200 @findex set-justification-left
2202 Make the region left-filled (@code{set-justification-left}).
2203 @kindex M-j r @r{(Enriched mode)}
2204 @findex set-justification-right
2206 Make the region right-filled (@code{set-justification-right}).
2207 @kindex M-j b @r{(Enriched mode)}
2208 @findex set-justification-full
2210 Make the region fully justified (@code{set-justification-full}).
2211 @kindex M-j c @r{(Enriched mode)}
2212 @kindex M-S @r{(Enriched mode)}
2213 @findex set-justification-center
2216 Make the region centered (@code{set-justification-center}).
2217 @kindex M-j u @r{(Enriched mode)}
2218 @findex set-justification-none
2220 Make the region unfilled (@code{set-justification-none}).
2223 Justification styles apply to entire paragraphs. All the
2224 justification-changing commands operate on the paragraph containing
2225 point, or, if the region is active, on all paragraphs which overlap the
2228 @vindex default-justification
2229 The default justification style is specified by the variable
2230 @code{default-justification}. Its value should be one of the symbols
2231 @code{left}, @code{right}, @code{full}, @code{center}, or @code{none}.
2232 This is a per-buffer variable. Setting the variable directly affects
2233 only the current buffer. However, customizing it in a Custom buffer
2234 sets (as always) the default value for buffers that do not override it.
2235 @xref{Locals}, and @ref{Easy Customization}.
2237 @node Format Properties
2238 @subsection Setting Other Text Properties
2240 The Special Properties menu lets you add or remove three other useful text
2241 properties: @code{read-only}, @code{invisible} and @code{intangible}.
2242 The @code{intangible} property disallows moving point within the text,
2243 the @code{invisible} text property hides text from display, and the
2244 @code{read-only} property disallows alteration of the text.
2246 Each of these special properties has a menu item to add it to the
2247 region. The last menu item, @samp{Remove Special}, removes all of these
2248 special properties from the text in the region.
2250 Currently, the @code{invisible} and @code{intangible} properties are
2251 @emph{not} saved in the text/enriched format. The @code{read-only}
2252 property is saved, but it is not a standard part of the text/enriched
2253 format, so other editors may not respect it.
2255 @node Forcing Enriched Mode
2256 @subsection Forcing Enriched Mode
2258 Normally, Emacs knows when you are editing formatted text because it
2259 recognizes the special annotations used in the file that you visited.
2260 However, there are situations in which you must take special actions
2261 to convert file contents or turn on Enriched mode:
2265 When you visit a file that was created with some other editor, Emacs may
2266 not recognize the file as being in the text/enriched format. In this
2267 case, when you visit the file you will see the formatting commands
2268 rather than the formatted text. Type @kbd{M-x format-decode-buffer} to
2269 translate it. This also automatically turns on Enriched mode.
2272 When you @emph{insert} a file into a buffer, rather than visiting it,
2273 Emacs does the necessary conversions on the text which you insert, but
2274 it does not enable Enriched mode. If you wish to do that, type @kbd{M-x
2278 The command @code{format-decode-buffer} translates text in various
2279 formats into Emacs's internal format. It asks you to specify the format
2280 to translate from; however, normally you can type just @key{RET}, which
2281 tells Emacs to guess the format.
2283 @findex format-find-file
2284 If you wish to look at a text/enriched file in its raw form, as a
2285 sequence of characters rather than as formatted text, use the @kbd{M-x
2286 find-file-literally} command. This visits a file, like
2287 @code{find-file}, but does not do format conversion. It also inhibits
2288 character code conversion (@pxref{Coding Systems}) and automatic
2289 uncompression (@pxref{Compressed Files}). To disable format conversion
2290 but allow character code conversion and/or automatic uncompression if
2291 appropriate, use @code{format-find-file} with suitable arguments.
2294 arch-tag: 8db54ed8-2036-49ca-b0df-23811d03dc70