annotate man/text.texi @ 38177:c6545dffc123

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