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