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