*** empty log message ***
[emacs.git] / man / text.texi
blobcd0c13e3d31312e0f93c49ece2adee3f7a6bc0d9
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
7 @cindex text
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
30 structure.
31 @iftex
32 @xref{Outline Mode}.
33 @end iftex
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{}
38 @iftex
39 mode (@pxref{TeX Mode}).
40 @end iftex
41 @ifinfo
42 mode.
43 @end ifinfo
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.
49 @iftex
50 @xref{Formatted Text}.
51 @end iftex
53   The `automatic typing' features may be useful when writing text.
54 @xref{Top, Autotyping, autotype, Features for Automatic Typing}.
56 @menu
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.
68 @end menu
70 @node Words
71 @section Words
72 @cindex words
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.
78 @c widecommands
79 @table @kbd
80 @item M-f
81 Move forward over a word (@code{forward-word}).
82 @item M-b
83 Move backward over a word (@code{backward-word}).
84 @item M-d
85 Kill up to the end of a word (@code{kill-word}).
86 @item M-@key{DEL}
87 Kill back to the beginning of a word (@code{backward-kill-word}).
88 @item M-@@
89 Mark the end of the next word (@code{mark-word}).
90 @item M-t
91 Transpose two words or drag a word across other words
92 (@code{transpose-words}).
93 @end table
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}}.
99 @kindex M-f
100 @kindex M-b
101 @findex forward-word
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
113 @kindex M-d
114 @findex kill-word
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
125 @kindex M-DEL
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
131 @kbd{M-@key{DEL}}.)
133 @kindex M-t
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.
141 @kindex M-@@
142 @findex mark-word
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
149 activates the mark.
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}.
155 @node Sentences
156 @section Sentences
157 @cindex sentences
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.
163 @table @kbd
164 @item M-a
165 Move back to the beginning of the sentence (@code{backward-sentence}).
166 @item M-e
167 Move forward to the end of the sentence (@code{forward-sentence}).
168 @item M-k
169 Kill forward to the end of the sentence (@code{kill-sentence}).
170 @item C-x @key{DEL}
171 Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
172 @end table
174 @kindex M-a
175 @kindex M-e
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.
190 @kindex M-k
191 @kindex C-x DEL
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.
211 @vindex sentence-end
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
215 normal value is
217 @example
218 "[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"
219 @end example
221 @noindent
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:
227 @example
228 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
229 @end example
231 @noindent
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
236 abbreviations.
238 @node Paragraphs
239 @section Paragraphs
240 @cindex paragraphs
241 @cindex manipulating paragraphs
242 @kindex M-@{
243 @kindex M-@}
244 @findex backward-paragraph
245 @findex forward-paragraph
247   The Emacs commands for manipulating paragraphs are also Meta keys.
249 @table @kbd
250 @item M-@{
251 Move back to previous paragraph beginning (@code{backward-paragraph}).
252 @item M-@}
253 Move forward to next paragraph end (@code{forward-paragraph}).
254 @item M-h
255 Put point and mark around this or next paragraph (@code{mark-paragraph}).
256 @end table
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}.
273 @kindex M-h
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
301 pages.
303 @node Pages
304 @section Pages
306 @cindex pages
307 @cindex formfeed
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.
318 @c WideCommands
319 @table @kbd
320 @item C-x [
321 Move point to previous page boundary (@code{backward-page}).
322 @item C-x ]
323 Move point to next page boundary (@code{forward-page}).
324 @item C-x C-p
325 Put point and mark around this page (or another page) (@code{mark-page}).
326 @item C-x l
327 Count the lines in this page (@code{count-lines-page}).
328 @end table
330 @kindex C-x [
331 @kindex C-x ]
332 @findex forward-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.
340 @kindex C-x C-p
341 @findex mark-page
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.
356 @kindex C-x l
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
363 @example
364 Page has 96 (72+25) lines
365 @end example
367 @noindent
368   Notice that the sum is off by one; this is correct if point is not at the
369 beginning of a line.
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.
377 @node Filling
378 @section Filling Text
379 @cindex 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
387 Text}).
389 @menu
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.
395 * Refill::              Keeping paragraphs filled.
396 @end menu
398 @node Auto Fill
399 @subsection Auto Fill Mode
400 @cindex Auto Fill mode
401 @cindex mode, Auto Fill
402 @cindex word wrap
404   @dfn{Auto Fill} mode is a minor mode in which lines are broken
405 automatically when they become too wide.  Breaking happens only when
406 you type a @key{SPC} or @key{RET}.
408 @table @kbd
409 @item M-x auto-fill-mode
410 Enable or disable Auto Fill mode.
411 @item @key{SPC}
412 @itemx @key{RET}
413 In Auto Fill mode, break lines when appropriate.
414 @end table
416 @findex auto-fill-mode
417   @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off
418 if it was on.  With a positive numeric argument it always turns Auto
419 Fill mode on, and with a negative argument always turns it off.  You can
420 see when Auto Fill mode is in effect by the presence of the word
421 @samp{Fill} in the mode line, inside the parentheses.  Auto Fill mode is
422 a minor mode which is enabled or disabled for each buffer individually.
423 @xref{Minor Modes}.
425   In Auto Fill mode, lines are broken automatically at spaces when they
426 get longer than the desired width.  Line breaking and rearrangement
427 takes place only when you type @key{SPC} or @key{RET}.  If you wish to
428 insert a space or newline without permitting line-breaking, type
429 @kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a
430 control-J).  Also, @kbd{C-o} inserts a newline without line breaking.
432   Auto Fill mode works well with programming-language modes, because it
433 indents new lines with @key{TAB}.  If a line ending in a comment gets
434 too long, the text of the comment is split into two comment lines.
435 Optionally, new comment delimiters are inserted at the end of the first
436 line and the beginning of the second so that each line is a separate
437 comment; the variable @code{comment-multi-line} controls the choice
438 (@pxref{Comments}).
440   Adaptive filling (see the following section) works for Auto Filling as
441 well as for explicit fill commands.  It takes a fill prefix
442 automatically from the second or first line of a paragraph.
444   Auto Fill mode does not refill entire paragraphs; it can break lines but
445 cannot merge lines.  So editing in the middle of a paragraph can result in
446 a paragraph that is not correctly filled.  The easiest way to make the
447 paragraph properly filled again is usually with the explicit fill commands.
448 @ifinfo
449 @xref{Fill Commands}.
450 @end ifinfo
452   Many users like Auto Fill mode and want to use it in all text files.
453 The section on init files says how to arrange this permanently for yourself.
454 @xref{Init File}.
456 @node Fill Commands
457 @subsection Explicit Fill Commands
459 @table @kbd
460 @item M-q
461 Fill current paragraph (@code{fill-paragraph}).
462 @item C-x f
463 Set the fill column (@code{set-fill-column}).
464 @item M-x fill-region
465 Fill each paragraph in the region (@code{fill-region}).
466 @item M-x fill-region-as-paragraph
467 Fill the region, considering it as one paragraph.
468 @item M-s
469 Center a line.
470 @end table
472 @kindex M-q
473 @findex fill-paragraph
474   To refill a paragraph, use the command @kbd{M-q}
475 (@code{fill-paragraph}).  This operates on the paragraph that point is
476 inside, or the one after point if point is between paragraphs.
477 Refilling works by removing all the line-breaks, then inserting new ones
478 where necessary.
480 @findex fill-region
481   To refill many paragraphs, use @kbd{M-x fill-region}, which
482 divides the region into paragraphs and fills each of them.
484 @findex fill-region-as-paragraph
485   @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h}
486 for finding paragraph boundaries (@pxref{Paragraphs}).  For more
487 control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
488 everything between point and mark.  This command deletes any blank lines
489 within the region, so separate blocks of text end up combined into one
490 block.@refill
492 @cindex justification
493   A numeric argument to @kbd{M-q} causes it to @dfn{justify} the text as
494 well as filling it.  This means that extra spaces are inserted to make
495 the right margin line up exactly at the fill column.  To remove the
496 extra spaces, use @kbd{M-q} with no argument.  (Likewise for
497 @code{fill-region}.)  Another way to control justification, and choose
498 other styles of filling, is with the @code{justification} text property;
499 see @ref{Format Justification}.
501 @kindex M-s @r{(Text mode)}
502 @cindex centering
503 @findex center-line
504   The command @kbd{M-s} (@code{center-line}) centers the current line
505 within the current fill column.  With an argument @var{n}, it centers
506 @var{n} lines individually and moves past them.
508 @vindex fill-column
509 @kindex C-x f
510 @findex set-fill-column
511   The maximum line width for filling is in the variable
512 @code{fill-column}.  Altering the value of @code{fill-column} makes it
513 local to the current buffer; until that time, the default value is in
514 effect.  The default is initially 70.  @xref{Locals}.  The easiest way
515 to set @code{fill-column} is to use the command @kbd{C-x f}
516 (@code{set-fill-column}).  With a numeric argument, it uses that as the
517 new fill column.  With just @kbd{C-u} as argument, it sets
518 @code{fill-column} to the current horizontal position of point.
520   Emacs commands normally consider a period followed by two spaces or by
521 a newline as the end of a sentence; a period followed by just one space
522 indicates an abbreviation and not the end of a sentence.  To preserve
523 the distinction between these two ways of using a period, the fill
524 commands do not break a line after a period followed by just one space.
526 @vindex sentence-end-double-space
527   If the variable @code{sentence-end-double-space} is @code{nil}, the
528 fill commands expect and leave just one space at the end of a sentence.
529 Ordinarily this variable is @code{t}, so the fill commands insist on
530 two spaces for the end of a sentence, as explained above.  @xref{Sentences}.
532 @vindex colon-double-space
533   If the variable @code{colon-double-space} is non-@code{nil}, the
534 fill commands put two spaces after a colon.
536 @vindex sentence-end-without-period
537 The variable @code{sentence-end-without-period} can be set
538 non-@code{nil} to indicate that a sentence will end without a period.
539 For example, a sentence in Thai text ends with double space but without
540 a period.
542 @node Fill Prefix
543 @subsection The Fill Prefix
545 @cindex fill prefix
546   To fill a paragraph in which each line starts with a special marker
547 (which might be a few spaces, giving an indented paragraph), you can use
548 the @dfn{fill prefix} feature.  The fill prefix is a string that Emacs
549 expects every line to start with, and which is not included in filling.
550 You can specify a fill prefix explicitly; Emacs can also deduce the
551 fill prefix automatically (@pxref{Adaptive Fill}).
553 @table @kbd
554 @item C-x .
555 Set the fill prefix (@code{set-fill-prefix}).
556 @item M-q
557 Fill a paragraph using current fill prefix (@code{fill-paragraph}).
558 @item M-x fill-individual-paragraphs
559 Fill the region, considering each change of indentation as starting a
560 new paragraph.
561 @item M-x fill-nonuniform-paragraphs
562 Fill the region, considering only paragraph-separator lines as starting
563 a new paragraph.
564 @end table
566 @kindex C-x .
567 @findex set-fill-prefix
568   To specify a fill prefix, move to a line that starts with the desired
569 prefix, put point at the end of the prefix, and give the command
570 @w{@kbd{C-x .}}@: (@code{set-fill-prefix}).  That's a period after the
571 @kbd{C-x}.  To turn off the fill prefix, specify an empty prefix: type
572 @w{@kbd{C-x .}}@: with point at the beginning of a line.@refill
574   When a fill prefix is in effect, the fill commands remove the fill
575 prefix from each line before filling and insert it on each line after
576 filling.  Auto Fill mode also inserts the fill prefix automatically when
577 it makes a new line.  The @kbd{C-o} command inserts the fill prefix on
578 new lines it creates, when you use it at the beginning of a line
579 (@pxref{Blank Lines}).  Conversely, the command @kbd{M-^} deletes the
580 prefix (if it occurs) after the newline that it deletes
581 (@pxref{Indentation}).
583   For example, if @code{fill-column} is 40 and you set the fill prefix
584 to @samp{;; }, then @kbd{M-q} in the following text
586 @example
587 ;; This is an
588 ;; example of a paragraph
589 ;; inside a Lisp-style comment.
590 @end example
592 @noindent
593 produces this:
595 @example
596 ;; This is an example of a paragraph
597 ;; inside a Lisp-style comment.
598 @end example
600   Lines that do not start with the fill prefix are considered to start
601 paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
602 good results for paragraphs with hanging indentation (every line
603 indented except the first one).  Lines which are blank or indented once
604 the prefix is removed also separate or start paragraphs; this is what
605 you want if you are writing multi-paragraph comments with a comment
606 delimiter on each line.
608 @findex fill-individual-paragraphs
609   You can use @kbd{M-x fill-individual-paragraphs} to set the fill
610 prefix for each paragraph automatically.  This command divides the
611 region into paragraphs, treating every change in the amount of
612 indentation as the start of a new paragraph, and fills each of these
613 paragraphs.  Thus, all the lines in one ``paragraph'' have the same
614 amount of indentation.  That indentation serves as the fill prefix for
615 that paragraph.
617 @findex fill-nonuniform-paragraphs
618   @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
619 the region into paragraphs in a different way.  It considers only
620 paragraph-separating lines (as defined by @code{paragraph-separate}) as
621 starting a new paragraph.  Since this means that the lines of one
622 paragraph may have different amounts of indentation, the fill prefix
623 used is the smallest amount of indentation of any of the lines of the
624 paragraph.  This gives good results with styles that indent a paragraph's
625 first line more or less that the rest of the paragraph.
627 @vindex fill-prefix
628   The fill prefix is stored in the variable @code{fill-prefix}.  Its value
629 is a string, or @code{nil} when there is no fill prefix.  This is a
630 per-buffer variable; altering the variable affects only the current buffer,
631 but there is a default value which you can change as well.  @xref{Locals}.
633   The @code{indentation} text property provides another way to control
634 the amount of indentation paragraphs receive.  @xref{Format Indentation}.
636 @node Adaptive Fill
637 @subsection Adaptive Filling
639 @cindex adaptive filling
640   The fill commands can deduce the proper fill prefix for a paragraph
641 automatically in certain cases: either whitespace or certain punctuation
642 characters at the beginning of a line are propagated to all lines of the
643 paragraph.
645   If the paragraph has two or more lines, the fill prefix is taken from
646 the paragraph's second line, but only if it appears on the first line as
647 well.
649   If a paragraph has just one line, fill commands @emph{may} take a
650 prefix from that line.  The decision is complicated because there are
651 three reasonable things to do in such a case:
653 @itemize @bullet
654 @item
655 Use the first line's prefix on all the lines of the paragraph.
657 @item
658 Indent subsequent lines with whitespace, so that they line up under the
659 text that follows the prefix on the first line, but don't actually copy
660 the prefix from the first line.
662 @item
663 Don't do anything special with the second and following lines.
664 @end itemize
666   All three of these styles of formatting are commonly used.  So the
667 fill commands try to determine what you would like, based on the prefix
668 that appears and on the major mode.  Here is how.
670 @vindex adaptive-fill-first-line-regexp
671   If the prefix found on the first line matches
672 @code{adaptive-fill-first-line-regexp}, or if it appears to be a
673 comment-starting sequence (this depends on the major mode), then the
674 prefix found is used for filling the paragraph, provided it would not
675 act as a paragraph starter on subsequent lines.
677   Otherwise, the prefix found is converted to an equivalent number of
678 spaces, and those spaces are used as the fill prefix for the rest of the
679 lines, provided they would not act as a paragraph starter on subsequent
680 lines.
682   In Text mode, and other modes where only blank lines and page
683 delimiters separate paragraphs, the prefix chosen by adaptive filling
684 never acts as a paragraph starter, so it can always be used for filling.
686 @vindex adaptive-fill-mode
687 @vindex adaptive-fill-regexp
688   The variable @code{adaptive-fill-regexp} determines what kinds of line
689 beginnings can serve as a fill prefix: any characters at the start of
690 the line that match this regular expression are used.  If you set the
691 variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
692 never chosen automatically.
694 @vindex adaptive-fill-function
695   You can specify more complex ways of choosing a fill prefix
696 automatically by setting the variable @code{adaptive-fill-function} to a
697 function.  This function is called with point after the left margin of a
698 line, and it should return the appropriate fill prefix based on that
699 line.  If it returns @code{nil}, that means it sees no fill prefix in
700 that line.
702 @node Refill
703 @subsection Refill Mode
704 @cindex refilling text, word processor style
705 @cindex modes, Refill
706 @cindex Refill minor mode
708 Refill minor mode provides support for keeping paragraphs filled as you
709 type or modify them in other ways.  It provides an effect similar to
710 typical word processor behaviour.  This works by running a
711 paragraph-filling command at suitable times.
713 When you are typing text, only characters which normally trigger auto
714 filling, like the space character, will trigger refilling.  This is to
715 avoid making it too slow.  Apart from self-inserting characters, other
716 commands which modify the text cause refilling.
718 The current implementation is preliminary and probably not robust.  We
719 expect to improve on it.
721 @node Case
722 @section Case Conversion Commands
723 @cindex case conversion
725   Emacs has commands for converting either a single word or any arbitrary
726 range of text to upper case or to lower case.
728 @c WideCommands
729 @table @kbd
730 @item M-l
731 Convert following word to lower case (@code{downcase-word}).
732 @item M-u
733 Convert following word to upper case (@code{upcase-word}).
734 @item M-c
735 Capitalize the following word (@code{capitalize-word}).
736 @item C-x C-l
737 Convert region to lower case (@code{downcase-region}).
738 @item C-x C-u
739 Convert region to upper case (@code{upcase-region}).
740 @end table
742 @kindex M-l
743 @kindex M-u
744 @kindex M-c
745 @cindex words, case conversion
746 @cindex converting text to upper or lower case
747 @cindex capitalizing words
748 @findex downcase-word
749 @findex upcase-word
750 @findex capitalize-word
751   The word conversion commands are the most useful.  @kbd{M-l}
752 (@code{downcase-word}) converts the word after point to lower case, moving
753 past it.  Thus, repeating @kbd{M-l} converts successive words.
754 @kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while
755 @kbd{M-c} (@code{capitalize-word}) puts the first letter of the word
756 into upper case and the rest into lower case.  All these commands convert
757 several words at once if given an argument.  They are especially convenient
758 for converting a large amount of text from all upper case to mixed case,
759 because you can move through the text using @kbd{M-l}, @kbd{M-u} or
760 @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
761 to skip a word.
763   When given a negative argument, the word case conversion commands apply
764 to the appropriate number of words before point, but do not move point.
765 This is convenient when you have just typed a word in the wrong case: you
766 can give the case conversion command and continue typing.
768   If a word case conversion command is given in the middle of a word, it
769 applies only to the part of the word which follows point.  This is just
770 like what @kbd{M-d} (@code{kill-word}) does.  With a negative argument,
771 case conversion applies only to the part of the word before point.
773 @kindex C-x C-l
774 @kindex C-x C-u
775 @findex downcase-region
776 @findex upcase-region
777   The other case conversion commands are @kbd{C-x C-u}
778 (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
779 convert everything between point and mark to the specified case.  Point and
780 mark do not move.
782   The region case conversion commands @code{upcase-region} and
783 @code{downcase-region} are normally disabled.  This means that they ask
784 for confirmation if you try to use them.  When you confirm, you may
785 enable the command, which means it will not ask for confirmation again.
786 @xref{Disabling}.
788 @node Text Mode
789 @section Text Mode
790 @cindex Text mode
791 @cindex mode, Text
792 @findex text-mode
794   When you edit files of text in a human language, it's more convenient
795 to use Text mode rather than Fundamental mode.  To enter Text mode, type
796 @kbd{M-x text-mode}.
798   In Text mode, only blank lines and page delimiters separate
799 paragraphs.  As a result, paragraphs can be indented, and adaptive
800 filling determines what indentation to use when filling a paragraph.
801 @xref{Adaptive Fill}.
803 @kindex TAB @r{(Text mode)}
804   Text mode defines @key{TAB} to run @code{indent-relative}
805 (@pxref{Indentation}), so that you can conveniently indent a line like
806 the previous line.  When the previous line is not indented,
807 @code{indent-relative} runs @code{tab-to-tab-stop}, which uses Emacs tab
808 stops that you can set (@pxref{Tab Stops}).
810   Text mode turns off the features concerned with comments except when
811 you explicitly invoke them.  It changes the syntax table so that periods
812 are not considered part of a word, while apostrophes, backspaces and
813 underlines are considered part of words.
815 @cindex Paragraph-Indent Text mode
816 @cindex mode, Paragraph-Indent Text
817 @findex paragraph-indent-text-mode
818 @findex paragraph-indent-minor-mode
819   If you indent the first lines of paragraphs, then you should use
820 Paragraph-Indent Text mode rather than Text mode.  In this mode, you do
821 not need to have blank lines between paragraphs, because the first-line
822 indentation is sufficient to start a paragraph; however paragraphs in
823 which every line is indented are not supported.  Use @kbd{M-x
824 paragraph-indent-text-mode} to enter this mode.  Use @kbd{M-x
825 paragraph-indent-minor-mode} to enter an equivalent minor mode, for
826 instance during mail composition.
828 @kindex M-TAB @r{(Text mode)}
829   Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} as
830 the command @code{ispell-complete-word}, which performs completion of
831 the partial word in the buffer before point, using the spelling
832 dictionary as the space of possible words.  @xref{Spelling}.
834 @vindex text-mode-hook
835   Entering Text mode runs the hook @code{text-mode-hook}.  Other major
836 modes related to Text mode also run this hook, followed by hooks of
837 their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{}
838 mode, Outline mode, and Mail mode.  Hook functions on
839 @code{text-mode-hook} can look at the value of @code{major-mode} to see
840 which of these modes is actually being entered.  @xref{Hooks}.
842 @ifinfo
843   Emacs provides two other modes for editing text that is to be passed
844 through a text formatter to produce fancy formatted printed output.
845 @xref{Nroff Mode}, for editing input to the formatter nroff.
846 @xref{TeX Mode}, for editing input to the formatter TeX.
848   Another mode is used for editing outlines.  It allows you to view the
849 text at various levels of detail.  You can view either the outline
850 headings alone or both headings and text; you can also hide some of the
851 headings at lower levels from view to make the high level structure more
852 visible.  @xref{Outline Mode}.
853 @end ifinfo
855 @node Outline Mode
856 @section Outline Mode
857 @cindex Outline mode
858 @cindex mode, Outline
859 @cindex selective display
860 @cindex invisible lines
862 @findex outline-mode
863 @findex outline-minor-mode
864 @vindex outline-minor-mode-prefix
865   Outline mode is a major mode much like Text mode but intended for
866 editing outlines.  It allows you to make parts of the text temporarily
867 invisible so that you can see the outline structure.  Type @kbd{M-x
868 outline-mode} to switch to Outline mode as the major mode of the current
869 buffer.
871   When Outline mode makes a line invisible, the line does not appear on
872 the screen.  The screen appears exactly as if the invisible line were
873 deleted, except that an ellipsis (three periods in a row) appears at the
874 end of the previous visible line (only one ellipsis no matter how many
875 invisible lines follow).
877   Editing commands that operate on lines, such as @kbd{C-n} and
878 @kbd{C-p}, treat the text of the invisible line as part of the previous
879 visible line.  Killing an entire visible line, including its terminating
880 newline, really kills all the following invisible lines along with it.
882   Outline minor mode provides the same commands as the major mode,
883 Outline mode, but you can use it in conjunction with other major modes.
884 Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in
885 the current buffer.  You can also specify this in the text of a file,
886 with a file local variable of the form @samp{mode: outline-minor}
887 (@pxref{File Variables}).
889 @kindex C-c @@ @r{(Outline minor mode)}
890   The major mode, Outline mode, provides special key bindings on the
891 @kbd{C-c} prefix.  Outline minor mode provides similar bindings with
892 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
893 major mode's special commands.  (The variable
894 @code{outline-minor-mode-prefix} controls the prefix used.)
896 @vindex outline-mode-hook
897   Entering Outline mode runs the hook @code{text-mode-hook} followed by
898 the hook @code{outline-mode-hook} (@pxref{Hooks}).
900 @menu
901 * Format: Outline Format.          What the text of an outline looks like.
902 * Motion: Outline Motion.          Special commands for moving through
903                                      outlines. 
904 * Visibility: Outline Visibility.  Commands to control what is visible.
905 * Views: Outline Views.            Outlines and multiple views.
906 * Foldout::                        Folding editing.
907 @end menu
909 @node Outline Format
910 @subsection Format of Outlines
912 @cindex heading lines (Outline mode)
913 @cindex body lines (Outline mode)
914   Outline mode assumes that the lines in the buffer are of two types:
915 @dfn{heading lines} and @dfn{body lines}.  A heading line represents a
916 topic in the outline.  Heading lines start with one or more stars; the
917 number of stars determines the depth of the heading in the outline
918 structure.  Thus, a heading line with one star is a major topic; all the
919 heading lines with two stars between it and the next one-star heading
920 are its subtopics; and so on.  Any line that is not a heading line is a
921 body line.  Body lines belong with the preceding heading line.  Here is
922 an example:
924 @example
925 * Food
926 This is the body,
927 which says something about the topic of food.
929 ** Delicious Food
930 This is the body of the second-level header.
932 ** Distasteful Food
933 This could have
934 a body too, with
935 several lines.
937 *** Dormitory Food
939 * Shelter
940 Another first-level topic with its header line.
941 @end example
943   A heading line together with all following body lines is called
944 collectively an @dfn{entry}.  A heading line together with all following
945 deeper heading lines and their body lines is called a @dfn{subtree}.
947 @vindex outline-regexp
948   You can customize the criterion for distinguishing heading lines
949 by setting the variable @code{outline-regexp}.  Any line whose
950 beginning has a match for this regexp is considered a heading line.
951 Matches that start within a line (not at the left margin) do not count.
952 The length of the matching text determines the level of the heading;
953 longer matches make a more deeply nested level.  Thus, for example,
954 if a text formatter has commands @samp{@@chapter}, @samp{@@section}
955 and @samp{@@subsection} to divide the document into chapters and
956 sections, you could make those lines count as heading lines by
957 setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}.
958 Note the trick: the two words @samp{chapter} and @samp{section} are equally
959 long, but by defining the regexp to match only @samp{chap} we ensure
960 that the length of the text matched on a chapter heading is shorter,
961 so that Outline mode will know that sections are contained in chapters.
962 This works as long as no other command starts with @samp{@@chap}.
964 @vindex outline-level
965   It is possible to change the rule for calculating the level of a
966 heading line by setting the variable @code{outline-level}.  The value of
967 @code{outline-level} should be a function that takes no arguments and
968 returns the level of the current heading.  Some major modes such as C,
969 Nroff, and Emacs Lisp mode set this variable and/or
970 @code{outline-regexp} in order to work with Outline minor mode.
972 @node Outline Motion
973 @subsection Outline Motion Commands
975   Outline mode provides special motion commands that move backward and
976 forward to heading lines.
978 @table @kbd
979 @item C-c C-n
980 Move point to the next visible heading line
981 (@code{outline-next-visible-heading}).
982 @item C-c C-p
983 Move point to the previous visible heading line
984 (@code{outline-previous-visible-heading}).
985 @item C-c C-f
986 Move point to the next visible heading line at the same level
987 as the one point is on (@code{outline-forward-same-level}).
988 @item C-c C-b
989 Move point to the previous visible heading line at the same level
990 (@code{outline-backward-same-level}).
991 @item C-c C-u
992 Move point up to a lower-level (more inclusive) visible heading line
993 (@code{outline-up-heading}).
994 @end table
996 @findex outline-next-visible-heading
997 @findex outline-previous-visible-heading
998 @kindex C-c C-n @r{(Outline mode)}
999 @kindex C-c C-p @r{(Outline mode)}
1000   @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next
1001 heading line.  @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves
1002 similarly backward.  Both accept numeric arguments as repeat counts.  The
1003 names emphasize that invisible headings are skipped, but this is not really
1004 a special feature.  All editing commands that look for lines ignore the
1005 invisible lines automatically.@refill
1007 @findex outline-up-heading
1008 @findex outline-forward-same-level
1009 @findex outline-backward-same-level
1010 @kindex C-c C-f @r{(Outline mode)}
1011 @kindex C-c C-b @r{(Outline mode)}
1012 @kindex C-c C-u @r{(Outline mode)}
1013   More powerful motion commands understand the level structure of headings.
1014 @kbd{C-c C-f} (@code{outline-forward-same-level}) and
1015 @kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
1016 heading line to another visible heading at the same depth in
1017 the outline.  @kbd{C-c C-u} (@code{outline-up-heading}) moves
1018 backward to another heading that is less deeply nested.
1020 @node Outline Visibility
1021 @subsection Outline Visibility Commands
1023   The other special commands of outline mode are used to make lines visible
1024 or invisible.  Their names all start with @code{hide} or @code{show}.
1025 Most of them fall into pairs of opposites.  They are not undoable; instead,
1026 you can undo right past them.  Making lines visible or invisible is simply
1027 not recorded by the undo mechanism.
1029 @table @kbd
1030 @item C-c C-t
1031 Make all body lines in the buffer invisible (@code{hide-body}).
1032 @item C-c C-a
1033 Make all lines in the buffer visible (@code{show-all}).
1034 @item C-c C-d
1035 Make everything under this heading invisible, not including this
1036 heading itself (@code{hide-subtree}).
1037 @item C-c C-s
1038 Make everything under this heading visible, including body,
1039 subheadings, and their bodies (@code{show-subtree}).
1040 @item C-c C-l
1041 Make the body of this heading line, and of all its subheadings,
1042 invisible (@code{hide-leaves}).
1043 @item C-c C-k
1044 Make all subheadings of this heading line, at all levels, visible
1045 (@code{show-branches}). 
1046 @item C-c C-i
1047 Make immediate subheadings (one level down) of this heading line
1048 visible (@code{show-children}).
1049 @item C-c C-c
1050 Make this heading line's body invisible (@code{hide-entry}).
1051 @item C-c C-e
1052 Make this heading line's body visible (@code{show-entry}).
1053 @item C-c C-q
1054 Hide everything except the top @var{n} levels of heading lines
1055 (@code{hide-sublevels}).
1056 @item C-c C-o
1057 Hide everything except for the heading or body that point is in, plus
1058 the headings leading up from there to the top level of the outline
1059 (@code{hide-other}).
1060 @end table
1062 @findex hide-entry
1063 @findex show-entry
1064 @kindex C-c C-c @r{(Outline mode)}
1065 @kindex C-c C-e @r{(Outline mode)}
1066   Two commands that are exact opposites are @kbd{C-c C-c}
1067 (@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}).  They are
1068 used with point on a heading line, and apply only to the body lines of
1069 that heading.  Subheadings and their bodies are not affected.
1071 @findex hide-subtree
1072 @findex show-subtree
1073 @kindex C-c C-s @r{(Outline mode)}
1074 @kindex C-c C-d @r{(Outline mode)}
1075 @cindex subtree (Outline mode)
1076   Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) and
1077 @kbd{C-c C-s} (@code{show-subtree}).  Both expect to be used when point is
1078 on a heading line, and both apply to all the lines of that heading's
1079 @dfn{subtree}: its body, all its subheadings, both direct and indirect, and
1080 all of their bodies.  In other words, the subtree contains everything
1081 following this heading line, up to and not including the next heading of
1082 the same or higher rank.@refill
1084 @findex hide-leaves
1085 @findex show-branches
1086 @kindex C-c C-l @r{(Outline mode)}
1087 @kindex C-c C-k @r{(Outline mode)}
1088   Intermediate between a visible subtree and an invisible one is having
1089 all the subheadings visible but none of the body.  There are two
1090 commands for doing this, depending on whether you want to hide the
1091 bodies or make the subheadings visible.  They are @kbd{C-c C-l}
1092 (@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}).
1094 @kindex C-c C-i @r{(Outline mode)}
1095 @findex show-children
1096   A little weaker than @code{show-branches} is @kbd{C-c C-i}
1097 (@code{show-children}).  It makes just the direct subheadings
1098 visible---those one level down.  Deeper subheadings remain invisible, if
1099 they were invisible.@refill
1101 @findex hide-body
1102 @findex show-all
1103 @kindex C-c C-t @r{(Outline mode)}
1104 @kindex C-c C-a @r{(Outline mode)}
1105   Two commands have a blanket effect on the whole file.  @kbd{C-c C-t}
1106 (@code{hide-body}) makes all body lines invisible, so that you see just
1107 the outline structure.  @kbd{C-c C-a} (@code{show-all}) makes all lines
1108 visible.  These commands can be thought of as a pair of opposites even
1109 though @kbd{C-c C-a} applies to more than just body lines.
1111 @findex hide-sublevels
1112 @kindex C-c C-q @r{(Outline mode)}
1113   The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the
1114 top level headings.  With a numeric argument @var{n}, it hides everything
1115 except the top @var{n} levels of heading lines.
1117 @findex hide-other
1118 @kindex C-c C-o @r{(Outline mode)}
1119   The command @kbd{C-c C-o} (@code{hide-other}) hides everything except
1120 the heading or body text that point is in, plus its parents (the headers
1121 leading up from there to top level in the outline).
1123   You can turn off the use of ellipses at the ends of visible lines by
1124 setting @code{selective-display-ellipses} to @code{nil}.  Then there is
1125 no visible indication of the presence of invisible lines.
1127   When incremental search finds text that is hidden by Outline mode,
1128 it makes that part of the buffer visible.  If you exit the search
1129 at that position, the text remains visible.
1131 @node Outline Views
1132 @subsection Viewing One Outline in Multiple Views
1134 @cindex multiple views of outline
1135 @cindex views of an outline
1136 @cindex outline with multiple views
1137 @cindex indirect buffers and outlines
1138   You can display two views of a single outline at the same time, in
1139 different windows.  To do this, you must create an indirect buffer using
1140 @kbd{M-x make-indirect-buffer}.  The first argument of this command is
1141 the existing outline buffer name, and its second argument is the name to
1142 use for the new indirect buffer.  @xref{Indirect Buffers}.
1144   Once the indirect buffer exists, you can display it in a window in the
1145 normal fashion, with @kbd{C-x 4 b} or other Emacs commands.  The Outline
1146 mode commands to show and hide parts of the text operate on each buffer
1147 independently; as a result, each buffer can have its own view.  If you
1148 want more than two views on the same outline, create additional indirect
1149 buffers.
1151 @node Foldout
1152 @subsection Folding editing
1154 @cindex folding editing
1155 The Foldout package provides folding editor extensions for Outline mode
1156 and Outline minor mode.  It may be used by putting in your @file{.emacs}
1158 @example
1159 (eval-after-load "outline" '(require 'foldout))
1160 @end example
1162 @noindent
1163 Folding editing works as follows.
1165 Consider an Outline mode buffer all the text and subheadings under
1166 level-1 headings hidden.  To look at what is hidden under one of these
1167 headings normally you would use @kbd{C-c C-e} (@kbd{M-x show-entry}) to
1168 expose the body or @kbd{C-c C-i} to expose the child (level-2) headings.
1170 @kindex C-c C-z
1171 @findex foldout-zoom-subtree
1172 With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1173 This exposes the body and child subheadings and narrows the buffer so
1174 that only the level-1 heading, the body and the level-2 headings are
1175 visible.  Now to look under one of the level-2 headings, position the
1176 cursor on it and use @kbd{C-c C-z} again.  This exposes the level-2 body
1177 and its level-3 child subheadings and narrows the buffer again.  Zooming
1178 in on successive subheadings can be done as much as you like.  A string
1179 in the modeline shows how deep you've gone.
1181 When zooming in on a heading, to see only the child subheadings specify
1182 a numeric argument: @kbd{C-u C-c C-z}.  The number of levels of children
1183 can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2
1184 C-c C-z} exposes two levels of child subheadings.  Alternatively, the
1185 body can be spcified with a negative argument: @kbd{M-- C-c C-z}.  The
1186 whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x
1187 show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}.
1189 While you're zoomed in you can still use outline-mode's exposure and
1190 hiding functions without disturbing Foldout.  Also, since the buffer is
1191 narrowed, `global' editing actions will only affect text under the
1192 zoomed-in heading.  This is useful for restricting changes to a
1193 particular chapter or section of your document.
1195 @kindex C-c C-x
1196 @findex foldout-exit-fold
1197 Unzoom (exit) a fold using @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1198 This hides all the text and subheadings under the top-level heading and
1199 returns you to the previous view of the buffer.  Specifying a numeric
1200 argument exits that many folds.  Specifying a zero argument exits all
1201 folds.
1203 You might want to exit a fold without hiding the text and subheadings,
1204 specify a negative argument.  For example, @kbd{M--2 C-c C-x} exits two
1205 folds and leaves the text and subheadings exposed.
1207 Foldout provides mouse bindings for entering and exiting folds and for
1208 showing and hiding text as follows:
1209 @table @asis
1210 @item @kbd{M-C-mouse-1} zooms in on the heading clicked on
1211 @table @asis
1212 @item single click
1213 expose body
1214 @item double click
1215 expose subheadings
1216 @item triple click
1217 expose body and subheadings
1218 @item quad click
1219 expose entire subtree
1220 @end table
1221 @item @kbd{M-C-mouse-2} exposes text under the heading clicked on
1222 @table @r
1223 @item single click
1224 expose body
1225 @item double click
1226 expose subheadings
1227 @item triple click
1228 expose body and subheadings
1229 @item quad click
1230 expose entire subtree
1231 @end table
1232 @item @kbd{M-C-mouse-3} hides text under the heading clicked on or exits fold
1233 @table @r
1234 @item single click
1235 hide subtree
1236 @item double click
1237 exit fold and hide text
1238 @item triple click
1239 exit fold without hiding text
1240 @item quad click
1241 exit all folds and hide text
1242 @end table
1243 @end table
1245 @vindex foldout-mouse-modifiers
1246 You can change the modifier keys used by setting
1247 @code{foldout-mouse-modifiers}.
1249 @node TeX Mode, Nroff Mode, Outline Mode, Text
1250 @section @TeX{} Mode
1251 @cindex @TeX{} mode
1252 @cindex La@TeX{} mode
1253 @cindex Sli@TeX{} mode
1254 @cindex mode, @TeX{}
1255 @cindex mode, La@TeX{}
1256 @cindex mode, Sli@TeX{}
1257 @findex tex-mode
1258 @findex plain-tex-mode
1259 @findex latex-mode
1260 @findex slitex-mode
1262   @TeX{} is a powerful text formatter written by Donald Knuth; it is also
1263 free, like GNU Emacs.  La@TeX{} is a simplified input format for @TeX{},
1264 implemented by @TeX{} macros; it comes with @TeX{}.  Sli@TeX{} is a special
1265 form of La@TeX{}.@footnote{Sli@TeX{} is obsoleted by the @samp{slides}
1266 document class in recent La@TeX{} versions.}
1268   Emacs has a special @TeX{} mode for editing @TeX{} input files.
1269 It provides facilities for checking the balance of delimiters and for
1270 invoking @TeX{} on all or part of the file.
1272 @vindex tex-default-mode
1273   @TeX{} mode has three variants, Plain @TeX{} mode, La@TeX{} mode, and
1274 Sli@TeX{} mode (these three distinct major modes differ only slightly).
1275 They are designed for editing the three different formats.  The command
1276 @kbd{M-x tex-mode} looks at the contents of the buffer to determine
1277 whether the contents appear to be either La@TeX{} input or Sli@TeX{}
1278 input; if so, it selects the appropriate mode.  If the file contents do
1279 not appear to be La@TeX{} or Sli@TeX{}, it selects Plain @TeX{} mode.
1280 If the contents are insufficient to determine this, the variable
1281 @code{tex-default-mode} controls which mode is used.
1283   When @kbd{M-x tex-mode} does not guess right, you can use the commands
1284 @kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, and @kbd{M-x
1285 slitex-mode} to select explicitly the particular variants of @TeX{}
1286 mode.
1288 @vindex tex-shell-hook
1289 @vindex tex-mode-hook
1290 @vindex latex-mode-hook
1291 @vindex slitex-mode-hook
1292 @vindex plain-tex-mode-hook
1293   Entering any kind of @TeX{} mode runs the hooks @code{text-mode-hook}
1294 and @code{tex-mode-hook}.  Then it runs either
1295 @code{plain-tex-mode-hook} or @code{latex-mode-hook}, whichever is
1296 appropriate.  For Sli@TeX{} files, it calls @code{slitex-mode-hook}.
1297 Starting the @TeX{} shell runs the hook @code{tex-shell-hook}.
1298 @xref{Hooks}.
1300 @findex iso-iso2tex
1301 @findex iso-tex2iso
1302 @findex iso-iso2gtex
1303 @findex iso-gtex2iso
1304 @cindex Latin-1 @TeX{} encoding
1305 @TeX{} encoding
1306 @vindex format-alist
1307 @findex format-find-file
1308 The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1309 iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert between
1310 Latin-1 encoded files and @TeX{}-encoded equivalents.  They are included
1311 by default in the @code{format-alist} variable, and so an be used with
1312 @kbd{M-x format-find-file}, for instance.
1314 @findex tildify-buffer
1315 @findex tildify-region
1316 @cindex ties, @TeX{}, inserting
1317 @cindex hard spaces, @TeX{}, inserting
1318 @cindex SGML
1319 @cindex HTML
1320 The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region} can
1321 be used to insert missing @samp{~} @dfn{tie} characters which should be
1322 present in the file to represent `hard spaces'.  This is set up for
1323 Czech---customize the group @samp{tildify} for other languages or for
1324 other sorts of markup; there is support for SGML (HTML).
1326 @cindex RefTeX package
1327 @cindex references, La@TeX{}
1328 @cindex La@TeX{} references
1329   For managing all kinds of references for La@TeX{}, you can use
1330 Ref@TeX{}.  @xref{Top, , RefTeX, reftex}.
1332 @cindex Bib@TeX{} mode
1333 @cindex mode, Bib@TeX{}
1334 @pindex bibtex
1335 @findex bibtex-mode
1336 There is also a mode for editing files for the Bib@TeX{} bibliography
1337 program often used with La@TeX{}.
1339 @menu
1340 * Editing: TeX Editing.   Special commands for editing in TeX mode.
1341 * LaTeX: LaTeX Editing.   Additional commands for LaTeX input files.
1342 * Printing: TeX Print.    Commands for printing part of a file with TeX.
1343 @end menu
1345 @node TeX Editing
1346 @subsection @TeX{} Editing Commands
1348   Here are the special commands provided in @TeX{} mode for editing the
1349 text of the file.
1351 @table @kbd
1352 @item "
1353 Insert, according to context, either @samp{``} or @samp{"} or
1354 @samp{''} (@code{tex-insert-quote}).
1355 @item C-j
1356 Insert a paragraph break (two newlines) and check the previous
1357 paragraph for unbalanced braces or dollar signs
1358 (@code{tex-terminate-paragraph}).
1359 @item M-x tex-validate-region
1360 Check each paragraph in the region for unbalanced braces or dollar signs.
1361 @item C-c @{
1362 Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1363 @item C-c @}
1364 Move forward past the next unmatched close brace (@code{up-list}).
1365 @end table
1367 @findex tex-insert-quote
1368 @kindex " @r{(@TeX{} mode)}
1369   In @TeX{}, the character @samp{"} is not normally used; we use
1370 @samp{``} to start a quotation and @samp{''} to end one.  To make
1371 editing easier under this formatting convention, @TeX{} mode overrides
1372 the normal meaning of the key @kbd{"} with a command that inserts a pair
1373 of single-quotes or backquotes (@code{tex-insert-quote}).  To be
1374 precise, this command inserts @samp{``} after whitespace or an open
1375 brace, @samp{"} after a backslash, and @samp{''} after any other
1376 character.
1378   If you need the character @samp{"} itself in unusual contexts, use
1379 @kbd{C-q} to insert it.  Also, @kbd{"} with a numeric argument always
1380 inserts that number of @samp{"} characters.  You can turn off the
1381 feature of @kbd{"} expansion by eliminating that binding in the local
1382 map (@pxref{Key Bindings}).
1384   In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1385 understand the way @TeX{} math mode delimiters match.  When you insert a
1386 @samp{$} that is meant to exit math mode, the position of the matching
1387 @samp{$} that entered math mode is displayed for a second.  This is the
1388 same feature that displays the open brace that matches a close brace that
1389 is inserted.  However, there is no way to tell whether a @samp{$} enters
1390 math mode or leaves it; so when you insert a @samp{$} that enters math
1391 mode, the previous @samp{$} position is shown as if it were a match, even
1392 though they are actually unrelated.
1394 @findex tex-insert-braces
1395 @kindex C-c @{ @r{(@TeX{} mode)}
1396 @findex up-list
1397 @kindex C-c @} @r{(@TeX{} mode)}
1398   @TeX{} uses braces as delimiters that must match.  Some users prefer
1399 to keep braces balanced at all times, rather than inserting them
1400 singly.  Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1401 braces.  It leaves point between the two braces so you can insert the
1402 text that belongs inside.  Afterward, use the command @kbd{C-c @}}
1403 (@code{up-list}) to move forward past the close brace.
1405 @findex tex-validate-region
1406 @findex tex-terminate-paragraph
1407 @kindex C-j @r{(@TeX{} mode)}
1408   There are two commands for checking the matching of braces.  @kbd{C-j}
1409 (@code{tex-terminate-paragraph}) checks the paragraph before point, and
1410 inserts two newlines to start a new paragraph.  It prints a message in
1411 the echo area if any mismatch is found.  @kbd{M-x tex-validate-region}
1412 checks a region, paragraph by paragraph.  The errors are listed in the
1413 @samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in
1414 that buffer to go to a particular mismatch.
1416   Note that Emacs commands count square brackets and parentheses in
1417 @TeX{} mode, not just braces.  This is not strictly correct for the
1418 purpose of checking @TeX{} syntax.  However, parentheses and square
1419 brackets are likely to be used in text as matching delimiters and it is
1420 useful for the various motion commands and automatic match display to
1421 work with them.
1423 @node LaTeX Editing
1424 @subsection La@TeX{} Editing Commands
1426   La@TeX{} mode, and its variant, Sli@TeX{} mode, provide a few extra
1427 features not applicable to plain @TeX{}.
1429 @table @kbd
1430 @item C-c C-o
1431 Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position
1432 point on a line between them (@code{tex-latex-block}).
1433 @item C-c C-e
1434 Close the innermost La@TeX{} block not yet closed
1435 (@code{tex-close-latex-block}).
1436 @end table
1438 @findex tex-latex-block
1439 @kindex C-c C-o @r{(La@TeX{} mode)}
1440 @vindex latex-block-names
1441   In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to
1442 group blocks of text.  To insert a @samp{\begin} and a matching
1443 @samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c
1444 C-o} (@code{tex-latex-block}).  A blank line is inserted between the
1445 two, and point is left there.  You can use completion when you enter the
1446 block type; to specify additional block type names beyond the standard
1447 list, set the variable @code{latex-block-names}.  For example, here's
1448 how to add @samp{theorem}, @samp{corollary}, and @samp{proof}:
1450 @example
1451 (setq latex-block-names '("theorem" "corollary" "proof"))
1452 @end example
1454 @findex tex-close-latex-block
1455 @kindex C-c C-e @r{(La@TeX{} mode)}
1456   In La@TeX{} input, @samp{\begin} and @samp{\end} commands must
1457 balance.  You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to
1458 insert automatically a matching @samp{\end} to match the last unmatched
1459 @samp{\begin}.  It indents the @samp{\end} to match the corresponding
1460 @samp{\begin}.  It inserts a newline after @samp{\end} if point is at
1461 the beginning of a line.
1463 @node TeX Print
1464 @subsection @TeX{} Printing Commands
1466   You can invoke @TeX{} as an inferior of Emacs on either the entire
1467 contents of the buffer or just a region at a time.  Running @TeX{} in
1468 this way on just one chapter is a good way to see what your changes
1469 look like without taking the time to format the entire file.
1471 @table @kbd
1472 @item C-c C-r
1473 Invoke @TeX{} on the current region, together with the buffer's header
1474 (@code{tex-region}).
1475 @item C-c C-b
1476 Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1477 @item C-c @key{TAB}
1478 Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1479 @item C-c C-f
1480 Invoke @TeX{} on the current file (@code{tex-file}).
1481 @item C-c C-l
1482 Recenter the window showing output from the inferior @TeX{} so that
1483 the last line can be seen (@code{tex-recenter-output-buffer}).
1484 @item C-c C-k
1485 Kill the @TeX{} subprocess (@code{tex-kill-job}).
1486 @item C-c C-p
1487 Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1488 C-f} command (@code{tex-print}).
1489 @item C-c C-v
1490 Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1491 C-f} command (@code{tex-view}).
1492 @item C-c C-q
1493 Show the printer queue (@code{tex-show-print-queue}).
1494 @end table
1496 @findex tex-buffer
1497 @kindex C-c C-b @r{(@TeX{} mode)}
1498 @findex tex-print
1499 @kindex C-c C-p @r{(@TeX{} mode)}
1500 @findex tex-view
1501 @kindex C-c C-v @r{(@TeX{} mode)}
1502 @findex tex-show-print-queue
1503 @kindex C-c C-q @r{(@TeX{} mode)}
1504   You can pass the current buffer through an inferior @TeX{} by means of
1505 @kbd{C-c C-b} (@code{tex-buffer}).  The formatted output appears in a
1506 temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}).
1507 Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to
1508 view the progress of your output towards being printed.  If your terminal
1509 has the ability to display @TeX{} output files, you can preview the
1510 output on the terminal with @kbd{C-c C-v} (@code{tex-view}).
1512 @cindex @env{TEXINPUTS} environment variable
1513 @vindex tex-directory
1514   You can specify the directory to use for running @TeX{} by setting the
1515 variable @code{tex-directory}.  @code{"."} is the default value.  If
1516 your environment variable @env{TEXINPUTS} contains relative directory
1517 names, or if your files contains @samp{\input} commands with relative
1518 file names, then @code{tex-directory} @emph{must} be @code{"."} or you
1519 will get the wrong results.  Otherwise, it is safe to specify some other
1520 directory, such as @code{"/tmp"}.
1522 @vindex tex-run-command
1523 @vindex latex-run-command
1524 @vindex slitex-run-command
1525 @vindex tex-dvi-print-command
1526 @vindex tex-dvi-view-command
1527 @vindex tex-show-queue-command
1528   If you want to specify which shell commands are used in the inferior @TeX{},
1529 you can do so by setting the values of the variables @code{tex-run-command},
1530 @code{latex-run-command}, @code{slitex-run-command},
1531 @code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and
1532 @code{tex-show-queue-command}.  You @emph{must} set the value of
1533 @code{tex-dvi-view-command} for your particular terminal; this variable
1534 has no default value.  The other variables have default values that may
1535 (or may not) be appropriate for your system.
1537   Normally, the file name given to these commands comes at the end of
1538 the command string; for example, @samp{latex @var{filename}}.  In some
1539 cases, however, the file name needs to be embedded in the command; an
1540 example is when you need to provide the file name as an argument to one
1541 command whose output is piped to another.  You can specify where to put
1542 the file name with @samp{*} in the command string.  For example,
1544 @example
1545 (setq tex-dvi-print-command "dvips -f * | lpr")
1546 @end example
1548 @findex tex-kill-job
1549 @kindex C-c C-k @r{(@TeX{} mode)}
1550 @findex tex-recenter-output-buffer
1551 @kindex C-c C-l @r{(@TeX{} mode)}
1552   The terminal output from @TeX{}, including any error messages, appears
1553 in a buffer called @samp{*tex-shell*}.  If @TeX{} gets an error, you can
1554 switch to this buffer and feed it input (this works as in Shell mode;
1555 @pxref{Interactive Shell}).  Without switching to this buffer you can
1556 scroll it so that its last line is visible by typing @kbd{C-c
1557 C-l}.
1559   Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1560 you see that its output is no longer useful.  Using @kbd{C-c C-b} or
1561 @kbd{C-c C-r} also kills any @TeX{} process still running.@refill
1563 @findex tex-region
1564 @kindex C-c C-r @r{(@TeX{} mode)}
1565   You can also pass an arbitrary region through an inferior @TeX{} by typing
1566 @kbd{C-c C-r} (@code{tex-region}).  This is tricky, however, because most files
1567 of @TeX{} input contain commands at the beginning to set parameters and
1568 define macros, without which no later part of the file will format
1569 correctly.  To solve this problem, @kbd{C-c C-r} allows you to designate a
1570 part of the file as containing essential commands; it is included before
1571 the specified region as part of the input to @TeX{}.  The designated part
1572 of the file is called the @dfn{header}.
1574 @cindex header (@TeX{} mode)
1575   To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1576 special strings in the file.  Insert @samp{%**start of header} before the
1577 header, and @samp{%**end of header} after it.  Each string must appear
1578 entirely on one line, but there may be other text on the line before or
1579 after.  The lines containing the two strings are included in the header.
1580 If @samp{%**start of header} does not appear within the first 100 lines of
1581 the buffer, @kbd{C-c C-r} assumes that there is no header.
1583   In La@TeX{} mode, the header begins with @samp{\documentclass} or
1584 @samp{\documentstyle} and ends with @samp{\begin@{document@}}.  These
1585 are commands that La@TeX{} requires you to use in any case, so nothing
1586 special needs to be done to identify the header.
1588 @findex tex-file
1589 @kindex C-c C-f @r{(@TeX{} mode)}
1590   The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1591 work in a temporary directory, and do not have available any of the auxiliary
1592 files needed by @TeX{} for cross-references; these commands are generally
1593 not suitable for running the final copy in which all of the cross-references
1594 need to be correct.
1596   When you want the auxiliary files for cross references, use @kbd{C-c
1597 C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1598 in that file's directory.  Before running @TeX{}, it offers to save any
1599 modified buffers.  Generally, you need to use (@code{tex-file}) twice to
1600 get the cross-references right.
1602 @vindex tex-start-options-string
1603   The value of the variable @code{tex-start-options-string} specifies
1604 options for the @TeX{} run.  The default value causes @TeX{} to run in
1605 nonstopmode.  To run @TeX{} interactively, set the variable to @code{""}.
1607 @vindex tex-main-file
1608   Large @TeX{} documents are often split into several files---one main
1609 file, plus subfiles.  Running @TeX{} on a subfile typically does not
1610 work; you have to run it on the main file.  In order to make
1611 @code{tex-file} useful when you are editing a subfile, you can set the
1612 variable @code{tex-main-file} to the name of the main file.  Then
1613 @code{tex-file} runs @TeX{} on that file.
1615   The most convenient way to use @code{tex-main-file} is to specify it
1616 in a local variable list in each of the subfiles.  @xref{File
1617 Variables}.
1619 @findex tex-bibtex-file
1620 @kindex C-c TAB @r{(@TeX{} mode)}
1621 @vindex tex-bibtex-command
1622   For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
1623 file for the current buffer's file.  Bib@TeX{} looks up bibliographic
1624 citations in a data base and prepares the cited references for the
1625 bibliography section.  The command @kbd{C-c TAB}
1626 (@code{tex-bibtex-file}) runs the shell command
1627 (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1628 current buffer's file.  Generally, you need to do @kbd{C-c C-f}
1629 (@code{tex-file}) once to generate the @samp{.aux} file, then do
1630 @kbd{C-c TAB} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1631 (@code{tex-file}) twice more to get the cross-references correct.
1633 @node Nroff Mode
1634 @section Nroff Mode
1636 @cindex nroff
1637 @findex nroff-mode
1638   Nroff mode is a mode like Text mode but modified to handle nroff commands
1639 present in the text.  Invoke @kbd{M-x nroff-mode} to enter this mode.  It
1640 differs from Text mode in only a few ways.  All nroff command lines are
1641 considered paragraph separators, so that filling will never garble the
1642 nroff commands.  Pages are separated by @samp{.bp} commands.  Comments
1643 start with backslash-doublequote.  Also, three special commands are
1644 provided that are not in Text mode:
1646 @findex forward-text-line
1647 @findex backward-text-line
1648 @findex count-text-lines
1649 @kindex M-n @r{(Nroff mode)}
1650 @kindex M-p @r{(Nroff mode)}
1651 @kindex M-? @r{(Nroff mode)}
1652 @table @kbd
1653 @item M-n
1654 Move to the beginning of the next line that isn't an nroff command
1655 (@code{forward-text-line}).  An argument is a repeat count.
1656 @item M-p
1657 Like @kbd{M-n} but move up (@code{backward-text-line}).
1658 @item M-?
1659 Prints in the echo area the number of text lines (lines that are not
1660 nroff commands) in the region (@code{count-text-lines}).
1661 @end table
1663 @findex electric-nroff-mode
1664   The other feature of Nroff mode is that you can turn on Electric Nroff
1665 mode.  This is a minor mode that you can turn on or off with @kbd{M-x
1666 electric-nroff-mode} (@pxref{Minor Modes}).  When the mode is on, each
1667 time you use @key{RET} to end a line that contains an nroff command that
1668 opens a kind of grouping, the matching nroff command to close that
1669 grouping is automatically inserted on the following line.  For example,
1670 if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
1671 this inserts the matching command @samp{.)b} on a new line following
1672 point.
1674   If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
1675 heading lines are lines of the form @samp{.H} followed by a number (the
1676 header level).
1678 @vindex nroff-mode-hook
1679   Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
1680 the hook @code{nroff-mode-hook} (@pxref{Hooks}).
1682 @node Formatted Text
1683 @section Editing Formatted Text
1685 @cindex Enriched mode
1686 @cindex mode, Enriched
1687 @cindex formatted text
1688 @cindex WYSIWYG
1689 @cindex word processing
1690   @dfn{Enriched mode} is a minor mode for editing files that contain
1691 formatted text in WYSIWYG fashion, as in a word processor.  Currently,
1692 formatted text in Enriched mode can specify fonts, colors, underlining,
1693 margins, and types of filling and justification.  In the future, we plan
1694 to implement other formatting features as well.
1696   Enriched mode is a minor mode (@pxref{Minor Modes}).  Typically it is
1697 used in conjunction with Text mode (@pxref{Text Mode}).  However, you
1698 can also use it with other major modes such as Outline mode and
1699 Paragraph-Indent Text mode.
1701 @cindex text/enriched MIME format
1702   Potentially, Emacs can store formatted text files in various file
1703 formats.  Currently, only one format is implemented: @dfn{text/enriched}
1704 format, which is defined by the MIME protocol.  @xref{Format
1705 Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual},
1706 for details of how Emacs recognizes and converts file formats.
1708   The Emacs distribution contains a formatted text file that can serve as
1709 an example.  Its name is @file{etc/enriched.doc}.  It contains samples
1710 illustrating all the features described in this section.  It also
1711 contains a list of ideas for future enhancements.
1713 @menu
1714 * Requesting Formatted Text::   Entering and exiting Enriched mode.
1715 * Hard and Soft Newlines::      There are two different kinds of newlines.
1716 * Editing Format Info::         How to edit text properties.
1717 * Faces: Format Faces.          Bold, italic, underline, etc.
1718 * Color: Format Colors.         Changing the color of text.
1719 * Indent: Format Indentation.   Changing the left and right margins.
1720 * Justification: Format Justification.
1721                                 Centering, setting text flush with the 
1722                                   left or right margin, etc.
1723 * Other: Format Properties.     The "special" text properties submenu.
1724 * Forcing Enriched Mode::       How to force use of Enriched mode.
1725 @end menu
1727 @node Requesting Formatted Text
1728 @subsection Requesting to Edit Formatted Text
1730   Whenever you visit a file that Emacs saved in the text/enriched format,
1731 Emacs automatically converts the formatting information in the file into
1732 Emacs's own internal format (text properties), and turns on Enriched
1733 mode.
1735 @findex enriched-mode
1736   To create a new file of formatted text, first visit the nonexistent
1737 file, then type @kbd{M-x enriched-mode} before you start inserting text.
1738 This command turns on Enriched mode.  Do this before you begin inserting
1739 text, to ensure that the text you insert is handled properly.
1741   More generally, the command @code{enriched-mode} turns Enriched mode
1742 on if it was off, and off if it was on.  With a prefix argument, this
1743 command turns Enriched mode on if the argument is positive, and turns
1744 the mode off otherwise.
1746   When you save a buffer while Enriched mode is enabled in it, Emacs
1747 automatically converts the text to text/enriched format while writing it
1748 into the file.  When you visit the file again, Emacs will automatically
1749 recognize the format, reconvert the text, and turn on Enriched mode
1750 again.
1752 @vindex enriched-fill-after-visiting
1753   Normally, after visiting a file in text/enriched format, Emacs refills
1754 each paragraph to fit the specified right margin.  You can turn off this
1755 refilling, to save time, by setting the variable
1756 @code{enriched-fill-after-visiting} to @code{nil} or to @code{ask}.
1758   However, when visiting a file that was saved from Enriched mode, there
1759 is no need for refilling, because Emacs saves the right margin settings
1760 along with the text.
1762 @vindex enriched-translations
1763   You can add annotations for saving additional text properties, which
1764 Emacs normally does not save, by adding to @code{enriched-translations}.
1765 Note that the text/enriched standard requires any non-standard
1766 annotations to have names starting with @samp{x-}, as in
1767 @samp{x-read-only}.  This ensures that they will not conflict with
1768 standard annotations that may be added later.
1770 @node Hard and Soft Newlines
1771 @subsection Hard and Soft Newlines
1772 @cindex hard newline
1773 @cindex soft newline
1774 @cindex newlines, hard and soft
1776   In formatted text, Emacs distinguishes between two different kinds of
1777 newlines, @dfn{hard} newlines and @dfn{soft} newlines.
1779   Hard newlines are used to separate paragraphs, or items in a list, or
1780 anywhere that there should always be a line break regardless of the
1781 margins.  The @key{RET} command (@code{newline}) and @kbd{C-o}
1782 (@code{open-line}) insert hard newlines.
1784   Soft newlines are used to make text fit between the margins.  All the
1785 fill commands, including Auto Fill, insert soft newlines---and they
1786 delete only soft newlines.
1788   Although hard and soft newlines look the same, it is important to bear
1789 the difference in mind.  Do not use @key{RET} to break lines in the
1790 middle of filled paragraphs, or else you will get hard newlines that are
1791 barriers to further filling.  Instead, let Auto Fill mode break lines,
1792 so that if the text or the margins change, Emacs can refill the lines
1793 properly.  @xref{Auto Fill}.
1795   On the other hand, in tables and lists, where the lines should always
1796 remain as you type them, you can use @key{RET} to end lines.  For these
1797 lines, you may also want to set the justification style to
1798 @code{unfilled}.  @xref{Format Justification}.
1800 @node Editing Format Info
1801 @subsection Editing Format Information
1803   There are two ways to alter the formatting information for a formatted
1804 text file: with keyboard commands, and with the mouse.
1806   The easiest way to add properties to your document is by using the Text
1807 Properties menu.  You can get to this menu in two ways: from the Edit
1808 menu in the menu bar, or with @kbd{C-mouse-2} (hold the @key{CTRL} key
1809 and press the middle mouse button).
1811   Most of the items in the Text Properties menu lead to other submenus.
1812 These are described in the sections that follow.  Some items run
1813 commands directly:
1815 @table @code
1816 @findex facemenu-remove-props
1817 @item Remove Properties
1818 Delete from the region all the text properties that the Text Properties
1819 menu works with (@code{facemenu-remove-props}).
1821 @findex facemenu-remove-all
1822 @item Remove All
1823 Delete @emph{all} text properties from the region
1824 (@code{facemenu-remove-all}).
1826 @findex list-text-properties-at
1827 @item List Properties
1828 List all the text properties of the character following point
1829 (@code{list-text-properties-at}).
1831 @item Display Faces
1832 Display a list of all the defined faces.
1834 @item Display Colors
1835 Display a list of all the defined colors.
1836 @end table
1837             
1838 @node Format Faces
1839 @subsection Faces in Formatted Text
1841   The Faces submenu lists various Emacs faces including @code{bold},
1842 @code{italic}, and @code{underline}.  Selecting one of these adds the
1843 chosen face to the region.  @xref{Faces}.  You can also specify a face
1844 with these keyboard commands:
1846 @table @kbd
1847 @kindex M-g d @r{(Enriched mode)}
1848 @findex facemenu-set-default
1849 @item M-g d
1850 Set the region, or the next inserted character, to the @code{default} face
1851 (@code{facemenu-set-default}).
1852 @kindex M-g b @r{(Enriched mode)}
1853 @findex facemenu-set-bold
1854 @item M-g b
1855 Set the region, or the next inserted character, to the @code{bold} face
1856 (@code{facemenu-set-bold}).
1857 @kindex M-g i @r{(Enriched mode)}
1858 @findex facemenu-set-italic
1859 @item M-g i
1860 Set the region, or the next inserted character, to the @code{italic} face
1861 (@code{facemenu-set-italic}).
1862 @kindex M-g l @r{(Enriched mode)}
1863 @findex facemenu-set-bold-italic
1864 @item M-g l
1865 Set the region, or the next inserted character, to the @code{bold-italic} face
1866 (@code{facemenu-set-bold-italic}).
1867 @kindex M-g u @r{(Enriched mode)}
1868 @findex facemenu-set-underline
1869 @item M-g u
1870 Set the region, or the next inserted character, to the @code{underline} face
1871 (@code{facemenu-set-underline}).
1872 @kindex M-g o @r{(Enriched mode)}
1873 @findex facemenu-set-face
1874 @item M-g o @var{face} @key{RET}
1875 Set the region, or the next inserted character, to the face @var{face}
1876 (@code{facemenu-set-face}).
1877 @end table
1879   If you use these commands with a prefix argument---or, in Transient Mark
1880 mode, if the region is not active---then these commands specify a face
1881 to use for your next self-inserting input.  @xref{Transient Mark}.  This
1882 applies to both the keyboard commands and the menu commands.
1884   Enriched mode defines two additional faces: @code{excerpt} and
1885 @code{fixed}.  These correspond to codes used in the text/enriched file
1886 format.
1888   The @code{excerpt} face is intended for quotations.  This face is the
1889 same as @code{italic} unless you customize it (@pxref{Face Customization}).
1891   The @code{fixed} face is meant to say, ``Use a fixed-width font for this
1892 part of the text.''  Emacs currently supports only fixed-width fonts;
1893 therefore, the @code{fixed} annotation is not necessary now.  However,
1894 we plan to support variable width fonts in future Emacs versions, and
1895 other systems that display text/enriched format may not use a
1896 fixed-width font as the default.  So if you specifically want a certain
1897 part of the text to use a fixed-width font, you should specify the
1898 @code{fixed} face for that part.
1900   The @code{fixed} face is normally defined to use a different font from
1901 the default.  However, different systems have different fonts installed,
1902 so you may need to customize this.
1904   If your terminal cannot display different faces, you will not be able
1905 to see them, but you can still edit documents containing faces.  You can
1906 even add faces and colors to documents.  They will be visible when the
1907 file is viewed on a terminal that can display them.
1909 @node Format Colors
1910 @subsection Colors in Formatted Text
1912   You can specify foreground and background colors for portions of the
1913 text.  There is a menu for specifying the foreground color and a menu
1914 for specifying the background color.  Each color menu lists all the
1915 colors that you have used in Enriched mode in the current Emacs session.
1917   If you specify a color with a prefix argument---or, in Transient Mark
1918 mode, if the region is not active---then it applies to your next
1919 self-inserting input.  @xref{Transient Mark}.  Otherwise, the command
1920 applies to the region.
1922   Each color menu contains one additional item: @samp{Other}.  You can use
1923 this item to specify a color that is not listed in the menu; it reads
1924 the color name with the minibuffer.  To display list of available colors
1925 and their names, use the @samp{Display Colors} menu item in the Text
1926 Properties menu (@pxref{Editing Format Info}).
1928   Any color that you specify in this way, or that is mentioned in a
1929 formatted text file that you read in, is added to both color menus for
1930 the duration of the Emacs session.
1932 @findex facemenu-set-foreground
1933 @findex facemenu-set-background
1934   There are no key bindings for specifying colors, but you can do so
1935 with the extended commands @kbd{M-x facemenu-set-foreground} and
1936 @kbd{M-x facemenu-set-background}.  Both of these commands read the name
1937 of the color with the minibuffer.
1939 @node Format Indentation
1940 @subsection Indentation in Formatted Text
1942   When editing formatted text, you can specify different amounts of
1943 indentation for the right or left margin of an entire paragraph or a
1944 part of a paragraph.  The margins you specify automatically affect the
1945 Emacs fill commands (@pxref{Filling}) and line-breaking commands.
1947   The Indentation submenu provides a convenient interface for specifying
1948 these properties.  The submenu contains four items:
1950 @table @code
1951 @kindex C-x TAB @r{(Enriched mode)}
1952 @findex increase-left-margin
1953 @item Indent More
1954 Indent the region by 4 columns (@code{increase-left-margin}).  In
1955 Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
1956 you supply a numeric argument, that says how many columns to add to the
1957 margin (a negative argument reduces the number of columns).
1959 @item Indent Less
1960 Remove 4 columns of indentation from the region.
1962 @item Indent Right More
1963 Make the text narrower by indenting 4 columns at the right margin.
1965 @item Indent Right Less
1966 Remove 4 columns of indentation from the right margin.
1967 @end table
1969   You can use these commands repeatedly to increase or decrease the
1970 indentation.
1972   The most common way to use these commands is to change the indentation
1973 of an entire paragraph.  However, that is not the only use.  You can
1974 change the margins at any point; the new values take effect at the end
1975 of the line (for right margins) or the beginning of the next line (for
1976 left margins).
1978   This makes it possible to format paragraphs with @dfn{hanging indents},
1979 which means that the first line is indented less than subsequent lines.
1980 To set up a hanging indent, increase the indentation of the region
1981 starting after the first word of the paragraph and running until the end
1982 of the paragraph.
1984   Indenting the first line of a paragraph is easier.  Set the margin for
1985 the whole paragraph where you want it to be for the body of the
1986 paragraph, then indent the first line by inserting extra spaces or tabs.
1988   Sometimes, as a result of editing, the filling of a paragraph becomes
1989 messed up---parts of the paragraph may extend past the left or right
1990 margins.  When this happens, use @kbd{M-q} (@code{fill-paragraph}) to
1991 refill the paragraph.
1993 @vindex standard-indent
1994   The variable @code{standard-indent} specifies how many columns these
1995 commands should add to or subtract from the indentation.  The default
1996 value is 4.  The overall default right margin for Enriched mode is
1997 controlled by the variable @code{fill-column}, as usual.
1999   The fill prefix, if any, works in addition to the specified paragraph
2000 indentation: @kbd{C-x .} does not include the specified indentation's
2001 whitespace in the new value for the fill prefix, and the fill commands
2002 look for the fill prefix after the indentation on each line.  @xref{Fill
2003 Prefix}.
2005 @node Format Justification
2006 @subsection Justification in Formatted Text
2007             
2008   When editing formatted text, you can specify various styles of
2009 justification for a paragraph.  The style you specify automatically
2010 affects the Emacs fill commands.
2012   The Justification submenu provides a convenient interface for specifying
2013 the style.  The submenu contains five items:
2015 @table @code
2016 @item Flush Left
2017 This is the most common style of justification (at least for English).
2018 Lines are aligned at the left margin but left uneven at the right.
2020 @item Flush Right
2021 This aligns each line with the right margin.  Spaces and tabs are added
2022 on the left, if necessary, to make lines line up on the right.
2024 @item Full
2025 This justifies the text, aligning both edges of each line.  Justified
2026 text looks very nice in a printed book, where the spaces can all be
2027 adjusted equally, but it does not look as nice with a fixed-width font
2028 on the screen.  Perhaps a future version of Emacs will be able to adjust
2029 the width of spaces in a line to achieve elegant justification.
2031 @item Center
2032 This centers every line between the current margins.
2034 @item None
2035 This turns off filling entirely.  Each line will remain as you wrote it;
2036 the fill and auto-fill functions will have no effect on text which has
2037 this setting.  You can, however, still indent the left margin.  In
2038 unfilled regions, all newlines are treated as hard newlines (@pxref{Hard
2039 and Soft Newlines}) .
2040 @end table
2042   In Enriched mode, you can also specify justification from the keyboard
2043 using the @kbd{M-j} prefix character:
2045 @table @kbd
2046 @kindex M-j l @r{(Enriched mode)}
2047 @findex set-justification-left
2048 @item M-j l
2049 Make the region left-filled (@code{set-justification-left}).
2050 @kindex M-j r @r{(Enriched mode)}
2051 @findex set-justification-right
2052 @item M-j r
2053 Make the region right-filled (@code{set-justification-right}).
2054 @kindex M-j f @r{(Enriched mode)}
2055 @findex set-justification-full
2056 @item M-j f
2057 Make the region fully-justified (@code{set-justification-full}).
2058 @kindex M-j c @r{(Enriched mode)}
2059 @kindex M-S @r{(Enriched mode)}
2060 @findex set-justification-center
2061 @item M-j c
2062 @itemx M-S
2063 Make the region centered (@code{set-justification-center}).
2064 @kindex M-j u @r{(Enriched mode)}
2065 @findex set-justification-none
2066 @item M-j u
2067 Make the region unfilled (@code{set-justification-none}).
2068 @end table
2070   Justification styles apply to entire paragraphs.  All the
2071 justification-changing commands operate on the paragraph containing
2072 point, or, if the region is active, on all paragraphs which overlap the
2073 region.
2075 @vindex default-justification
2076   The default justification style is specified by the variable
2077 @code{default-justification}.  Its value should be one of the symbols
2078 @code{left}, @code{right}, @code{full}, @code{center}, or @code{none}.
2079          
2080 @node Format Properties
2081 @subsection Setting Other Text Properties
2083   The Other Properties menu lets you add or remove three other useful text
2084 properties: @code{read-only}, @code{invisible} and @code{intangible}.
2085 The @code{intangible} property disallows moving point within the text,
2086 the @code{invisible} text property hides text from display, and the
2087 @code{read-only} property disallows alteration of the text.
2089   Each of these special properties has a menu item to add it to the
2090 region.  The last menu item, @samp{Remove Special}, removes all of these
2091 special properties from the text in the region.
2093   Currently, the @code{invisible} and @code{intangible} properties are
2094 @emph{not} saved in the text/enriched format.  The @code{read-only}
2095 property is saved, but it is not a standard part of the text/enriched
2096 format, so other editors may not respect it.
2098 @node Forcing Enriched Mode
2099 @subsection Forcing Enriched Mode
2101   Normally, Emacs knows when you are editing formatted text because it
2102 recognizes the special annotations used in the file that you visited.
2103 However, there are situations in which you must take special actions
2104 to convert file contents or turn on Enriched mode:
2106 @itemize @bullet
2107 @item
2108 When you visit a file that was created with some other editor, Emacs may
2109 not recognize the file as being in the text/enriched format.  In this
2110 case, when you visit the file you will see the formatting commands
2111 rather than the formatted text.  Type @kbd{M-x format-decode-buffer} to
2112 translate it.
2114 @item
2115 When you @emph{insert} a file into a buffer, rather than visiting it.
2116 Emacs does the necessary conversions on the text which you insert, but
2117 it does not enable Enriched mode.  If you wish to do that, type @kbd{M-x
2118 enriched-mode}.
2119 @end itemize 
2121   The command @code{format-decode-buffer} translates text in various
2122 formats into Emacs's internal format.  It asks you to specify the format
2123 to translate from; however, normally you can type just @key{RET}, which
2124 tells Emacs to guess the format.
2126 @findex format-find-file
2127   If you wish to look at text/enriched file in its raw form, as a
2128 sequence of characters rather than as formatted text, use the @kbd{M-x
2129 find-file-literally} command.  This visits a file, like
2130 @code{find-file}, but does not do format conversion.  It also inhibits
2131 character code conversion (@pxref{Coding Systems}) and automatic
2132 uncompression (@pxref{Compressed Files}).  To disable format conversion
2133 but allow character code conversion and/or automatic uncompression if
2134 appropriate, use @code{format-find-file} with suitable arguments.