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