1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
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}.
53 The `automatic typing' features may be useful when writing text.
54 @xref{Top, Autotyping, autotype, Features for Automatic Typing}.
57 * Words:: Moving over and killing words.
58 * Sentences:: Moving over and killing sentences.
59 * Paragraphs:: Moving over paragraphs.
60 * Pages:: Moving over pages.
61 * Filling:: Filling or justifying text.
62 * Case:: Changing the case of text.
63 * Text Mode:: The major modes for editing text files.
64 * Outline Mode:: Editing outlines.
65 * TeX Mode:: Editing input to the formatter TeX.
66 * Nroff Mode:: Editing input to the formatter nroff.
67 * Formatted Text:: Editing formatted text directly in WYSIWYG fashion.
73 @cindex Meta commands and words
75 Emacs has commands for moving over or operating on words. By convention,
76 the keys for them are all Meta characters.
81 Move forward over a word (@code{forward-word}).
83 Move backward over a word (@code{backward-word}).
85 Kill up to the end of a word (@code{kill-word}).
87 Kill back to the beginning of a word (@code{backward-kill-word}).
89 Mark the end of the next word (@code{mark-word}).
91 Transpose two words or drag a word across other words
92 (@code{transpose-words}).
95 Notice how these keys form a series that parallels the character-based
96 @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is
97 cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
102 @findex backward-word
103 The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b}
104 (@code{backward-word}) move forward and backward over words. These
105 Meta characters are thus analogous to the corresponding control
106 characters, @kbd{C-f} and @kbd{C-b}, which move over single characters
107 in the text. The analogy extends to numeric arguments, which serve as
108 repeat counts. @kbd{M-f} with a negative argument moves backward, and
109 @kbd{M-b} with a negative argument moves forward. Forward motion
110 stops right after the last letter of the word, while backward motion
111 stops right before the first letter.@refill
115 @kbd{M-d} (@code{kill-word}) kills the word after point. To be
116 precise, it kills everything from point to the place @kbd{M-f} would
117 move to. Thus, if point is in the middle of a word, @kbd{M-d} kills
118 just the part after point. If some punctuation comes between point and the
119 next word, it is killed along with the word. (If you wish to kill only the
120 next word but not the punctuation before it, simply do @kbd{M-f} to get
121 the end, and kill the word backwards with @kbd{M-@key{DEL}}.)
122 @kbd{M-d} takes arguments just like @kbd{M-f}.
124 @findex backward-kill-word
126 @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
127 point. It kills everything from point back to where @kbd{M-b} would
128 move to. If point is after the space in @w{@samp{FOO, BAR}}, then
129 @w{@samp{FOO, }} is killed. (If you wish to kill just @samp{FOO}, and
130 not the comma and the space, use @kbd{M-b M-d} instead of
134 @findex transpose-words
135 @kbd{M-t} (@code{transpose-words}) exchanges the word before or
136 containing point with the following word. The delimiter characters between
137 the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
138 @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
139 more on transposition and on arguments to transposition commands.
143 To operate on the next @var{n} words with an operation which applies
144 between point and mark, you can either set the mark at point and then move
145 over the words, or you can use the command @kbd{M-@@} (@code{mark-word})
146 which does not move point, but sets the mark where @kbd{M-f} would move
147 to. @kbd{M-@@} accepts a numeric argument that says how many words to
148 scan for the place to put the mark. In Transient Mark mode, this command
151 The word commands' understanding of syntax is completely controlled by
152 the syntax table. Any character can, for example, be declared to be a word
153 delimiter. @xref{Syntax}.
158 @cindex manipulating sentences
160 The Emacs commands for manipulating sentences and paragraphs are mostly
161 on Meta keys, so as to be like the word-handling commands.
165 Move back to the beginning of the sentence (@code{backward-sentence}).
167 Move forward to the end of the sentence (@code{forward-sentence}).
169 Kill forward to the end of the sentence (@code{kill-sentence}).
171 Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
176 @findex backward-sentence
177 @findex forward-sentence
178 The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and
179 @code{forward-sentence}) move to the beginning and end of the current
180 sentence, respectively. They were chosen to resemble @kbd{C-a} and
181 @kbd{C-e}, which move to the beginning and end of a line. Unlike them,
182 @kbd{M-a} and @kbd{M-e} if repeated or given numeric arguments move over
183 successive sentences.
185 Moving backward over a sentence places point just before the first
186 character of the sentence; moving forward places point right after the
187 punctuation that ends the sentence. Neither one moves over the
188 whitespace at the sentence boundary.
192 @findex kill-sentence
193 @findex backward-kill-sentence
194 Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
195 with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
196 @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of
197 the sentence. With minus one as an argument it kills back to the
198 beginning of the sentence. Larger arguments serve as a repeat count.
199 There is also a command, @kbd{C-x @key{DEL}}
200 (@code{backward-kill-sentence}), for killing back to the beginning of a
201 sentence. This command is useful when you change your mind in the
202 middle of composing text.@refill
204 The sentence commands assume that you follow the American typist's
205 convention of putting two spaces at the end of a sentence; they consider
206 a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!}
207 followed by the end of a line or two spaces, with any number of
208 @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between.
209 A sentence also begins or ends wherever a paragraph begins or ends.
212 The variable @code{sentence-end} controls recognition of the end of a
213 sentence. It is a regexp that matches the last few characters of a
214 sentence, together with the whitespace following the sentence. Its
218 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
222 This example is explained in the section on regexps. @xref{Regexps}.
224 If you want to use just one space between sentences, you should
225 set @code{sentence-end} to this value:
228 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
232 You should also set the variable @code{sentence-end-double-space} to
233 @code{nil} so that the fill commands expect and leave just one space at
234 the end of a sentence. Note that this makes it impossible to
235 distinguish between periods that end sentences and those that indicate
241 @cindex manipulating paragraphs
244 @findex backward-paragraph
245 @findex forward-paragraph
247 The Emacs commands for manipulating paragraphs are also Meta keys.
251 Move back to previous paragraph beginning (@code{backward-paragraph}).
253 Move forward to next paragraph end (@code{forward-paragraph}).
255 Put point and mark around this or next paragraph (@code{mark-paragraph}).
258 @kbd{M-@{} moves to the beginning of the current or previous
259 paragraph, while @kbd{M-@}} moves to the end of the current or next
260 paragraph. Blank lines and text-formatter command lines separate
261 paragraphs and are not considered part of any paragraph. In Fundamental
262 mode, but not in Text mode, an indented line also starts a new
263 paragraph. (If a paragraph is preceded by a blank line, these commands
264 treat that blank line as the beginning of the paragraph.)
266 In major modes for programs, paragraphs begin and end only at blank
267 lines. This makes the paragraph commands continue to be useful even
268 though there are no paragraphs per se.
270 When there is a fill prefix, then paragraphs are delimited by all lines
271 which don't start with the fill prefix. @xref{Filling}.
274 @findex mark-paragraph
275 When you wish to operate on a paragraph, you can use the command
276 @kbd{M-h} (@code{mark-paragraph}) to set the region around it. Thus,
277 for example, @kbd{M-h C-w} kills the paragraph around or after point.
278 The @kbd{M-h} command puts point at the beginning and mark at the end of
279 the paragraph point was in. In Transient Mark mode, it activates the
280 mark. If point is between paragraphs (in a run of blank lines, or at a
281 boundary), the paragraph following point is surrounded by point and
282 mark. If there are blank lines preceding the first line of the
283 paragraph, one of these blank lines is included in the region.
285 @vindex paragraph-start
286 @vindex paragraph-separate
287 The precise definition of a paragraph boundary is controlled by the
288 variables @code{paragraph-separate} and @code{paragraph-start}. The
289 value of @code{paragraph-start} is a regexp that should match any line
290 that either starts or separates paragraphs. The value of
291 @code{paragraph-separate} is another regexp that should match only lines
292 that separate paragraphs without being part of any paragraph (for
293 example, blank lines). Lines that start a new paragraph and are
294 contained in it must match only @code{paragraph-start}, not
295 @code{paragraph-separate}. For example, in Fundamental mode,
296 @code{paragraph-start} is @code{"[ @t{\}t@t{\}n@t{\}f]"} and
297 @code{paragraph-separate} is @code{"[ @t{\}t@t{\}f]*$"}.@refill
299 Normally it is desirable for page boundaries to separate paragraphs.
300 The default values of these variables recognize the usual separator for
308 Files are often thought of as divided into @dfn{pages} by the
309 @dfn{formfeed} character (ASCII control-L, octal code 014). When you
310 print hardcopy for a file, this character forces a page break; thus,
311 each page of the file goes on a separate page on paper. Most Emacs
312 commands treat the page-separator character just like any other
313 character: you can insert it with @kbd{C-q C-l}, and delete it with
314 @key{DEL}. Thus, you are free to paginate your file or not. However,
315 since pages are often meaningful divisions of the file, Emacs provides
316 commands to move over them and operate on them.
321 Move point to previous page boundary (@code{backward-page}).
323 Move point to next page boundary (@code{forward-page}).
325 Put point and mark around this page (or another page) (@code{mark-page}).
327 Count the lines in this page (@code{count-lines-page}).
333 @findex backward-page
334 The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
335 after the previous page delimiter. If point is already right after a page
336 delimiter, it skips that one and stops at the previous one. A numeric
337 argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
338 command moves forward past the next page delimiter.
342 The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
343 beginning of the current page and the mark at the end. The page
344 delimiter at the end is included (the mark follows it). The page
345 delimiter at the front is excluded (point follows it). @kbd{C-x C-p
346 C-w} is a handy way to kill a page to move it elsewhere. If you move to
347 another page delimiter with @kbd{C-x [} and @kbd{C-x ]}, then yank the
348 killed page, all the pages will be properly delimited once again. The
349 reason @kbd{C-x C-p} includes only the following page delimiter in the
350 region is to ensure that.
352 A numeric argument to @kbd{C-x C-p} is used to specify which page to go
353 to, relative to the current one. Zero means the current page. One means
354 the next page, and @minus{}1 means the previous one.
357 @findex count-lines-page
358 The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
359 where to break a page in two. It prints in the echo area the total number
360 of lines in the current page, and then divides it up into those preceding
361 the current line and those following, as in
364 Page has 96 (72+25) lines
368 Notice that the sum is off by one; this is correct if point is not at the
371 @vindex page-delimiter
372 The variable @code{page-delimiter} controls where pages begin. Its
373 value is a regexp that matches the beginning of a line that separates
374 pages. The normal value of this variable is @code{"^@t{\}f"}, which
375 matches a formfeed character at the beginning of a line.
378 @section Filling Text
381 @dfn{Filling} text means breaking it up into lines that fit a
382 specified width. Emacs does filling in two ways. In Auto Fill mode,
383 inserting text with self-inserting characters also automatically fills
384 it. There are also explicit fill commands that you can use when editing
385 text leaves it unfilled. When you edit formatted text, you can specify
386 a style of filling for each portion of the text (@pxref{Formatted
390 * Auto Fill:: Auto Fill mode breaks long lines automatically.
391 * Fill Commands:: Commands to refill paragraphs and center lines.
392 * Fill Prefix:: Filling paragraphs that are indented
393 or in a comment, etc.
394 * Adaptive Fill:: How Emacs can determine the fill prefix automatically.
398 @subsection Auto Fill Mode
399 @cindex Auto Fill mode
400 @cindex mode, Auto Fill
403 @dfn{Auto Fill} mode is a minor mode in which lines are broken
404 automatically when they become too wide. Breaking happens only when
405 you type a @key{SPC} or @key{RET}.
408 @item M-x auto-fill-mode
409 Enable or disable Auto Fill mode.
412 In Auto Fill mode, break lines when appropriate.
415 @findex auto-fill-mode
416 @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off
417 if it was on. With a positive numeric argument it always turns Auto
418 Fill mode on, and with a negative argument always turns it off. You can
419 see when Auto Fill mode is in effect by the presence of the word
420 @samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is
421 a minor mode which is enabled or disabled for each buffer individually.
424 In Auto Fill mode, lines are broken automatically at spaces when they
425 get longer than the desired width. Line breaking and rearrangement
426 takes place only when you type @key{SPC} or @key{RET}. If you wish to
427 insert a space or newline without permitting line-breaking, type
428 @kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a
429 control-J). Also, @kbd{C-o} inserts a newline without line breaking.
431 Auto Fill mode works well with programming-language modes, because it
432 indents new lines with @key{TAB}. If a line ending in a comment gets
433 too long, the text of the comment is split into two comment lines.
434 Optionally, new comment delimiters are inserted at the end of the first
435 line and the beginning of the second so that each line is a separate
436 comment; the variable @code{comment-multi-line} controls the choice
439 Adaptive filling (see the following section) works for Auto Filling as
440 well as for explicit fill commands. It takes a fill prefix
441 automatically from the second or first line of a paragraph.
443 Auto Fill mode does not refill entire paragraphs; it can break lines but
444 cannot merge lines. So editing in the middle of a paragraph can result in
445 a paragraph that is not correctly filled. The easiest way to make the
446 paragraph properly filled again is usually with the explicit fill commands.
448 @xref{Fill Commands}.
451 Many users like Auto Fill mode and want to use it in all text files.
452 The section on init files says how to arrange this permanently for yourself.
456 @subsection Explicit Fill Commands
460 Fill current paragraph (@code{fill-paragraph}).
462 Set the fill column (@code{set-fill-column}).
463 @item M-x fill-region
464 Fill each paragraph in the region (@code{fill-region}).
465 @item M-x fill-region-as-paragraph
466 Fill the region, considering it as one paragraph.
472 @findex fill-paragraph
473 To refill a paragraph, use the command @kbd{M-q}
474 (@code{fill-paragraph}). This operates on the paragraph that point is
475 inside, or the one after point if point is between paragraphs.
476 Refilling works by removing all the line-breaks, then inserting new ones
480 To refill many paragraphs, use @kbd{M-x fill-region}, which
481 divides the region into paragraphs and fills each of them.
483 @findex fill-region-as-paragraph
484 @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h}
485 for finding paragraph boundaries (@pxref{Paragraphs}). For more
486 control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
487 everything between point and mark. This command deletes any blank lines
488 within the region, so separate blocks of text end up combined into one
491 @cindex justification
492 A numeric argument to @kbd{M-q} causes it to @dfn{justify} the text as
493 well as filling it. This means that extra spaces are inserted to make
494 the right margin line up exactly at the fill column. To remove the
495 extra spaces, use @kbd{M-q} with no argument. (Likewise for
496 @code{fill-region}.) Another way to control justification, and choose
497 other styles of filling, is with the @code{justification} text property;
498 see @ref{Format Justification}.
500 @kindex M-s @r{(Text mode)}
503 The command @kbd{M-s} (@code{center-line}) centers the current line
504 within the current fill column. With an argument @var{n}, it centers
505 @var{n} lines individually and moves past them.
509 @findex set-fill-column
510 The maximum line width for filling is in the variable
511 @code{fill-column}. Altering the value of @code{fill-column} makes it
512 local to the current buffer; until that time, the default value is in
513 effect. The default is initially 70. @xref{Locals}. The easiest way
514 to set @code{fill-column} is to use the command @kbd{C-x f}
515 (@code{set-fill-column}). With a numeric argument, it uses that as the
516 new fill column. With just @kbd{C-u} as argument, it sets
517 @code{fill-column} to the current horizontal position of point.
519 Emacs commands normally consider a period followed by two spaces or by
520 a newline as the end of a sentence; a period followed by just one space
521 indicates an abbreviation and not the end of a sentence. To preserve
522 the distinction between these two ways of using a period, the fill
523 commands do not break a line after a period followed by just one space.
525 @vindex sentence-end-double-space
526 If the variable @code{sentence-end-double-space} is @code{nil}, the
527 fill commands expect and leave just one space at the end of a sentence.
528 Ordinarily this variable is @code{t}, so the fill commands insist on
529 two spaces for the end of a sentence, as explained above. @xref{Sentences}.
531 @vindex colon-double-space
532 If the variable @code{colon-double-space} is non-@code{nil}, the
533 fill commands put two spaces after a colon.
536 @subsection The Fill Prefix
539 To fill a paragraph in which each line starts with a special marker
540 (which might be a few spaces, giving an indented paragraph), you can use
541 the @dfn{fill prefix} feature. The fill prefix is a string that Emacs
542 expects every line to start with, and which is not included in filling.
543 You can specify a fill prefix explicitly; Emacs can also deduce the
544 fill prefix automatically (@pxref{Adaptive Fill}).
548 Set the fill prefix (@code{set-fill-prefix}).
550 Fill a paragraph using current fill prefix (@code{fill-paragraph}).
551 @item M-x fill-individual-paragraphs
552 Fill the region, considering each change of indentation as starting a
554 @item M-x fill-nonuniform-paragraphs
555 Fill the region, considering only paragraph-separator lines as starting
560 @findex set-fill-prefix
561 To specify a fill prefix, move to a line that starts with the desired
562 prefix, put point at the end of the prefix, and give the command
563 @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). That's a period after the
564 @kbd{C-x}. To turn off the fill prefix, specify an empty prefix: type
565 @w{@kbd{C-x .}}@: with point at the beginning of a line.@refill
567 When a fill prefix is in effect, the fill commands remove the fill
568 prefix from each line before filling and insert it on each line after
569 filling. Auto Fill mode also inserts the fill prefix automatically when
570 it makes a new line. The @kbd{C-o} command inserts the fill prefix on
571 new lines it creates, when you use it at the beginning of a line
572 (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes the
573 prefix (if it occurs) after the newline that it deletes
574 (@pxref{Indentation}).
576 For example, if @code{fill-column} is 40 and you set the fill prefix
577 to @samp{;; }, then @kbd{M-q} in the following text
581 ;; example of a paragraph
582 ;; inside a Lisp-style comment.
589 ;; This is an example of a paragraph
590 ;; inside a Lisp-style comment.
593 Lines that do not start with the fill prefix are considered to start
594 paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
595 good results for paragraphs with hanging indentation (every line
596 indented except the first one). Lines which are blank or indented once
597 the prefix is removed also separate or start paragraphs; this is what
598 you want if you are writing multi-paragraph comments with a comment
599 delimiter on each line.
601 @findex fill-individual-paragraphs
602 You can use @kbd{M-x fill-individual-paragraphs} to set the fill
603 prefix for each paragraph automatically. This command divides the
604 region into paragraphs, treating every change in the amount of
605 indentation as the start of a new paragraph, and fills each of these
606 paragraphs. Thus, all the lines in one ``paragraph'' have the same
607 amount of indentation. That indentation serves as the fill prefix for
610 @findex fill-nonuniform-paragraphs
611 @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
612 the region into paragraphs in a different way. It considers only
613 paragraph-separating lines (as defined by @code{paragraph-separate}) as
614 starting a new paragraph. Since this means that the lines of one
615 paragraph may have different amounts of indentation, the fill prefix
616 used is the smallest amount of indentation of any of the lines of the
617 paragraph. This gives good results with styles that indent a paragraph's
618 first line more or less that the rest of the paragraph.
621 The fill prefix is stored in the variable @code{fill-prefix}. Its value
622 is a string, or @code{nil} when there is no fill prefix. This is a
623 per-buffer variable; altering the variable affects only the current buffer,
624 but there is a default value which you can change as well. @xref{Locals}.
626 The @code{indentation} text property provides another way to control
627 the amount of indentation paragraphs receive. @xref{Format Indentation}.
630 @subsection Adaptive Filling
632 @cindex adaptive filling
633 The fill commands can deduce the proper fill prefix for a paragraph
634 automatically in certain cases: either whitespace or certain punctuation
635 characters at the beginning of a line are propagated to all lines of the
638 If the paragraph has two or more lines, the fill prefix is taken from
639 the paragraph's second line, but only if it appears on the first line as
642 If a paragraph has just one line, fill commands @emph{may} take a
643 prefix from that line. The decision is complicated because there are
644 three reasonable things to do in such a case:
648 Use the first line's prefix on all the lines of the paragraph.
651 Indent subsequent lines with whitespace, so that they line up under the
652 text that follows the prefix on the first line, but don't actually copy
653 the prefix from the first line.
656 Don't do anything special with the second and following lines.
659 All three of these styles of formatting are commonly used. So the
660 fill commands try to determine what you would like, based on the prefix
661 that appears and on the major mode. Here is how.
663 @vindex adaptive-fill-first-line-regexp
664 If the prefix found on the first line matches
665 @code{adaptive-fill-first-line-regexp}, or if it appears to be a
666 comment-starting sequence (this depends on the major mode), then the
667 prefix found is used for filling the paragraph, provided it would not
668 act as a paragraph starter on subsequent lines.
670 Otherwise, the prefix found is converted to an equivalent number of
671 spaces, and those spaces are used as the fill prefix for the rest of the
672 lines, provided they would not act as a paragraph starter on subsequent
675 In Text mode, and other modes where only blank lines and page
676 delimiters separate paragraphs, the prefix chosen by adaptive filling
677 never acts as a paragraph starter, so it can always be used for filling.
679 @vindex adaptive-fill-mode
680 @vindex adaptive-fill-regexp
681 The variable @code{adaptive-fill-regexp} determines what kinds of line
682 beginnings can serve as a fill prefix: any characters at the start of
683 the line that match this regular expression are used. If you set the
684 variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
685 never chosen automatically.
687 @vindex adaptive-fill-function
688 You can specify more complex ways of choosing a fill prefix
689 automatically by setting the variable @code{adaptive-fill-function} to a
690 function. This function is called with point after the left margin of a
691 line, and it should return the appropriate fill prefix based on that
692 line. If it returns @code{nil}, that means it sees no fill prefix in
696 @section Case Conversion Commands
697 @cindex case conversion
699 Emacs has commands for converting either a single word or any arbitrary
700 range of text to upper case or to lower case.
705 Convert following word to lower case (@code{downcase-word}).
707 Convert following word to upper case (@code{upcase-word}).
709 Capitalize the following word (@code{capitalize-word}).
711 Convert region to lower case (@code{downcase-region}).
713 Convert region to upper case (@code{upcase-region}).
719 @cindex words, case conversion
720 @cindex converting text to upper or lower case
721 @cindex capitalizing words
722 @findex downcase-word
724 @findex capitalize-word
725 The word conversion commands are the most useful. @kbd{M-l}
726 (@code{downcase-word}) converts the word after point to lower case, moving
727 past it. Thus, repeating @kbd{M-l} converts successive words.
728 @kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while
729 @kbd{M-c} (@code{capitalize-word}) puts the first letter of the word
730 into upper case and the rest into lower case. All these commands convert
731 several words at once if given an argument. They are especially convenient
732 for converting a large amount of text from all upper case to mixed case,
733 because you can move through the text using @kbd{M-l}, @kbd{M-u} or
734 @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
737 When given a negative argument, the word case conversion commands apply
738 to the appropriate number of words before point, but do not move point.
739 This is convenient when you have just typed a word in the wrong case: you
740 can give the case conversion command and continue typing.
742 If a word case conversion command is given in the middle of a word, it
743 applies only to the part of the word which follows point. This is just
744 like what @kbd{M-d} (@code{kill-word}) does. With a negative argument,
745 case conversion applies only to the part of the word before point.
749 @findex downcase-region
750 @findex upcase-region
751 The other case conversion commands are @kbd{C-x C-u}
752 (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
753 convert everything between point and mark to the specified case. Point and
756 The region case conversion commands @code{upcase-region} and
757 @code{downcase-region} are normally disabled. This means that they ask
758 for confirmation if you try to use them. When you confirm, you may
759 enable the command, which means it will not ask for confirmation again.
768 When you edit files of text in a human language, it's more convenient
769 to use Text mode rather than Fundamental mode. To enter Text mode, type
772 In Text mode, only blank lines and page delimiters separate
773 paragraphs. As a result, paragraphs can be indented, and adaptive
774 filling determines what indentation to use when filling a paragraph.
775 @xref{Adaptive Fill}.
777 @kindex TAB @r{(Text mode)}
778 Text mode defines @key{TAB} to run @code{indent-relative}
779 (@pxref{Indentation}), so that you can conveniently indent a line like
780 the previous line. When the previous line is not indented,
781 @code{indent-relative} runs @code{tab-to-tab-stop}, which uses Emacs tab
782 stops that you can set (@pxref{Tab Stops}).
784 Text mode turns off the features concerned with comments except when
785 you explicitly invoke them. It changes the syntax table so that periods
786 are not considered part of a word, while apostrophes, backspaces and
787 underlines are considered part of words.
789 @cindex Paragraph-Indent Text mode
790 @cindex mode, Paragraph-Indent Text
791 @findex paragraph-indent-text-mode
792 @findex paragraph-indent-minor-mode
793 If you indent the first lines of paragraphs, then you should use
794 Paragraph-Indent Text mode rather than Text mode. In this mode, you do
795 not need to have blank lines between paragraphs, because the first-line
796 indentation is sufficient to start a paragraph; however paragraphs in
797 which every line is indented are not supported. Use @kbd{M-x
798 paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x
799 paragraph-indent-minor-mode} to enter an equivalent minor mode, for
800 instance during mail composition.
802 @kindex M-TAB @r{(Text mode)}
803 Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} as
804 the command @code{ispell-complete-word}, which performs completion of
805 the partial word in the buffer before point, using the spelling
806 dictionary as the space of possible words. @xref{Spelling}.
808 @vindex text-mode-hook
809 Entering Text mode runs the hook @code{text-mode-hook}. Other major
810 modes related to Text mode also run this hook, followed by hooks of
811 their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{}
812 mode, Outline mode, and Mail mode. Hook functions on
813 @code{text-mode-hook} can look at the value of @code{major-mode} to see
814 which of these modes is actually being entered. @xref{Hooks}.
817 Emacs provides two other modes for editing text that is to be passed
818 through a text formatter to produce fancy formatted printed output.
819 @xref{Nroff Mode}, for editing input to the formatter nroff.
820 @xref{TeX Mode}, for editing input to the formatter TeX.
822 Another mode is used for editing outlines. It allows you to view the
823 text at various levels of detail. You can view either the outline
824 headings alone or both headings and text; you can also hide some of the
825 headings at lower levels from view to make the high level structure more
826 visible. @xref{Outline Mode}.
830 @section Outline Mode
832 @cindex mode, Outline
833 @cindex selective display
834 @cindex invisible lines
837 @findex outline-minor-mode
838 @vindex outline-minor-mode-prefix
839 Outline mode is a major mode much like Text mode but intended for
840 editing outlines. It allows you to make parts of the text temporarily
841 invisible so that you can see the outline structure. Type @kbd{M-x
842 outline-mode} to switch to Outline mode as the major mode of the current
845 When Outline mode makes a line invisible, the line does not appear on
846 the screen. The screen appears exactly as if the invisible line were
847 deleted, except that an ellipsis (three periods in a row) appears at the
848 end of the previous visible line (only one ellipsis no matter how many
849 invisible lines follow).
851 Editing commands that operate on lines, such as @kbd{C-n} and
852 @kbd{C-p}, treat the text of the invisible line as part of the previous
853 visible line. Killing an entire visible line, including its terminating
854 newline, really kills all the following invisible lines along with it.
856 Outline minor mode provides the same commands as the major mode,
857 Outline mode, but you can use it in conjunction with other major modes.
858 Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in
859 the current buffer. You can also specify this in the text of a file,
860 with a file local variable of the form @samp{mode: outline-minor}
861 (@pxref{File Variables}).
863 @kindex C-c @@ @r{(Outline minor mode)}
864 The major mode, Outline mode, provides special key bindings on the
865 @kbd{C-c} prefix. Outline minor mode provides similar bindings with
866 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
867 major mode's special commands. (The variable
868 @code{outline-minor-mode-prefix} controls the prefix used.)
870 @vindex outline-mode-hook
871 Entering Outline mode runs the hook @code{text-mode-hook} followed by
872 the hook @code{outline-mode-hook} (@pxref{Hooks}).
875 * Format: Outline Format. What the text of an outline looks like.
876 * Motion: Outline Motion. Special commands for moving through
878 * Visibility: Outline Visibility. Commands to control what is visible.
879 * Views: Outline Views. Outlines and multiple views.
880 * Foldout:: Folding editing.
884 @subsection Format of Outlines
886 @cindex heading lines (Outline mode)
887 @cindex body lines (Outline mode)
888 Outline mode assumes that the lines in the buffer are of two types:
889 @dfn{heading lines} and @dfn{body lines}. A heading line represents a
890 topic in the outline. Heading lines start with one or more stars; the
891 number of stars determines the depth of the heading in the outline
892 structure. Thus, a heading line with one star is a major topic; all the
893 heading lines with two stars between it and the next one-star heading
894 are its subtopics; and so on. Any line that is not a heading line is a
895 body line. Body lines belong with the preceding heading line. Here is
901 which says something about the topic of food.
904 This is the body of the second-level header.
914 Another first-level topic with its header line.
917 A heading line together with all following body lines is called
918 collectively an @dfn{entry}. A heading line together with all following
919 deeper heading lines and their body lines is called a @dfn{subtree}.
921 @vindex outline-regexp
922 You can customize the criterion for distinguishing heading lines
923 by setting the variable @code{outline-regexp}. Any line whose
924 beginning has a match for this regexp is considered a heading line.
925 Matches that start within a line (not at the left margin) do not count.
926 The length of the matching text determines the level of the heading;
927 longer matches make a more deeply nested level. Thus, for example,
928 if a text formatter has commands @samp{@@chapter}, @samp{@@section}
929 and @samp{@@subsection} to divide the document into chapters and
930 sections, you could make those lines count as heading lines by
931 setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}.
932 Note the trick: the two words @samp{chapter} and @samp{section} are equally
933 long, but by defining the regexp to match only @samp{chap} we ensure
934 that the length of the text matched on a chapter heading is shorter,
935 so that Outline mode will know that sections are contained in chapters.
936 This works as long as no other command starts with @samp{@@chap}.
938 @vindex outline-level
939 It is possible to change the rule for calculating the level of a
940 heading line by setting the variable @code{outline-level}. The value of
941 @code{outline-level} should be a function that takes no arguments and
942 returns the level of the current heading. Some major modes such as C,
943 Nroff, and Emacs Lisp mode set this variable and/or
944 @code{outline-regexp} in order to work with Outline minor mode.
947 @subsection Outline Motion Commands
949 Outline mode provides special motion commands that move backward and
950 forward to heading lines.
954 Move point to the next visible heading line
955 (@code{outline-next-visible-heading}).
957 Move point to the previous visible heading line
958 (@code{outline-previous-visible-heading}).
960 Move point to the next visible heading line at the same level
961 as the one point is on (@code{outline-forward-same-level}).
963 Move point to the previous visible heading line at the same level
964 (@code{outline-backward-same-level}).
966 Move point up to a lower-level (more inclusive) visible heading line
967 (@code{outline-up-heading}).
970 @findex outline-next-visible-heading
971 @findex outline-previous-visible-heading
972 @kindex C-c C-n @r{(Outline mode)}
973 @kindex C-c C-p @r{(Outline mode)}
974 @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next
975 heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves
976 similarly backward. Both accept numeric arguments as repeat counts. The
977 names emphasize that invisible headings are skipped, but this is not really
978 a special feature. All editing commands that look for lines ignore the
979 invisible lines automatically.@refill
981 @findex outline-up-heading
982 @findex outline-forward-same-level
983 @findex outline-backward-same-level
984 @kindex C-c C-f @r{(Outline mode)}
985 @kindex C-c C-b @r{(Outline mode)}
986 @kindex C-c C-u @r{(Outline mode)}
987 More powerful motion commands understand the level structure of headings.
988 @kbd{C-c C-f} (@code{outline-forward-same-level}) and
989 @kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
990 heading line to another visible heading at the same depth in
991 the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves
992 backward to another heading that is less deeply nested.
994 @node Outline Visibility
995 @subsection Outline Visibility Commands
997 The other special commands of outline mode are used to make lines visible
998 or invisible. Their names all start with @code{hide} or @code{show}.
999 Most of them fall into pairs of opposites. They are not undoable; instead,
1000 you can undo right past them. Making lines visible or invisible is simply
1001 not recorded by the undo mechanism.
1005 Make all body lines in the buffer invisible (@code{hide-body}).
1007 Make all lines in the buffer visible (@code{show-all}).
1009 Make everything under this heading invisible, not including this
1010 heading itself (@code{hide-subtree}).
1012 Make everything under this heading visible, including body,
1013 subheadings, and their bodies (@code{show-subtree}).
1015 Make the body of this heading line, and of all its subheadings,
1016 invisible (@code{hide-leaves}).
1018 Make all subheadings of this heading line, at all levels, visible
1019 (@code{show-branches}).
1021 Make immediate subheadings (one level down) of this heading line
1022 visible (@code{show-children}).
1024 Make this heading line's body invisible (@code{hide-entry}).
1026 Make this heading line's body visible (@code{show-entry}).
1028 Hide everything except the top @var{n} levels of heading lines
1029 (@code{hide-sublevels}).
1031 Hide everything except for the heading or body that point is in, plus
1032 the headings leading up from there to the top level of the outline
1033 (@code{hide-other}).
1038 @kindex C-c C-c @r{(Outline mode)}
1039 @kindex C-c C-e @r{(Outline mode)}
1040 Two commands that are exact opposites are @kbd{C-c C-c}
1041 (@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They are
1042 used with point on a heading line, and apply only to the body lines of
1043 that heading. Subheadings and their bodies are not affected.
1045 @findex hide-subtree
1046 @findex show-subtree
1047 @kindex C-c C-s @r{(Outline mode)}
1048 @kindex C-c C-d @r{(Outline mode)}
1049 @cindex subtree (Outline mode)
1050 Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) and
1051 @kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is
1052 on a heading line, and both apply to all the lines of that heading's
1053 @dfn{subtree}: its body, all its subheadings, both direct and indirect, and
1054 all of their bodies. In other words, the subtree contains everything
1055 following this heading line, up to and not including the next heading of
1056 the same or higher rank.@refill
1059 @findex show-branches
1060 @kindex C-c C-l @r{(Outline mode)}
1061 @kindex C-c C-k @r{(Outline mode)}
1062 Intermediate between a visible subtree and an invisible one is having
1063 all the subheadings visible but none of the body. There are two
1064 commands for doing this, depending on whether you want to hide the
1065 bodies or make the subheadings visible. They are @kbd{C-c C-l}
1066 (@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}).
1068 @kindex C-c C-i @r{(Outline mode)}
1069 @findex show-children
1070 A little weaker than @code{show-branches} is @kbd{C-c C-i}
1071 (@code{show-children}). It makes just the direct subheadings
1072 visible---those one level down. Deeper subheadings remain invisible, if
1073 they were invisible.@refill
1077 @kindex C-c C-t @r{(Outline mode)}
1078 @kindex C-c C-a @r{(Outline mode)}
1079 Two commands have a blanket effect on the whole file. @kbd{C-c C-t}
1080 (@code{hide-body}) makes all body lines invisible, so that you see just
1081 the outline structure. @kbd{C-c C-a} (@code{show-all}) makes all lines
1082 visible. These commands can be thought of as a pair of opposites even
1083 though @kbd{C-c C-a} applies to more than just body lines.
1085 @findex hide-sublevels
1086 @kindex C-c C-q @r{(Outline mode)}
1087 The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the
1088 top level headings. With a numeric argument @var{n}, it hides everything
1089 except the top @var{n} levels of heading lines.
1092 @kindex C-c C-o @r{(Outline mode)}
1093 The command @kbd{C-c C-o} (@code{hide-other}) hides everything except
1094 the heading or body text that point is in, plus its parents (the headers
1095 leading up from there to top level in the outline).
1097 You can turn off the use of ellipses at the ends of visible lines by
1098 setting @code{selective-display-ellipses} to @code{nil}. Then there is
1099 no visible indication of the presence of invisible lines.
1101 When incremental search finds text that is hidden by Outline mode,
1102 it makes that part of the buffer visible. If you exit the search
1103 at that position, the text remains visible.
1106 @subsection Viewing One Outline in Multiple Views
1108 @cindex multiple views of outline
1109 @cindex views of an outline
1110 @cindex outline with multiple views
1111 @cindex indirect buffers and outlines
1112 You can display two views of a single outline at the same time, in
1113 different windows. To do this, you must create an indirect buffer using
1114 @kbd{M-x make-indirect-buffer}. The first argument of this command is
1115 the existing outline buffer name, and its second argument is the name to
1116 use for the new indirect buffer. @xref{Indirect Buffers}.
1118 Once the indirect buffer exists, you can display it in a window in the
1119 normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline
1120 mode commands to show and hide parts of the text operate on each buffer
1121 independently; as a result, each buffer can have its own view. If you
1122 want more than two views on the same outline, create additional indirect
1126 @subsection Folding editing
1128 @cindex folding editing
1129 The Foldout package provides folding editor extensions for Outline mode
1130 and Outline minor mode. It may be used by putting in your @file{.emacs}
1133 (eval-after-load "outline" '(require 'foldout))
1137 Folding editing works as follows.
1139 Consider an Outline mode buffer all the text and subheadings under
1140 level-1 headings hidden. To look at what is hidden under one of these
1141 headings normally you would use @kbd{C-c C-e} (@kbd{M-x show-entry}) to
1142 expose the body or @kbd{C-c C-i} to expose the child (level-2) headings.
1145 @findex foldout-zoom-subtree
1146 With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1147 This exposes the body and child subheadings and narrows the buffer so
1148 that only the level-1 heading, the body and the level-2 headings are
1149 visible. Now to look under one of the level-2 headings, position the
1150 cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body
1151 and its level-3 child subheadings and narrows the buffer again. Zooming
1152 in on successive subheadings can be done as much as you like. A string
1153 in the modeline shows how deep you've gone.
1155 When zooming in on a heading, to see only the child subheadings specify
1156 a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children
1157 can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2
1158 C-c C-z} exposes two levels of child subheadings. Alternatively, the
1159 body can be spcified with a negative argument: @kbd{M-- C-c C-z}. The
1160 whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x
1161 show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}.
1163 While you're zoomed in you can still use outline-mode's exposure and
1164 hiding functions without disturbing Foldout. Also, since the buffer is
1165 narrowed, `global' editing actions will only affect text under the
1166 zoomed-in heading. This is useful for restricting changes to a
1167 particular chapter or section of your document.
1170 @findex foldout-exit-fold
1171 Unzoom (exit) a fold using @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1172 This hides all the text and subheadings under the top-level heading and
1173 returns you to the previous view of the buffer. Specifying a numeric
1174 argument exits that many folds. Specifying a zero argument exits all
1177 You might want to exit a fold without hiding the text and subheadings,
1178 specify a negative argument. For example, @kbd{M--2 C-c C-x} exits two
1179 folds and leaves the text and subheadings exposed.
1181 Foldout provides mouse bindings for entering and exiting folds and for
1182 showing and hiding text as follows:
1184 @item @kbd{M-C-mouse-1} zooms in on the heading clicked on
1191 expose body and subheadings
1193 expose entire subtree
1195 @item @kbd{M-C-mouse-2} exposes text under the heading clicked on
1202 expose body and subheadings
1204 expose entire subtree
1206 @item @kbd{M-C-mouse-3} hides text under the heading clicked on or exits fold
1211 exit fold and hide text
1213 exit fold without hiding text
1215 exit all folds and hide text
1219 @vindex foldout-mouse-modifiers
1220 You can change the modifier keys used by setting
1221 @code{foldout-mouse-modifiers}.
1223 @node TeX Mode, Nroff Mode, Outline Mode, Text
1224 @section @TeX{} Mode
1226 @cindex La@TeX{} mode
1227 @cindex Sli@TeX{} mode
1228 @cindex mode, @TeX{}
1229 @cindex mode, La@TeX{}
1230 @cindex mode, Sli@TeX{}
1232 @findex plain-tex-mode
1236 @TeX{} is a powerful text formatter written by Donald Knuth; it is also
1237 free, like GNU Emacs. La@TeX{} is a simplified input format for @TeX{},
1238 implemented by @TeX{} macros; it comes with @TeX{}. Sli@TeX{} is a special
1239 form of La@TeX{}.@footnote{Sli@TeX{} is obsoleted by the @samp{slides}
1240 document class in recent La@TeX{} versions.}
1242 Emacs has a special @TeX{} mode for editing @TeX{} input files.
1243 It provides facilities for checking the balance of delimiters and for
1244 invoking @TeX{} on all or part of the file.
1246 @vindex tex-default-mode
1247 @TeX{} mode has three variants, Plain @TeX{} mode, La@TeX{} mode, and
1248 Sli@TeX{} mode (these three distinct major modes differ only slightly).
1249 They are designed for editing the three different formats. The command
1250 @kbd{M-x tex-mode} looks at the contents of the buffer to determine
1251 whether the contents appear to be either La@TeX{} input or Sli@TeX{}
1252 input; if so, it selects the appropriate mode. If the file contents do
1253 not appear to be La@TeX{} or Sli@TeX{}, it selects Plain @TeX{} mode.
1254 If the contents are insufficient to determine this, the variable
1255 @code{tex-default-mode} controls which mode is used.
1257 When @kbd{M-x tex-mode} does not guess right, you can use the commands
1258 @kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, and @kbd{M-x
1259 slitex-mode} to select explicitly the particular variants of @TeX{}
1262 @vindex tex-shell-hook
1263 @vindex tex-mode-hook
1264 @vindex latex-mode-hook
1265 @vindex slitex-mode-hook
1266 @vindex plain-tex-mode-hook
1267 Entering any kind of @TeX{} mode runs the hooks @code{text-mode-hook}
1268 and @code{tex-mode-hook}. Then it runs either
1269 @code{plain-tex-mode-hook} or @code{latex-mode-hook}, whichever is
1270 appropriate. For Sli@TeX{} files, it calls @code{slitex-mode-hook}.
1271 Starting the @TeX{} shell runs the hook @code{tex-shell-hook}.
1276 @findex iso-iso2gtex
1277 @findex iso-gtex2iso
1278 @cindex Latin-1 @TeX{} encoding
1280 @vindex format-alist
1281 @findex format-find-file
1282 The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1283 iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert between
1284 Latin-1 encoded files and @TeX{}-encoded equivalents. They are included
1285 by default in the @code{format-alist} variable, and so an be used with
1286 @kbd{M-x format-find-file}, for instance.
1288 @findex tildify-buffer
1289 @findex tildify-region
1290 @cindex ties, @TeX{}, inserting
1291 @cindex hard spaces, @TeX{}, inserting
1294 The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region} can
1295 be used to insert missing @samp{~} @dfn{tie} characters which should be
1296 present in the file to represent `hard spaces'. This is set up for
1297 Czech---customize the group @samp{tildify} for other languages or for
1298 other sorts of markup; there is support for SGML (HTML).
1300 @cindex RefTeX package
1301 @cindex references, La@TeX{}
1302 @cindex La@TeX{} references
1303 For managing all kinds of references for La@TeX{}, you can use
1304 Ref@TeX{}. @xref{Top, , RefTeX, reftex}.
1306 @cindex Bib@TeX{} mode
1307 @cindex mode, Bib@TeX{}
1310 There is also a mode for editing files for the Bib@TeX{} bibliography
1311 program often used with La@TeX{}.
1314 * Editing: TeX Editing. Special commands for editing in TeX mode.
1315 * LaTeX: LaTeX Editing. Additional commands for LaTeX input files.
1316 * Printing: TeX Print. Commands for printing part of a file with TeX.
1320 @subsection @TeX{} Editing Commands
1322 Here are the special commands provided in @TeX{} mode for editing the
1327 Insert, according to context, either @samp{``} or @samp{"} or
1328 @samp{''} (@code{tex-insert-quote}).
1330 Insert a paragraph break (two newlines) and check the previous
1331 paragraph for unbalanced braces or dollar signs
1332 (@code{tex-terminate-paragraph}).
1333 @item M-x tex-validate-region
1334 Check each paragraph in the region for unbalanced braces or dollar signs.
1336 Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1338 Move forward past the next unmatched close brace (@code{up-list}).
1341 @findex tex-insert-quote
1342 @kindex " @r{(@TeX{} mode)}
1343 In @TeX{}, the character @samp{"} is not normally used; we use
1344 @samp{``} to start a quotation and @samp{''} to end one. To make
1345 editing easier under this formatting convention, @TeX{} mode overrides
1346 the normal meaning of the key @kbd{"} with a command that inserts a pair
1347 of single-quotes or backquotes (@code{tex-insert-quote}). To be
1348 precise, this command inserts @samp{``} after whitespace or an open
1349 brace, @samp{"} after a backslash, and @samp{''} after any other
1352 If you need the character @samp{"} itself in unusual contexts, use
1353 @kbd{C-q} to insert it. Also, @kbd{"} with a numeric argument always
1354 inserts that number of @samp{"} characters. You can turn off the
1355 feature of @kbd{"} expansion by eliminating that binding in the local
1356 map (@pxref{Key Bindings}).
1358 In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1359 understand the way @TeX{} math mode delimiters match. When you insert a
1360 @samp{$} that is meant to exit math mode, the position of the matching
1361 @samp{$} that entered math mode is displayed for a second. This is the
1362 same feature that displays the open brace that matches a close brace that
1363 is inserted. However, there is no way to tell whether a @samp{$} enters
1364 math mode or leaves it; so when you insert a @samp{$} that enters math
1365 mode, the previous @samp{$} position is shown as if it were a match, even
1366 though they are actually unrelated.
1368 @findex tex-insert-braces
1369 @kindex C-c @{ @r{(@TeX{} mode)}
1371 @kindex C-c @} @r{(@TeX{} mode)}
1372 @TeX{} uses braces as delimiters that must match. Some users prefer
1373 to keep braces balanced at all times, rather than inserting them
1374 singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1375 braces. It leaves point between the two braces so you can insert the
1376 text that belongs inside. Afterward, use the command @kbd{C-c @}}
1377 (@code{up-list}) to move forward past the close brace.
1379 @findex tex-validate-region
1380 @findex tex-terminate-paragraph
1381 @kindex C-j @r{(@TeX{} mode)}
1382 There are two commands for checking the matching of braces. @kbd{C-j}
1383 (@code{tex-terminate-paragraph}) checks the paragraph before point, and
1384 inserts two newlines to start a new paragraph. It prints a message in
1385 the echo area if any mismatch is found. @kbd{M-x tex-validate-region}
1386 checks a region, paragraph by paragraph. The errors are listed in the
1387 @samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in
1388 that buffer to go to a particular mismatch.
1390 Note that Emacs commands count square brackets and parentheses in
1391 @TeX{} mode, not just braces. This is not strictly correct for the
1392 purpose of checking @TeX{} syntax. However, parentheses and square
1393 brackets are likely to be used in text as matching delimiters and it is
1394 useful for the various motion commands and automatic match display to
1398 @subsection La@TeX{} Editing Commands
1400 La@TeX{} mode, and its variant, Sli@TeX{} mode, provide a few extra
1401 features not applicable to plain @TeX{}.
1405 Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position
1406 point on a line between them (@code{tex-latex-block}).
1408 Close the innermost La@TeX{} block not yet closed
1409 (@code{tex-close-latex-block}).
1412 @findex tex-latex-block
1413 @kindex C-c C-o @r{(La@TeX{} mode)}
1414 @vindex latex-block-names
1415 In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to
1416 group blocks of text. To insert a @samp{\begin} and a matching
1417 @samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c
1418 C-o} (@code{tex-latex-block}). A blank line is inserted between the
1419 two, and point is left there. You can use completion when you enter the
1420 block type; to specify additional block type names beyond the standard
1421 list, set the variable @code{latex-block-names}. For example, here's
1422 how to add @samp{theorem}, @samp{corollary}, and @samp{proof}:
1425 (setq latex-block-names '("theorem" "corollary" "proof"))
1428 @findex tex-close-latex-block
1429 @kindex C-c C-e @r{(La@TeX{} mode)}
1430 In La@TeX{} input, @samp{\begin} and @samp{\end} commands must
1431 balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to
1432 insert automatically a matching @samp{\end} to match the last unmatched
1433 @samp{\begin}. It indents the @samp{\end} to match the corresponding
1434 @samp{\begin}. It inserts a newline after @samp{\end} if point is at
1435 the beginning of a line.
1438 @subsection @TeX{} Printing Commands
1440 You can invoke @TeX{} as an inferior of Emacs on either the entire
1441 contents of the buffer or just a region at a time. Running @TeX{} in
1442 this way on just one chapter is a good way to see what your changes
1443 look like without taking the time to format the entire file.
1447 Invoke @TeX{} on the current region, together with the buffer's header
1448 (@code{tex-region}).
1450 Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1452 Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1454 Invoke @TeX{} on the current file (@code{tex-file}).
1456 Recenter the window showing output from the inferior @TeX{} so that
1457 the last line can be seen (@code{tex-recenter-output-buffer}).
1459 Kill the @TeX{} subprocess (@code{tex-kill-job}).
1461 Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1462 C-f} command (@code{tex-print}).
1464 Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1465 C-f} command (@code{tex-view}).
1467 Show the printer queue (@code{tex-show-print-queue}).
1471 @kindex C-c C-b @r{(@TeX{} mode)}
1473 @kindex C-c C-p @r{(@TeX{} mode)}
1475 @kindex C-c C-v @r{(@TeX{} mode)}
1476 @findex tex-show-print-queue
1477 @kindex C-c C-q @r{(@TeX{} mode)}
1478 You can pass the current buffer through an inferior @TeX{} by means of
1479 @kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a
1480 temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}).
1481 Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to
1482 view the progress of your output towards being printed. If your terminal
1483 has the ability to display @TeX{} output files, you can preview the
1484 output on the terminal with @kbd{C-c C-v} (@code{tex-view}).
1486 @cindex @env{TEXINPUTS} environment variable
1487 @vindex tex-directory
1488 You can specify the directory to use for running @TeX{} by setting the
1489 variable @code{tex-directory}. @code{"."} is the default value. If
1490 your environment variable @env{TEXINPUTS} contains relative directory
1491 names, or if your files contains @samp{\input} commands with relative
1492 file names, then @code{tex-directory} @emph{must} be @code{"."} or you
1493 will get the wrong results. Otherwise, it is safe to specify some other
1494 directory, such as @code{"/tmp"}.
1496 @vindex tex-run-command
1497 @vindex latex-run-command
1498 @vindex slitex-run-command
1499 @vindex tex-dvi-print-command
1500 @vindex tex-dvi-view-command
1501 @vindex tex-show-queue-command
1502 If you want to specify which shell commands are used in the inferior @TeX{},
1503 you can do so by setting the values of the variables @code{tex-run-command},
1504 @code{latex-run-command}, @code{slitex-run-command},
1505 @code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and
1506 @code{tex-show-queue-command}. You @emph{must} set the value of
1507 @code{tex-dvi-view-command} for your particular terminal; this variable
1508 has no default value. The other variables have default values that may
1509 (or may not) be appropriate for your system.
1511 Normally, the file name given to these commands comes at the end of
1512 the command string; for example, @samp{latex @var{filename}}. In some
1513 cases, however, the file name needs to be embedded in the command; an
1514 example is when you need to provide the file name as an argument to one
1515 command whose output is piped to another. You can specify where to put
1516 the file name with @samp{*} in the command string. For example,
1519 (setq tex-dvi-print-command "dvips -f * | lpr")
1522 @findex tex-kill-job
1523 @kindex C-c C-k @r{(@TeX{} mode)}
1524 @findex tex-recenter-output-buffer
1525 @kindex C-c C-l @r{(@TeX{} mode)}
1526 The terminal output from @TeX{}, including any error messages, appears
1527 in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can
1528 switch to this buffer and feed it input (this works as in Shell mode;
1529 @pxref{Interactive Shell}). Without switching to this buffer you can
1530 scroll it so that its last line is visible by typing @kbd{C-c
1533 Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1534 you see that its output is no longer useful. Using @kbd{C-c C-b} or
1535 @kbd{C-c C-r} also kills any @TeX{} process still running.@refill
1538 @kindex C-c C-r @r{(@TeX{} mode)}
1539 You can also pass an arbitrary region through an inferior @TeX{} by typing
1540 @kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files
1541 of @TeX{} input contain commands at the beginning to set parameters and
1542 define macros, without which no later part of the file will format
1543 correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a
1544 part of the file as containing essential commands; it is included before
1545 the specified region as part of the input to @TeX{}. The designated part
1546 of the file is called the @dfn{header}.
1548 @cindex header (@TeX{} mode)
1549 To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1550 special strings in the file. Insert @samp{%**start of header} before the
1551 header, and @samp{%**end of header} after it. Each string must appear
1552 entirely on one line, but there may be other text on the line before or
1553 after. The lines containing the two strings are included in the header.
1554 If @samp{%**start of header} does not appear within the first 100 lines of
1555 the buffer, @kbd{C-c C-r} assumes that there is no header.
1557 In La@TeX{} mode, the header begins with @samp{\documentclass} or
1558 @samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
1559 are commands that La@TeX{} requires you to use in any case, so nothing
1560 special needs to be done to identify the header.
1563 @kindex C-c C-f @r{(@TeX{} mode)}
1564 The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1565 work in a temporary directory, and do not have available any of the auxiliary
1566 files needed by @TeX{} for cross-references; these commands are generally
1567 not suitable for running the final copy in which all of the cross-references
1570 When you want the auxiliary files for cross references, use @kbd{C-c
1571 C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1572 in that file's directory. Before running @TeX{}, it offers to save any
1573 modified buffers. Generally, you need to use (@code{tex-file}) twice to
1574 get the cross-references right.
1576 @vindex tex-start-options-string
1577 The value of the variable @code{tex-start-options-string} specifies
1578 options for the @TeX{} run. The default value causes @TeX{} to run in
1579 nonstopmode. To run @TeX{} interactively, set the variable to @code{""}.
1581 @vindex tex-main-file
1582 Large @TeX{} documents are often split into several files---one main
1583 file, plus subfiles. Running @TeX{} on a subfile typically does not
1584 work; you have to run it on the main file. In order to make
1585 @code{tex-file} useful when you are editing a subfile, you can set the
1586 variable @code{tex-main-file} to the name of the main file. Then
1587 @code{tex-file} runs @TeX{} on that file.
1589 The most convenient way to use @code{tex-main-file} is to specify it
1590 in a local variable list in each of the subfiles. @xref{File
1593 @findex tex-bibtex-file
1594 @kindex C-c TAB @r{(@TeX{} mode)}
1595 @vindex tex-bibtex-command
1596 For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
1597 file for the current buffer's file. Bib@TeX{} looks up bibliographic
1598 citations in a data base and prepares the cited references for the
1599 bibliography section. The command @kbd{C-c TAB}
1600 (@code{tex-bibtex-file}) runs the shell command
1601 (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1602 current buffer's file. Generally, you need to do @kbd{C-c C-f}
1603 (@code{tex-file}) once to generate the @samp{.aux} file, then do
1604 @kbd{C-c TAB} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1605 (@code{tex-file}) twice more to get the cross-references correct.
1612 Nroff mode is a mode like Text mode but modified to handle nroff commands
1613 present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
1614 differs from Text mode in only a few ways. All nroff command lines are
1615 considered paragraph separators, so that filling will never garble the
1616 nroff commands. Pages are separated by @samp{.bp} commands. Comments
1617 start with backslash-doublequote. Also, three special commands are
1618 provided that are not in Text mode:
1620 @findex forward-text-line
1621 @findex backward-text-line
1622 @findex count-text-lines
1623 @kindex M-n @r{(Nroff mode)}
1624 @kindex M-p @r{(Nroff mode)}
1625 @kindex M-? @r{(Nroff mode)}
1628 Move to the beginning of the next line that isn't an nroff command
1629 (@code{forward-text-line}). An argument is a repeat count.
1631 Like @kbd{M-n} but move up (@code{backward-text-line}).
1633 Prints in the echo area the number of text lines (lines that are not
1634 nroff commands) in the region (@code{count-text-lines}).
1637 @findex electric-nroff-mode
1638 The other feature of Nroff mode is that you can turn on Electric Nroff
1639 mode. This is a minor mode that you can turn on or off with @kbd{M-x
1640 electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
1641 time you use @key{RET} to end a line that contains an nroff command that
1642 opens a kind of grouping, the matching nroff command to close that
1643 grouping is automatically inserted on the following line. For example,
1644 if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
1645 this inserts the matching command @samp{.)b} on a new line following
1648 If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
1649 heading lines are lines of the form @samp{.H} followed by a number (the
1652 @vindex nroff-mode-hook
1653 Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
1654 the hook @code{nroff-mode-hook} (@pxref{Hooks}).
1656 @node Formatted Text
1657 @section Editing Formatted Text
1659 @cindex Enriched mode
1660 @cindex mode, Enriched
1661 @cindex formatted text
1663 @cindex word processing
1664 @dfn{Enriched mode} is a minor mode for editing files that contain
1665 formatted text in WYSIWYG fashion, as in a word processor. Currently,
1666 formatted text in Enriched mode can specify fonts, colors, underlining,
1667 margins, and types of filling and justification. In the future, we plan
1668 to implement other formatting features as well.
1670 Enriched mode is a minor mode (@pxref{Minor Modes}). Typically it is
1671 used in conjunction with Text mode (@pxref{Text Mode}). However, you
1672 can also use it with other major modes such as Outline mode and
1673 Paragraph-Indent Text mode.
1675 @cindex text/enriched MIME format
1676 Potentially, Emacs can store formatted text files in various file
1677 formats. Currently, only one format is implemented: @dfn{text/enriched}
1678 format, which is defined by the MIME protocol. @xref{Format
1679 Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual},
1680 for details of how Emacs recognizes and converts file formats.
1682 The Emacs distribution contains a formatted text file that can serve as
1683 an example. Its name is @file{etc/enriched.doc}. It contains samples
1684 illustrating all the features described in this section. It also
1685 contains a list of ideas for future enhancements.
1688 * Requesting Formatted Text:: Entering and exiting Enriched mode.
1689 * Hard and Soft Newlines:: There are two different kinds of newlines.
1690 * Editing Format Info:: How to edit text properties.
1691 * Faces: Format Faces. Bold, italic, underline, etc.
1692 * Color: Format Colors. Changing the color of text.
1693 * Indent: Format Indentation. Changing the left and right margins.
1694 * Justification: Format Justification.
1695 Centering, setting text flush with the
1696 left or right margin, etc.
1697 * Other: Format Properties. The "special" text properties submenu.
1698 * Forcing Enriched Mode:: How to force use of Enriched mode.
1701 @node Requesting Formatted Text
1702 @subsection Requesting to Edit Formatted Text
1704 Whenever you visit a file that Emacs saved in the text/enriched format,
1705 Emacs automatically converts the formatting information in the file into
1706 Emacs's own internal format (text properties), and turns on Enriched
1709 @findex enriched-mode
1710 To create a new file of formatted text, first visit the nonexistent
1711 file, then type @kbd{M-x enriched-mode} before you start inserting text.
1712 This command turns on Enriched mode. Do this before you begin inserting
1713 text, to ensure that the text you insert is handled properly.
1715 More generally, the command @code{enriched-mode} turns Enriched mode
1716 on if it was off, and off if it was on. With a prefix argument, this
1717 command turns Enriched mode on if the argument is positive, and turns
1718 the mode off otherwise.
1720 When you save a buffer while Enriched mode is enabled in it, Emacs
1721 automatically converts the text to text/enriched format while writing it
1722 into the file. When you visit the file again, Emacs will automatically
1723 recognize the format, reconvert the text, and turn on Enriched mode
1726 @vindex enriched-fill-after-visiting
1727 Normally, after visiting a file in text/enriched format, Emacs refills
1728 each paragraph to fit the specified right margin. You can turn off this
1729 refilling, to save time, by setting the variable
1730 @code{enriched-fill-after-visiting} to @code{nil} or to @code{ask}.
1732 However, when visiting a file that was saved from Enriched mode, there
1733 is no need for refilling, because Emacs saves the right margin settings
1734 along with the text.
1736 @vindex enriched-translations
1737 You can add annotations for saving additional text properties, which
1738 Emacs normally does not save, by adding to @code{enriched-translations}.
1739 Note that the text/enriched standard requires any non-standard
1740 annotations to have names starting with @samp{x-}, as in
1741 @samp{x-read-only}. This ensures that they will not conflict with
1742 standard annotations that may be added later.
1744 @node Hard and Soft Newlines
1745 @subsection Hard and Soft Newlines
1746 @cindex hard newline
1747 @cindex soft newline
1748 @cindex newlines, hard and soft
1750 In formatted text, Emacs distinguishes between two different kinds of
1751 newlines, @dfn{hard} newlines and @dfn{soft} newlines.
1753 Hard newlines are used to separate paragraphs, or items in a list, or
1754 anywhere that there should always be a line break regardless of the
1755 margins. The @key{RET} command (@code{newline}) and @kbd{C-o}
1756 (@code{open-line}) insert hard newlines.
1758 Soft newlines are used to make text fit between the margins. All the
1759 fill commands, including Auto Fill, insert soft newlines---and they
1760 delete only soft newlines.
1762 Although hard and soft newlines look the same, it is important to bear
1763 the difference in mind. Do not use @key{RET} to break lines in the
1764 middle of filled paragraphs, or else you will get hard newlines that are
1765 barriers to further filling. Instead, let Auto Fill mode break lines,
1766 so that if the text or the margins change, Emacs can refill the lines
1767 properly. @xref{Auto Fill}.
1769 On the other hand, in tables and lists, where the lines should always
1770 remain as you type them, you can use @key{RET} to end lines. For these
1771 lines, you may also want to set the justification style to
1772 @code{unfilled}. @xref{Format Justification}.
1774 @node Editing Format Info
1775 @subsection Editing Format Information
1777 There are two ways to alter the formatting information for a formatted
1778 text file: with keyboard commands, and with the mouse.
1780 The easiest way to add properties to your document is by using the Text
1781 Properties menu. You can get to this menu in two ways: from the Edit
1782 menu in the menu bar, or with @kbd{C-mouse-2} (hold the @key{CTRL} key
1783 and press the middle mouse button).
1785 Most of the items in the Text Properties menu lead to other submenus.
1786 These are described in the sections that follow. Some items run
1790 @findex facemenu-remove-props
1791 @item Remove Properties
1792 Delete from the region all the text properties that the Text Properties
1793 menu works with (@code{facemenu-remove-props}).
1795 @findex facemenu-remove-all
1797 Delete @emph{all} text properties from the region
1798 (@code{facemenu-remove-all}).
1800 @findex list-text-properties-at
1801 @item List Properties
1802 List all the text properties of the character following point
1803 (@code{list-text-properties-at}).
1806 Display a list of all the defined faces.
1808 @item Display Colors
1809 Display a list of all the defined colors.
1813 @subsection Faces in Formatted Text
1815 The Faces submenu lists various Emacs faces including @code{bold},
1816 @code{italic}, and @code{underline}. Selecting one of these adds the
1817 chosen face to the region. @xref{Faces}. You can also specify a face
1818 with these keyboard commands:
1821 @kindex M-g d @r{(Enriched mode)}
1822 @findex facemenu-set-default
1824 Set the region, or the next inserted character, to the @code{default} face
1825 (@code{facemenu-set-default}).
1826 @kindex M-g b @r{(Enriched mode)}
1827 @findex facemenu-set-bold
1829 Set the region, or the next inserted character, to the @code{bold} face
1830 (@code{facemenu-set-bold}).
1831 @kindex M-g i @r{(Enriched mode)}
1832 @findex facemenu-set-italic
1834 Set the region, or the next inserted character, to the @code{italic} face
1835 (@code{facemenu-set-italic}).
1836 @kindex M-g l @r{(Enriched mode)}
1837 @findex facemenu-set-bold-italic
1839 Set the region, or the next inserted character, to the @code{bold-italic} face
1840 (@code{facemenu-set-bold-italic}).
1841 @kindex M-g u @r{(Enriched mode)}
1842 @findex facemenu-set-underline
1844 Set the region, or the next inserted character, to the @code{underline} face
1845 (@code{facemenu-set-underline}).
1846 @kindex M-g o @r{(Enriched mode)}
1847 @findex facemenu-set-face
1848 @item M-g o @var{face} @key{RET}
1849 Set the region, or the next inserted character, to the face @var{face}
1850 (@code{facemenu-set-face}).
1853 If you use these commands with a prefix argument---or, in Transient Mark
1854 mode, if the region is not active---then these commands specify a face
1855 to use for your next self-inserting input. @xref{Transient Mark}. This
1856 applies to both the keyboard commands and the menu commands.
1858 Enriched mode defines two additional faces: @code{excerpt} and
1859 @code{fixed}. These correspond to codes used in the text/enriched file
1862 The @code{excerpt} face is intended for quotations. This face is the
1863 same as @code{italic} unless you customize it (@pxref{Face Customization}).
1865 The @code{fixed} face is meant to say, ``Use a fixed-width font for this
1866 part of the text.'' Emacs currently supports only fixed-width fonts;
1867 therefore, the @code{fixed} annotation is not necessary now. However,
1868 we plan to support variable width fonts in future Emacs versions, and
1869 other systems that display text/enriched format may not use a
1870 fixed-width font as the default. So if you specifically want a certain
1871 part of the text to use a fixed-width font, you should specify the
1872 @code{fixed} face for that part.
1874 The @code{fixed} face is normally defined to use a different font from
1875 the default. However, different systems have different fonts installed,
1876 so you may need to customize this.
1878 If your terminal cannot display different faces, you will not be able
1879 to see them, but you can still edit documents containing faces. You can
1880 even add faces and colors to documents. They will be visible when the
1881 file is viewed on a terminal that can display them.
1884 @subsection Colors in Formatted Text
1886 You can specify foreground and background colors for portions of the
1887 text. There is a menu for specifying the foreground color and a menu
1888 for specifying the background color. Each color menu lists all the
1889 colors that you have used in Enriched mode in the current Emacs session.
1891 If you specify a color with a prefix argument---or, in Transient Mark
1892 mode, if the region is not active---then it applies to your next
1893 self-inserting input. @xref{Transient Mark}. Otherwise, the command
1894 applies to the region.
1896 Each color menu contains one additional item: @samp{Other}. You can use
1897 this item to specify a color that is not listed in the menu; it reads
1898 the color name with the minibuffer. To display list of available colors
1899 and their names, use the @samp{Display Colors} menu item in the Text
1900 Properties menu (@pxref{Editing Format Info}).
1902 Any color that you specify in this way, or that is mentioned in a
1903 formatted text file that you read in, is added to both color menus for
1904 the duration of the Emacs session.
1906 @findex facemenu-set-foreground
1907 @findex facemenu-set-background
1908 There are no key bindings for specifying colors, but you can do so
1909 with the extended commands @kbd{M-x facemenu-set-foreground} and
1910 @kbd{M-x facemenu-set-background}. Both of these commands read the name
1911 of the color with the minibuffer.
1913 @node Format Indentation
1914 @subsection Indentation in Formatted Text
1916 When editing formatted text, you can specify different amounts of
1917 indentation for the right or left margin of an entire paragraph or a
1918 part of a paragraph. The margins you specify automatically affect the
1919 Emacs fill commands (@pxref{Filling}) and line-breaking commands.
1921 The Indentation submenu provides a convenient interface for specifying
1922 these properties. The submenu contains four items:
1925 @kindex C-x TAB @r{(Enriched mode)}
1926 @findex increase-left-margin
1928 Indent the region by 4 columns (@code{increase-left-margin}). In
1929 Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
1930 you supply a numeric argument, that says how many columns to add to the
1931 margin (a negative argument reduces the number of columns).
1934 Remove 4 columns of indentation from the region.
1936 @item Indent Right More
1937 Make the text narrower by indenting 4 columns at the right margin.
1939 @item Indent Right Less
1940 Remove 4 columns of indentation from the right margin.
1943 You can use these commands repeatedly to increase or decrease the
1946 The most common way to use these commands is to change the indentation
1947 of an entire paragraph. However, that is not the only use. You can
1948 change the margins at any point; the new values take effect at the end
1949 of the line (for right margins) or the beginning of the next line (for
1952 This makes it possible to format paragraphs with @dfn{hanging indents},
1953 which means that the first line is indented less than subsequent lines.
1954 To set up a hanging indent, increase the indentation of the region
1955 starting after the first word of the paragraph and running until the end
1958 Indenting the first line of a paragraph is easier. Set the margin for
1959 the whole paragraph where you want it to be for the body of the
1960 paragraph, then indent the first line by inserting extra spaces or tabs.
1962 Sometimes, as a result of editing, the filling of a paragraph becomes
1963 messed up---parts of the paragraph may extend past the left or right
1964 margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to
1965 refill the paragraph.
1967 @vindex standard-indent
1968 The variable @code{standard-indent} specifies how many columns these
1969 commands should add to or subtract from the indentation. The default
1970 value is 4. The overall default right margin for Enriched mode is
1971 controlled by the variable @code{fill-column}, as usual.
1973 The fill prefix, if any, works in addition to the specified paragraph
1974 indentation: @kbd{C-x .} does not include the specified indentation's
1975 whitespace in the new value for the fill prefix, and the fill commands
1976 look for the fill prefix after the indentation on each line. @xref{Fill
1979 @node Format Justification
1980 @subsection Justification in Formatted Text
1982 When editing formatted text, you can specify various styles of
1983 justification for a paragraph. The style you specify automatically
1984 affects the Emacs fill commands.
1986 The Justification submenu provides a convenient interface for specifying
1987 the style. The submenu contains five items:
1991 This is the most common style of justification (at least for English).
1992 Lines are aligned at the left margin but left uneven at the right.
1995 This aligns each line with the right margin. Spaces and tabs are added
1996 on the left, if necessary, to make lines line up on the right.
1999 This justifies the text, aligning both edges of each line. Justified
2000 text looks very nice in a printed book, where the spaces can all be
2001 adjusted equally, but it does not look as nice with a fixed-width font
2002 on the screen. Perhaps a future version of Emacs will be able to adjust
2003 the width of spaces in a line to achieve elegant justification.
2006 This centers every line between the current margins.
2009 This turns off filling entirely. Each line will remain as you wrote it;
2010 the fill and auto-fill functions will have no effect on text which has
2011 this setting. You can, however, still indent the left margin. In
2012 unfilled regions, all newlines are treated as hard newlines (@pxref{Hard
2013 and Soft Newlines}) .
2016 In Enriched mode, you can also specify justification from the keyboard
2017 using the @kbd{M-j} prefix character:
2020 @kindex M-j l @r{(Enriched mode)}
2021 @findex set-justification-left
2023 Make the region left-filled (@code{set-justification-left}).
2024 @kindex M-j r @r{(Enriched mode)}
2025 @findex set-justification-right
2027 Make the region right-filled (@code{set-justification-right}).
2028 @kindex M-j f @r{(Enriched mode)}
2029 @findex set-justification-full
2031 Make the region fully-justified (@code{set-justification-full}).
2032 @kindex M-j c @r{(Enriched mode)}
2033 @kindex M-S @r{(Enriched mode)}
2034 @findex set-justification-center
2037 Make the region centered (@code{set-justification-center}).
2038 @kindex M-j u @r{(Enriched mode)}
2039 @findex set-justification-none
2041 Make the region unfilled (@code{set-justification-none}).
2044 Justification styles apply to entire paragraphs. All the
2045 justification-changing commands operate on the paragraph containing
2046 point, or, if the region is active, on all paragraphs which overlap the
2049 @vindex default-justification
2050 The default justification style is specified by the variable
2051 @code{default-justification}. Its value should be one of the symbols
2052 @code{left}, @code{right}, @code{full}, @code{center}, or @code{none}.
2054 @node Format Properties
2055 @subsection Setting Other Text Properties
2057 The Other Properties menu lets you add or remove three other useful text
2058 properties: @code{read-only}, @code{invisible} and @code{intangible}.
2059 The @code{intangible} property disallows moving point within the text,
2060 the @code{invisible} text property hides text from display, and the
2061 @code{read-only} property disallows alteration of the text.
2063 Each of these special properties has a menu item to add it to the
2064 region. The last menu item, @samp{Remove Special}, removes all of these
2065 special properties from the text in the region.
2067 Currently, the @code{invisible} and @code{intangible} properties are
2068 @emph{not} saved in the text/enriched format. The @code{read-only}
2069 property is saved, but it is not a standard part of the text/enriched
2070 format, so other editors may not respect it.
2072 @node Forcing Enriched Mode
2073 @subsection Forcing Enriched Mode
2075 Normally, Emacs knows when you are editing formatted text because it
2076 recognizes the special annotations used in the file that you visited.
2077 However, there are situations in which you must take special actions
2078 to convert file contents or turn on Enriched mode:
2082 When you visit a file that was created with some other editor, Emacs may
2083 not recognize the file as being in the text/enriched format. In this
2084 case, when you visit the file you will see the formatting commands
2085 rather than the formatted text. Type @kbd{M-x format-decode-buffer} to
2089 When you @emph{insert} a file into a buffer, rather than visiting it.
2090 Emacs does the necessary conversions on the text which you insert, but
2091 it does not enable Enriched mode. If you wish to do that, type @kbd{M-x
2095 The command @code{format-decode-buffer} translates text in various
2096 formats into Emacs's internal format. It asks you to specify the format
2097 to translate from; however, normally you can type just @key{RET}, which
2098 tells Emacs to guess the format.
2100 @findex format-find-file
2101 If you wish to look at text/enriched file in its raw form, as a
2102 sequence of characters rather than as formatted text, use the @kbd{M-x
2103 find-file-literally} command. This visits a file, like
2104 @code{find-file}, but does not do format conversion. It also inhibits
2105 character code conversion (@pxref{Coding Systems}) and automatic
2106 uncompression (@pxref{Compressed Files}). To disable format conversion
2107 but allow character code conversion and/or automatic uncompression if
2108 appropriate, use @code{format-find-file} with suitable arguments.