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