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