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