(Fprocess_send_eof): Abort if fail to open null device.
[emacs.git] / man / text.texi
blob97e6aa5033835ebe74a73bf7a1b46c4e9a0cfd7f
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
3 @c   2002, 2003, 2004, 2005, 2006 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 binary data.  This chapter is concerned with
16 editing text in the narrower sense.
18   Human languages have syntactic/stylistic conventions that can be
19 supported or used to advantage by editor commands: conventions involving
20 words, sentences, paragraphs, and capital letters.  This chapter
21 describes Emacs commands for all of these things.  There are also
22 commands for @dfn{filling}, which means rearranging the lines of a
23 paragraph to be approximately equal in length.  The commands for moving
24 over and killing words, sentences and paragraphs, while intended
25 primarily for editing text, are also often useful for editing programs.
27   Emacs has several major modes for editing human-language text.  If the
28 file contains text pure and simple, use Text mode, which customizes
29 Emacs in small ways for the syntactic conventions of text.  Outline mode
30 provides special commands for operating on text with an outline
31 structure.
32 @iftex
33 @xref{Outline Mode}.
34 @end iftex
36   For text which contains embedded commands for text formatters, Emacs
37 has other major modes, each for a particular text formatter.  Thus, for
38 input to @TeX{}, you would use @TeX{}
39 @iftex
40 mode (@pxref{TeX Mode}).
41 @end iftex
42 @ifinfo
43 mode.
44 @end ifinfo
45 For input to groff or nroff, use Nroff mode.
47   Instead of using a text formatter, you can edit formatted text in
48 WYSIWYG style (``what you see is what you get''), with Enriched mode.
49 Then the formatting appears on the screen in Emacs while you edit.
50 @iftex
51 @xref{Formatted Text}.
52 @end iftex
54 @cindex ASCII art
55   If you need to edit pictures made out of text characters (commonly
56 referred to as ``ASCII art''), use @kbd{M-x edit-picture} to enter
57 Picture mode, a special major mode for editing such pictures.
58 @inforef{Picture Mode,, emacs-xtra}.
60 @cindex skeletons
61 @cindex templates
62 @cindex autotyping
63 @cindex automatic typing
64   The ``automatic typing'' features may be useful when writing text.
65 @inforef{Top,, autotype}.
67 @menu
68 * Words::               Moving over and killing words.
69 * Sentences::           Moving over and killing sentences.
70 * Paragraphs::          Moving over paragraphs.
71 * Pages::               Moving over pages.
72 * Filling::             Filling or justifying text.
73 * Case::                Changing the case of text.
74 * Text Mode::           The major modes for editing text files.
75 * Outline Mode::        Editing outlines.
76 * TeX Mode::            Editing input to the formatter TeX.
77 * HTML Mode::           Editing HTML, SGML, and XML files.
78 * Nroff Mode::          Editing input to the formatter nroff.
79 * Formatted Text::      Editing formatted text directly in WYSIWYG fashion.
80 * Text Based Tables::   Editing text-based tables in WYSIWYG fashion.
81 @end menu
83 @node Words
84 @section Words
85 @cindex words
86 @cindex Meta commands and words
88   Emacs has commands for moving over or operating on words.  By convention,
89 the keys for them are all Meta characters.
91 @table @kbd
92 @item M-f
93 Move forward over a word (@code{forward-word}).
94 @item M-b
95 Move backward over a word (@code{backward-word}).
96 @item M-d
97 Kill up to the end of a word (@code{kill-word}).
98 @item M-@key{DEL}
99 Kill back to the beginning of a word (@code{backward-kill-word}).
100 @item M-@@
101 Mark the end of the next word (@code{mark-word}).
102 @item M-t
103 Transpose two words or drag a word across other words
104 (@code{transpose-words}).
105 @end table
107   Notice how these keys form a series that parallels the character-based
108 @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}.  @kbd{M-@@} is
109 cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
111 @kindex M-f
112 @kindex M-b
113 @findex forward-word
114 @findex backward-word
115   The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b}
116 (@code{backward-word}) move forward and backward over words.  These
117 Meta characters are thus analogous to the corresponding control
118 characters, @kbd{C-f} and @kbd{C-b}, which move over single characters
119 in the text.  The analogy extends to numeric arguments, which serve as
120 repeat counts.  @kbd{M-f} with a negative argument moves backward, and
121 @kbd{M-b} with a negative argument moves forward.  Forward motion
122 stops right after the last letter of the word, while backward motion
123 stops right before the first letter.
125 @kindex M-d
126 @findex kill-word
127   @kbd{M-d} (@code{kill-word}) kills the word after point.  To be
128 precise, it kills everything from point to the place @kbd{M-f} would
129 move to.  Thus, if point is in the middle of a word, @kbd{M-d} kills
130 just the part after point.  If some punctuation comes between point and the
131 next word, it is killed along with the word.  (If you wish to kill only the
132 next word but not the punctuation before it, simply do @kbd{M-f} to get
133 the end, and kill the word backwards with @kbd{M-@key{DEL}}.)
134 @kbd{M-d} takes arguments just like @kbd{M-f}.
136 @findex backward-kill-word
137 @kindex M-DEL
138   @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
139 point.  It kills everything from point back to where @kbd{M-b} would
140 move to.  For instance, if point is after the space in @w{@samp{FOO,
141 BAR}}, it kills @w{@samp{FOO, }}.  If you wish to kill just
142 @samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead
143 of @kbd{M-@key{DEL}}.
145 @c Don't index M-t and transpose-words here, they are indexed in
146 @c fixit.texi, in the node "Transpose".
147 @c @kindex M-t
148 @c @findex transpose-words
149   @kbd{M-t} (@code{transpose-words}) exchanges the word before or
150 containing point with the following word.  The delimiter characters between
151 the words do not move.  For example, @w{@samp{FOO, BAR}} transposes into
152 @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.  @xref{Transpose}, for
153 more on transposition and on arguments to transposition commands.
155 @kindex M-@@
156 @findex mark-word
157   To operate on the next @var{n} words with an operation which applies
158 between point and mark, you can either set the mark at point and then move
159 over the words, or you can use the command @kbd{M-@@} (@code{mark-word})
160 which does not move point, but sets the mark where @kbd{M-f} would move
161 to.  @kbd{M-@@} accepts a numeric argument that says how many words to
162 scan for the place to put the mark.  In Transient Mark mode, this command
163 activates the mark.
165   The word commands' understanding of word boundaries is controlled
166 by the syntax table.  Any character can, for example, be declared to
167 be a word delimiter.  @xref{Syntax}.
169 @node Sentences
170 @section Sentences
171 @cindex sentences
172 @cindex manipulating sentences
174   The Emacs commands for manipulating sentences and paragraphs are mostly
175 on Meta keys, so as to be like the word-handling commands.
177 @table @kbd
178 @item M-a
179 Move back to the beginning of the sentence (@code{backward-sentence}).
180 @item M-e
181 Move forward to the end of the sentence (@code{forward-sentence}).
182 @item M-k
183 Kill forward to the end of the sentence (@code{kill-sentence}).
184 @item C-x @key{DEL}
185 Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
186 @end table
188 @kindex M-a
189 @kindex M-e
190 @findex backward-sentence
191 @findex forward-sentence
192   The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and
193 @code{forward-sentence}) move to the beginning and end of the current
194 sentence, respectively.  They were chosen to resemble @kbd{C-a} and
195 @kbd{C-e}, which move to the beginning and end of a line.  Unlike
196 them, @kbd{M-a} and @kbd{M-e} move over successive sentences if
197 repeated.
199   Moving backward over a sentence places point just before the first
200 character of the sentence; moving forward places point right after the
201 punctuation that ends the sentence.  Neither one moves over the
202 whitespace at the sentence boundary.
204 @kindex M-k
205 @kindex C-x DEL
206 @findex kill-sentence
207 @findex backward-kill-sentence
208   Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
209 with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
210 @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of
211 the sentence.  With minus one as an argument it kills back to the
212 beginning of the sentence.  Larger arguments serve as a repeat count.
213 There is also a command, @kbd{C-x @key{DEL}}
214 (@code{backward-kill-sentence}), for killing back to the beginning of a
215 sentence.  This command is useful when you change your mind in the
216 middle of composing text.
218   The sentence commands assume that you follow the American typist's
219 convention of putting two spaces at the end of a sentence; they consider
220 a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!}
221 followed by the end of a line or two spaces, with any number of
222 @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between.
223 A sentence also begins or ends wherever a paragraph begins or ends.
224 It is useful to follow this convention, because it makes a distinction
225 between periods that end a sentence and periods that indicate
226 abbreviations; that enables the Emacs sentence commands to distinguish,
227 too.  These commands to not stop for periods that indicate abbreviations.
229 @vindex sentence-end-double-space
230   If you want to use just one space between sentences, you can set the
231 variable @code{sentence-end-double-space} to @code{nil} to make the
232 sentence commands stop for single spaces.  However, this mode has a
233 drawback: there is no way to distinguish between periods that end
234 sentences and those that indicate abbreviations.  For convenient and
235 reliable editing, we therefore recommend you follow the two-space
236 convention.  The variable @code{sentence-end-double-space} also
237 affects filling (@pxref{Fill Commands}) in related ways.
239 @vindex sentence-end
240   The variable @code{sentence-end} controls how to recognize the end
241 of a sentence.  If non-@code{nil}, it is a regexp that matches the
242 last few characters of a sentence, together with the whitespace
243 following the sentence.  If the value is @code{nil}, the default, then
244 Emacs computes the regexp according to various criteria such as the
245 value of @code{sentence-end-double-space}.  @xref{Regexp Example}, for
246 a detailed explanation of one of the regular expressions Emacs uses
247 for this purpose.
249 @vindex sentence-end-without-period
250   Some languages do not use period to indicate end of sentence.  For
251 example, a sentence in Thai text ends with double space but without a
252 period.  Set the variable @code{sentence-end-without-period} to
253 @code{t} to tell the sentence commands that a period is not necessary.
255 @node Paragraphs
256 @section Paragraphs
257 @cindex paragraphs
258 @cindex manipulating paragraphs
259 @kindex M-@{
260 @kindex M-@}
261 @findex backward-paragraph
262 @findex forward-paragraph
264   The Emacs commands for manipulating paragraphs are also Meta keys.
266 @table @kbd
267 @item M-@{
268 Move back to previous paragraph beginning (@code{backward-paragraph}).
269 @item M-@}
270 Move forward to next paragraph end (@code{forward-paragraph}).
271 @item M-h
272 Put point and mark around this or next paragraph (@code{mark-paragraph}).
273 @end table
275   @kbd{M-@{} moves to the beginning of the current or previous
276 paragraph, while @kbd{M-@}} moves to the end of the current or next
277 paragraph.  Blank lines and text-formatter command lines separate
278 paragraphs and are not considered part of any paragraph.  If there is
279 a blank line before the paragraph, @kbd{M-@{} moves to the blank line,
280 because that is convenient in practice.
282   In Text mode, an indented line is not a paragraph break.  If you
283 want indented lines to have this effect, use Paragraph-Indent Text
284 mode instead.  @xref{Text Mode}.
286   In major modes for programs, paragraphs begin and end only at blank
287 lines.  This makes the paragraph commands useful, even though there
288 are no paragraphs as such in a program.
290   When you have set a fill prefix, then paragraphs are delimited by
291 all lines which don't start with the fill prefix.  @xref{Filling}.
293 @kindex M-h
294 @findex mark-paragraph
295   When you wish to operate on a paragraph, you can use the command
296 @kbd{M-h} (@code{mark-paragraph}) to set the region around it.  Thus,
297 for example, @kbd{M-h C-w} kills the paragraph around or after point.
298 The @kbd{M-h} command puts point at the beginning and mark at the end of
299 the paragraph point was in.  In Transient Mark mode, it activates the
300 mark.  If point is between paragraphs (in a run of blank lines, or at a
301 boundary), the paragraph following point is surrounded by point and
302 mark.  If there are blank lines preceding the first line of the
303 paragraph, one of these blank lines is included in the region.
305 @vindex paragraph-start
306 @vindex paragraph-separate
307   The precise definition of a paragraph boundary is controlled by the
308 variables @code{paragraph-separate} and @code{paragraph-start}.  The
309 value of @code{paragraph-start} is a regexp that should match any line
310 that either starts or separates paragraphs.  The value of
311 @code{paragraph-separate} is another regexp that should match only lines
312 that separate paragraphs without being part of any paragraph (for
313 example, blank lines).  Lines that start a new paragraph and are
314 contained in it must match only @code{paragraph-start}, not
315 @code{paragraph-separate}.  Each regular expression must match at the
316 left margin.  For example, in Fundamental mode, @code{paragraph-start}
317 is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is
318 @w{@code{"[ \t\f]*$"}}.
320   Normally it is desirable for page boundaries to separate paragraphs.
321 The default values of these variables recognize the usual separator for
322 pages.
324 @node Pages
325 @section Pages
327 @cindex pages
328 @cindex formfeed
329   Files are often thought of as divided into @dfn{pages} by the
330 @dfn{formfeed} character (@acronym{ASCII} control-L, octal code 014).
331 When you print hardcopy for a file, this character forces a page break;
332 thus, each page of the file goes on a separate page on paper.  Most Emacs
333 commands treat the page-separator character just like any other
334 character: you can insert it with @kbd{C-q C-l}, and delete it with
335 @key{DEL}.  Thus, you are free to paginate your file or not.  However,
336 since pages are often meaningful divisions of the file, Emacs provides
337 commands to move over them and operate on them.
339 @table @kbd
340 @item C-x [
341 Move point to previous page boundary (@code{backward-page}).
342 @item C-x ]
343 Move point to next page boundary (@code{forward-page}).
344 @item C-x C-p
345 Put point and mark around this page (or another page) (@code{mark-page}).
346 @item C-x l
347 Count the lines in this page (@code{count-lines-page}).
348 @end table
350 @kindex C-x [
351 @kindex C-x ]
352 @findex forward-page
353 @findex backward-page
354   The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
355 after the previous page delimiter.  If point is already right after a page
356 delimiter, it skips that one and stops at the previous one.  A numeric
357 argument serves as a repeat count.  The @kbd{C-x ]} (@code{forward-page})
358 command moves forward past the next page delimiter.
360 @kindex C-x C-p
361 @findex mark-page
362   The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
363 beginning of the current page and the mark at the end.  The page
364 delimiter at the end is included (the mark follows it).  The page
365 delimiter at the front is excluded (point follows it).  In Transient
366 Mark mode, this command activates the mark.
368   @kbd{C-x C-p C-w} is a handy way to kill a page to move it
369 elsewhere.  If you move to another page delimiter with @kbd{C-x [} and
370 @kbd{C-x ]}, then yank the killed page, all the pages will be properly
371 delimited once again.  The reason @kbd{C-x C-p} includes only the
372 following page delimiter in the region is to ensure that.
374   A numeric argument to @kbd{C-x C-p} is used to specify which page to go
375 to, relative to the current one.  Zero means the current page.  One means
376 the next page, and @minus{}1 means the previous one.
378 @kindex C-x l
379 @findex count-lines-page
380   The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
381 where to break a page in two.  It displays in the echo area the total number
382 of lines in the current page, and then divides it up into those preceding
383 the current line and those following, as in
385 @example
386 Page has 96 (72+25) lines
387 @end example
389 @noindent
390   Notice that the sum is off by one; this is correct if point is not at the
391 beginning of a line.
393 @vindex page-delimiter
394   The variable @code{page-delimiter} controls where pages begin.  Its
395 value is a regexp that matches the beginning of a line that separates
396 pages.  The normal value of this variable is @code{"^\f"}, which
397 matches a formfeed character at the beginning of a line.
399 @node Filling
400 @section Filling Text
401 @cindex filling text
403   @dfn{Filling} text means breaking it up into lines that fit a
404 specified width.  Emacs does filling in two ways.  In Auto Fill mode,
405 inserting text with self-inserting characters also automatically fills
406 it.  There are also explicit fill commands that you can use when editing
407 text leaves it unfilled.  When you edit formatted text, you can specify
408 a style of filling for each portion of the text (@pxref{Formatted
409 Text}).
411 @menu
412 * Auto Fill::           Auto Fill mode breaks long lines automatically.
413 * Fill Commands::       Commands to refill paragraphs and center lines.
414 * Fill Prefix::         Filling paragraphs that are indented
415                           or in a comment, etc.
416 * Adaptive Fill::       How Emacs can determine the fill prefix automatically.
417 * Refill::              Keeping paragraphs filled.
418 * Longlines::           Editing text with very long lines.
419 @end menu
421 @node Auto Fill
422 @subsection Auto Fill Mode
423 @cindex Auto Fill mode
424 @cindex mode, Auto Fill
426   @dfn{Auto Fill} mode is a minor mode in which lines are broken
427 automatically when they become too wide.  Breaking happens only when
428 you type a @key{SPC} or @key{RET}.
430 @table @kbd
431 @item M-x auto-fill-mode
432 Enable or disable Auto Fill mode.
433 @item @key{SPC}
434 @itemx @key{RET}
435 In Auto Fill mode, break lines when appropriate.
436 @end table
438 @findex auto-fill-mode
439   @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off
440 if it was on.  With a positive numeric argument it always turns Auto
441 Fill mode on, and with a negative argument always turns it off.  You can
442 see when Auto Fill mode is in effect by the presence of the word
443 @samp{Fill} in the mode line, inside the parentheses.  Auto Fill mode is
444 a minor mode which is enabled or disabled for each buffer individually.
445 @xref{Minor Modes}.
447   In Auto Fill mode, lines are broken automatically at spaces when they
448 get longer than the desired width.  Line breaking and rearrangement
449 takes place only when you type @key{SPC} or @key{RET}.  If you wish to
450 insert a space or newline without permitting line-breaking, type
451 @kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a
452 control-J).  Also, @kbd{C-o} inserts a newline without line breaking.
454   Auto Fill mode works well with programming-language modes, because it
455 indents new lines with @key{TAB}.  If a line ending in a comment gets
456 too long, the text of the comment is split into two comment lines.
457 Optionally, new comment delimiters are inserted at the end of the first
458 line and the beginning of the second so that each line is a separate
459 comment; the variable @code{comment-multi-line} controls the choice
460 (@pxref{Comments}).
462   Adaptive filling (@pxref{Adaptive Fill}) works for Auto Filling as
463 well as for explicit fill commands.  It takes a fill prefix
464 automatically from the second or first line of a paragraph.
466   Auto Fill mode does not refill entire paragraphs; it can break lines but
467 cannot merge lines.  So editing in the middle of a paragraph can result in
468 a paragraph that is not correctly filled.  The easiest way to make the
469 paragraph properly filled again is usually with the explicit fill commands.
470 @ifinfo
471 @xref{Fill Commands}.
472 @end ifinfo
474   Many users like Auto Fill mode and want to use it in all text files.
475 The section on init files says how to arrange this permanently for yourself.
476 @xref{Init File}.
478 @node Fill Commands
479 @subsection Explicit Fill Commands
481 @table @kbd
482 @item M-q
483 Fill current paragraph (@code{fill-paragraph}).
484 @item C-x f
485 Set the fill column (@code{set-fill-column}).
486 @item M-x fill-region
487 Fill each paragraph in the region (@code{fill-region}).
488 @item M-x fill-region-as-paragraph
489 Fill the region, considering it as one paragraph.
490 @item M-s
491 Center a line.
492 @end table
494 @kindex M-q
495 @findex fill-paragraph
496   To refill a paragraph, use the command @kbd{M-q}
497 (@code{fill-paragraph}).  This operates on the paragraph that point is
498 inside, or the one after point if point is between paragraphs.
499 Refilling works by removing all the line-breaks, then inserting new ones
500 where necessary.
502 @findex fill-region
503   To refill many paragraphs, use @kbd{M-x fill-region}, which
504 finds the paragraphs in the region and fills each of them.
506 @findex fill-region-as-paragraph
507   @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h}
508 for finding paragraph boundaries (@pxref{Paragraphs}).  For more
509 control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
510 everything between point and mark as a single paragraph.  This command
511 deletes any blank lines within the region, so separate blocks of text
512 end up combined into one block.
514 @cindex justification
515   A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text
516 as well as filling it.  This means that extra spaces are inserted to
517 make the right margin line up exactly at the fill column.  To remove
518 the extra spaces, use @kbd{M-q} with no argument.  (Likewise for
519 @code{fill-region}.)  Another way to control justification, and choose
520 other styles of filling, is with the @code{justification} text
521 property; see @ref{Format Justification}.
523 @kindex M-s @r{(Text mode)}
524 @cindex centering
525 @findex center-line
526   The command @kbd{M-s} (@code{center-line}) centers the current line
527 within the current fill column.  With an argument @var{n}, it centers
528 @var{n} lines individually and moves past them.  This binding is
529 made by Text mode and is available only in that and related modes
530 (@pxref{Text Mode}).
532 @vindex fill-column
533 @kindex C-x f
534 @findex set-fill-column
535   The maximum line width for filling is in the variable
536 @code{fill-column}.  Altering the value of @code{fill-column} makes it
537 local to the current buffer; until that time, the default value is in
538 effect.  The default is initially 70.  @xref{Locals}.  The easiest way
539 to set @code{fill-column} is to use the command @kbd{C-x f}
540 (@code{set-fill-column}).  With a numeric argument, it uses that as the
541 new fill column.  With just @kbd{C-u} as argument, it sets
542 @code{fill-column} to the current horizontal position of point.
544   Emacs commands normally consider a period followed by two spaces or by
545 a newline as the end of a sentence; a period followed by just one space
546 indicates an abbreviation and not the end of a sentence.  To preserve
547 the distinction between these two ways of using a period, the fill
548 commands do not break a line after a period followed by just one space.
550   If the variable @code{sentence-end-double-space} is @code{nil}, the
551 fill commands expect and leave just one space at the end of a sentence.
552 Ordinarily this variable is @code{t}, so the fill commands insist on
553 two spaces for the end of a sentence, as explained above.  @xref{Sentences}.
555 @vindex colon-double-space
556   If the variable @code{colon-double-space} is non-@code{nil}, the
557 fill commands put two spaces after a colon.
559 @vindex fill-nobreak-predicate
560   The variable @code{fill-nobreak-predicate} is a hook (an abnormal
561 hook, @pxref{Hooks}) specifying additional conditions where
562 line-breaking is not allowed.  Each function is called with no
563 arguments, with point at a place where Emacs is considering breaking
564 the line.  If a function returns a non-@code{nil} value, then that's
565 a bad place to break the line.  Two standard functions you can use are
566 @code{fill-single-word-nobreak-p} (don't break after the first word of
567 a sentence or before the last) and @code{fill-french-nobreak-p} (don't
568 break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}).
570 @node Fill Prefix
571 @subsection The Fill Prefix
573 @cindex fill prefix
574   To fill a paragraph in which each line starts with a special marker
575 (which might be a few spaces, giving an indented paragraph), you can use
576 the @dfn{fill prefix} feature.  The fill prefix is a string that Emacs
577 expects every line to start with, and which is not included in filling.
578 You can specify a fill prefix explicitly; Emacs can also deduce the
579 fill prefix automatically (@pxref{Adaptive Fill}).
581 @table @kbd
582 @item C-x .
583 Set the fill prefix (@code{set-fill-prefix}).
584 @item M-q
585 Fill a paragraph using current fill prefix (@code{fill-paragraph}).
586 @item M-x fill-individual-paragraphs
587 Fill the region, considering each change of indentation as starting a
588 new paragraph.
589 @item M-x fill-nonuniform-paragraphs
590 Fill the region, considering only paragraph-separator lines as starting
591 a new paragraph.
592 @end table
594 @kindex C-x .
595 @findex set-fill-prefix
596   To specify a fill prefix for the current buffer, move to a line that
597 starts with the desired prefix, put point at the end of the prefix,
598 and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}).  (That's a period
599 after the @kbd{C-x}.)  To turn off the fill prefix, specify an empty
600 prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line.
602   When a fill prefix is in effect, the fill commands remove the fill
603 prefix from each line of the paragraph before filling and insert it on
604 each line after filling.  (The beginning of the first line of the
605 paragraph is left unchanged, since often that is intentionally
606 different.)  Auto Fill mode also inserts the fill prefix automatically
607 when it makes a new line.  The @kbd{C-o} command inserts the fill
608 prefix on new lines it creates, when you use it at the beginning of a
609 line (@pxref{Blank Lines}).  Conversely, the command @kbd{M-^} deletes
610 the prefix (if it occurs) after the newline that it deletes
611 (@pxref{Indentation}).
613   For example, if @code{fill-column} is 40 and you set the fill prefix
614 to @samp{;; }, then @kbd{M-q} in the following text
616 @example
617 ;; This is an
618 ;; example of a paragraph
619 ;; inside a Lisp-style comment.
620 @end example
622 @noindent
623 produces this:
625 @example
626 ;; This is an example of a paragraph
627 ;; inside a Lisp-style comment.
628 @end example
630   Lines that do not start with the fill prefix are considered to start
631 paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
632 good results for paragraphs with hanging indentation (every line
633 indented except the first one).  Lines which are blank or indented once
634 the prefix is removed also separate or start paragraphs; this is what
635 you want if you are writing multi-paragraph comments with a comment
636 delimiter on each line.
638 @findex fill-individual-paragraphs
639   You can use @kbd{M-x fill-individual-paragraphs} to set the fill
640 prefix for each paragraph automatically.  This command divides the
641 region into paragraphs, treating every change in the amount of
642 indentation as the start of a new paragraph, and fills each of these
643 paragraphs.  Thus, all the lines in one ``paragraph'' have the same
644 amount of indentation.  That indentation serves as the fill prefix for
645 that paragraph.
647 @findex fill-nonuniform-paragraphs
648   @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
649 the region into paragraphs in a different way.  It considers only
650 paragraph-separating lines (as defined by @code{paragraph-separate}) as
651 starting a new paragraph.  Since this means that the lines of one
652 paragraph may have different amounts of indentation, the fill prefix
653 used is the smallest amount of indentation of any of the lines of the
654 paragraph.  This gives good results with styles that indent a paragraph's
655 first line more or less that the rest of the paragraph.
657 @vindex fill-prefix
658   The fill prefix is stored in the variable @code{fill-prefix}.  Its value
659 is a string, or @code{nil} when there is no fill prefix.  This is a
660 per-buffer variable; altering the variable affects only the current buffer,
661 but there is a default value which you can change as well.  @xref{Locals}.
663   The @code{indentation} text property provides another way to control
664 the amount of indentation paragraphs receive.  @xref{Format Indentation}.
666 @node Adaptive Fill
667 @subsection Adaptive Filling
669 @cindex adaptive filling
670   The fill commands can deduce the proper fill prefix for a paragraph
671 automatically in certain cases: either whitespace or certain punctuation
672 characters at the beginning of a line are propagated to all lines of the
673 paragraph.
675   If the paragraph has two or more lines, the fill prefix is taken from
676 the paragraph's second line, but only if it appears on the first line as
677 well.
679   If a paragraph has just one line, fill commands @emph{may} take a
680 prefix from that line.  The decision is complicated because there are
681 three reasonable things to do in such a case:
683 @itemize @bullet
684 @item
685 Use the first line's prefix on all the lines of the paragraph.
687 @item
688 Indent subsequent lines with whitespace, so that they line up under the
689 text that follows the prefix on the first line, but don't actually copy
690 the prefix from the first line.
692 @item
693 Don't do anything special with the second and following lines.
694 @end itemize
696   All three of these styles of formatting are commonly used.  So the
697 fill commands try to determine what you would like, based on the prefix
698 that appears and on the major mode.  Here is how.
700 @vindex adaptive-fill-first-line-regexp
701   If the prefix found on the first line matches
702 @code{adaptive-fill-first-line-regexp}, or if it appears to be a
703 comment-starting sequence (this depends on the major mode), then the
704 prefix found is used for filling the paragraph, provided it would not
705 act as a paragraph starter on subsequent lines.
707   Otherwise, the prefix found is converted to an equivalent number of
708 spaces, and those spaces are used as the fill prefix for the rest of the
709 lines, provided they would not act as a paragraph starter on subsequent
710 lines.
712   In Text mode, and other modes where only blank lines and page
713 delimiters separate paragraphs, the prefix chosen by adaptive filling
714 never acts as a paragraph starter, so it can always be used for filling.
716 @vindex adaptive-fill-mode
717 @vindex adaptive-fill-regexp
718   The variable @code{adaptive-fill-regexp} determines what kinds of line
719 beginnings can serve as a fill prefix: any characters at the start of
720 the line that match this regular expression are used.  If you set the
721 variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
722 never chosen automatically.
724 @vindex adaptive-fill-function
725   You can specify more complex ways of choosing a fill prefix
726 automatically by setting the variable @code{adaptive-fill-function} to a
727 function.  This function is called with point after the left margin of a
728 line, and it should return the appropriate fill prefix based on that
729 line.  If it returns @code{nil}, @code{adaptive-fill-regexp} gets
730 a chance to find a prefix.
732 @node Refill
733 @subsection Refill Mode
734 @cindex refilling text, word processor style
735 @cindex modes, Refill
736 @cindex Refill minor mode
738   Refill minor mode provides support for keeping paragraphs filled as
739 you type or modify them in other ways.  It provides an effect similar
740 to typical word processor behavior.  This works by running a
741 paragraph-filling command at suitable times.
743   To toggle the use of Refill mode in the current buffer, type
744 @kbd{M-x refill-mode}.  When you are typing text, only characters
745 which normally trigger auto filling, like the space character, will
746 trigger refilling.  This is to avoid making it too slow.  Apart from
747 self-inserting characters, other commands which modify the text cause
748 refilling.
750   The current implementation is preliminary and not robust.  You can
751 get better ``line wrapping'' behavior using Longlines mode.
752 @xref{Longlines}.  However, Longlines mode has an important
753 side-effect: the newlines that it inserts for you are not saved to
754 disk, so the files that you make with Longlines mode will appear to be
755 completely unfilled if you edit them without Longlines mode.
757 @node Longlines
758 @subsection Long Lines Mode
759 @cindex refilling text, word processor style
760 @cindex modes, Long Lines
761 @cindex word wrap
762 @cindex Long Lines minor mode
764   Long Lines mode is a minor mode for @dfn{word wrapping}; it lets you
765 edit ``unfilled'' text files, which Emacs would normally display as a
766 bunch of extremely long lines.  Many text editors, such as those built
767 into many web browsers, normally do word wrapping.
769 @findex longlines-mode
770   To enable Long Lines mode, type @kbd{M-x longlines-mode}.  If the
771 text is full of long lines, this will ``wrap'' them
772 immediately---i.e., break up to fit in the window.  As you edit the
773 text, Long Lines mode automatically re-wraps lines by inserting or
774 deleting @dfn{soft newlines} as necessary (@pxref{Hard and Soft
775 Newlines}.)  These soft newlines won't show up when you save the
776 buffer into a file, or when you copy the text into the kill ring,
777 clipboard, or a register.
779 @findex longlines-auto-wrap
780   Word wrapping is @emph{not} the same as ordinary filling
781 (@pxref{Fill Commands}).  It does not contract multiple spaces into a
782 single space, recognize fill prefixes (@pxref{Fill Prefix}), or
783 perform adaptive filling (@pxref{Adaptive Fill}).  The reason for this
784 is that a wrapped line is still, conceptually, a single line.  Each
785 soft newline is equivalent to exactly one space in that long line, and
786 vice versa.  However, you can still call filling functions such as
787 @kbd{M-q}, and these will work as expected, inserting soft newlines
788 that won't show up on disk or when the text is copied.  You can even
789 rely entirely on the normal fill commands by turning off automatic
790 line wrapping, with @kbd{C-u M-x longlines-auto-wrap}.  To turn
791 automatic line wrapping back on, type @kbd{M-x longlines-auto-wrap}.
793 @findex longlines-show-hard-newlines
794   Type @kbd{RET} to insert a hard newline, one which automatic
795 refilling will not remove.  If you want to see where all the hard
796 newlines are, type @kbd{M-x longlines-show-hard-newlines}.  This will
797 mark each hard newline with a special symbol.  The same command with a
798 prefix argument turns this display off.
800   Long Lines mode does not change normal text files that are already
801 filled, since the existing newlines are considered hard newlines.
802 Before Long Lines can do anything, you need to transform each
803 paragraph into a long line.  One way is to set @code{fill-column} to a
804 large number (e.g., @kbd{C-u 9999 C-x f}), re-fill all the paragraphs,
805 and then set @code{fill-column} back to its original value.
807 @node Case
808 @section Case Conversion Commands
809 @cindex case conversion
811   Emacs has commands for converting either a single word or any arbitrary
812 range of text to upper case or to lower case.
814 @table @kbd
815 @item M-l
816 Convert following word to lower case (@code{downcase-word}).
817 @item M-u
818 Convert following word to upper case (@code{upcase-word}).
819 @item M-c
820 Capitalize the following word (@code{capitalize-word}).
821 @item C-x C-l
822 Convert region to lower case (@code{downcase-region}).
823 @item C-x C-u
824 Convert region to upper case (@code{upcase-region}).
825 @end table
827 @kindex M-l
828 @kindex M-u
829 @kindex M-c
830 @cindex words, case conversion
831 @cindex converting text to upper or lower case
832 @cindex capitalizing words
833 @findex downcase-word
834 @findex upcase-word
835 @findex capitalize-word
836   The word conversion commands are the most useful.  @kbd{M-l}
837 (@code{downcase-word}) converts the word after point to lower case, moving
838 past it.  Thus, repeating @kbd{M-l} converts successive words.
839 @kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while
840 @kbd{M-c} (@code{capitalize-word}) puts the first letter of the word
841 into upper case and the rest into lower case.  All these commands convert
842 several words at once if given an argument.  They are especially convenient
843 for converting a large amount of text from all upper case to mixed case,
844 because you can move through the text using @kbd{M-l}, @kbd{M-u} or
845 @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
846 to skip a word.
848   When given a negative argument, the word case conversion commands apply
849 to the appropriate number of words before point, but do not move point.
850 This is convenient when you have just typed a word in the wrong case: you
851 can give the case conversion command and continue typing.
853   If a word case conversion command is given in the middle of a word,
854 it applies only to the part of the word which follows point.  (This is
855 comparable to what @kbd{M-d} (@code{kill-word}) does.)  With a
856 negative argument, case conversion applies only to the part of the
857 word before point.
859 @kindex C-x C-l
860 @kindex C-x C-u
861 @findex downcase-region
862 @findex upcase-region
863   The other case conversion commands are @kbd{C-x C-u}
864 (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
865 convert everything between point and mark to the specified case.  Point and
866 mark do not move.
868   The region case conversion commands @code{upcase-region} and
869 @code{downcase-region} are normally disabled.  This means that they ask
870 for confirmation if you try to use them.  When you confirm, you may
871 enable the command, which means it will not ask for confirmation again.
872 @xref{Disabling}.
874 @node Text Mode
875 @section Text Mode
876 @cindex Text mode
877 @cindex mode, Text
878 @findex text-mode
880   When you edit files of text in a human language, it's more convenient
881 to use Text mode rather than Fundamental mode.  To enter Text mode, type
882 @kbd{M-x text-mode}.
884   In Text mode, only blank lines and page delimiters separate
885 paragraphs.  As a result, paragraphs can be indented, and adaptive
886 filling determines what indentation to use when filling a paragraph.
887 @xref{Adaptive Fill}.
889 @kindex TAB @r{(Text mode)}
890   Text mode defines @key{TAB} to run @code{indent-relative}
891 (@pxref{Indentation}), so that you can conveniently indent a line like
892 the previous line.
894   Text mode turns off the features concerned with comments except when
895 you explicitly invoke them.  It changes the syntax table so that
896 single-quotes are considered part of words.  However, if a word starts
897 with single-quotes, these are treated as a prefix for purposes such as
898 capitalization.  That is, @kbd{M-c} will convert @samp{'hello'} into
899 @samp{'Hello'}, as expected.
901 @cindex Paragraph-Indent Text mode
902 @cindex mode, Paragraph-Indent Text
903 @findex paragraph-indent-text-mode
904 @findex paragraph-indent-minor-mode
905   If you indent the first lines of paragraphs, then you should use
906 Paragraph-Indent Text mode rather than Text mode.  In this mode, you
907 do not need to have blank lines between paragraphs, because the
908 first-line indentation is sufficient to start a paragraph; however
909 paragraphs in which every line is indented are not supported.  Use
910 @kbd{M-x paragraph-indent-text-mode} to enter this mode.  Use @kbd{M-x
911 paragraph-indent-minor-mode} to enable an equivalent minor mode in
912 situations where you can't change the major mode---in mail
913 composition, for instance.
915 @kindex M-TAB @r{(Text mode)}
916   Text mode, and all the modes based on it, define @kbd{M-@key{TAB}}
917 as the command @code{ispell-complete-word}, which performs completion
918 of the partial word in the buffer before point, using the spelling
919 dictionary as the space of possible words.  @xref{Spelling}.  If your
920 window manager defines @kbd{M-@key{TAB}} to switch windows, you can
921 type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.
923 @vindex text-mode-hook
924   Entering Text mode runs the hook @code{text-mode-hook}.  Other major
925 modes related to Text mode also run this hook, followed by hooks of
926 their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{}
927 mode, Outline mode, and Mail mode.  Hook functions on
928 @code{text-mode-hook} can look at the value of @code{major-mode} to see
929 which of these modes is actually being entered.  @xref{Hooks}.
931 @ifinfo
932   Emacs provides two other modes for editing text that is to be passed
933 through a text formatter to produce fancy formatted printed output.
934 @xref{Nroff Mode}, for editing input to the formatter nroff.
935 @xref{TeX Mode}, for editing input to the formatter TeX.
937   Another mode is used for editing outlines.  It allows you to view the
938 text at various levels of detail.  You can view either the outline
939 headings alone or both headings and text; you can also hide some of the
940 headings at lower levels from view to make the high level structure more
941 visible.  @xref{Outline Mode}.
942 @end ifinfo
944 @node Outline Mode
945 @section Outline Mode
946 @cindex Outline mode
947 @cindex mode, Outline
948 @cindex invisible lines
950 @findex outline-mode
951 @findex outline-minor-mode
952 @vindex outline-minor-mode-prefix
953   Outline mode is a major mode much like Text mode but intended for
954 editing outlines.  It allows you to make parts of the text temporarily
955 invisible so that you can see the outline structure.  Type @kbd{M-x
956 outline-mode} to switch to Outline mode as the major mode of the current
957 buffer.
959   When Outline mode makes a line invisible, the line does not appear
960 on the screen.  The screen appears exactly as if the invisible line
961 were deleted, except that an ellipsis (three periods in a row) appears
962 at the end of the previous visible line.  (Multiple consecutive
963 invisible lines produce just one ellipsis.)
965   Editing commands that operate on lines, such as @kbd{C-n} and
966 @kbd{C-p}, treat the text of the invisible line as part of the previous
967 visible line.  Killing the ellipsis at the end of a visible line
968 really kills all the following invisible lines.
970   Outline minor mode provides the same commands as the major mode,
971 Outline mode, but you can use it in conjunction with other major modes.
972 Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in
973 the current buffer.  You can also specify this in the text of a file,
974 with a file local variable of the form @samp{mode: outline-minor}
975 (@pxref{File Variables}).
977 @kindex C-c @@ @r{(Outline minor mode)}
978   The major mode, Outline mode, provides special key bindings on the
979 @kbd{C-c} prefix.  Outline minor mode provides similar bindings with
980 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
981 major mode's special commands.  (The variable
982 @code{outline-minor-mode-prefix} controls the prefix used.)
984 @vindex outline-mode-hook
985   Entering Outline mode runs the hook @code{text-mode-hook} followed by
986 the hook @code{outline-mode-hook} (@pxref{Hooks}).
988 @menu
989 * Format: Outline Format.          What the text of an outline looks like.
990 * Motion: Outline Motion.          Special commands for moving through
991                                      outlines.
992 * Visibility: Outline Visibility.  Commands to control what is visible.
993 * Views: Outline Views.            Outlines and multiple views.
994 * Foldout::                        Folding means zooming in on outlines.
995 @end menu
997 @node Outline Format
998 @subsection Format of Outlines
1000 @cindex heading lines (Outline mode)
1001 @cindex body lines (Outline mode)
1002   Outline mode assumes that the lines in the buffer are of two types:
1003 @dfn{heading lines} and @dfn{body lines}.  A heading line represents a
1004 topic in the outline.  Heading lines start with one or more stars; the
1005 number of stars determines the depth of the heading in the outline
1006 structure.  Thus, a heading line with one star is a major topic; all the
1007 heading lines with two stars between it and the next one-star heading
1008 are its subtopics; and so on.  Any line that is not a heading line is a
1009 body line.  Body lines belong with the preceding heading line.  Here is
1010 an example:
1012 @example
1013 * Food
1014 This is the body,
1015 which says something about the topic of food.
1017 ** Delicious Food
1018 This is the body of the second-level header.
1020 ** Distasteful Food
1021 This could have
1022 a body too, with
1023 several lines.
1025 *** Dormitory Food
1027 * Shelter
1028 Another first-level topic with its header line.
1029 @end example
1031   A heading line together with all following body lines is called
1032 collectively an @dfn{entry}.  A heading line together with all following
1033 deeper heading lines and their body lines is called a @dfn{subtree}.
1035 @vindex outline-regexp
1036   You can customize the criterion for distinguishing heading lines
1037 by setting the variable @code{outline-regexp}.  Any line whose
1038 beginning has a match for this regexp is considered a heading line.
1039 Matches that start within a line (not at the left margin) do not count.
1040 The length of the matching text determines the level of the heading;
1041 longer matches make a more deeply nested level.  Thus, for example,
1042 if a text formatter has commands @samp{@@chapter}, @samp{@@section}
1043 and @samp{@@subsection} to divide the document into chapters and
1044 sections, you could make those lines count as heading lines by
1045 setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}.
1046 Note the trick: the two words @samp{chapter} and @samp{section} are equally
1047 long, but by defining the regexp to match only @samp{chap} we ensure
1048 that the length of the text matched on a chapter heading is shorter,
1049 so that Outline mode will know that sections are contained in chapters.
1050 This works as long as no other command starts with @samp{@@chap}.
1052 @vindex outline-level
1053   You can change the rule for calculating the level of a heading line
1054 by setting the variable @code{outline-level}.  The value of
1055 @code{outline-level} should be a function that takes no arguments and
1056 returns the level of the current heading.  Some major modes such as C,
1057 Nroff, and Emacs Lisp mode set this variable and @code{outline-regexp}
1058 in order to work with Outline minor mode.
1060 @node Outline Motion
1061 @subsection Outline Motion Commands
1063   Outline mode provides special motion commands that move backward and
1064 forward to heading lines.
1066 @table @kbd
1067 @item C-c C-n
1068 Move point to the next visible heading line
1069 (@code{outline-next-visible-heading}).
1070 @item C-c C-p
1071 Move point to the previous visible heading line
1072 (@code{outline-previous-visible-heading}).
1073 @item C-c C-f
1074 Move point to the next visible heading line at the same level
1075 as the one point is on (@code{outline-forward-same-level}).
1076 @item C-c C-b
1077 Move point to the previous visible heading line at the same level
1078 (@code{outline-backward-same-level}).
1079 @item C-c C-u
1080 Move point up to a lower-level (more inclusive) visible heading line
1081 (@code{outline-up-heading}).
1082 @end table
1084 @findex outline-next-visible-heading
1085 @findex outline-previous-visible-heading
1086 @kindex C-c C-n @r{(Outline mode)}
1087 @kindex C-c C-p @r{(Outline mode)}
1088   @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next
1089 heading line.  @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves
1090 similarly backward.  Both accept numeric arguments as repeat counts.  The
1091 names emphasize that invisible headings are skipped, but this is not really
1092 a special feature.  All editing commands that look for lines ignore the
1093 invisible lines automatically.
1095 @findex outline-up-heading
1096 @findex outline-forward-same-level
1097 @findex outline-backward-same-level
1098 @kindex C-c C-f @r{(Outline mode)}
1099 @kindex C-c C-b @r{(Outline mode)}
1100 @kindex C-c C-u @r{(Outline mode)}
1101   More powerful motion commands understand the level structure of headings.
1102 @kbd{C-c C-f} (@code{outline-forward-same-level}) and
1103 @kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
1104 heading line to another visible heading at the same depth in
1105 the outline.  @kbd{C-c C-u} (@code{outline-up-heading}) moves
1106 backward to another heading that is less deeply nested.
1108 @node Outline Visibility
1109 @subsection Outline Visibility Commands
1111   The other special commands of outline mode are used to make lines visible
1112 or invisible.  Their names all start with @code{hide} or @code{show}.
1113 Most of them fall into pairs of opposites.  They are not undoable; instead,
1114 you can undo right past them.  Making lines visible or invisible is simply
1115 not recorded by the undo mechanism.
1117   Many of these commands act on the ``current'' heading line.  If
1118 point is on a heading line, that is the current heading line; if point
1119 is on a body line, the current heading line is the nearest preceding
1120 header line.
1122 @table @kbd
1123 @item C-c C-c
1124 Make the current heading line's body invisible (@code{hide-entry}).
1125 @item C-c C-e
1126 Make the current heading line's body visible (@code{show-entry}).
1127 @item C-c C-d
1128 Make everything under the current heading invisible, not including the
1129 heading itself (@code{hide-subtree}).
1130 @item C-c C-s
1131 Make everything under the current heading visible, including body,
1132 subheadings, and their bodies (@code{show-subtree}).
1133 @item C-c C-l
1134 Make the body of the current heading line, and of all its subheadings,
1135 invisible (@code{hide-leaves}).
1136 @item C-c C-k
1137 Make all subheadings of the current heading line, at all levels,
1138 visible (@code{show-branches}).
1139 @item C-c C-i
1140 Make immediate subheadings (one level down) of the current heading
1141 line visible (@code{show-children}).
1142 @item C-c C-t
1143 Make all body lines in the buffer invisible (@code{hide-body}).
1144 @item C-c C-a
1145 Make all lines in the buffer visible (@code{show-all}).
1146 @item C-c C-q
1147 Hide everything except the top @var{n} levels of heading lines
1148 (@code{hide-sublevels}).
1149 @item C-c C-o
1150 Hide everything except for the heading or body that point is in, plus
1151 the headings leading up from there to the top level of the outline
1152 (@code{hide-other}).
1153 @end table
1155 @findex hide-entry
1156 @findex show-entry
1157 @kindex C-c C-c @r{(Outline mode)}
1158 @kindex C-c C-e @r{(Outline mode)}
1159   Two commands that are exact opposites are @kbd{C-c C-c}
1160 (@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}).  They apply
1161 to the body lines directly following the current heading line.
1162 Subheadings and their bodies are not affected.
1164 @findex hide-subtree
1165 @findex show-subtree
1166 @kindex C-c C-s @r{(Outline mode)}
1167 @kindex C-c C-d @r{(Outline mode)}
1168 @cindex subtree (Outline mode)
1169   Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree})
1170 and @kbd{C-c C-s} (@code{show-subtree}).  Both apply to the current
1171 heading line's @dfn{subtree}: its body, all its subheadings, both
1172 direct and indirect, and all of their bodies.  In other words, the
1173 subtree contains everything following the current heading line, up to
1174 and not including the next heading of the same or higher rank.
1176 @findex hide-leaves
1177 @findex show-branches
1178 @kindex C-c C-l @r{(Outline mode)}
1179 @kindex C-c C-k @r{(Outline mode)}
1180   Intermediate between a visible subtree and an invisible one is having
1181 all the subheadings visible but none of the body.  There are two
1182 commands for doing this, depending on whether you want to hide the
1183 bodies or make the subheadings visible.  They are @kbd{C-c C-l}
1184 (@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}).
1186 @kindex C-c C-i @r{(Outline mode)}
1187 @findex show-children
1188   A little weaker than @code{show-branches} is @kbd{C-c C-i}
1189 (@code{show-children}).  It makes just the direct subheadings
1190 visible---those one level down.  Deeper subheadings remain invisible, if
1191 they were invisible.
1193 @findex hide-body
1194 @findex show-all
1195 @kindex C-c C-t @r{(Outline mode)}
1196 @kindex C-c C-a @r{(Outline mode)}
1197   Two commands have a blanket effect on the whole file.  @kbd{C-c C-t}
1198 (@code{hide-body}) makes all body lines invisible, so that you see just
1199 the outline structure (as a special exception, it will not hide lines
1200 at the top of the file, preceding the first header line, even though
1201 these are technically body lines).  @kbd{C-c C-a} (@code{show-all})
1202 makes all lines visible.  These commands can be thought of as a pair
1203 of opposites even though @kbd{C-c C-a} applies to more than just body
1204 lines.
1206 @findex hide-sublevels
1207 @kindex C-c C-q @r{(Outline mode)}
1208   The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the
1209 top level headings.  With a numeric argument @var{n}, it hides everything
1210 except the top @var{n} levels of heading lines.
1212 @findex hide-other
1213 @kindex C-c C-o @r{(Outline mode)}
1214   The command @kbd{C-c C-o} (@code{hide-other}) hides everything except
1215 the heading and body text that point is in, plus its parents (the headers
1216 leading up from there to top level in the outline) and the top level
1217 headings.
1219 @findex reveal-mode
1220   When incremental search finds text that is hidden by Outline mode,
1221 it makes that part of the buffer visible.  If you exit the search
1222 at that position, the text remains visible.  You can also
1223 automatically make text visible as you navigate in it by using
1224 @kbd{M-x reveal-mode}.
1226 @node Outline Views
1227 @subsection Viewing One Outline in Multiple Views
1229 @cindex multiple views of outline
1230 @cindex views of an outline
1231 @cindex outline with multiple views
1232 @cindex indirect buffers and outlines
1233   You can display two views of a single outline at the same time, in
1234 different windows.  To do this, you must create an indirect buffer using
1235 @kbd{M-x make-indirect-buffer}.  The first argument of this command is
1236 the existing outline buffer name, and its second argument is the name to
1237 use for the new indirect buffer.  @xref{Indirect Buffers}.
1239   Once the indirect buffer exists, you can display it in a window in the
1240 normal fashion, with @kbd{C-x 4 b} or other Emacs commands.  The Outline
1241 mode commands to show and hide parts of the text operate on each buffer
1242 independently; as a result, each buffer can have its own view.  If you
1243 want more than two views on the same outline, create additional indirect
1244 buffers.
1246 @node Foldout
1247 @subsection Folding Editing
1249 @cindex folding editing
1250   The Foldout package extends Outline mode and Outline minor mode with
1251 ``folding'' commands.  The idea of folding is that you zoom in on a
1252 nested portion of the outline, while hiding its relatives at higher
1253 levels.
1255   Consider an Outline mode buffer with all the text and subheadings under
1256 level-1 headings hidden.  To look at what is hidden under one of these
1257 headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose
1258 the body, or @kbd{C-c C-i} to expose the child (level-2) headings.
1260 @kindex C-c C-z
1261 @findex foldout-zoom-subtree
1262   With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1263 This exposes the body and child subheadings, and narrows the buffer so
1264 that only the @w{level-1} heading, the body and the level-2 headings are
1265 visible.  Now to look under one of the level-2 headings, position the
1266 cursor on it and use @kbd{C-c C-z} again.  This exposes the level-2 body
1267 and its level-3 child subheadings and narrows the buffer again.  Zooming
1268 in on successive subheadings can be done as much as you like.  A string
1269 in the mode line shows how deep you've gone.
1271   When zooming in on a heading, to see only the child subheadings specify
1272 a numeric argument: @kbd{C-u C-c C-z}.  The number of levels of children
1273 can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2
1274 C-c C-z} exposes two levels of child subheadings.  Alternatively, the
1275 body can be specified with a negative argument: @kbd{M-- C-c C-z}.  The
1276 whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x
1277 show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}.
1279   While you're zoomed in, you can still use Outline mode's exposure and
1280 hiding functions without disturbing Foldout.  Also, since the buffer is
1281 narrowed, ``global'' editing actions will only affect text under the
1282 zoomed-in heading.  This is useful for restricting changes to a
1283 particular chapter or section of your document.
1285 @kindex C-c C-x
1286 @findex foldout-exit-fold
1287   To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1288 This hides all the text and subheadings under the top-level heading and
1289 returns you to the previous view of the buffer.  Specifying a numeric
1290 argument exits that many levels of folds.  Specifying a zero argument
1291 exits all folds.
1293   To cancel the narrowing of a fold without hiding the text and
1294 subheadings, specify a negative argument.  For example, @kbd{M--2 C-c
1295 C-x} exits two folds and leaves the text and subheadings exposed.
1297   Foldout mode also provides mouse commands for entering and exiting
1298 folds, and for showing and hiding text:
1300 @table @asis
1301 @item @kbd{C-M-Mouse-1} zooms in on the heading clicked on
1302 @itemize @asis
1303 @item
1304 single click: expose body.
1305 @item
1306 double click: expose subheadings.
1307 @item
1308 triple click: expose body and subheadings.
1309 @item
1310 quad click: expose entire subtree.
1311 @end itemize
1312 @item @kbd{C-M-Mouse-2} exposes text under the heading clicked on
1313 @itemize @asis
1314 @item
1315 single click: expose body.
1316 @item
1317 double click: expose subheadings.
1318 @item
1319 triple click: expose body and subheadings.
1320 @item
1321 quad click: expose entire subtree.
1322 @end itemize
1323 @item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold
1324 @itemize @asis
1325 @item
1326 single click: hide subtree.
1327 @item
1328 double click: exit fold and hide text.
1329 @item
1330 triple click: exit fold without hiding text.
1331 @item
1332 quad click: exit all folds and hide text.
1333 @end itemize
1334 @end table
1336 @vindex foldout-mouse-modifiers
1337   You can specify different modifier keys (instead of
1338 @kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if
1339 you have already loaded the @file{foldout.el} library, you must reload
1340 it in order for this to take effect.
1342   To use the Foldout package, you can type @kbd{M-x load-library
1343 @key{RET} foldout @key{RET}}; or you can arrange for to do that
1344 automatically by putting this in your @file{.emacs} file:
1346 @example
1347 (eval-after-load "outline" '(require 'foldout))
1348 @end example
1350 @node TeX Mode
1351 @section @TeX{} Mode
1352 @cindex @TeX{} mode
1353 @cindex La@TeX{} mode
1354 @cindex Sli@TeX{} mode
1355 @cindex Doc@TeX{} mode
1356 @cindex mode, @TeX{}
1357 @cindex mode, La@TeX{}
1358 @cindex mode, Sli@TeX{}
1359 @cindex mode, Doc@TeX{}
1360 @findex tex-mode
1361 @findex plain-tex-mode
1362 @findex latex-mode
1363 @findex slitex-mode
1364 @findex doctex-mode
1366   @TeX{} is a powerful text formatter written by Donald Knuth; it is
1367 also free software, like GNU Emacs.  La@TeX{} is a simplified input
1368 format for @TeX{}, implemented by @TeX{} macros; it comes with @TeX{}.
1369 Sli@TeX{} is a special form of La@TeX{}.@footnote{Sli@TeX{} is
1370 obsoleted by the @samp{slides} document class in recent La@TeX{}
1371 versions.}  Doc@TeX{} (@file{.dtx}) is a special file format in which
1372 the La@TeX{} sources are written, combining sources with
1373 documentation.
1375   Emacs has a special @TeX{} mode for editing @TeX{} input files.
1376 It provides facilities for checking the balance of delimiters and for
1377 invoking @TeX{} on all or part of the file.
1379 @vindex tex-default-mode
1380   @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode,
1381 Sli@TeX{} mode, and Doc@TeX{} mode (these distinct major modes differ
1382 only slightly).  They are designed for editing the four different
1383 formats.  The command @kbd{M-x tex-mode} looks at the contents of the
1384 buffer to determine whether the contents appear to be either La@TeX{}
1385 input, Sli@TeX{}, or Doc@TeX{} input; if so, it selects the
1386 appropriate mode.  If the file contents do not appear to be La@TeX{},
1387 Sli@TeX{} or Doc@TeX{}, it selects Plain @TeX{} mode.  If the contents
1388 are insufficient to determine this, the variable
1389 @code{tex-default-mode} controls which mode is used.
1391   When @kbd{M-x tex-mode} does not guess right, you can use the commands
1392 @kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, @kbd{M-x slitex-mode},
1393 and @kbd{doctex-mode} to select explicitly the particular variants of
1394 @TeX{} mode.
1396 @menu
1397 * Editing: TeX Editing.   Special commands for editing in TeX mode.
1398 * LaTeX: LaTeX Editing.   Additional commands for LaTeX input files.
1399 * Printing: TeX Print.    Commands for printing part of a file with TeX.
1400 * Misc: TeX Misc.         Customization of TeX mode, and related features.
1401 @end menu
1403 @node TeX Editing
1404 @subsection @TeX{} Editing Commands
1406   Here are the special commands provided in @TeX{} mode for editing the
1407 text of the file.
1409 @table @kbd
1410 @item "
1411 Insert, according to context, either @samp{``} or @samp{"} or
1412 @samp{''} (@code{tex-insert-quote}).
1413 @item C-j
1414 Insert a paragraph break (two newlines) and check the previous
1415 paragraph for unbalanced braces or dollar signs
1416 (@code{tex-terminate-paragraph}).
1417 @item M-x tex-validate-region
1418 Check each paragraph in the region for unbalanced braces or dollar signs.
1419 @item C-c @{
1420 Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1421 @item C-c @}
1422 Move forward past the next unmatched close brace (@code{up-list}).
1423 @end table
1425 @findex tex-insert-quote
1426 @kindex " @r{(@TeX{} mode)}
1427   In @TeX{}, the character @samp{"} is not normally used; we use
1428 @samp{``} to start a quotation and @samp{''} to end one.  To make
1429 editing easier under this formatting convention, @TeX{} mode overrides
1430 the normal meaning of the key @kbd{"} with a command that inserts a pair
1431 of single-quotes or backquotes (@code{tex-insert-quote}).  To be
1432 precise, this command inserts @samp{``} after whitespace or an open
1433 brace, @samp{"} after a backslash, and @samp{''} after any other
1434 character.
1436   If you need the character @samp{"} itself in unusual contexts, use
1437 @kbd{C-q} to insert it.  Also, @kbd{"} with a numeric argument always
1438 inserts that number of @samp{"} characters.  You can turn off the
1439 feature of @kbd{"} expansion by eliminating that binding in the local
1440 map (@pxref{Key Bindings}).
1442   In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1443 understand the way @TeX{} math mode delimiters match.  When you insert a
1444 @samp{$} that is meant to exit math mode, the position of the matching
1445 @samp{$} that entered math mode is displayed for a second.  This is the
1446 same feature that displays the open brace that matches a close brace that
1447 is inserted.  However, there is no way to tell whether a @samp{$} enters
1448 math mode or leaves it; so when you insert a @samp{$} that enters math
1449 mode, the previous @samp{$} position is shown as if it were a match, even
1450 though they are actually unrelated.
1452 @findex tex-insert-braces
1453 @kindex C-c @{ @r{(@TeX{} mode)}
1454 @findex up-list
1455 @kindex C-c @} @r{(@TeX{} mode)}
1456   @TeX{} uses braces as delimiters that must match.  Some users prefer
1457 to keep braces balanced at all times, rather than inserting them
1458 singly.  Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1459 braces.  It leaves point between the two braces so you can insert the
1460 text that belongs inside.  Afterward, use the command @kbd{C-c @}}
1461 (@code{up-list}) to move forward past the close brace.
1463 @findex tex-validate-region
1464 @findex tex-terminate-paragraph
1465 @kindex C-j @r{(@TeX{} mode)}
1466   There are two commands for checking the matching of braces.  @kbd{C-j}
1467 (@code{tex-terminate-paragraph}) checks the paragraph before point, and
1468 inserts two newlines to start a new paragraph.  It outputs a message in
1469 the echo area if any mismatch is found.  @kbd{M-x tex-validate-region}
1470 checks a region, paragraph by paragraph.  The errors are listed in the
1471 @samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in
1472 that buffer to go to a particular mismatch.
1474   Note that Emacs commands count square brackets and parentheses in
1475 @TeX{} mode, not just braces.  This is not strictly correct for the
1476 purpose of checking @TeX{} syntax.  However, parentheses and square
1477 brackets are likely to be used in text as matching delimiters and it is
1478 useful for the various motion commands and automatic match display to
1479 work with them.
1481 @node LaTeX Editing
1482 @subsection La@TeX{} Editing Commands
1484   La@TeX{} mode, and its variant, Sli@TeX{} mode, provide a few extra
1485 features not applicable to plain @TeX{}.
1487 @table @kbd
1488 @item C-c C-o
1489 Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position
1490 point on a line between them (@code{tex-latex-block}).
1491 @item C-c C-e
1492 Close the innermost La@TeX{} block not yet closed
1493 (@code{tex-close-latex-block}).
1494 @end table
1496 @findex tex-latex-block
1497 @kindex C-c C-o @r{(La@TeX{} mode)}
1498 @vindex latex-block-names
1499   In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to
1500 group blocks of text.  To insert a @samp{\begin} and a matching
1501 @samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c
1502 C-o} (@code{tex-latex-block}).  A blank line is inserted between the
1503 two, and point is left there.  You can use completion when you enter the
1504 block type; to specify additional block type names beyond the standard
1505 list, set the variable @code{latex-block-names}.  For example, here's
1506 how to add @samp{theorem}, @samp{corollary}, and @samp{proof}:
1508 @example
1509 (setq latex-block-names '("theorem" "corollary" "proof"))
1510 @end example
1512 @findex tex-close-latex-block
1513 @kindex C-c C-e @r{(La@TeX{} mode)}
1514   In La@TeX{} input, @samp{\begin} and @samp{\end} commands must
1515 balance.  You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to
1516 insert automatically a matching @samp{\end} to match the last unmatched
1517 @samp{\begin}.  It indents the @samp{\end} to match the corresponding
1518 @samp{\begin}.  It inserts a newline after @samp{\end} if point is at
1519 the beginning of a line.
1521 @node TeX Print
1522 @subsection @TeX{} Printing Commands
1524   You can invoke @TeX{} as an inferior of Emacs on either the entire
1525 contents of the buffer or just a region at a time.  Running @TeX{} in
1526 this way on just one chapter is a good way to see what your changes
1527 look like without taking the time to format the entire file.
1529 @table @kbd
1530 @item C-c C-r
1531 Invoke @TeX{} on the current region, together with the buffer's header
1532 (@code{tex-region}).
1533 @item C-c C-b
1534 Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1535 @item C-c @key{TAB}
1536 Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1537 @item C-c C-f
1538 Invoke @TeX{} on the current file (@code{tex-file}).
1539 @item C-c C-l
1540 Recenter the window showing output from the inferior @TeX{} so that
1541 the last line can be seen (@code{tex-recenter-output-buffer}).
1542 @item C-c C-k
1543 Kill the @TeX{} subprocess (@code{tex-kill-job}).
1544 @item C-c C-p
1545 Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1546 C-f} command (@code{tex-print}).
1547 @item C-c C-v
1548 Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
1549 C-f} command (@code{tex-view}).
1550 @item C-c C-q
1551 Show the printer queue (@code{tex-show-print-queue}).
1552 @item C-c C-c
1553 Invoke some other compilation command on the entire current buffer
1554 (@code{tex-compile}).
1555 @end table
1557 @findex tex-buffer
1558 @kindex C-c C-b @r{(@TeX{} mode)}
1559 @findex tex-print
1560 @kindex C-c C-p @r{(@TeX{} mode)}
1561 @findex tex-view
1562 @kindex C-c C-v @r{(@TeX{} mode)}
1563 @findex tex-show-print-queue
1564 @kindex C-c C-q @r{(@TeX{} mode)}
1565   You can pass the current buffer through an inferior @TeX{} by means of
1566 @kbd{C-c C-b} (@code{tex-buffer}).  The formatted output appears in a
1567 temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}).
1568 Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to
1569 view the progress of your output towards being printed.  If your terminal
1570 has the ability to display @TeX{} output files, you can preview the
1571 output on the terminal with @kbd{C-c C-v} (@code{tex-view}).
1573 @cindex @env{TEXINPUTS} environment variable
1574 @vindex tex-directory
1575   You can specify the directory to use for running @TeX{} by setting the
1576 variable @code{tex-directory}.  @code{"."} is the default value.  If
1577 your environment variable @env{TEXINPUTS} contains relative directory
1578 names, or if your files contains @samp{\input} commands with relative
1579 file names, then @code{tex-directory} @emph{must} be @code{"."} or you
1580 will get the wrong results.  Otherwise, it is safe to specify some other
1581 directory, such as @code{"/tmp"}.
1583 @vindex tex-run-command
1584 @vindex latex-run-command
1585 @vindex slitex-run-command
1586 @vindex tex-dvi-print-command
1587 @vindex tex-dvi-view-command
1588 @vindex tex-show-queue-command
1589   If you want to specify which shell commands are used in the inferior @TeX{},
1590 you can do so by setting the values of the variables @code{tex-run-command},
1591 @code{latex-run-command}, @code{slitex-run-command},
1592 @code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and
1593 @code{tex-show-queue-command}.  You @emph{must} set the value of
1594 @code{tex-dvi-view-command} for your particular terminal; this variable
1595 has no default value.  The other variables have default values that may
1596 (or may not) be appropriate for your system.
1598   Normally, the file name given to these commands comes at the end of
1599 the command string; for example, @samp{latex @var{filename}}.  In some
1600 cases, however, the file name needs to be embedded in the command; an
1601 example is when you need to provide the file name as an argument to one
1602 command whose output is piped to another.  You can specify where to put
1603 the file name with @samp{*} in the command string.  For example,
1605 @example
1606 (setq tex-dvi-print-command "dvips -f * | lpr")
1607 @end example
1609 @findex tex-kill-job
1610 @kindex C-c C-k @r{(@TeX{} mode)}
1611 @findex tex-recenter-output-buffer
1612 @kindex C-c C-l @r{(@TeX{} mode)}
1613   The terminal output from @TeX{}, including any error messages, appears
1614 in a buffer called @samp{*tex-shell*}.  If @TeX{} gets an error, you can
1615 switch to this buffer and feed it input (this works as in Shell mode;
1616 @pxref{Interactive Shell}).  Without switching to this buffer you can
1617 scroll it so that its last line is visible by typing @kbd{C-c
1618 C-l}.
1620   Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1621 you see that its output is no longer useful.  Using @kbd{C-c C-b} or
1622 @kbd{C-c C-r} also kills any @TeX{} process still running.
1624 @findex tex-region
1625 @kindex C-c C-r @r{(@TeX{} mode)}
1626   You can also pass an arbitrary region through an inferior @TeX{} by typing
1627 @kbd{C-c C-r} (@code{tex-region}).  This is tricky, however, because most files
1628 of @TeX{} input contain commands at the beginning to set parameters and
1629 define macros, without which no later part of the file will format
1630 correctly.  To solve this problem, @kbd{C-c C-r} allows you to designate a
1631 part of the file as containing essential commands; it is included before
1632 the specified region as part of the input to @TeX{}.  The designated part
1633 of the file is called the @dfn{header}.
1635 @cindex header (@TeX{} mode)
1636   To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1637 special strings in the file.  Insert @samp{%**start of header} before the
1638 header, and @samp{%**end of header} after it.  Each string must appear
1639 entirely on one line, but there may be other text on the line before or
1640 after.  The lines containing the two strings are included in the header.
1641 If @samp{%**start of header} does not appear within the first 100 lines of
1642 the buffer, @kbd{C-c C-r} assumes that there is no header.
1644   In La@TeX{} mode, the header begins with @samp{\documentclass} or
1645 @samp{\documentstyle} and ends with @samp{\begin@{document@}}.  These
1646 are commands that La@TeX{} requires you to use in any case, so nothing
1647 special needs to be done to identify the header.
1649 @findex tex-file
1650 @kindex C-c C-f @r{(@TeX{} mode)}
1651   The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1652 work in a temporary directory, and do not have available any of the auxiliary
1653 files needed by @TeX{} for cross-references; these commands are generally
1654 not suitable for running the final copy in which all of the cross-references
1655 need to be correct.
1657   When you want the auxiliary files for cross references, use @kbd{C-c
1658 C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1659 in that file's directory.  Before running @TeX{}, it offers to save any
1660 modified buffers.  Generally, you need to use (@code{tex-file}) twice to
1661 get the cross-references right.
1663 @vindex tex-start-options
1664   The value of the variable @code{tex-start-options} specifies
1665 options for the @TeX{} run.
1667 @vindex tex-start-commands
1668   The value of the variable @code{tex-start-commands} specifies @TeX{}
1669 commands for starting @TeX{}.  The default value causes @TeX{} to run
1670 in nonstop mode.  To run @TeX{} interactively, set the variable to
1671 @code{""}.
1673 @vindex tex-main-file
1674   Large @TeX{} documents are often split into several files---one main
1675 file, plus subfiles.  Running @TeX{} on a subfile typically does not
1676 work; you have to run it on the main file.  In order to make
1677 @code{tex-file} useful when you are editing a subfile, you can set the
1678 variable @code{tex-main-file} to the name of the main file.  Then
1679 @code{tex-file} runs @TeX{} on that file.
1681   The most convenient way to use @code{tex-main-file} is to specify it
1682 in a local variable list in each of the subfiles.  @xref{File
1683 Variables}.
1685 @findex tex-bibtex-file
1686 @kindex C-c TAB @r{(@TeX{} mode)}
1687 @vindex tex-bibtex-command
1688   For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
1689 file for the current buffer's file.  Bib@TeX{} looks up bibliographic
1690 citations in a data base and prepares the cited references for the
1691 bibliography section.  The command @kbd{C-c @key{TAB}}
1692 (@code{tex-bibtex-file}) runs the shell command
1693 (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1694 current buffer's file.  Generally, you need to do @kbd{C-c C-f}
1695 (@code{tex-file}) once to generate the @samp{.aux} file, then do
1696 @kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1697 (@code{tex-file}) twice more to get the cross-references correct.
1699 @findex tex-compile
1700 @kindex C-c C-c @r{(@TeX{} mode)}
1701   To invoke some other compilation program on the current @TeX{}
1702 buffer, type @kbd{C-c C-c} (@code{tex-compile}).  This command knows
1703 how to pass arguments to many common programs, including
1704 @file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}.  You can
1705 select your desired compilation program using the standard completion
1706 keys (@pxref{Completion}).
1708 @node TeX Misc
1709 @subsection @TeX{} Mode Miscellany
1711 @vindex tex-shell-hook
1712 @vindex tex-mode-hook
1713 @vindex latex-mode-hook
1714 @vindex slitex-mode-hook
1715 @vindex plain-tex-mode-hook
1716   Entering any variant of @TeX{} mode runs the hooks
1717 @code{text-mode-hook} and @code{tex-mode-hook}.  Then it runs either
1718 @code{plain-tex-mode-hook}, @code{latex-mode-hook}, or
1719 @code{slitex-mode-hook}, whichever is appropriate.  Starting the
1720 @TeX{} shell runs the hook @code{tex-shell-hook}.  @xref{Hooks}.
1722 @findex iso-iso2tex
1723 @findex iso-tex2iso
1724 @findex iso-iso2gtex
1725 @findex iso-gtex2iso
1726 @cindex Latin-1 @TeX{} encoding
1727 @cindex @TeX{} encoding
1728   The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1729 iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert
1730 between Latin-1 encoded files and @TeX{}-encoded equivalents.
1731 @ignore
1732 @c Too cryptic to be useful, too cryptic for me to make it better -- rms.
1733   They
1734 are included by default in the @code{format-alist} variable, so they
1735 can be used with @kbd{M-x format-find-file}, for instance.
1736 @end ignore
1738 @ignore  @c Not worth documenting if it is only for Czech -- rms.
1739 @findex tildify-buffer
1740 @findex tildify-region
1741 @cindex ties, @TeX{}, inserting
1742 @cindex hard spaces, @TeX{}, inserting
1743   The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region}
1744 insert @samp{~} (@dfn{tie}) characters where they are conventionally
1745 required.  This is set up for Czech---customize the group
1746 @samp{tildify} for other languages or for other sorts of markup.
1747 @end ignore
1749 @cindex Ref@TeX{} package
1750 @cindex references, La@TeX{}
1751 @cindex La@TeX{} references
1752   For managing all kinds of references for La@TeX{}, you can use
1753 Ref@TeX{}.  @inforef{Top,, reftex}.
1755 @node HTML Mode
1756 @section SGML, XML, and HTML Modes
1758   The major modes for SGML and HTML include indentation support and
1759 commands to operate on tags.  This section describes the special
1760 commands of these modes.  (HTML mode is a slightly customized variant
1761 of SGML mode.)
1763 @table @kbd
1764 @item C-c C-n
1765 @kindex C-c C-n @r{(SGML mode)}
1766 @findex sgml-name-char
1767 Interactively specify a special character and insert the SGML
1768 @samp{&}-command for that character.
1770 @item C-c C-t
1771 @kindex C-c C-t @r{(SGML mode)}
1772 @findex sgml-tag
1773 Interactively specify a tag and its attributes (@code{sgml-tag}).
1774 This command asks you for a tag name and for the attribute values,
1775 then inserts both the opening tag and the closing tag, leaving point
1776 between them.
1778 With a prefix argument @var{n}, the command puts the tag around the
1779 @var{n} words already present in the buffer after point.  With
1780 @minus{}1 as argument, it puts the tag around the region.  (In
1781 Transient Mark mode, it does this whenever a region is active.)
1783 @item C-c C-a
1784 @kindex C-c C-a @r{(SGML mode)}
1785 @findex sgml-attributes
1786 Interactively insert attribute values for the current tag
1787 (@code{sgml-attributes}).
1789 @item C-c C-f
1790 @kindex C-c C-f @r{(SGML mode)}
1791 @findex sgml-skip-tag-forward
1792 Skip across a balanced tag group (which extends from an opening tag
1793 through its corresponding closing tag) (@code{sgml-skip-tag-forward}).
1794 A numeric argument acts as a repeat count.
1796 @item C-c C-b
1797 @kindex C-c C-b @r{(SGML mode)}
1798 @findex sgml-skip-tag-backward
1799 Skip backward across a balanced tag group (which extends from an
1800 opening tag through its corresponding closing tag)
1801 (@code{sgml-skip-tag-forward}).  A numeric argument acts as a repeat
1802 count.
1804 @item C-c C-d
1805 @kindex C-c C-d @r{(SGML mode)}
1806 @findex sgml-delete-tag
1807 Delete the tag at or after point, and delete the matching tag too
1808 (@code{sgml-delete-tag}).  If the tag at or after point is an opening
1809 tag, delete the closing tag too; if it is a closing tag, delete the
1810 opening tag too.
1812 @item C-c ? @var{tag} @key{RET}
1813 @kindex C-c ? @r{(SGML mode)}
1814 @findex sgml-tag-help
1815 Display a description of the meaning of tag @var{tag}
1816 (@code{sgml-tag-help}).  If the argument @var{tag} is empty, describe
1817 the tag at point.
1819 @item C-c /
1820 @kindex C-c / @r{(SGML mode)}
1821 @findex sgml-close-tag
1822 Insert a close tag for the innermost unterminated tag
1823 (@code{sgml-close-tag}).  If called from within a tag or a comment,
1824 close this element instead of inserting a close tag.
1826 @item C-c 8
1827 @kindex C-c 8 @r{(SGML mode)}
1828 @findex sgml-name-8bit-mode
1829 Toggle a minor mode in which Latin-1 characters insert the
1830 corresponding SGML commands that stand for them, instead of the
1831 characters themselves (@code{sgml-name-8bit-mode}).
1833 @item C-c C-v
1834 @kindex C-c C-v @r{(SGML mode)}
1835 @findex sgml-validate
1836 Run a shell command (which you must specify) to validate the current
1837 buffer as SGML (@code{sgml-validate}).
1839 @item C-x TAB
1840 @kindex C-c TAB @r{(SGML mode)}
1841 @findex sgml-tags-invisible
1842 Toggle the visibility of existing tags in the buffer.  This can be
1843 used as a cheap preview.
1844 @end table
1846 @vindex sgml-xml-mode
1847   SGML mode and HTML mode support XML also.  In XML, every opening tag
1848 must have an explicit closing tag.  When @code{sgml-xml-mode} is
1849 non-@code{nil}, SGML mode and HTML mode always insert explicit
1850 closing tags.  When you visit a file, these modes determine from the
1851 file contents whether it is XML or not, and set @code{sgml-xml-mode}
1852 accordingly, so that they do the right thing for the file in either
1853 case.
1855 @node Nroff Mode
1856 @section Nroff Mode
1858 @cindex nroff
1859 @findex nroff-mode
1860   Nroff mode is a mode like Text mode but modified to handle nroff commands
1861 present in the text.  Invoke @kbd{M-x nroff-mode} to enter this mode.  It
1862 differs from Text mode in only a few ways.  All nroff command lines are
1863 considered paragraph separators, so that filling will never garble the
1864 nroff commands.  Pages are separated by @samp{.bp} commands.  Comments
1865 start with backslash-doublequote.  Also, three special commands are
1866 provided that are not in Text mode:
1868 @findex forward-text-line
1869 @findex backward-text-line
1870 @findex count-text-lines
1871 @kindex M-n @r{(Nroff mode)}
1872 @kindex M-p @r{(Nroff mode)}
1873 @kindex M-? @r{(Nroff mode)}
1874 @table @kbd
1875 @item M-n
1876 Move to the beginning of the next line that isn't an nroff command
1877 (@code{forward-text-line}).  An argument is a repeat count.
1878 @item M-p
1879 Like @kbd{M-n} but move up (@code{backward-text-line}).
1880 @item M-?
1881 Displays in the echo area the number of text lines (lines that are not
1882 nroff commands) in the region (@code{count-text-lines}).
1883 @end table
1885 @findex electric-nroff-mode
1886   The other feature of Nroff mode is that you can turn on Electric Nroff
1887 mode.  This is a minor mode that you can turn on or off with @kbd{M-x
1888 electric-nroff-mode} (@pxref{Minor Modes}).  When the mode is on, each
1889 time you use @key{RET} to end a line that contains an nroff command that
1890 opens a kind of grouping, the matching nroff command to close that
1891 grouping is automatically inserted on the following line.  For example,
1892 if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
1893 this inserts the matching command @samp{.)b} on a new line following
1894 point.
1896   If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
1897 heading lines are lines of the form @samp{.H} followed by a number (the
1898 header level).
1900 @vindex nroff-mode-hook
1901   Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
1902 the hook @code{nroff-mode-hook} (@pxref{Hooks}).
1904 @node Formatted Text
1905 @section Editing Formatted Text
1907 @cindex Enriched mode
1908 @cindex mode, Enriched
1909 @cindex formatted text
1910 @cindex WYSIWYG
1911 @cindex word processing
1912   @dfn{Enriched mode} is a minor mode for editing files that contain
1913 formatted text in WYSIWYG fashion, as in a word processor.  Currently,
1914 formatted text in Enriched mode can specify fonts, colors, underlining,
1915 margins, and types of filling and justification.  In the future, we plan
1916 to implement other formatting features as well.
1918   Enriched mode is a minor mode (@pxref{Minor Modes}).  It is
1919 typically used in conjunction with Text mode (@pxref{Text Mode}), but
1920 you can also use it with other major modes such as Outline mode and
1921 Paragraph-Indent Text mode.
1923 @cindex text/enriched MIME format
1924   Potentially, Emacs can store formatted text files in various file
1925 formats.  Currently, only one format is implemented: @dfn{text/enriched}
1926 format, which is defined by the MIME protocol.  @xref{Format
1927 Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual},
1928 for details of how Emacs recognizes and converts file formats.
1930   The Emacs distribution contains a formatted text file that can serve as
1931 an example.  Its name is @file{etc/enriched.doc}.  It contains samples
1932 illustrating all the features described in this section.  It also
1933 contains a list of ideas for future enhancements.
1935 @menu
1936 * Requesting Formatted Text::   Entering and exiting Enriched mode.
1937 * Hard and Soft Newlines::      There are two different kinds of newlines.
1938 * Editing Format Info::         How to edit text properties.
1939 * Faces: Format Faces.          Bold, italic, underline, etc.
1940 * Color: Format Colors.         Changing the color of text.
1941 * Indent: Format Indentation.   Changing the left and right margins.
1942 * Justification: Format Justification.
1943                                 Centering, setting text flush with the
1944                                   left or right margin, etc.
1945 * Other: Format Properties.     The "special" text properties submenu.
1946 * Forcing Enriched Mode::       How to force use of Enriched mode.
1947 @end menu
1949 @node Requesting Formatted Text
1950 @subsection Requesting to Edit Formatted Text
1952   Whenever you visit a file that Emacs saved in the text/enriched
1953 format, Emacs automatically converts the formatting information in the
1954 file into Emacs's own internal format (known as @dfn{text
1955 properties}), and turns on Enriched mode.
1957 @findex enriched-mode
1958   To create a new file of formatted text, first visit the nonexistent
1959 file, then type @kbd{M-x enriched-mode} before you start inserting text.
1960 This command turns on Enriched mode.  Do this before you begin inserting
1961 text, to ensure that the text you insert is handled properly.
1963   More generally, the command @code{enriched-mode} turns Enriched mode
1964 on if it was off, and off if it was on.  With a prefix argument, this
1965 command turns Enriched mode on if the argument is positive, and turns
1966 the mode off otherwise.
1968   When you save a buffer while Enriched mode is enabled in it, Emacs
1969 automatically converts the text to text/enriched format while writing it
1970 into the file.  When you visit the file again, Emacs will automatically
1971 recognize the format, reconvert the text, and turn on Enriched mode
1972 again.
1974 @vindex enriched-translations
1975   You can add annotations for saving additional text properties, which
1976 Emacs normally does not save, by adding to @code{enriched-translations}.
1977 Note that the text/enriched standard requires any non-standard
1978 annotations to have names starting with @samp{x-}, as in
1979 @samp{x-read-only}.  This ensures that they will not conflict with
1980 standard annotations that may be added later.
1982   @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual},
1983 for more information about text properties.
1985 @node Hard and Soft Newlines
1986 @subsection Hard and Soft Newlines
1987 @cindex hard newline
1988 @cindex soft newline
1989 @cindex newlines, hard and soft
1991 @cindex use-hard-newlines
1992   In formatted text, Emacs distinguishes between two different kinds of
1993 newlines, @dfn{hard} newlines and @dfn{soft} newlines.  (You can enable
1994 or disable this feature separately in any  buffer with the command
1995 @code{use-hard-newlines}.)
1997   Hard newlines are used to separate paragraphs, or items in a list, or
1998 anywhere that there should always be a line break regardless of the
1999 margins.  The @key{RET} command (@code{newline}) and @kbd{C-o}
2000 (@code{open-line}) insert hard newlines.
2002   Soft newlines are used to make text fit between the margins.  All the
2003 fill commands, including Auto Fill, insert soft newlines---and they
2004 delete only soft newlines.
2006   Although hard and soft newlines look the same, it is important to bear
2007 the difference in mind.  Do not use @key{RET} to break lines in the
2008 middle of filled paragraphs, or else you will get hard newlines that are
2009 barriers to further filling.  Instead, let Auto Fill mode break lines,
2010 so that if the text or the margins change, Emacs can refill the lines
2011 properly.  @xref{Auto Fill}.
2013   On the other hand, in tables and lists, where the lines should always
2014 remain as you type them, you can use @key{RET} to end lines.  For these
2015 lines, you may also want to set the justification style to
2016 @code{unfilled}.  @xref{Format Justification}.
2018 @node Editing Format Info
2019 @subsection Editing Format Information
2021   There are two ways to alter the formatting information for a formatted
2022 text file: with keyboard commands, and with the mouse.
2024   The easiest way to add properties to your document is with the Text
2025 Properties menu.  You can get to this menu in two ways: from the Edit
2026 menu in the menu bar (use @kbd{@key{F10} e t} if you have no mouse),
2027 or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle
2028 mouse button).  There are also keyboard commands described in the
2029 following section.
2031   Most of the items in the Text Properties menu lead to other submenus.
2032 These are described in the sections that follow.  Some items run
2033 commands directly:
2035 @table @code
2036 @findex facemenu-remove-face-props
2037 @item Remove Face Properties
2038 Delete from the region all face and color text properties
2039 (@code{facemenu-remove-face-props}).
2041 @findex facemenu-remove-all
2042 @item Remove Text Properties
2043 Delete @emph{all} text properties from the region
2044 (@code{facemenu-remove-all}).
2046 @findex describe-text-properties
2047 @cindex text properties of characters
2048 @cindex overlays at character position
2049 @cindex widgets at buffer position
2050 @cindex buttons at buffer position
2051 @item Describe Properties
2052 List all the text properties, widgets, buttons, and overlays of the
2053 character following point (@code{describe-text-properties}).
2055 @item Display Faces
2056 Display a list of all the defined faces (@code{list-faces-display}).
2058 @item Display Colors
2059 Display a list of all the defined colors (@code{list-colors-display}).
2060 @end table
2062 @node Format Faces
2063 @subsection Faces in Formatted Text
2065   The Faces submenu lists various Emacs faces including @code{bold},
2066 @code{italic}, and @code{underline}.  Selecting one of these adds the
2067 chosen face to the region.  @xref{Faces}.  You can also specify a face
2068 with these keyboard commands:
2070 @table @kbd
2071 @kindex M-o d @r{(Enriched mode)}
2072 @findex facemenu-set-default
2073 @item M-o d
2074 Set the region, or the next inserted character, to the @code{default} face
2075 (@code{facemenu-set-default}).
2076 @kindex M-o b @r{(Enriched mode)}
2077 @findex facemenu-set-bold
2078 @item M-o b
2079 Set the region, or the next inserted character, to the @code{bold} face
2080 (@code{facemenu-set-bold}).
2081 @kindex M-o i @r{(Enriched mode)}
2082 @findex facemenu-set-italic
2083 @item M-o i
2084 Set the region, or the next inserted character, to the @code{italic} face
2085 (@code{facemenu-set-italic}).
2086 @kindex M-o l @r{(Enriched mode)}
2087 @findex facemenu-set-bold-italic
2088 @item M-o l
2089 Set the region, or the next inserted character, to the @code{bold-italic} face
2090 (@code{facemenu-set-bold-italic}).
2091 @kindex M-o u @r{(Enriched mode)}
2092 @findex facemenu-set-underline
2093 @item M-o u
2094 Set the region, or the next inserted character, to the @code{underline} face
2095 (@code{facemenu-set-underline}).
2096 @kindex M-o o @r{(Enriched mode)}
2097 @findex facemenu-set-face
2098 @item M-o o @var{face} @key{RET}
2099 Set the region, or the next inserted character, to the face @var{face}
2100 (@code{facemenu-set-face}).
2101 @end table
2103   If you use these commands with a prefix argument---or, in Transient Mark
2104 mode, if the region is not active---then these commands specify a face
2105 to use for any immediately following self-inserting input.
2106 @xref{Transient Mark}.  This applies to both the keyboard commands and
2107 the menu commands.
2109   Specifying the @code{default} face also resets foreground and
2110 background color to their defaults.(@pxref{Format Colors}).
2112   Any self-inserting character you type inherits, by default, the face
2113 properties (as well as most other text properties) of the preceding
2114 character.  Specifying any face property, including foreground or
2115 background color, for your next self-inserting character will prevent
2116 it from inheriting any face properties from the preceding character,
2117 although it will still inherit other text properties.  Characters
2118 inserted by yanking do not inherit text properties.
2120   Enriched mode defines two additional faces: @code{excerpt} and
2121 @code{fixed}.  These correspond to codes used in the text/enriched file
2122 format.
2124   The @code{excerpt} face is intended for quotations.  This face is the
2125 same as @code{italic} unless you customize it (@pxref{Face Customization}).
2127   The @code{fixed} face means, ``Use a fixed-width font for this part
2128 of the text.''  Applying the @code{fixed} face to a part of the text
2129 will cause that part of the text to appear in a fixed-width font, even
2130 if the default font is variable-width.  This applies to Emacs and to
2131 other systems that display text/enriched format.  So if you
2132 specifically want a certain part of the text to use a fixed-width
2133 font, you should specify the @code{fixed} face for that part.
2135   By default, the @code{fixed} face looks the same as @code{bold}.
2136 This is an attempt to distinguish it from @code{default}.  You may
2137 wish to customize @code{fixed} to some other fixed-width medium font.
2138 @xref{Face Customization}.
2140   If your terminal cannot display different faces, you will not be
2141 able to see them, but you can still edit documents containing faces,
2142 and even add faces and colors to documents.  The faces you specify
2143 will be visible when the file is viewed on a terminal that can display
2144 them.
2146 @node Format Colors
2147 @subsection Colors in Formatted Text
2149   You can specify foreground and background colors for portions of the
2150 text.  There is a menu for specifying the foreground color and a menu
2151 for specifying the background color.  Each color menu lists all the
2152 colors that you have used in Enriched mode in the current Emacs session.
2154   If you specify a color with a prefix argument---or, in Transient
2155 Mark mode, if the region is not active---then it applies to any
2156 immediately following self-inserting input.  @xref{Transient Mark}.
2157 Otherwise, the command applies to the region.
2159   Each color menu contains one additional item: @samp{Other}.  You can use
2160 this item to specify a color that is not listed in the menu; it reads
2161 the color name with the minibuffer.  To display a list of available colors
2162 and their names, use the @samp{Display Colors} menu item in the Text
2163 Properties menu (@pxref{Editing Format Info}).
2165   Any color that you specify in this way, or that is mentioned in a
2166 formatted text file that you read in, is added to the corresponding
2167 color menu for the duration of the Emacs session.
2169 @findex facemenu-set-foreground
2170 @findex facemenu-set-background
2171   There are no key bindings for specifying colors, but you can do so
2172 with the extended commands @kbd{M-x facemenu-set-foreground} and
2173 @kbd{M-x facemenu-set-background}.  Both of these commands read the name
2174 of the color with the minibuffer.
2176 @node Format Indentation
2177 @subsection Indentation in Formatted Text
2179   When editing formatted text, you can specify different amounts of
2180 indentation for the right or left margin of an entire paragraph or a
2181 part of a paragraph.  The margins you specify automatically affect the
2182 Emacs fill commands (@pxref{Filling}) and line-breaking commands.
2184   The Indentation submenu provides a convenient interface for specifying
2185 these properties.  The submenu contains four items:
2187 @table @code
2188 @kindex C-x TAB @r{(Enriched mode)}
2189 @findex increase-left-margin
2190 @item Indent More
2191 Indent the region by 4 columns (@code{increase-left-margin}).  In
2192 Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
2193 you supply a numeric argument, that says how many columns to add to the
2194 margin (a negative argument reduces the number of columns).
2196 @item Indent Less
2197 Remove 4 columns of indentation from the region.
2199 @item Indent Right More
2200 Make the text narrower by indenting 4 columns at the right margin.
2202 @item Indent Right Less
2203 Remove 4 columns of indentation from the right margin.
2204 @end table
2206   You can use these commands repeatedly to increase or decrease the
2207 indentation.
2209   The most common way to use them is to change the indentation of an
2210 entire paragraph.  For other uses, the effects of refilling can be
2211 hard to predict, except in some special cases like the one described
2212 next.
2214   The most common other use is to format paragraphs with @dfn{hanging
2215 indents}, which means that the first line is indented less than
2216 subsequent lines.  To set up a hanging indent, increase the
2217 indentation of the region starting after the first word of the
2218 paragraph and running until the end of the paragraph.
2220   Indenting the first line of a paragraph is easier.  Set the margin for
2221 the whole paragraph where you want it to be for the body of the
2222 paragraph, then indent the first line by inserting extra spaces or tabs.
2224 @vindex standard-indent
2225   The variable @code{standard-indent} specifies how many columns these
2226 commands should add to or subtract from the indentation.  The default
2227 value is 4.  The overall default right margin for Enriched mode is
2228 controlled by the variable @code{fill-column}, as usual.
2230 @kindex C-c [ @r{(Enriched mode)}
2231 @kindex C-c ] @r{(Enriched mode)}
2232 @findex set-left-margin
2233 @findex set-right-margin
2234   There are also two commands for setting the left or right margin of
2235 the region absolutely: @code{set-left-margin} and
2236 @code{set-right-margin}.  Enriched mode binds these commands to
2237 @kbd{C-c [} and @kbd{C-c ]}, respectively.  You can specify the
2238 margin width either with a numeric argument or in the minibuffer.
2240   Sometimes, as a result of editing, the filling of a paragraph becomes
2241 messed up---parts of the paragraph may extend past the left or right
2242 margins.  When this happens, use @kbd{M-q} (@code{fill-paragraph}) to
2243 refill the paragraph.
2245   The fill prefix, if any, works in addition to the specified paragraph
2246 indentation: @kbd{C-x .} does not include the specified indentation's
2247 whitespace in the new value for the fill prefix, and the fill commands
2248 look for the fill prefix after the indentation on each line.  @xref{Fill
2249 Prefix}.
2251 @node Format Justification
2252 @subsection Justification in Formatted Text
2254   When editing formatted text, you can specify various styles of
2255 justification for a paragraph.  The style you specify automatically
2256 affects the Emacs fill commands.
2258   The Justification submenu provides a convenient interface for specifying
2259 the style.  The submenu contains five items:
2261 @table @code
2262 @item Left
2263 This is the most common style of justification (at least for English).
2264 Lines are aligned at the left margin but left uneven at the right.
2266 @item Right
2267 This aligns each line with the right margin.  Spaces and tabs are added
2268 on the left, if necessary, to make lines line up on the right.
2270 @item Full
2271 This justifies the text, aligning both edges of each line.  Justified
2272 text looks very nice in a printed book, where the spaces can all be
2273 adjusted equally, but it does not look as nice with a fixed-width font
2274 on the screen.  Perhaps a future version of Emacs will be able to adjust
2275 the width of spaces in a line to achieve elegant justification.
2277 @item Center
2278 This centers every line between the current margins.
2280 @item Unfilled
2281 This turns off filling entirely.  Each line will remain as you wrote it;
2282 the fill and auto-fill functions will have no effect on text which has
2283 this setting.  You can, however, still indent the left margin.  In
2284 unfilled regions, all newlines are treated as hard newlines (@pxref{Hard
2285 and Soft Newlines}) .
2286 @end table
2288   In Enriched mode, you can also specify justification from the keyboard
2289 using the @kbd{M-j} prefix character:
2291 @table @kbd
2292 @kindex M-j l @r{(Enriched mode)}
2293 @findex set-justification-left
2294 @item M-j l
2295 Make the region left-filled (@code{set-justification-left}).
2296 @kindex M-j r @r{(Enriched mode)}
2297 @findex set-justification-right
2298 @item M-j r
2299 Make the region right-filled (@code{set-justification-right}).
2300 @kindex M-j b @r{(Enriched mode)}
2301 @findex set-justification-full
2302 @item M-j b
2303 Make the region fully justified (@code{set-justification-full}).
2304 @kindex M-j c @r{(Enriched mode)}
2305 @kindex M-S @r{(Enriched mode)}
2306 @findex set-justification-center
2307 @item M-j c
2308 @itemx M-S
2309 Make the region centered (@code{set-justification-center}).
2310 @kindex M-j u @r{(Enriched mode)}
2311 @findex set-justification-none
2312 @item M-j u
2313 Make the region unfilled (@code{set-justification-none}).
2314 @end table
2316   Justification styles apply to entire paragraphs.  All the
2317 justification-changing commands operate on the paragraph containing
2318 point, or, if the region is active, on all paragraphs which overlap the
2319 region.
2321 @vindex default-justification
2322   The default justification style is specified by the variable
2323 @code{default-justification}.  Its value should be one of the symbols
2324 @code{left}, @code{right}, @code{full}, @code{center}, or @code{none}.
2325 This is a per-buffer variable.  Setting the variable directly affects
2326 only the current buffer.  However, customizing it in a Custom buffer
2327 sets (as always) the default value for buffers that do not override it.
2328 @xref{Locals}, and @ref{Easy Customization}.
2330 @node Format Properties
2331 @subsection Setting Other Text Properties
2333   The Special Properties menu lets you add or remove three other useful text
2334 properties: @code{read-only}, @code{invisible} and @code{intangible}.
2335 The @code{intangible} property disallows moving point within the text,
2336 the @code{invisible} text property hides text from display, and the
2337 @code{read-only} property disallows alteration of the text.
2339   Each of these special properties has a menu item to add it to the
2340 region.  The last menu item, @samp{Remove Special}, removes all of these
2341 special properties from the text in the region.
2343   Currently, the @code{invisible} and @code{intangible} properties are
2344 @emph{not} saved in the text/enriched format.  The @code{read-only}
2345 property is saved, but it is not a standard part of the text/enriched
2346 format, so other editors may not respect it.
2348 @node Forcing Enriched Mode
2349 @subsection Forcing Enriched Mode
2351   Normally, Emacs knows when you are editing formatted text because it
2352 recognizes the special annotations used in the file that you visited.
2353 However, there are situations in which you must take special actions
2354 to convert file contents or turn on Enriched mode:
2356 @itemize @bullet
2357 @item
2358 When you visit a file that was created with some other editor, Emacs may
2359 not recognize the file as being in the text/enriched format.  In this
2360 case, when you visit the file you will see the formatting commands
2361 rather than the formatted text.  Type @kbd{M-x format-decode-buffer} to
2362 translate it.  This also automatically turns on Enriched mode.
2364 @item
2365 When you @emph{insert} a file into a buffer, rather than visiting it,
2366 Emacs does the necessary conversions on the text which you insert, but
2367 it does not enable Enriched mode.  If you wish to do that, type @kbd{M-x
2368 enriched-mode}.
2369 @end itemize
2371   The command @code{format-decode-buffer} translates text in various
2372 formats into Emacs's internal format.  It asks you to specify the format
2373 to translate from; however, normally you can type just @key{RET}, which
2374 tells Emacs to guess the format.
2376 @findex format-find-file
2377   If you wish to look at a text/enriched file in its raw form, as a
2378 sequence of characters rather than as formatted text, use the @kbd{M-x
2379 find-file-literally} command.  This visits a file, like
2380 @code{find-file}, but does not do format conversion.  It also inhibits
2381 character code conversion (@pxref{Coding Systems}) and automatic
2382 uncompression (@pxref{Compressed Files}).  To disable format conversion
2383 but allow character code conversion and/or automatic uncompression if
2384 appropriate, use @code{format-find-file} with suitable arguments.
2386 @node Text Based Tables
2387 @section Editing Text-based Tables
2388 @cindex table mode
2389 @cindex text-based tables
2391   Table mode provides an easy and intuitive way to create and edit WYSIWYG
2392 text-based tables.  Here is an example of such a table:
2394 @smallexample
2395 +-----------------+--------------------------------+-----------------+
2396 |     Command     |          Description           |   Key Binding   |
2397 +-----------------+--------------------------------+-----------------+
2398 |  forward-char   |Move point right N characters   |       C-f       |
2399 |                 |(left if N is negative).        |                 |
2400 |                 |                                |                 |
2401 |                 |On reaching end of buffer, stop |                 |
2402 |                 |and signal error.               |                 |
2403 +-----------------+--------------------------------+-----------------+
2404 |  backward-char  |Move point left N characters    |       C-b       |
2405 |                 |(right if N is negative).       |                 |
2406 |                 |                                |                 |
2407 |                 |On attempt to pass beginning or |                 |
2408 |                 |end of buffer, stop and signal  |                 |
2409 |                 |error.                          |                 |
2410 +-----------------+--------------------------------+-----------------+
2411 @end smallexample
2413   Table mode allows the contents of the table such as this one to be
2414 easily manipulated by inserting or deleting characters inside a cell.
2415 A cell is effectively a localized rectangular edit region and edits to
2416 a cell do not affect the contents of the surrounding cells.  If the
2417 contents do not fit into a cell, then the cell is automatically
2418 expanded in the vertical and/or horizontal directions and the rest of
2419 the table is restructured and reformatted in accordance with the
2420 growth of the cell.
2422 @menu
2423 * Table Definition::          What is a text based table.
2424 * Table Creation::            How to create a table.
2425 * Table Recognition::         How to activate and deactivate tables.
2426 * Cell Commands::             Cell-oriented commands in a table.
2427 * Cell Justification::        Justifying cell contents.
2428 * Row Commands::              Manipulating rows of table cell.
2429 * Column Commands::           Manipulating columns of table cell.
2430 * Fixed Width Mode::          Fixing cell width.
2431 * Table Conversion::          Converting between plain text and tables.
2432 * Measuring Tables::          Analyzing table dimension.
2433 * Table Misc::                Table miscellany.
2434 @end menu
2436 @node Table Definition
2437 @subsection What is a Text-based Table?
2439   Keep the following examples of valid tables in mind as a reference
2440 while you read this section:
2442 @example
2443               +--+----+---+     +-+     +--+-----+
2444               |  |    |   |     | |     |  |     |
2445               +--+----+---+     +-+     |  +--+--+
2446               |  |    |   |             |  |  |  |
2447               +--+----+---+             +--+--+  |
2448                                         |     |  |
2449                                         +-----+--+
2450 @end example
2452   A table consists of a rectangular frame whose inside is divided into
2453 cells.  Each cell must be at least one character wide and one
2454 character high, not counting its border lines.  A cell can be
2455 subdivided into multiple rectangular cells, but cells cannot overlap.
2457   The table frame and cell border lines are made of three special
2458 characters.  These variables specify those characters:
2460 @table @code
2461 @vindex table-cell-vertical-char
2462 @item table-cell-vertical-char
2463 Holds the character used for vertical lines.  The default value is
2464 @samp{|}.
2466 @vindex table-cell-horizontal-char
2467 @item table-cell-horizontal-char
2468 Holds the character used for horizontal lines.  The default value is
2469 @samp{-}.
2471 @vindex table-cell-intersection-char
2472 @item table-cell-intersection-char
2473 Holds the character used at where horizontal line and vertical line
2474 meet.  The default value is @samp{+}.
2475 @end table
2477 @noindent
2478 Based on this definition, the following five tables are examples of invalid
2479 tables:
2481 @example
2482    +-----+    +-----+       +--+    +-++--+    ++
2483    |     |    |     |       |  |    | ||  |    ++
2484    | +-+ |    |     |       |  |    | ||  |
2485    | | | |    +--+  |    +--+--+    +-++--+
2486    | +-+ |    |  |  |    |  |  |    +-++--+
2487    |     |    |  |  |    |  |  |    | ||  |
2488    +-----+    +--+--+    +--+--+    +-++--+
2489      a           b          c          d        e
2490 @end example
2492 From left to right:
2494 @enumerate a
2495 @item
2496 Overlapped cells or non-rectangular cells are not allowed.
2497 @item
2498 Same as a.
2499 @item
2500 The border must be rectangular.
2501 @item
2502 Cells must have a minimum width/height of one character.
2503 @item
2504 Same as d.
2505 @end enumerate
2507 @node Table Creation
2508 @subsection How to Create a Table?
2509 @cindex create a text-based table
2510 @cindex table creation
2512 @findex table-insert
2513   The command to create a table is @code{table-insert}.  When called
2514 interactively, it asks for the number of columns, number of rows, cell
2515 width and cell height.  The number of columns is the number of cells
2516 horizontally side by side.  The number of rows is the number of cells
2517 vertically within the table's height.  The cell width is a number of
2518 characters that each cell holds, left to right.  The cell height is a
2519 number of lines each cell holds.  The cell width and the cell height
2520 can be either an integer (when the value is constant across the table)
2521 or a series of integer, separated by spaces or commas, where each
2522 number corresponds to the next cell within a row from left to right,
2523 or the next cell within a column from top to bottom.
2525 @node Table Recognition
2526 @subsection Table Recognition
2527 @cindex table recognition
2529 @findex table-recognize
2530 @findex table-unrecognize
2531   Table mode maintains special text properties in the buffer to allow
2532 editing in a convenient fashion.  When a buffer with tables is saved
2533 to its file, these text properties are lost, so when you visit this
2534 file again later, Emacs does not see a table, but just formatted text.
2535 To resurrect the table text properties, issue the @kbd{M-x
2536 table-recognize} command.  It scans the current buffer, recognizes
2537 valid table cells, and attaches appropriate text properties to allow
2538 for table editing.  The converse command, @code{table-unrecognize}, is
2539 used to remove the special text properties and convert the buffer back
2540 to plain text.
2542   Special commands exist to enable or disable tables within a region,
2543 enable or disable individual tables, and enable/disable individual
2544 cells.  These commands are:
2546 @table @kbd
2547 @findex table-recognize-region
2548 @item M-x table-recognize-region
2549 Recognize tables within the current region and activate them.
2550 @findex table-unrecognize-region
2551 @item M-x table-unrecognize-region
2552 Deactivate tables within the current region.
2553 @findex table-recognize-table
2554 @item M-x table-recognize-table
2555 Recognize the table under point and activate it.
2556 @findex table-unrecognize-table
2557 @item M-x table-unrecognize-table
2558 Deactivate the table under point.
2559 @findex table-recognize-cell
2560 @item M-x table-recognize-cell
2561 Recognize the cell under point and activate it.
2562 @findex table-unrecognize-cell
2563 @item M-x table-unrecognize-cell
2564 Deactivate the cell under point.
2565 @end table
2567   For another way of converting text into tables, see @ref{Table
2568 Conversion}.
2570 @node Cell Commands
2571 @subsection Commands for Table Cells
2573 @findex table-forward-cell
2574 @findex table-backward-cell
2575   The commands @code{table-forward-cell} and
2576 @code{table-backward-cell} move point from the current cell to an
2577 adjacent cell forward and backward respectively.  The order of the
2578 cells is cyclic: when point is in the last cell of a table, typing
2579 @kbd{M-x table-forward-cell} moves to the first cell in the table.
2580 Likewise @kbd{M-x table-backward-cell} from the first cell in a table
2581 moves to the last cell.
2583 @findex table-span-cell
2584   The command @code{table-span-cell} merges the current cell with the
2585 adjacent cell in a specified direction---right, left, above or below.
2586 You specify the direction with the minibuffer.  It does not allow
2587 merges which don't result in a legitimate cell layout.
2589 @findex table-split-cell
2590 @cindex text-based tables, split a cell
2591 @cindex split table cell
2592   The command @code{table-split-cell} splits the current cell
2593 vertically or horizontally.  This command is a wrapper to the
2594 direction specific commands @code{table-split-cell-vertically} and
2595 @code{table-split-cell-horizontally}.  You specify the direction with
2596 a minibuffer argument.
2598 @findex table-split-cell-vertically
2599   The command @code{table-split-cell-vertically} splits the current
2600 cell vertically and creates a pair of cells above and below where
2601 point is located.  The content in the original cell is split as well.
2603 @findex table-split-cell-horizontally
2604   The command @code{table-split-cell-horizontally} splits the current
2605 cell horizontally and creates a pair of cells right and left of where
2606 point is located.  If the cell being split is not empty, this asks you
2607 how to handle the cell contents.  The three options are: @code{split},
2608 @code{left}, or @code{right}.  @code{split} splits the contents at
2609 point literally, while the @code{left} and @code{right} options move
2610 the entire contents into the left or right cell respectively.
2612 @cindex enlarge a table cell
2613 @cindex shrink a table cell
2614   The next four commands enlarge or shrink a cell.  They use numeric
2615 arguments (@pxref{Arguments}) to specify how many columns or rows to
2616 enlarge or shrink a particular table.
2618 @table @kbd
2619 @findex table-heighten-cell
2620 @item M-x table-heighten-cell
2621 Enlarge the current cell vertically.
2622 @findex table-shorten-cell
2623 @item M-x table-shorten-cell
2624 Shrink the current cell vertically.
2625 @findex table-widen-cell
2626 @item M-x table-widen-cell
2627 Enlarge the current cell horizontally.
2628 @findex table-narrow-cell
2629 @item M-x table-narrow-cell
2630 Shrink the current cell horizontally.
2631 @end table
2633 @node Cell Justification
2634 @subsection Cell Justification
2635 @cindex cell text justification
2637   You can specify text justification for each cell.  The justification
2638 is remembered independently for each cell and the subsequent editing
2639 of cell contents is subject to the specified justification.
2641 @findex table-justify
2642   The command @code{table-justify} ask you to specify what to justify:
2643 a cell, a column, or a row.  If you select cell justification, this
2644 command sets the justification only for the current cell.  Selecting
2645 column or row justification sets the justification for all the cells
2646 within a column or row respectively.  The command then ask you which
2647 kind of justification to apply: @code{left}, @code{center},
2648 @code{right}, @code{top}, @code{middle}, @code{bottom}, or
2649 @code{none}.  Horizontal justification and vertical justification are
2650 specified independently.  The options @code{left}, @code{center}, and
2651 @code{right} specify horizontal justification while the options
2652 @code{top}, @code{middle}, @code{bottom}, and @code{none} specify
2653 vertical justification.  The vertical justification @code{none}
2654 effectively removes vertical justification.  Horizontal justification
2655 must be one of @code{left}, @code{center}, or @code{right}.
2657 @vindex table-detect-cell-alignment
2658   Justification information is stored in the buffer as a part of text
2659 property.  Therefore, this information is ephemeral and does not
2660 survive through the loss of the buffer (closing the buffer and
2661 revisiting the buffer erase any previous text properties).  To
2662 countermand for this, the command @code{table-recognize} and other
2663 recognition commands (@pxref{Table Recognition}) are equipped with a
2664 convenience feature (turned on by default).  During table recognition,
2665 the contents of a cell are examined to determine which justification
2666 was originally applied to the cell and then applies this justification
2667 to the cell.  This is a speculative algorithm and is therefore not
2668 perfect, however, the justification is deduced correctly most of the
2669 time.  To disable this feature, customize the variable
2670 @code{table-detect-cell-alignment} and set it to @code{nil}.
2672 @node Row Commands
2673 @subsection Commands for Table Rows
2674 @cindex table row commands
2676 @cindex insert row in table
2677 @findex table-insert-row
2678   The command @code{table-insert-row} inserts a row of cells before
2679 the current row in a table.  The current row where point is located is
2680 pushed down after the newly inserted row.  A numeric prefix argument
2681 specifies the number of rows to insert.  Note that in order to insert
2682 rows @emph{after} the last row at the bottom of a table, you must
2683 place point below the table---that is, outside the table---prior to
2684 invoking this command.
2686 @cindex delete row in table
2687 @findex table-delete-row
2688   The command @code{table-delete-row} deletes a row of cells at point.
2689 A numeric prefix argument specifies the number of rows to delete.
2691 @node Column Commands
2692 @subsection Commands for Table Columns
2693 @cindex table column commands
2695 @cindex insert column in table
2696 @findex table-insert-column
2697   The command @code{table-insert-column} inserts a column of cells to
2698 the left of the current row in a table.  This pushes the current
2699 column to the right.  To insert a column to the right side of the
2700 rightmost column, place point to the right of the rightmost column,
2701 which is outside of the table, prior to invoking this command.  A
2702 numeric prefix argument specifies the number of columns to insert.
2704 @cindex delete column in table
2705   A command @code{table-delete-column} deletes a column of cells at
2706 point.  A numeric prefix argument specifies the number of columns to
2707 delete.
2709 @node Fixed Width Mode
2710 @subsection Fix Width of Cells
2711 @cindex fix width of table cells
2713 @findex table-fixed-width-mode
2714   The command @code{table-fixed-width-mode} toggles fixed width mode
2715 on and off.  When fixed width mode is turned on, editing inside a
2716 cell never changes the cell width; when it is off, the cell width
2717 expands automatically in order to prevent a word from being folded
2718 into multiple lines.  By default, fixed width mode is disabled.
2720 @node Table Conversion
2721 @subsection Conversion Between Plain Text and Tables
2722 @cindex text to table
2723 @cindex table to text
2725 @findex table-capture
2726   The command @code{table-capture} captures plain text in a region and
2727 turns it into a table.  Unlike @code{table-recognize} (@pxref{Table
2728 Recognition}), the original text does not have a table appearance but
2729 may hold a logical table structure.  For example, some elements
2730 separated by known patterns form a two dimensional structure which can
2731 be turned into a table.
2733   Here's an example of data that @code{table-capture} can operate on.
2734 The numbers are horizontally separated by a comma and vertically
2735 separated by a newline character.
2737 @example
2738 1, 2, 3, 4
2739 5, 6, 7, 8
2740 , 9, 10
2741 @end example
2743 @noindent
2744 Invoking @kbd{M-x table-capture} on that text produces this table:
2746 @example
2747 +-----+-----+-----+-----+
2748 |1    |2    |3    |4    |
2749 +-----+-----+-----+-----+
2750 |5    |6    |7    |8    |
2751 +-----+-----+-----+-----+
2752 |     |9    |10   |     |
2753 +-----+-----+-----+-----+
2754 @end example
2756 @noindent
2757 The conversion uses @samp{,} for the column delimiter and newline for
2758 a row delimiter, cells are left justified, and minimum cell width is
2761 @findex table-release
2762   The command @code{table-release} does the opposite of
2763 @code{table-capture}.  It releases a table by removing the table frame
2764 and cell borders.  This leaves the table contents as plain text.  One
2765 of the useful applications of @code{table-capture} and
2766 @code{table-release} is to edit a text in layout.  Look at the
2767 following three paragraphs (the latter two are indented with header
2768 lines):
2770 @example
2771 @samp{table-capture} is a powerful command however mastering its power
2772 requires some practice.  Here are some things it can do:
2774 Parse Cell Items      By using column delimiter regular
2775                       expression and raw delimiter regular
2776                       expression, it parses the specified text
2777                       area and extracts cell items from
2778                       non-table text and then forms a table out
2779                       of them.
2781 Capture Text Area     When no delimiters are specified it
2782                       creates a single cell table.  The text in
2783                       the specified region is placed in that
2784                       cell.
2785 @end example
2787 @noindent
2788 Applying @code{table-capture} to a region containing the above three
2789 paragraphs, with empty strings for column delimiter regexp and row
2790 delimiter regexp, creates a table with a single cell like the
2791 following one.
2793 @c The first line's right-hand frame in the following two examples
2794 @c sticks out to accommodate for the removal of @samp in the
2795 @c produced output!!
2796 @example
2797 +-----------------------------------------------------------------+
2798 |@samp{table-capture} is a powerful command, but mastering its         |
2799 |power requires some practice.  Here are some things it can do:   |
2800 |                                                                 |
2801 |Parse Cell Items      By using column delimiter regular          |
2802 |                      expression and raw delimiter regular       |
2803 |                      expression, it parses the specified text   |
2804 |                      area and extracts cell items from          |
2805 |                      non-table text and then forms a table out  |
2806 |                      of them.                                   |
2807 |                                                                 |
2808 |Capture Text Area     When no delimiters are specified it        |
2809 |                      creates a single cell table.  The text in  |
2810 |                      the specified region is placed in that     |
2811 |                      cell.                                      |
2812 +-----------------------------------------------------------------+
2813 @end example
2815 @noindent
2816 By splitting the cell appropriately we now have a table consisting of
2817 paragraphs occupying its own cell.  Each cell can now be edited
2818 independently without affecting the layout of other cells.
2820 @example
2821 +-----------------------------------------------------------------+
2822 |@samp{table-capture} is a powerful command, but mastering its         |
2823 |power requires some practice.  Here are some things it can do:   |
2824 +---------------------+-------------------------------------------+
2825 |Parse Cell Items     |By using column delimiter regular          |
2826 |                     |expression and raw delimiter regular       |
2827 |                     |expression, it parses the specified text   |
2828 |                     |area and extracts cell items from          |
2829 |                     |non-table text and then forms a table out  |
2830 |                     |of them.                                   |
2831 +---------------------+-------------------------------------------+
2832 |Capture Text Area    |When no delimiters are specified it        |
2833 |                     |creates a single cell table.  The text in  |
2834 |                     |the specified region is placed in that     |
2835 |                     |cell.                                      |
2836 +---------------------+-------------------------------------------+
2837 @end example
2839 @noindent
2840 By applying @code{table-release}, which does the opposite process, the
2841 contents become once again plain text.  @code{table-release} works as
2842 a companion command to @code{table-capture}.
2844 @node Measuring Tables
2845 @subsection Analyzing Table Dimensions
2846 @cindex table dimensions
2848 @findex table-query-dimension
2849   The command @code{table-query-dimension} analyzes a table structure
2850 and reports information regarding its dimensions.  In case of the
2851 above example table, the @code{table-query-dimension} command displays
2852 in echo area:
2854 @smallexample
2855 Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
2856 @end smallexample
2858 @noindent
2859 This indicates that the current cell is 21 character wide and 6 lines
2860 high, the entire table is 67 characters wide and 16 lines high.  The
2861 table has 2 columns and 3 rows.  It has a total of 5 cells, since the
2862 first row has a spanned cell.
2864 @node Table Misc
2865 @subsection Table Miscellany
2867 @cindex insert string into table cells
2868 @findex table-insert-sequence
2869   The command @code{table-insert-sequence} inserts a string into each
2870 cell.  Each string is a part of a sequence i.e.@: a series of
2871 increasing integer numbers.
2873 @cindex table in language format
2874 @cindex table for HTML and LaTeX
2875 @findex table-generate-source
2876   The command @code{table-generate-source} generates a table formatted
2877 for a specific markup language.  It asks for a language (which must be
2878 one of @code{html}, @code{latex}, or @code{cals}), a destination
2879 buffer where to put the result, and the table caption (a string), and
2880 then inserts the generated table in the proper syntax into the
2881 destination buffer.  The default destination buffer is
2882 @code{table.@var{lang}}, where @var{lang} is the language you
2883 specified.
2885 @ignore
2886    arch-tag: 8db54ed8-2036-49ca-b0df-23811d03dc70
2887 @end ignore