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