0001: @c -*- coding: utf-8 -*-
0002: @c This is part of the Emacs manual.
0003: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software
0004: @c Foundation, Inc.
0005: @c See file emacs.texi for copying conditions.
0006: @node Text
0007: @chapter Commands for Human Languages
0008: @cindex text
0009: @cindex manipulating text
0010: 
0011:   This chapter describes Emacs commands that act on @dfn{text}, by
0012: which we mean sequences of characters in a human language (as opposed
0013: to, say, a computer programming language).  These commands act in ways
0014: that take into account the syntactic and stylistic conventions of
0015: human languages: conventions involving words, sentences, paragraphs,
0016: and capital letters.  There are also commands for @dfn{filling}, which
0017: means rearranging the lines of a paragraph to be approximately equal
0018: in length.  These commands, while intended primarily for editing text,
0019: are also often useful for editing programs.
0020: 
0021:   Emacs has several major modes for editing human-language text.  If
0022: the file contains ordinary text, use Text mode, which customizes Emacs
0023: in small ways for the syntactic conventions of text.  Outline mode
0024: provides special commands for operating on text with an outline
0025: structure.  @xref{Outline Mode}.
0026: 
0027:   Org mode extends Outline mode and turns Emacs into a full-fledged
0028: organizer: you can manage TODO lists, store notes and publish them in
0029: many formats.
0030: @ifinfo
0031: @xref{Top, The Org Manual,,org, The Org Manual}.
0032: @end ifinfo
0033: @ifnotinfo
0034: See the Org Info manual, which is distributed with Emacs.
0035: @end ifnotinfo
0036: 
0037:   Emacs has other major modes for text which contains embedded
0038: commands, such as @TeX{} and @LaTeX{} (@pxref{TeX Mode}); HTML and
0039: SGML (@pxref{HTML Mode}); XML
0040: @ifinfo
0041: (@pxref{Top,The nXML Mode Manual,,nxml-mode, nXML Mode});
0042: @end ifinfo
0043: @ifnotinfo
0044: (see the nXML mode Info manual, which is distributed with Emacs);
0045: @end ifnotinfo
0046: and Groff and Nroff (@pxref{Nroff Mode}).
0047: 
0048: @cindex ASCII art
0049:   If you need to edit ASCII art pictures made out of text characters,
0050: use Picture mode, a special major mode for editing such pictures.
0051: @iftex
0052: @xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}.
0053: @end iftex
0054: @ifnottex
0055: @xref{Picture Mode}.
0056: @end ifnottex
0057: 
0058: @ifinfo
0059: @cindex skeletons
0060: @cindex templates
0061: @cindex autotyping
0062: @cindex automatic typing
0063:   The automatic typing features may be useful when writing text.
0064: @inforef{Top,The Autotype Manual,autotype}.
0065: @end ifinfo
0066: 
0067: @menu
0068: * Words::               Moving over and killing words.
0069: * Sentences::           Moving over and killing sentences.
0070: * Paragraphs::          Moving over paragraphs.
0071: * Pages::               Moving over pages.
0072: * Quotation Marks::     Inserting quotation marks.
0073: * Filling::             Filling or justifying text.
0074: * Case::                Changing the case of text.
0075: * Text Mode::           The major modes for editing text files.
0076: * Outline Mode::        Editing outlines.
0077: * Org Mode::            The Emacs organizer.
0078: * TeX Mode::            Editing TeX and LaTeX files.
0079: * HTML Mode::           Editing HTML and SGML files.
0080: * Nroff Mode::          Editing input to the nroff formatter.
0081: * Enriched Text::       Editing text enriched with fonts, colors, etc.
0082: * Text Based Tables::   Commands for editing text-based tables.
0083: * Two-Column::          Splitting text columns into separate windows.
0084: @end menu
0085: 
0086: @node Words
0087: @section Words
0088: @cindex words
0089: @cindex Meta commands and words
0090: 
0091:   Emacs defines several commands for moving over or operating on
0092: words:
0093: 
0094: @table @kbd
0095: @item M-f
0096: Move forward over a word (@code{forward-word}).
0097: @item M-b
0098: Move backward over a word (@code{backward-word}).
0099: @item M-d
0100: Kill up to the end of a word (@code{kill-word}).
0101: @item M-@key{DEL}
0102: Kill back to the beginning of a word (@code{backward-kill-word}).
0103: @item M-@@
0104: Set mark at the end of the next word (@code{mark-word}).
0105: @item M-t
0106: Transpose two words or drag a word across others
0107: (@code{transpose-words}).
0108: @end table
0109: 
0110:   Notice how these keys form a series that parallels the character-based
0111: @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}.  @kbd{M-@@} is
0112: cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
0113: 
0114: @kindex M-f
0115: @kindex M-b
0116: @findex forward-word
0117: @findex backward-word
0118:   The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b}
0119: (@code{backward-word}) move forward and backward over words.  These
0120: @key{Meta}-based key sequences are analogous to the key sequences
0121: @kbd{C-f} and @kbd{C-b}, which move over single characters.  The
0122: analogy extends to numeric arguments, which serve as repeat counts.
0123: @kbd{M-f} with a negative argument moves backward, and @kbd{M-b} with
0124: a negative argument moves forward.  Forward motion stops right after
0125: the last letter of the word, while backward motion stops right before
0126: the first letter.
0127: 
0128: @kindex M-d
0129: @findex kill-word
0130:   @kbd{M-d} (@code{kill-word}) kills the word after point.  To be
0131: precise, it kills everything from point to the place @kbd{M-f} would
0132: move to.  Thus, if point is in the middle of a word, @kbd{M-d} kills
0133: just the part after point.  If some punctuation comes between point
0134: and the next word, it is killed along with the word.  (If you wish to
0135: kill only the next word but not the punctuation before it, simply do
0136: @kbd{M-f} to get the end, and kill the word backwards with
0137: @kbd{M-@key{DEL}}.)  @kbd{M-d} takes arguments just like @kbd{M-f}.
0138: 
0139: @findex backward-kill-word
0140: @kindex M-DEL
0141:   @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
0142: point.  It kills everything from point back to where @kbd{M-b} would
0143: move to.  For instance, if point is after the space in @w{@samp{FOO,
0144: BAR}}, it kills @w{@samp{FOO, }}.  If you wish to kill just
0145: @samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead
0146: of @kbd{M-@key{DEL}}.
0147: 
0148: @c Don't index M-t and transpose-words here, they are indexed in
0149: @c fixit.texi, in the node "Transpose".
0150: @c @kindex M-t
0151: @c @findex transpose-words
0152:   @kbd{M-t} (@code{transpose-words}) exchanges the word before or
0153: containing point with the following word.  The delimiter characters between
0154: the words do not move.  For example, @w{@samp{FOO, BAR}} transposes into
0155: @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.  @xref{Transpose}, for
0156: more on transposition.
0157: 
0158: @kindex M-@@
0159:   To operate on words with an operation which acts on the region, use
0160: the command @kbd{M-@@} (@code{mark-word}).  This command sets the mark
0161: where @kbd{M-f} would move to.  @xref{Marking Objects}, for more
0162: information about this command.
0163: 
0164:   The word commands' understanding of word boundaries is controlled by
0165: the syntax table.  Any character can, for example, be declared to be a
0166: word delimiter.  @xref{Syntax Tables,, Syntax Tables, elisp, The Emacs
0167: Lisp Reference Manual}.
0168: 
0169:   In addition, see @ref{Position Info} for the @kbd{M-=}
0170: (@code{count-words-region}) and @kbd{M-x count-words} commands, which
0171: count and report the number of words in the region or buffer.
0172: 
0173: @node Sentences
0174: @section Sentences
0175: @cindex sentences
0176: @cindex manipulating sentences
0177: 
0178:   The Emacs commands for manipulating sentences and paragraphs are
0179: mostly on Meta keys, like the word-handling commands.
0180: 
0181: @table @kbd
0182: @item M-a
0183: Move back to the beginning of the sentence (@code{backward-sentence}).
0184: @item M-e
0185: Move forward to the end of the sentence (@code{forward-sentence}).
0186: @item M-k
0187: Kill forward to the end of the sentence (@code{kill-sentence}).
0188: @item C-x @key{DEL}
0189: Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
0190: @end table
0191: 
0192: @kindex M-a
0193: @kindex M-e
0194: @findex backward-sentence
0195: @findex forward-sentence
0196:   The commands @kbd{M-a} (@code{backward-sentence}) and @kbd{M-e}
0197: (@code{forward-sentence}) move to the beginning and end of the current
0198: sentence, respectively.  Their bindings were chosen to resemble
0199: @kbd{C-a} and @kbd{C-e}, which move to the beginning and end of a
0200: line.  Unlike them, @kbd{M-a} and @kbd{M-e} move over successive
0201: sentences if repeated.
0202: 
0203:   Moving backward over a sentence places point just before the first
0204: character of the sentence; moving forward places point right after the
0205: punctuation that ends the sentence.  Neither one moves over the
0206: whitespace at the sentence boundary.
0207: 
0208: @kindex M-k
0209: @findex kill-sentence
0210:   Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to
0211: go with them, @kbd{M-a} and @kbd{M-e} have a corresponding kill
0212: command: @kbd{M-k} (@code{kill-sentence}) kills from point to the end
0213: of the sentence.  With a positive numeric argument @var{n}, it kills
0214: the next @var{n} sentences; with a negative argument @minus{}@var{n},
0215: it kills back to the beginning of the @var{n}th preceding sentence.
0216: 
0217: @kindex C-x DEL
0218: @findex backward-kill-sentence
0219:   The @kbd{C-x @key{DEL}} (@code{backward-kill-sentence}) kills back
0220: to the beginning of a sentence.
0221: 
0222:   The sentence commands assume that you follow the American typist's
0223: convention of putting two spaces at the end of a sentence.  That is, a
0224: sentence ends wherever there is a @samp{.}, @samp{?} or @samp{!}
0225: followed by the end of a line or two spaces, with any number of
0226: @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in
0227: between.  A sentence also begins or ends wherever a paragraph begins
0228: or ends.  It is useful to follow this convention, because it allows
0229: the Emacs sentence commands to distinguish between periods that end a
0230: sentence and periods that indicate abbreviations.
0231: 
0232: @vindex sentence-end-double-space
0233:   If you want to use just one space between sentences, you can set the
0234: variable @code{sentence-end-double-space} to @code{nil} to make the
0235: sentence commands stop for single spaces.  However, this has a
0236: drawback: there is no way to distinguish between periods that end
0237: sentences and those that indicate abbreviations.  For convenient and
0238: reliable editing, we therefore recommend you follow the two-space
0239: convention.  The variable @code{sentence-end-double-space} also
0240: affects filling (@pxref{Fill Commands}).
0241: 
0242: @vindex sentence-end
0243:   The variable @code{sentence-end} controls how to recognize the end
0244: of a sentence.  If non-@code{nil}, its value should be a regular
0245: expression, which is used to match the last few characters of a
0246: sentence, together with the whitespace following the sentence
0247: (@pxref{Regexps}).  If the value is @code{nil}, the default, then
0248: Emacs computes sentence ends according to various criteria such as the
0249: value of @code{sentence-end-double-space}.
0250: 
0251: @vindex sentence-end-without-period
0252:   Some languages, such as Thai, do not use periods to indicate the end
0253: of a sentence.  Set the variable @code{sentence-end-without-period} to
0254: @code{t} in such cases.
0255: 
0256: @node Paragraphs
0257: @section Paragraphs
0258: @cindex paragraphs
0259: @cindex manipulating paragraphs
0260: 
0261:   The Emacs commands for manipulating paragraphs are also on Meta keys.
0262: 
0263: @table @kbd
0264: @item M-@{
0265: Move back to previous paragraph beginning (@code{backward-paragraph}).
0266: @item M-@}
0267: Move forward to next paragraph end (@code{forward-paragraph}).
0268: @item M-h
0269: Put point and mark around this or next paragraph (@code{mark-paragraph}).
0270: @end table
0271: 
0272: @kindex M-@{
0273: @kindex M-@}
0274: @findex backward-paragraph
0275: @findex forward-paragraph
0276:   @kbd{M-@{} (@code{backward-paragraph}) moves to the beginning of the
0277: current or previous paragraph, depending on where point is when the
0278: command is invoked (see below for the definition of a paragraph).
0279: @kbd{M-@}} (@code{forward-paragraph}) similarly moves to the end of
0280: the current or next paragraph.  If there is a blank line before the
0281: paragraph, @kbd{M-@{} moves to the blank line.
0282: 
0283: @kindex M-h
0284: @findex mark-paragraph
0285:   When you wish to operate on a paragraph, type @kbd{M-h}
0286: (@code{mark-paragraph}) to set the region around it.  For example,
0287: @kbd{M-h C-w} kills the paragraph around or after point.  @kbd{M-h}
0288: puts point at the beginning and mark at the end of the paragraph point
0289: was in.  If point is between paragraphs (in a run of blank lines, or
0290: at a boundary), @kbd{M-h} sets the region around the paragraph
0291: following point.  If there are blank lines preceding the first line of
0292: the paragraph, one of these blank lines is included in the region.  If
0293: the region is already active, the command sets the mark without
0294: changing point, and each subsequent @kbd{M-h} further advances the
0295: mark by one paragraph.
0296: 
0297:   The definition of a paragraph depends on the major mode.  In
0298: Fundamental mode, as well as Text mode and related modes, a paragraph
0299: is separated from neighboring paragraphs by one or more
0300: @dfn{blank lines}---lines that are either empty, or consist solely of
0301: space, tab and/or formfeed characters.  In programming language modes,
0302: paragraphs are usually defined in a similar way, so that you can use
0303: the paragraph commands even though there are no paragraphs as such in
0304: a program.
0305: 
0306:   Note that an indented line is @emph{not} itself a paragraph break in
0307: Text mode.  If you want indented lines to separate paragraphs, use
0308: Paragraph-Indent Text mode instead.  @xref{Text Mode}.
0309: 
0310:   If you set a fill prefix, then paragraphs are delimited by all lines
0311: which don't start with the fill prefix.  @xref{Filling}.
0312: 
0313: @vindex paragraph-start
0314: @vindex paragraph-separate
0315:   The precise definition of a paragraph boundary is controlled by the
0316: variables @code{paragraph-separate} and @code{paragraph-start}.  The
0317: value of @code{paragraph-start} is a regular expression that should
0318: match lines that either start or separate paragraphs
0319: (@pxref{Regexps}).  The value of @code{paragraph-separate} is another
0320: regular expression that should match lines that separate paragraphs
0321: without being part of any paragraph (for example, blank lines).  Lines
0322: that start a new paragraph and are contained in it must match only
0323: @code{paragraph-start}, not @code{paragraph-separate}.  For example,
0324: in Fundamental mode, @code{paragraph-start} is @w{@code{"\f\\|[
0325: \t]*$"}}, and @code{paragraph-separate} is @w{@code{"[ \t\f]*$"}}.
0326: 
0327:   Note that @code{paragraph-start} and @code{paragraph-separate} are
0328: matched against the text at the left margin, which is not necessarily
0329: the beginning of the line, so these regexps should not use @samp{^} as
0330: an anchor, to ensure that the paragraph functions will work equally
0331: within a region of text indented by a margin setting.
0332: 
0333: @node Pages
0334: @section Pages
0335: 
0336: @cindex pages
0337: @cindex formfeed character
0338:   Within some text files, text is divided into @dfn{pages} delimited
0339: by the @dfn{formfeed character} (@acronym{ASCII} code 12, also denoted
0340: as @samp{control-L}), which is displayed in Emacs as the escape
0341: sequence @samp{^L} (@pxref{Text Display}).  Traditionally, when such
0342: text files are printed to hardcopy, each formfeed character forces a
0343: page break.  Most Emacs commands treat it just like any other
0344: character, so you can insert it with @kbd{C-q C-l}, delete it with
0345: @key{DEL}, etc.  In addition, Emacs provides commands to move over
0346: pages and operate on them.
0347: 
0348: @table @kbd
0349: @item M-x what-page
0350: Display the page number of point, and the line number within that page.
0351: @item C-x [
0352: Move point to previous page boundary (@code{backward-page}).
0353: @item C-x ]
0354: Move point to next page boundary (@code{forward-page}).
0355: @item C-x C-p
0356: Put point and mark around this page (or another page) (@code{mark-page}).
0357: @item C-x l
0358: Count the lines in this page (@code{count-lines-page}).
0359: @end table
0360: 
0361: @findex what-page
0362:   @kbd{M-x what-page} counts pages from the beginning of the file, and
0363: counts lines within the page, showing both numbers in the echo area.
0364: 
0365: @kindex C-x [
0366: @kindex C-x ]
0367: @findex forward-page
0368: @findex backward-page
0369:   The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
0370: after the previous page delimiter.  If point is already right after a page
0371: delimiter, it skips that one and stops at the previous one.  A numeric
0372: argument serves as a repeat count.  The @kbd{C-x ]} (@code{forward-page})
0373: command moves forward past the next page delimiter.
0374: 
0375: @kindex C-x C-p
0376: @findex mark-page
0377:   The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
0378: beginning of the current page (after that page delimiter at the
0379: front), and the mark at the end of the page (after the page delimiter
0380: at the end).
0381: 
0382:   @kbd{C-x C-p C-w} is a handy way to kill a page to move it
0383: elsewhere.  If you move to another page delimiter with @kbd{C-x [} and
0384: @kbd{C-x ]}, then yank the killed page, all the pages will be properly
0385: delimited once again.  Making sure this works as expected is the
0386: reason @kbd{C-x C-p} includes only the following page delimiter in the
0387: region.
0388: 
0389:   A numeric argument to @kbd{C-x C-p} specifies which page to go to,
0390: relative to the current one.  Zero means the current page, one means
0391: the next page, and @minus{}1 means the previous one.
0392: 
0393: @kindex C-x l
0394: @findex count-lines-page
0395:   The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
0396: where to break a page in two.  It displays in the echo area the total number
0397: of lines in the current page, and then divides it up into those preceding
0398: the current line and those following, as in
0399: 
0400: @example
0401: Page has 96 (72+25) lines
0402: @end example
0403: 
0404: @noindent
0405:   Notice that the sum is off by one; this is correct if point is not at the
0406: beginning of a line.
0407: 
0408: @vindex page-delimiter
0409:   The variable @code{page-delimiter} controls where pages begin.  Its
0410: value is a regular expression that matches the beginning of a line
0411: that separates pages (@pxref{Regexps}).  The normal value of this
0412: variable is @code{"^\f"}, which matches a formfeed character at the
0413: beginning of a line.
0414: 
0415: @node Quotation Marks
0416: @section Quotation Marks
0417: @cindex Quotation marks
0418: @cindex Electric Quote mode
0419: @cindex mode, Electric Quote
0420: @cindex curly quotes
0421: @cindex curved quotes
0422: @cindex guillemets
0423: @findex electric-quote-mode
0424: @c The funny quoting below is to make the printed version look
0425: @c correct.  FIXME.
0426:   One common way to quote is the typewriter convention, which quotes
0427: using straight apostrophes @t{'like this'} or double-quotes @t{"like
0428: this"}.  Another common way is the curved quote convention, which uses
0429: left and right single or double quotation marks `@t{like this}' or
0430: ``@t{like this}''@footnote{
0431: The curved single quote characters are U+2018 LEFT SINGLE QUOTATION
0432: MARK and U+2018 RIGHT SINGLE QUOTATION MARK; the curved double quotes
0433: are U+201C LEFT DOUBLE QUOTATION MARK and U+201D RIGHT DOUBLE
0434: QUOTATION MARK.  On text terminals which cannot display these
0435: characters, the Info reader might show them as the typewriter ASCII
0436: quote characters.
0437: }.  In text files, typewriter quotes are simple and
0438: portable; curved quotes are less ambiguous and typically look nicer.
0439: 
0440: @vindex electric-quote-chars
0441:   Electric Quote mode makes it easier to type curved quotes.  As you
0442: type characters it optionally converts @t{`} to ‘, @t{'} to ',
0443: @t{``} to ``, and @t{''} to ''.  It's possible to change the
0444: default quotes listed above, by customizing the variable
0445: @code{electric-quote-chars}, a list of four characters, where the
0446: items correspond to the left single quote, the right single quote, the
0447: left double quote and the right double quote, respectively, whose
0448: default value is @code{'(?@r{`} ?@r{'} ?@r{``} ?@r{''})}.
0449: 
0450: @vindex electric-quote-paragraph
0451: @vindex electric-quote-comment
0452: @vindex electric-quote-string
0453:   You can customize the behavior of Electric Quote mode by customizing
0454: variables that control where it is active.  It is active in text
0455: paragraphs if @code{electric-quote-paragraph} is non-@code{nil}, in
0456: programming-language comments if @code{electric-quote-comment} is
0457: non-@code{nil}, and in programming-language strings if
0458: @code{electric-quote-string} is non-@code{nil}.  The default is
0459: @code{nil} for @code{electric-quote-string} and @code{t} for the other
0460: variables.
0461: 
0462: @vindex electric-quote-replace-double
0463:   You can also set the option @code{electric-quote-replace-double} to
0464: a non-@code{nil} value.  Then, typing @t{"} insert an appropriate
0465: curved double quote depending on context: @t{“} at the beginning of
0466: the buffer or after a line break, whitespace, opening parenthesis, or
0467: quote character, and @t{”} otherwise.
0468: 
0469:   Electric Quote mode is disabled by default.  To toggle it in a
0470: single buffer, use @kbd{M-x electric-quote-local-mode}.
0471: To toggle it globally, type
0472: @kbd{M-x electric-quote-mode}.  To suppress it for a single use,
0473: type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}.  To
0474: insert a curved quote even when Electric Quote is disabled or
0475: inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for
0476: @t{’}, @kbd{C-x 8 @{} for ``, and @kbd{C-x 8 @}} for ''.
0477: @xref{Inserting Text}.  Note that the value of
0478: @code{electric-quote-chars} does not affect these keybindings, they
0479: are not keybindings of @code{electric-quote-mode} but bound in
0480: @code{global-map}.
0481: 
0482: @node Filling
0483: @section Filling Text
0484: @cindex filling text
0485: 
0486:   @dfn{Filling} text means breaking it up into lines that fit a
0487: specified width.  Emacs does filling in two ways.  In Auto Fill mode,
0488: inserting text with self-inserting characters also automatically fills
0489: it.  There are also explicit fill commands that you can use when editing
0490: text.
0491: 
0492: @menu
0493: * Auto Fill::      Auto Fill mode breaks long lines automatically.
0494: * Fill Commands::  Commands to refill paragraphs and center lines.
0495: * Fill Prefix::    Filling paragraphs that are indented or in a comment, etc.
0496: * Adaptive Fill::  How Emacs can determine the fill prefix automatically.
0497: @end menu
0498: 
0499: @node Auto Fill
0500: @subsection Auto Fill Mode
0501: @cindex Auto Fill mode
0502: @cindex mode, Auto Fill
0503: 
0504:   @dfn{Auto Fill} mode is a buffer-local minor mode (@pxref{Minor
0505: Modes}) in which lines are broken automatically at spaces when the
0506: line becomes too wide.
0507: 
0508: @table @kbd
0509: @item M-x auto-fill-mode
0510: Enable or disable Auto Fill mode.
0511: @item @key{SPC}
0512: @itemx @key{RET}
0513: In Auto Fill mode, break lines when appropriate.
0514: @end table
0515: 
0516: @findex auto-fill-mode
0517:   The mode command @kbd{M-x auto-fill-mode} toggles Auto Fill mode in
0518: the current buffer.  Like any other minor mode, with a positive
0519: numeric argument, it enables Auto Fill mode, and with a negative
0520: argument it disables it.  To enable Auto Fill mode automatically in
0521: certain major modes, add @code{auto-fill-mode} to the mode hooks
0522: (@pxref{Major Modes}).  When Auto Fill mode is enabled, the mode
0523: indicator @samp{Fill} appears in the mode line (@pxref{Mode Line}).
0524: 
0525:   Auto Fill mode breaks lines automatically at spaces whenever they
0526: get longer than the desired width.  This line breaking occurs only
0527: when you type @key{SPC} or @key{RET}.  If you wish to insert a space
0528: or newline without permitting line-breaking, type @kbd{C-q @key{SPC}}
0529: or @kbd{C-q C-j} respectively.  Also, @kbd{C-o} inserts a newline
0530: without line breaking.
0531: 
0532:   When Auto Fill mode breaks a line, it tries to obey the
0533: @dfn{adaptive fill prefix}: if a fill prefix can be deduced from the
0534: first and/or second line of the current paragraph, it is inserted into
0535: the new line (@pxref{Adaptive Fill}).  Otherwise the new line is
0536: indented, as though you had typed @key{TAB} on it
0537: (@pxref{Indentation}).  In a programming language mode, if a line is
0538: broken in the middle of a comment, the comment is split by inserting
0539: new comment delimiters as appropriate.
0540: 
0541:   Auto Fill mode does not refill entire paragraphs; it breaks lines
0542: but does not merge lines.  Therefore, editing in the middle of a
0543: paragraph can result in a paragraph that is not correctly filled.  To
0544: fill it, call the explicit fill commands
0545: @iftex
0546: described in the next section.
0547: @end iftex
0548: @ifnottex
0549: (@pxref{Fill Commands}).
0550: @end ifnottex
0551: 
0552: @node Fill Commands
0553: @subsection Explicit Fill Commands
0554: 
0555: @table @kbd
0556: @item M-q
0557: Fill current paragraph (@code{fill-paragraph}).
0558: @item C-x f
0559: Set the fill column (@code{set-fill-column}).
0560: @item M-x fill-region
0561: Fill each paragraph in the region (@code{fill-region}).
0562: @item M-x fill-region-as-paragraph
0563: Fill the region, considering it as one paragraph.
0564: @item M-o M-s
0565: Center a line.
0566: @end table
0567: 
0568: @kindex M-q
0569: @findex fill-paragraph
0570:   The command @kbd{M-q} (@code{fill-paragraph}) @dfn{fills} the
0571: current paragraph.  It redistributes the line breaks within the
0572: paragraph, and deletes any excess space and tab characters occurring
0573: within the paragraph, in such a way that the lines end up fitting
0574: within a certain maximum width.
0575: 
0576: @findex fill-region
0577:   Normally, @kbd{M-q} acts on the paragraph where point is, but if
0578: point is between paragraphs, it acts on the paragraph after point.  If
0579: the region is active, it acts instead on the text in the region.  You
0580: can also call @kbd{M-x fill-region} to specifically fill the text in
0581: the region.
0582: 
0583: @findex fill-region-as-paragraph
0584:   @kbd{M-q} and @code{fill-region} use the usual Emacs criteria for
0585: finding paragraph boundaries (@pxref{Paragraphs}).  For more control,
0586: you can use @kbd{M-x fill-region-as-paragraph}, which refills
0587: everything between point and mark as a single paragraph.  This command
0588: deletes any blank lines within the region, so separate blocks of text
0589: end up combined into one block.
0590: 
0591: @cindex justification
0592:   A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text
0593: as well as filling it.  This means that extra spaces are inserted to
0594: make the right margin line up exactly at the fill column.  To remove
0595: the extra spaces, use @kbd{M-q} with no argument.  (Likewise for
0596: @code{fill-region}.)
0597: 
0598: @vindex fill-column
0599: @kindex C-x f
0600: @findex set-fill-column
0601:   The maximum line width for filling is specified by the buffer-local
0602: variable @code{fill-column}.  The default value (@pxref{Locals}) is
0603: 70.  The easiest way to set @code{fill-column} in the current buffer
0604: is to use the command @kbd{C-x f} (@code{set-fill-column}).  With a
0605: numeric argument, it uses that as the new fill column.  With just
0606: @kbd{C-u} as argument, it sets @code{fill-column} to the current
0607: horizontal position of point.
0608: 
0609: @kindex M-o M-s @r{(Text mode)}
0610: @cindex centering
0611: @findex center-line
0612:   The command @kbd{M-o M-s} (@code{center-line}) centers the current line
0613: within the current fill column.  With an argument @var{n}, it centers
0614: @var{n} lines individually and moves past them.  This binding is
0615: made by Text mode and is available only in that and related modes
0616: (@pxref{Text Mode}).
0617: 
0618:   By default, Emacs considers a period followed by two spaces or by a
0619: newline as the end of a sentence; a period followed by just one space
0620: indicates an abbreviation, not the end of a sentence.  Accordingly,
0621: the fill commands will not break a line after a period followed by
0622: just one space.  If you set the variable
0623: @code{sentence-end-double-space} to @code{nil}, the fill commands will
0624: break a line after a period followed by one space, and put just one
0625: space after each period.  @xref{Sentences}, for other effects and
0626: possible drawbacks of this.
0627: 
0628: @vindex colon-double-space
0629:   If the variable @code{colon-double-space} is non-@code{nil}, the
0630: fill commands put two spaces after a colon.
0631: 
0632: @vindex fill-nobreak-predicate
0633:   To specify additional conditions where line-breaking is not allowed,
0634: customize the abnormal hook variable @code{fill-nobreak-predicate}
0635: (@pxref{Hooks}).  Each function in this hook is called with no
0636: arguments, with point positioned where Emacs is considering breaking a
0637: line.  If a function returns a non-@code{nil} value, Emacs will not
0638: break the line there.  Functions you can use there include:
0639: @code{fill-single-word-nobreak-p} (don't break after the first word of
0640: a sentence or before the last); @code{fill-single-char-nobreak-p}
0641: (don't break after a one-letter word preceded by a whitespace
0642: character); @code{fill-french-nobreak-p} (don't break after @samp{(}
0643: or before @samp{)}, @samp{:} or @samp{?}); and
0644: @code{fill-polish-nobreak-p} (don't break after a one letter word,
0645: even if preceded by a non-whitespace character).
0646: 
0647: @node Fill Prefix
0648: @subsection The Fill Prefix
0649: 
0650: @cindex fill prefix
0651:   The @dfn{fill prefix} feature allows paragraphs to be filled so that
0652: each line starts with a special string of characters (such as a
0653: sequence of spaces, giving an indented paragraph).  You can specify a
0654: fill prefix explicitly; otherwise, Emacs tries to deduce one
0655: automatically (@pxref{Adaptive Fill}).
0656: 
0657: @table @kbd
0658: @item C-x .
0659: Set the fill prefix (@code{set-fill-prefix}).
0660: @item M-q
0661: Fill a paragraph using current fill prefix (@code{fill-paragraph}).
0662: @item M-x fill-individual-paragraphs
0663: Fill the region, considering each change of indentation as starting a
0664: new paragraph.
0665: @item M-x fill-nonuniform-paragraphs
0666: Fill the region, considering only paragraph-separator lines as starting
0667: a new paragraph.
0668: @end table
0669: 
0670: @kindex C-x .
0671: @findex set-fill-prefix
0672:   To specify a fill prefix for the current buffer, move to a line that
0673: starts with the desired prefix, put point at the end of the prefix,
0674: and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}).  (That's a period
0675: after the @kbd{C-x}.)  To turn off the fill prefix, specify an empty
0676: prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line.
0677: 
0678:   When a fill prefix is in effect, the fill commands remove the fill
0679: prefix from each line of the paragraph before filling, and insert it
0680: on each line after filling.  (The beginning of the first line of the
0681: paragraph is left unchanged, since often that is intentionally
0682: different.)  Auto Fill mode also inserts the fill prefix automatically
0683: when it makes a new line (@pxref{Auto Fill}).  The @kbd{C-o} command
0684: inserts the fill prefix on new lines it creates, when you use it at
0685: the beginning of a line (@pxref{Blank Lines}).  Conversely, the
0686: command @kbd{M-^} deletes the prefix (if it occurs) after the newline
0687: that it deletes (@pxref{Indentation}).
0688: 
0689:   For example, if @code{fill-column} is 40 and you set the fill prefix
0690: to @samp{;; }, then @kbd{M-q} in the following text
0691: 
0692: @example
0693: ;; This is an
0694: ;; example of a paragraph
0695: ;; inside a Lisp-style comment.
0696: @end example
0697: 
0698: @noindent
0699: produces this:
0700: 
0701: @example
0702: ;; This is an example of a paragraph
0703: ;; inside a Lisp-style comment.
0704: @end example
0705: 
0706:   Lines that do not start with the fill prefix are considered to start
0707: paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
0708: good results for paragraphs with hanging indentation (every line
0709: indented except the first one).  Lines which are blank or indented once
0710: the prefix is removed also separate or start paragraphs; this is what
0711: you want if you are writing multi-paragraph comments with a comment
0712: delimiter on each line.
0713: 
0714: @findex fill-individual-paragraphs
0715:   You can use @kbd{M-x fill-individual-paragraphs} to set the fill
0716: prefix for each paragraph automatically.  This command divides the
0717: region into paragraphs, treating every change in the amount of
0718: indentation as the start of a new paragraph, and fills each of these
0719: paragraphs.  Thus, all the lines in one paragraph have the same
0720: amount of indentation.  That indentation serves as the fill prefix for
0721: that paragraph.
0722: 
0723: @findex fill-nonuniform-paragraphs
0724:   @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
0725: the region into paragraphs in a different way.  It considers only
0726: paragraph-separating lines (as defined by @code{paragraph-separate}) as
0727: starting a new paragraph.  Since this means that the lines of one
0728: paragraph may have different amounts of indentation, the fill prefix
0729: used is the smallest amount of indentation of any of the lines of the
0730: paragraph.  This gives good results with styles that indent a paragraph's
0731: first line more or less that the rest of the paragraph.
0732: 
0733: @vindex fill-prefix
0734:   The fill prefix is stored in the variable @code{fill-prefix}.  Its value
0735: is a string, or @code{nil} when there is no fill prefix.  This is a
0736: per-buffer variable; altering the variable affects only the current buffer,
0737: but there is a default value which you can change as well.  @xref{Locals}.
0738: 
0739:   The @code{indentation} text property provides another way to control
0740: the amount of indentation paragraphs receive.  @xref{Enriched
0741: Indentation}.
0742: 
0743: @node Adaptive Fill
0744: @subsection Adaptive Filling
0745: 
0746: @cindex adaptive filling
0747:   The fill commands can deduce the proper fill prefix for a paragraph
0748: automatically in certain cases: either whitespace or certain punctuation
0749: characters at the beginning of a line are propagated to all lines of the
0750: paragraph.
0751: 
0752:   If the paragraph has two or more lines, the fill prefix is taken from
0753: the paragraph's second line, but only if it appears on the first line as
0754: well.
0755: 
0756:   If a paragraph has just one line, fill commands @emph{may} take a
0757: prefix from that line.  The decision is complicated because there are
0758: three reasonable things to do in such a case:
0759: 
0760: @itemize @bullet
0761: @item
0762: Use the first line's prefix on all the lines of the paragraph.
0763: 
0764: @item
0765: Indent subsequent lines with whitespace, so that they line up under the
0766: text that follows the prefix on the first line, but don't actually copy
0767: the prefix from the first line.
0768: 
0769: @item
0770: Don't do anything special with the second and following lines.
0771: @end itemize
0772: 
0773:   All three of these styles of formatting are commonly used.  So the
0774: fill commands try to determine what you would like, based on the prefix
0775: that appears and on the major mode.  Here is how.
0776: 
0777: @vindex adaptive-fill-first-line-regexp
0778:   If the prefix found on the first line matches
0779: @code{adaptive-fill-first-line-regexp}, or if it appears to be a
0780: comment-starting sequence (this depends on the major mode), then the
0781: prefix found is used for filling the paragraph, provided it would not
0782: act as a paragraph starter on subsequent lines.
0783: 
0784:   Otherwise, the prefix found is converted to an equivalent number of
0785: spaces, and those spaces are used as the fill prefix for the rest of the
0786: lines, provided they would not act as a paragraph starter on subsequent
0787: lines.
0788: 
0789:   In Text mode, and other modes where only blank lines and page
0790: delimiters separate paragraphs, the prefix chosen by adaptive filling
0791: never acts as a paragraph starter, so it can always be used for filling.
0792: 
0793: @vindex adaptive-fill-mode
0794: @vindex adaptive-fill-regexp
0795:   The variable @code{adaptive-fill-regexp} determines what kinds of line
0796: beginnings can serve as a fill prefix: any characters at the start of
0797: the line that match this regular expression are used.  If you set the
0798: variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
0799: never chosen automatically.
0800: 
0801: @vindex adaptive-fill-function
0802:   You can specify more complex ways of choosing a fill prefix
0803: automatically by setting the variable @code{adaptive-fill-function} to a
0804: function.  This function is called with point after the left margin of a
0805: line, and it should return the appropriate fill prefix based on that
0806: line.  If it returns @code{nil}, @code{adaptive-fill-regexp} gets
0807: a chance to find a prefix.
0808: 
0809: @node Case
0810: @section Case Conversion Commands
0811: @cindex case conversion
0812: 
0813:   Emacs has commands for converting either a single word or any arbitrary
0814: range of text to upper case or to lower case.
0815: 
0816: @table @kbd
0817: @item M-l
0818: Convert following word to lower case (@code{downcase-word}).
0819: @item M-u
0820: Convert following word to upper case (@code{upcase-word}).
0821: @item M-c
0822: Capitalize the following word (@code{capitalize-word}).
0823: @item C-x C-l
0824: Convert region to lower case (@code{downcase-region}).
0825: @item C-x C-u
0826: Convert region to upper case (@code{upcase-region}).
0827: @end table
0828: 
0829: @kindex M-l
0830: @kindex M-u
0831: @kindex M-c
0832: @cindex words, case conversion
0833: @cindex converting text to upper or lower case
0834: @cindex capitalizing words
0835: @findex downcase-word
0836: @findex upcase-word
0837: @findex capitalize-word
0838:   @kbd{M-l} (@code{downcase-word}) converts the word after point to
0839: lower case, moving past it.  Thus, repeating @kbd{M-l} converts
0840: successive words.  @kbd{M-u} (@code{upcase-word}) converts to all
0841: capitals instead, while @kbd{M-c} (@code{capitalize-word}) puts the
0842: first letter of the word into upper case and the rest into lower case.
0843: All these commands convert several words at once if given an argument.
0844: They are especially convenient for converting a large amount of text
0845: from all upper case to mixed case, because you can move through the
0846: text using @kbd{M-l}, @kbd{M-u} or @kbd{M-c} on each word as
0847: appropriate, occasionally using @kbd{M-f} instead to skip a word.
0848: 
0849:   When given a negative argument, the word case conversion commands apply
0850: to the appropriate number of words before point, but do not move point.
0851: This is convenient when you have just typed a word in the wrong case: you
0852: can give the case conversion command and continue typing.
0853: 
0854:   If a word case conversion command is given in the middle of a word,
0855: it applies only to the part of the word which follows point.  (This is
0856: comparable to what @kbd{M-d} (@code{kill-word}) does.)  With a
0857: negative argument, case conversion applies only to the part of the
0858: word before point.
0859: 
0860: @kindex C-x C-l
0861: @kindex C-x C-u
0862: @findex downcase-region
0863: @findex upcase-region
0864:   The other case conversion commands are @kbd{C-x C-u}
0865: (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
0866: convert everything between point and mark to the specified case.  Point and
0867: mark do not move.
0868: 
0869:   The region case conversion commands @code{upcase-region} and
0870: @code{downcase-region} are normally disabled.  This means that they ask
0871: for confirmation if you try to use them.  When you confirm, you may
0872: enable the command, which means it will not ask for confirmation again.
0873: @xref{Disabling}.
0874: 
0875: @node Text Mode
0876: @section Text Mode
0877: @cindex Text mode
0878: @cindex mode, Text
0879: @findex text-mode
0880: 
0881:   Text mode is a major mode for editing files of text in a human
0882: language.  Files which have names ending in the extension @file{.txt}
0883: are usually opened in Text mode (@pxref{Choosing Modes}).  To
0884: explicitly switch to Text mode, type @kbd{M-x text-mode}.
0885: 
0886:   In Text mode, only blank lines and page delimiters separate
0887: paragraphs.  As a result, paragraphs can be indented, and adaptive
0888: filling determines what indentation to use when filling a paragraph.
0889: @xref{Adaptive Fill}.
0890: 
0891: @kindex TAB @r{(Text mode)}
0892:   In Text mode, the @key{TAB} (@code{indent-for-tab-command}) command
0893: usually inserts whitespace up to the next tab stop, instead of
0894: indenting the current line.  @xref{Indentation}, for details.
0895: 
0896:   Text mode turns off the features concerned with comments except when
0897: you explicitly invoke them.  It changes the syntax table so that
0898: apostrophes are considered part of words (e.g., @samp{don't} is
0899: considered one word).  However, if a word starts with an apostrophe,
0900: it is treated as a prefix for the purposes of capitalization
0901: (e.g., @kbd{M-c} converts @samp{'hello'} into @samp{'Hello'}, as
0902: expected).
0903: 
0904: @cindex Paragraph-Indent Text mode
0905: @cindex mode, Paragraph-Indent Text
0906: @findex paragraph-indent-text-mode
0907: @findex paragraph-indent-minor-mode
0908:   If you indent the first lines of paragraphs, then you should use
0909: Paragraph-Indent Text mode (@kbd{M-x paragraph-indent-text-mode})
0910: rather than Text mode.  In that mode, you do not need to have blank
0911: lines between paragraphs, because the first-line indentation is
0912: sufficient to start a paragraph; however paragraphs in which every
0913: line is indented are not supported.  Use @kbd{M-x
0914: paragraph-indent-minor-mode} to enable an equivalent minor mode for
0915: situations where you shouldn't change the major mode---in mail
0916: composition, for instance.
0917: 
0918: @kindex M-TAB @r{(Text mode)}
0919:   Text mode binds @kbd{M-@key{TAB}} to @code{ispell-complete-word}.
0920: This command performs completion of the partial word in the buffer
0921: before point, using the spelling dictionary as the space of possible
0922: words.  @xref{Spelling}.  If your window manager defines
0923: @kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC}
0924: @key{TAB}} or @kbd{C-M-i} instead.
0925: 
0926: @vindex text-mode-hook
0927:   Entering Text mode runs the mode hook @code{text-mode-hook}
0928: (@pxref{Major Modes}).
0929: 
0930:   The following sections describe several major modes that are
0931: @dfn{derived} from Text mode.  These derivatives share most of the
0932: features of Text mode described above.  In particular, derivatives of
0933: Text mode run @code{text-mode-hook} prior to running their own mode
0934: hooks.
0935: 
0936: @node Outline Mode
0937: @section Outline Mode
0938: @cindex Outline mode
0939: @cindex mode, Outline
0940: @cindex invisible lines
0941: 
0942: @findex outline-mode
0943: @findex outline-minor-mode
0944: @vindex outline-minor-mode-prefix
0945: @vindex outline-mode-hook
0946:   Outline mode is a major mode derived from Text mode, which is
0947: specialized for editing outlines.  It provides commands to navigate
0948: between entries in the outline structure, and commands to make parts
0949: of a buffer temporarily invisible, so that the outline structure may
0950: be more easily viewed.  Type @kbd{M-x outline-mode} to switch to
0951: Outline mode.  Entering Outline mode runs the hook
0952: @code{text-mode-hook} followed by the hook @code{outline-mode-hook}
0953: (@pxref{Hooks}).
0954: 
0955:   When you use an Outline mode command to make a line invisible
0956: (@pxref{Outline Visibility}), the line disappears from the screen.  An
0957: ellipsis (three periods in a row) is displayed at the end of the
0958: previous visible line, to indicate the hidden text.  Multiple
0959: consecutive invisible lines produce just one ellipsis.
0960: 
0961:   Editing commands that operate on lines, such as @kbd{C-n} and
0962: @kbd{C-p}, treat the text of the invisible line as part of the
0963: previous visible line.  Killing the ellipsis at the end of a visible
0964: line really kills all the following invisible text associated with the
0965: ellipsis.
0966: 
0967:   Outline minor mode is a buffer-local minor mode which provides the
0968: same commands as the major mode, Outline mode, but can be used in
0969: conjunction with other major modes.  You can type @kbd{M-x
0970: outline-minor-mode} to toggle Outline minor mode in the current
0971: buffer, or use a file-local variable setting to enable it in a
0972: specific file (@pxref{File Variables}).
0973: 
0974: @kindex C-c @@ @r{(Outline minor mode)}
0975:   The major mode, Outline mode, provides special key bindings on the
0976: @kbd{C-c} prefix.  Outline minor mode provides similar bindings with
0977: @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
0978: major mode's special commands.  (The variable
0979: @code{outline-minor-mode-prefix} controls the prefix used.)
0980: 
0981: @menu
0982: * Outline Format::      What the text of an outline looks like.
0983: * Outline Motion::      Special commands for moving through outlines.
0984: * Outline Visibility::  Commands to control what is visible.
0985: * Outline Views::       Outlines and multiple views.
0986: * Foldout::             Folding means zooming in on outlines.
0987: @end menu
0988: 
0989: @node Outline Format
0990: @subsection Format of Outlines
0991: 
0992: @cindex heading lines (Outline mode)
0993: @cindex body lines (Outline mode)
0994:   Outline mode assumes that the lines in the buffer are of two types:
0995: @dfn{heading lines} and @dfn{body lines}.  A heading line represents a
0996: topic in the outline.  Heading lines start with one or more asterisk
0997: (@samp{*}) characters; the number of asterisks determines the depth of
0998: the heading in the outline structure.  Thus, a heading line with one
0999: @samp{*} is a major topic; all the heading lines with two @samp{*}s
1000: between it and the next one-@samp{*} heading are its subtopics; and so
1001: on.  Any line that is not a heading line is a body line.  Body lines
1002: belong with the preceding heading line.  Here is an example:
1003: 
1004: @example
1005: * Food
1006: This is the body,
1007: which says something about the topic of food.
1008: 
1009: ** Delicious Food
1010: This is the body of the second-level header.
1011: 
1012: ** Distasteful Food
1013: This could have
1014: a body too, with
1015: several lines.
1016: 
1017: *** Dormitory Food
1018: 
1019: * Shelter
1020: Another first-level topic with its header line.
1021: @end example
1022: 
1023:   A heading line together with all following body lines is called
1024: collectively an @dfn{entry}.  A heading line together with all following
1025: deeper heading lines and their body lines is called a @dfn{subtree}.
1026: 
1027: @vindex outline-regexp
1028:   You can customize the criterion for distinguishing heading lines by
1029: setting the variable @code{outline-regexp}.  (The recommended ways to
1030: do this are in a major mode function or with a file local variable.)
1031: Any line whose beginning has a match for this regexp is considered a
1032: heading line.  Matches that start within a line (not at the left
1033: margin) do not count.
1034: 
1035:   The length of the matching text determines the level of the heading;
1036: longer matches make a more deeply nested level.  Thus, for example, if
1037: a text formatter has commands @samp{@@chapter}, @samp{@@section} and
1038: @samp{@@subsection} to divide the document into chapters and sections,
1039: you could make those lines count as heading lines by setting
1040: @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}.  Note
1041: the trick: the two words @samp{chapter} and @samp{section} are equally
1042: long, but by defining the regexp to match only @samp{chap} we ensure
1043: that the length of the text matched on a chapter heading is shorter,
1044: so that Outline mode will know that sections are contained in
1045: chapters.  This works as long as no other command starts with
1046: @samp{@@chap}.
1047: 
1048: @vindex outline-level
1049:   You can explicitly specify a rule for calculating the level of a
1050: heading line by setting the variable @code{outline-level}.  The value
1051: of @code{outline-level} should be a function that takes no arguments
1052: and returns the level of the current heading.  The recommended ways to
1053: set this variable are in a major mode command or with a file local
1054: variable.
1055: 
1056: @node Outline Motion
1057: @subsection Outline Motion Commands
1058: 
1059:   Outline mode provides special motion commands that move backward and
1060: forward to heading lines.
1061: 
1062: @table @kbd
1063: @item C-c C-n
1064: @findex outline-next-visible-heading
1065: @kindex C-c C-n @r{(Outline mode)}
1066: Move point to the next visible heading line
1067: (@code{outline-next-visible-heading}).
1068: @item C-c C-p
1069: @findex outline-previous-visible-heading
1070: @kindex C-c C-p @r{(Outline mode)}
1071: Move point to the previous visible heading line
1072: (@code{outline-previous-visible-heading}).
1073: @item C-c C-f
1074: @findex outline-forward-same-level
1075: @kindex C-c C-f @r{(Outline mode)}
1076: Move point to the next visible heading line at the same level
1077: as the one point is on (@code{outline-forward-same-level}).
1078: @item C-c C-b
1079: @findex outline-backward-same-level
1080: @kindex C-c C-b @r{(Outline mode)}
1081: Move point to the previous visible heading line at the same level
1082: (@code{outline-backward-same-level}).
1083: @item C-c C-u
1084: @findex outline-up-heading
1085: @kindex C-c C-u @r{(Outline mode)}
1086: Move point up to a lower-level (more inclusive) visible heading line
1087: (@code{outline-up-heading}).
1088: @end table
1089: 
1090:   All of the above commands accept numeric arguments as repeat counts.
1091: For example, @kbd{C-c C-f}, when given an argument, moves forward that
1092: many visible heading lines on the same level, and @kbd{C-c C-u} with
1093: an argument moves out of that many nested levels.
1094: 
1095: @node Outline Visibility
1096: @subsection Outline Visibility Commands
1097: 
1098:   Outline mode provides several commands for temporarily hiding or
1099: revealing parts of the buffer, based on the outline structure.  These
1100: commands are not undoable; their effects are simply not recorded by
1101: the undo mechanism, so you can undo right past them (@pxref{Undo}).
1102: 
1103:   Many of these commands act on the current heading line.  If
1104: point is on a heading line, that is the current heading line; if point
1105: is on a body line, the current heading line is the nearest preceding
1106: header line.
1107: 
1108: @table @kbd
1109: @item C-c C-c
1110: Make the current heading line's body invisible
1111: (@code{outline-hide-entry}).
1112: @item C-c C-e
1113: Make the current heading line's body visible
1114: (@code{outline-show-entry}).
1115: @item C-c C-d
1116: Make everything under the current heading invisible, not including the
1117: heading itself (@code{outline-hide-subtree}).
1118: @item C-c C-s
1119: Make everything under the current heading visible, including body,
1120: subheadings, and their bodies (@code{outline-show-subtree}).
1121: @item C-c C-l
1122: Make the body of the current heading line, and of all its subheadings,
1123: invisible (@code{outline-hide-leaves}).
1124: @item C-c C-k
1125: Make all subheadings of the current heading line, at all levels,
1126: visible (@code{outline-show-branches}).
1127: @item C-c C-i
1128: Make immediate subheadings (one level down) of the current heading
1129: line visible (@code{outline-show-children}).
1130: @item C-c C-t
1131: Make all body lines in the buffer invisible
1132: (@code{outline-hide-body}).
1133: @item C-c C-a
1134: Make all lines in the buffer visible (@code{outline-show-all}).
1135: @item C-c C-q
1136: Hide everything except the top @var{n} levels of heading lines
1137: (@code{outline-hide-sublevels}).
1138: @item C-c C-o
1139: Hide everything except for the heading or body that point is in, plus
1140: the headings leading up from there to the top level of the outline
1141: (@code{outline-hide-other}).
1142: @end table
1143: 
1144: @findex outline-hide-entry
1145: @findex outline-show-entry
1146: @kindex C-c C-c @r{(Outline mode)}
1147: @kindex C-c C-e @r{(Outline mode)}
1148:   The simplest of these commands are @kbd{C-c C-c}
1149: (@code{outline-hide-entry}), which hides the body lines directly
1150: following the current heading line, and @kbd{C-c C-e}
1151: (@code{outline-show-entry}), which reveals them.  Subheadings and
1152: their bodies are not affected.
1153: 
1154: @findex outline-hide-subtree
1155: @findex outline-show-subtree
1156: @kindex C-c C-s @r{(Outline mode)}
1157: @kindex C-c C-d @r{(Outline mode)}
1158: @cindex subtree (Outline mode)
1159:   The commands @kbd{C-c C-d} (@code{outline-hide-subtree}) and
1160: @kbd{C-c C-s} (@code{outline-show-subtree}) are more powerful.  They
1161: apply to the current heading line's @dfn{subtree}: its body, all of
1162: its subheadings, both direct and indirect, and all of their bodies.
1163: 
1164: @findex outline-hide-leaves
1165: @findex outline-show-branches
1166: @findex outline-show-children
1167: @kindex C-c C-l @r{(Outline mode)}
1168: @kindex C-c C-k @r{(Outline mode)}
1169: @kindex C-c C-i @r{(Outline mode)}
1170:   The command @kbd{C-c C-l} (@code{outline-hide-leaves}) hides the
1171: body of the current heading line as well as all the bodies in its
1172: subtree; the subheadings themselves are left visible.  The command
1173: @kbd{C-c C-k} (@code{outline-show-branches}) reveals the subheadings,
1174: if they had previously been hidden (e.g., by @kbd{C-c C-d}).  The
1175: command @kbd{C-c C-i} (@code{outline-show-children}) is a weaker
1176: version of this; it reveals just the direct subheadings, i.e., those
1177: one level down.
1178: 
1179: @findex outline-hide-other
1180: @kindex C-c C-o @r{(Outline mode)}
1181:   The command @kbd{C-c C-o} (@code{outline-hide-other}) hides
1182: everything except the entry that point is in, plus its parents (the
1183: headers leading up from there to top level in the outline) and the top
1184: level headings.  It also reveals body lines preceding the first
1185: heading in the buffer.
1186: 
1187: @findex outline-hide-body
1188: @findex outline-show-all
1189: @kindex C-c C-t @r{(Outline mode)}
1190: @kindex C-c C-a @r{(Outline mode)}
1191: @findex hide-sublevels
1192: @kindex C-c C-q @r{(Outline mode)}
1193:   The remaining commands affect the whole buffer.  @kbd{C-c C-t}
1194: (@code{outline-hide-body}) makes all body lines invisible, so that you
1195: see just the outline structure (as a special exception, it will not
1196: hide lines at the top of the file, preceding the first header line,
1197: even though these are technically body lines).  @kbd{C-c C-a}
1198: (@code{outline-show-all}) makes all lines visible.  @kbd{C-c C-q}
1199: (@code{outline-hide-sublevels}) hides all but the top level headings
1200: at and above the level of the current heading line (defaulting to 1 if
1201: point is not on a heading); with a numeric argument @var{n}, it hides
1202: everything except the top @var{n} levels of heading lines.  Note that
1203: it completely reveals all the @var{n} top levels and the body lines
1204: before the first heading.
1205: 
1206: @anchor{Outline Search}
1207: @findex reveal-mode
1208: @vindex search-invisible
1209:   When incremental search finds text that is hidden by Outline mode,
1210: it makes that part of the buffer visible.  If you exit the search at
1211: that position, the text remains visible.  To toggle whether or not
1212: an active incremental search can match hidden text, type @kbd{M-s i}.
1213: To change the default for future searches, customize the option
1214: @code{search-invisible}.  (This option also affects how @code{query-replace}
1215: and related functions treat hidden text, @pxref{Query Replace}.)
1216: You can also automatically make text visible as you navigate in it by
1217: using Reveal mode (@kbd{M-x reveal-mode}), a buffer-local minor mode.
1218: 
1219: @node Outline Views
1220: @subsection Viewing One Outline in Multiple Views
1221: 
1222: @cindex multiple views of outline
1223: @cindex views of an outline
1224: @cindex outline with multiple views
1225: @cindex indirect buffers and outlines
1226:   You can display two views of a single outline at the same time, in
1227: different windows.  To do this, you must create an indirect buffer using
1228: @kbd{M-x make-indirect-buffer}.  The first argument of this command is
1229: the existing outline buffer name, and its second argument is the name to
1230: use for the new indirect buffer.  @xref{Indirect Buffers}.
1231: 
1232:   Once the indirect buffer exists, you can display it in a window in the
1233: normal fashion, with @kbd{C-x 4 b} or other Emacs commands.  The Outline
1234: mode commands to show and hide parts of the text operate on each buffer
1235: independently; as a result, each buffer can have its own view.  If you
1236: want more than two views on the same outline, create additional indirect
1237: buffers.
1238: 
1239: @node Foldout
1240: @subsection Folding Editing
1241: 
1242: @cindex folding editing
1243:   The Foldout package extends Outline mode and Outline minor mode with
1244: folding commands.  The idea of folding is that you zoom in on a
1245: nested portion of the outline, while hiding its relatives at higher
1246: levels.
1247: 
1248:   Consider an Outline mode buffer with all the text and subheadings under
1249: level-1 headings hidden.  To look at what is hidden under one of these
1250: headings, you could use @kbd{C-c C-e} (@kbd{M-x outline-show-entry})
1251: to expose the body, or @kbd{C-c C-i} to expose the child (level-2)
1252: headings.
1253: 
1254: @kindex C-c C-z
1255: @findex foldout-zoom-subtree
1256:   With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
1257: This exposes the body and child subheadings, and narrows the buffer so
1258: that only the @w{level-1} heading, the body and the level-2 headings are
1259: visible.  Now to look under one of the level-2 headings, position the
1260: cursor on it and use @kbd{C-c C-z} again.  This exposes the level-2 body
1261: and its level-3 child subheadings and narrows the buffer again.  Zooming
1262: in on successive subheadings can be done as much as you like.  A string
1263: in the mode line shows how deep you've gone.
1264: 
1265:   When zooming in on a heading, to see only the child subheadings specify
1266: a numeric argument: @kbd{C-u C-c C-z}.  The number of levels of children
1267: can be specified too (compare @kbd{M-x outline-show-children}), e.g.,
1268: @w{@kbd{M-2 C-c C-z}} exposes two levels of child subheadings.
1269: Alternatively, the body can be specified with a negative argument:
1270: @w{@kbd{M-- C-c C-z}}.  The whole subtree can be expanded, similarly to
1271: @kbd{C-c C-s} (@kbd{M-x outline-show-subtree}), by specifying a zero
1272: argument: @w{@kbd{M-0 C-c C-z}}.
1273: 
1274:   While you're zoomed in, you can still use Outline mode's exposure and
1275: hiding functions without disturbing Foldout.  Also, since the buffer is
1276: narrowed, global editing actions will only affect text under the
1277: zoomed-in heading.  This is useful for restricting changes to a
1278: particular chapter or section of your document.
1279: 
1280: @kindex C-c C-x
1281: @findex foldout-exit-fold
1282:   To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
1283: This hides all the text and subheadings under the top-level heading and
1284: returns you to the previous view of the buffer.  Specifying a numeric
1285: argument exits that many levels of folds.  Specifying a zero argument
1286: exits all folds.
1287: 
1288:   To cancel the narrowing of a fold without hiding the text and
1289: subheadings, specify a negative argument.  For example, @w{@kbd{M--2 C-c
1290: C-x}} exits two folds and leaves the text and subheadings exposed.
1291: 
1292:   Foldout mode also provides mouse commands for entering and exiting
1293: folds, and for showing and hiding text:
1294: 
1295: @table @asis
1296: @item @kbd{C-M-mouse-1} zooms in on the heading clicked on
1297: @itemize @w{}
1298: @item
1299: single click: expose body.
1300: @item
1301: double click: expose subheadings.
1302: @item
1303: triple click: expose body and subheadings.
1304: @item
1305: quad click: expose entire subtree.
1306: @end itemize
1307: @item @kbd{C-M-mouse-2} exposes text under the heading clicked on
1308: @itemize @w{}
1309: @item
1310: single click: expose body.
1311: @item
1312: double click: expose subheadings.
1313: @item
1314: triple click: expose body and subheadings.
1315: @item
1316: quad click: expose entire subtree.
1317: @end itemize
1318: @item @kbd{C-M-mouse-3} hides text under the heading clicked on or exits fold
1319: @itemize @w{}
1320: @item
1321: single click: hide subtree.
1322: @item
1323: double click: exit fold and hide text.
1324: @item
1325: triple click: exit fold without hiding text.
1326: @item
1327: quad click: exit all folds and hide text.
1328: @end itemize
1329: @end table
1330: 
1331: @c FIXME not marked as a user variable
1332: @vindex foldout-mouse-modifiers
1333:   You can specify different modifier keys (instead of
1334: @kbd{@key{Ctrl}-@key{Meta}-}) by setting @code{foldout-mouse-modifiers}; but if
1335: you have already loaded the @file{foldout.el} library, you must reload
1336: it in order for this to take effect.
1337: 
1338:   To use the Foldout package, you can type @kbd{M-x load-library
1339: @key{RET} foldout @key{RET}}; or you can arrange for to do that
1340: automatically by putting the following in your init file:
1341: 
1342: @example
1343: (with-eval-after-load "outline"
1344:   (require 'foldout))
1345: @end example
1346: 
1347: @node Org Mode
1348: @section Org Mode
1349: @cindex organizer
1350: @cindex planner
1351: @cindex Org mode
1352: @cindex mode, Org
1353: 
1354: @findex org-mode
1355:   Org mode is a variant of Outline mode for using Emacs as an
1356: organizer and/or authoring system.  Files with names ending in the
1357: extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}).
1358: To explicitly switch to Org mode, type @kbd{M-x org-mode}.
1359: 
1360:   In Org mode, as in Outline mode, each entry has a heading line that
1361: starts with one or more @samp{*} characters.  @xref{Outline Format}.
1362: In addition, any line that begins with the @samp{#} character is
1363: treated as a comment.
1364: 
1365: @kindex TAB @r{(Org Mode)}
1366: @findex org-cycle
1367:   Org mode provides commands for easily viewing and manipulating the
1368: outline structure.  The simplest of these commands is @key{TAB}
1369: (@code{org-cycle}).  If invoked on a heading line, it cycles through
1370: the different visibility states of the subtree: (i) showing only that
1371: heading line, (ii) showing only the heading line and the heading lines
1372: of its direct children, if any, and (iii) showing the entire subtree.
1373: If invoked in a body line, the global binding for @key{TAB} is
1374: executed.
1375: 
1376: @kindex S-TAB @r{(Org Mode)}
1377: @findex org-shifttab
1378:   Typing @kbd{S-@key{TAB}} (@code{org-shifttab}) anywhere in an Org mode
1379: buffer cycles the visibility of the entire outline structure, between
1380: (i) showing only top-level heading lines, (ii) showing all heading
1381: lines but no body lines, and (iii) showing everything.
1382: 
1383: @kindex M-UP @r{(Org Mode)}
1384: @kindex M-DOWN @r{(Org Mode)}
1385: @kindex M-LEFT @r{(Org Mode)}
1386: @kindex M-RIGHT @r{(Org Mode)}
1387: @findex org-metaup
1388: @findex org-metadown
1389: @findex org-metaleft
1390: @findex org-metaright
1391:   You can move an entire entry up or down in the buffer, including its
1392: body lines and subtree (if any), by typing @kbd{M-@key{UP}}
1393: (@code{org-metaup}) or @kbd{M-@key{DOWN}} (@code{org-metadown}) on the
1394: heading line.  Similarly, you can promote or demote a heading line
1395: with @kbd{M-@key{LEFT}} (@code{org-metaleft}) and @kbd{M-@key{RIGHT}}
1396: (@code{org-metaright}).  These commands execute their global bindings
1397: if invoked on a body line.
1398: 
1399:   The following subsections give basic instructions for using Org mode
1400: as an organizer and as an authoring system.  For details, @pxref{Top,
1401: The Org Mode Manual, Introduction, org, The Org Manual}.
1402: 
1403: @menu
1404: * Org Organizer::   Managing TODO lists and agendas.
1405: * Org Authoring::   Exporting Org buffers to various formats.
1406: @end menu
1407: 
1408: @node Org Organizer
1409: @subsection Org as an organizer
1410: @cindex TODO item
1411: @cindex Org agenda
1412: 
1413: @kindex C-c C-t @r{(Org Mode)}
1414: @findex org-todo
1415: @vindex org-todo-keywords
1416:   You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c
1417: C-t} (@code{org-todo}) anywhere in the entry.  This adds the keyword
1418: @samp{TODO} to the heading line.  Typing @kbd{C-c C-t} again switches
1419: the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword
1420: entirely, and so forth.  You can customize the keywords used by
1421: @kbd{C-c C-t} via the variable @code{org-todo-keywords}.
1422: 
1423: @kindex C-c C-s @r{(Org Mode)}
1424: @kindex C-c C-d @r{(Org Mode)}
1425: @findex org-schedule
1426: @findex org-deadline
1427:   Apart from marking an entry as TODO, you can attach a date to it, by
1428: typing @kbd{C-c C-s} (@code{org-schedule}) in the entry.  This prompts
1429: for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}),
1430: and then adds the tag @samp{SCHEDULED}, together with the selected
1431: date, beneath the heading line.  The command @kbd{C-c C-d}
1432: (@code{org-deadline}) has the same effect, except that it uses the tag
1433: @code{DEADLINE}.
1434: 
1435: @kindex C-c [ @r{(Org Mode)}
1436: @findex org-agenda-file-to-front
1437: @vindex org-agenda-files
1438:   Once you have some TODO items planned in an Org file, you can add
1439: that file to the list of @dfn{agenda files} by typing @kbd{C-c [}
1440: (@code{org-agenda-file-to-front}).  Org mode is designed to let you
1441: easily maintain multiple agenda files, e.g., for organizing different
1442: aspects of your life.  The list of agenda files is stored in the
1443: variable @code{org-agenda-files}.
1444: 
1445: @findex org-agenda
1446:   To view items coming from your agenda files, type @kbd{M-x
1447: org-agenda}.  This command prompts for what you want to see: a list of
1448: things to do this week, a list of TODO items with specific keywords,
1449: etc.
1450: @ifnottex
1451: @xref{Agenda views,,,org, The Org Manual}, for details.
1452: @end ifnottex
1453: 
1454: @node Org Authoring
1455: @subsection Org as an authoring system
1456: @cindex Org exporting
1457: 
1458: @findex org-export
1459: @kindex C-c C-e @r{(Org mode)}
1460:   You may want to format your Org notes nicely and to prepare them for
1461: export and publication.  To export the current buffer, type @kbd{C-c
1462: C-e} (@code{org-export}) anywhere in an Org buffer.  This command
1463: prompts for an export format; currently supported formats include
1464: HTML, @LaTeX{}, Texinfo, OpenDocument (@file{.odt}), iCalendar,
1465: Markdown, man-page, and PDF@.  Some formats, such as PDF, require
1466: certain system tools to be installed.
1467: 
1468: @vindex org-publish-project-alist
1469:   To export several files at once to a specific directory, either
1470: locally or over the network, you must define a list of projects
1471: through the variable @code{org-publish-project-alist}.  See its
1472: documentation for details.
1473: 
1474:   Org supports a simple markup scheme for applying text formatting to
1475: exported documents:
1476: 
1477: @example
1478: - This text is /emphasized/
1479: - This text is *in bold*
1480: - This text is _underlined_
1481: - This text uses =a teletype font=
1482: 
1483: #+begin_quote
1484: ``This is a quote.''
1485: #+end_quote
1486: 
1487: #+begin_example
1488: This is an example.
1489: #+end_example
1490: @end example
1491: 
1492:   For further details, @ref{Exporting,,,org, The Org Manual}, and
1493: @ref{Publishing,,,org, The Org Manual}.
1494: 
1495: @node TeX Mode
1496: @section @TeX{} Mode
1497: @cindex @TeX{} mode
1498: @cindex @LaTeX{} mode
1499: @cindex Sli@TeX{} mode
1500: @cindex Doc@TeX{} mode
1501: @cindex mode, @TeX{}
1502: @cindex mode, @LaTeX{}
1503: @cindex mode, Sli@TeX{}
1504: @cindex mode, Doc@TeX{}
1505: @findex tex-mode
1506: @findex plain-tex-mode
1507: @findex latex-mode
1508: @findex slitex-mode
1509: @findex doctex-mode
1510: @findex bibtex-mode
1511: 
1512:   @TeX{} is a powerful text formatter written by Donald Knuth; like
1513: GNU Emacs, it is free software.  The @TeX{} format has several
1514: variants, including @LaTeX{}, a simplified input format for @TeX{};
1515: Doc@TeX{}, a special file format in which the @LaTeX{} sources are
1516: written, combining sources with documentation; and Sli@TeX{}, an
1517: obsolete special form of @LaTeX{}@footnote{
1518: It has been replaced by the @samp{slides} document class, which comes
1519: with @LaTeX{}.}.
1520: 
1521: @vindex tex-default-mode
1522:   Emacs provides a @TeX{} major mode for each of these variants: Plain
1523: @TeX{} mode, @LaTeX{} mode, Doc@TeX{} mode, and Sli@TeX{} mode.  Emacs
1524: selects the appropriate mode by looking at the contents of the buffer.
1525: (This is done by invoking the @code{tex-mode} command, which is
1526: normally called automatically when you visit a @TeX{}-like file.
1527: @xref{Choosing Modes}.)  If the contents are insufficient to determine
1528: this, Emacs chooses the mode specified by the variable
1529: @code{tex-default-mode}; its default value is @code{latex-mode}.  If
1530: Emacs does not guess right, you can select the correct variant of
1531: @TeX{} mode using the commands @code{plain-tex-mode},
1532: @code{latex-mode}, @code{slitex-mode}, or @code{doctex-mode}.
1533: 
1534:   The following sections document the features of @TeX{} mode and its
1535: variants.  There are several other @TeX{}-related Emacs packages,
1536: which are not documented in this manual:
1537: 
1538: @itemize @bullet
1539: @item
1540: Bib@TeX{} mode is a major mode for Bib@TeX{} files, which are commonly
1541: used for keeping bibliographic references for @LaTeX{} documents.  For
1542: more information, see the documentation string for the command
1543: @code{bibtex-mode}.
1544: 
1545: @item
1546: The Ref@TeX{} package provides a minor mode which can be used with
1547: @LaTeX{} mode to manage bibliographic references.
1548: @ifinfo
1549: @xref{Top,The Ref@TeX{} Manual,,reftex}.
1550: @end ifinfo
1551: @ifnotinfo
1552: For more information, see the Ref@TeX{} Info manual, which is
1553: distributed with Emacs.
1554: @end ifnotinfo
1555: 
1556: @item
1557: The AUC@TeX{} package provides more advanced features for editing
1558: @TeX{} and its related formats, including the ability to preview
1559: @TeX{} equations within Emacs buffers.  Unlike Bib@TeX{} mode and the
1560: Ref@TeX{} package, AUC@TeX{} is not distributed with Emacs by default.
1561: It can be downloaded via the Package Menu (@pxref{Packages}); once
1562: installed, see
1563: @ifinfo
1564: @ref{Top,The AUC@TeX{} Manual,,auctex}.
1565: @end ifinfo
1566: @ifnotinfo
1567: the AUC@TeX{} manual, which is included with the package.
1568: @end ifnotinfo
1569: @end itemize
1570: 
1571: @menu
1572: * TeX Editing::   Special commands for editing in TeX mode.
1573: * LaTeX Editing:: Additional commands for LaTeX input files.
1574: * TeX Print::     Commands for printing part of a file with TeX.
1575: * TeX Misc::      Customization of TeX mode, and related features.
1576: @end menu
1577: 
1578: @node TeX Editing
1579: @subsection @TeX{} Editing Commands
1580: 
1581: @table @kbd
1582: @item "
1583: Insert, according to context, either @samp{``} or @samp{"} or
1584: @samp{''} (@code{tex-insert-quote}).
1585: @item C-j
1586: Insert a paragraph break (two newlines) and check the previous
1587: paragraph for unbalanced braces or dollar signs
1588: (@code{tex-terminate-paragraph}).
1589: @item M-x tex-validate-region
1590: Check each paragraph in the region for unbalanced braces or dollar signs.
1591: @item C-c @{
1592: Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
1593: @item C-c @}
1594: Move forward past the next unmatched close brace (@code{up-list}).
1595: @end table
1596: 
1597: @findex tex-insert-quote
1598: @kindex " @r{(@TeX{} mode)}
1599:   In @TeX{}, the character @samp{"} is not normally used; instead,
1600: quotations begin with @samp{``} and end with @samp{''}.  @TeX{} mode
1601: therefore binds the @kbd{"} key to the @code{tex-insert-quote}
1602: command.  This inserts @samp{``} after whitespace or an open brace,
1603: @samp{"} after a backslash, and @samp{''} after any other character.
1604: 
1605:   As a special exception, if you type @kbd{"} when the text before
1606: point is either @samp{``} or @samp{''}, Emacs replaces that preceding
1607: text with a single @samp{"} character.  You can therefore type
1608: @kbd{""} to insert @samp{"}, should you ever need to do so.  (You can
1609: also use @kbd{C-q "} to insert this character.)
1610: 
1611:   In @TeX{} mode, @samp{$} has a special syntax code which attempts to
1612: understand the way @TeX{} math mode delimiters match.  When you insert a
1613: @samp{$} that is meant to exit math mode, the position of the matching
1614: @samp{$} that entered math mode is displayed for a second.  This is the
1615: same feature that displays the open brace that matches a close brace that
1616: is inserted.  However, there is no way to tell whether a @samp{$} enters
1617: math mode or leaves it; so when you insert a @samp{$} that enters math
1618: mode, the previous @samp{$} position is shown as if it were a match, even
1619: though they are actually unrelated.
1620: 
1621: @findex tex-insert-braces
1622: @kindex C-c @{ @r{(@TeX{} mode)}
1623: @findex up-list
1624: @kindex C-c @} @r{(@TeX{} mode)}
1625:   @TeX{} uses braces as delimiters that must match.  Some users prefer
1626: to keep braces balanced at all times, rather than inserting them
1627: singly.  Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
1628: braces.  It leaves point between the two braces so you can insert the
1629: text that belongs inside.  Afterward, use the command @kbd{C-c @}}
1630: (@code{up-list}) to move forward past the close brace.  You can also
1631: invoke @kbd{C-c @{} after marking some text: then the command encloses
1632: the marked text in braces.
1633: 
1634: @findex tex-validate-region
1635: @findex tex-terminate-paragraph
1636: @kindex C-j @r{(@TeX{} mode)}
1637:   There are two commands for checking the matching of braces.
1638: @kbd{C-j} (@code{tex-terminate-paragraph}) checks the paragraph before
1639: point, and inserts two newlines to start a new paragraph.  It outputs
1640: a message in the echo area if any mismatch is found.  @kbd{M-x
1641: tex-validate-region} checks a region, paragraph by paragraph.  The
1642: errors are listed in an @file{*Occur*} buffer; you can use the usual
1643: Occur mode commands in that buffer, such as @kbd{C-c C-c}, to visit a
1644: particular mismatch (@pxref{Other Repeating Search}).
1645: 
1646:   Note that Emacs commands count square brackets and parentheses in
1647: @TeX{} mode, not just braces.  This is not strictly correct for the
1648: purpose of checking @TeX{} syntax.  However, parentheses and square
1649: brackets are likely to be used in text as matching delimiters, and it
1650: is useful for the various motion commands and automatic match display
1651: to work with them.
1652: 
1653: @node LaTeX Editing
1654: @subsection @LaTeX{} Editing Commands
1655: 
1656:   @LaTeX{} mode provides a few extra features not applicable to plain
1657: @TeX{}:
1658: 
1659: @table @kbd
1660: @item C-c C-o
1661: Insert @samp{\begin} and @samp{\end} for @LaTeX{} block and position
1662: point on a line between them (@code{tex-latex-block}).
1663: @item C-c C-e
1664: Close the innermost @LaTeX{} block not yet closed
1665: (@code{tex-close-latex-block}).
1666: @end table
1667: 
1668: @findex tex-latex-block
1669: @kindex C-c C-o @r{(@LaTeX{} mode)}
1670:   In @LaTeX{} input, @samp{\begin} and @samp{\end} tags are used to
1671: group blocks of text.  To insert a block, type @kbd{C-c C-o}
1672: (@code{tex-latex-block}).  This prompts for a block type, and inserts
1673: the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a
1674: blank line between the two and moving point there.
1675: 
1676: @vindex latex-block-names
1677:   When entering the block type argument to @kbd{C-c C-o}, you can use
1678: the usual completion commands (@pxref{Completion}).  The default
1679: completion list contains the standard @LaTeX{} block types.  If you
1680: want additional block types for completion, customize the list
1681: variable @code{latex-block-names}.
1682: 
1683: @findex tex-close-latex-block
1684: @kindex C-c C-e @r{(@LaTeX{} mode)}
1685: @findex latex-electric-env-pair-mode
1686:   In @LaTeX{} input, @samp{\begin} and @samp{\end} tags must balance.
1687: You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an
1688: @samp{\end} tag which matches the last unmatched @samp{\begin}.  It
1689: also indents the @samp{\end} to match the corresponding @samp{\begin},
1690: and inserts a newline after the @samp{\end} tag if point is at the
1691: beginning of a line.  The minor mode @code{latex-electric-env-pair-mode}
1692: automatically inserts an @samp{\end} or @samp{\begin} tag for you
1693: when you type the corresponding one.
1694: 
1695: @node TeX Print
1696: @subsection @TeX{} Printing Commands
1697: 
1698:   You can invoke @TeX{} as a subprocess of Emacs, supplying either
1699: the entire contents of the buffer or just part of it (e.g., one
1700: chapter of a larger document).
1701: 
1702: @table @kbd
1703: @item C-c C-b
1704: Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
1705: 
1706: @item C-c C-r
1707: Invoke @TeX{} on the current region, together with the buffer's header
1708: (@code{tex-region}).
1709: 
1710: @item C-c C-f
1711: Invoke @TeX{} on the current file (@code{tex-file}).
1712: 
1713: @item C-c C-v
1714: Preview the output from the last @kbd{C-c C-b}, @kbd{C-c C-r}, or @kbd{C-c
1715: C-f} command (@code{tex-view}).
1716: 
1717: @item C-c C-p
1718: Print the output from the last @kbd{C-c C-b}, @kbd{C-c C-r}, or
1719: @kbd{C-c C-f} command (@code{tex-print}).
1720: 
1721: @item C-c @key{TAB}
1722: Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
1723: @item C-c C-l
1724: Recenter the window showing output from @TeX{} so that the last line
1725: can be seen (@code{tex-recenter-output-buffer}).
1726: @item C-c C-k
1727: Kill the @TeX{} subprocess (@code{tex-kill-job}).
1728: @item C-c C-c
1729: Invoke some other compilation command on the entire current buffer
1730: (@code{tex-compile}).
1731: @end table
1732: 
1733: @findex tex-buffer
1734: @kindex C-c C-b @r{(@TeX{} mode)}
1735: @findex tex-view
1736: @kindex C-c C-v @r{(@TeX{} mode)}
1737: @findex tex-print
1738: @kindex C-c C-p @r{(@TeX{} mode)}
1739:   To pass the current buffer through @TeX{}, type @kbd{C-c C-b}
1740: (@code{tex-buffer}).  The formatted output goes in a temporary file,
1741: normally a @file{.dvi} file.  Afterwards, you can type @kbd{C-c C-v}
1742: (@code{tex-view}) to launch an external program, such as
1743: @command{xdvi}, to view this output file.  You can also type @kbd{C-c
1744: C-p} (@code{tex-print}) to print a hardcopy of the output file.
1745: 
1746: @cindex @env{TEXINPUTS} environment variable
1747: @vindex tex-directory
1748:   By default, @kbd{C-c C-b} runs @TeX{} in the current directory.  The
1749: output of @TeX{} is also created in this directory.  To run @TeX{} in a
1750: different directory, change the variable @code{tex-directory} to
1751: the desired directory.  If your environment variable @env{TEXINPUTS}
1752: contains relative names, or if your files contain
1753: @samp{\input} commands with relative file names, then
1754: @code{tex-directory} @emph{must} be @code{"."} or you will get the
1755: wrong results.  Otherwise, it is safe to specify some other directory,
1756: such as @code{"/tmp"}.
1757: 
1758: @vindex tex-run-command
1759: @vindex latex-run-command
1760: @vindex tex-dvi-view-command
1761: @vindex tex-dvi-print-command
1762: @vindex tex-print-file-extension
1763:   The buffer's @TeX{} variant determines what shell command @kbd{C-c
1764: C-b} actually runs.  In Plain @TeX{} mode, it is specified by the
1765: variable @code{tex-run-command}, which defaults to @code{"tex"}.  In
1766: @LaTeX{} mode, it is specified by @code{latex-run-command}, which
1767: defaults to @code{"latex"}.  The shell command that @kbd{C-c C-v} runs
1768: to view the @file{.dvi} output is determined by the variable
1769: @code{tex-dvi-view-command}, regardless of the @TeX{} variant.  The
1770: shell command that @kbd{C-c C-p} runs to print the output is
1771: determined by the variable @code{tex-dvi-print-command}.  The variable
1772: @code{tex-print-file-extension} can be set to the required file
1773: extension for viewing and printing @TeX{}-compiled files.  For
1774: example, you can set it to @file{.pdf}, and update
1775: @code{tex-dvi-view-command} and @code{tex-dvi-print-command}
1776: accordingly.
1777: 
1778:   Normally, Emacs automatically appends the output file name to the
1779: shell command strings described in the preceding paragraph.  For
1780: example, if @code{tex-dvi-view-command} is @code{"xdvi"}, @kbd{C-c
1781: C-v} runs @command{xdvi @var{output-file-name}}.  In some cases,
1782: however, the file name needs to be embedded in the command, e.g., if
1783: you need to provide the file name as an argument to one command whose
1784: output is piped to another.  You can specify where to put the file
1785: name with @samp{*} in the command string.  For example,
1786: 
1787: @example
1788: (setq tex-dvi-print-command "dvips -f * | lpr")
1789: @end example
1790: 
1791: @findex tex-kill-job
1792: @kindex C-c C-k @r{(@TeX{} mode)}
1793: @findex tex-recenter-output-buffer
1794: @kindex C-c C-l @r{(@TeX{} mode)}
1795:   The terminal output from @TeX{}, including any error messages,
1796: appears in a buffer called @file{*tex-shell*}.  If @TeX{} gets an
1797: error, you can switch to this buffer and feed it input (this works as
1798: in Shell mode; @pxref{Interactive Shell}).  Without switching to this
1799: buffer you can scroll it so that its last line is visible by typing
1800: @kbd{C-c C-l}.
1801: 
1802:   Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
1803: you see that its output is no longer useful.  Using @kbd{C-c C-b} or
1804: @kbd{C-c C-r} also kills any @TeX{} process still running.
1805: 
1806: @findex tex-region
1807: @kindex C-c C-r @r{(@TeX{} mode)}
1808:   You can also pass an arbitrary region through @TeX{} by typing
1809: @kbd{C-c C-r} (@code{tex-region}).  This is tricky, however, because
1810: most files of @TeX{} input contain commands at the beginning to set
1811: parameters and define macros, without which no later part of the file
1812: will format correctly.  To solve this problem, @kbd{C-c C-r} allows
1813: you to designate a part of the file as containing essential commands;
1814: it is included before the specified region as part of the input to
1815: @TeX{}.  The designated part of the file is called the @dfn{header}.
1816: 
1817: @cindex header (@TeX{} mode)
1818:   To indicate the bounds of the header in Plain @TeX{} mode, you insert two
1819: special strings in the file.  Insert @samp{%**start of header} before the
1820: header, and @samp{%**end of header} after it.  Each string must appear
1821: entirely on one line, but there may be other text on the line before or
1822: after.  The lines containing the two strings are included in the header.
1823: If @samp{%**start of header} does not appear within the first 100 lines of
1824: the buffer, @kbd{C-c C-r} assumes that there is no header.
1825: 
1826:   In @LaTeX{} mode, the header begins with @samp{\documentclass} or
1827: @samp{\documentstyle} and ends with @samp{\begin@{document@}}.  These
1828: are commands that @LaTeX{} requires you to use in any case, so nothing
1829: special needs to be done to identify the header.
1830: 
1831: @findex tex-file
1832: @kindex C-c C-f @r{(@TeX{} mode)}
1833:   The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
1834: work in a temporary directory, and do not have available any of the auxiliary
1835: files needed by @TeX{} for cross-references; these commands are generally
1836: not suitable for running the final copy in which all of the cross-references
1837: need to be correct.
1838: 
1839:   When you want the auxiliary files for cross references, use @kbd{C-c
1840: C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
1841: in that file's directory.  Before running @TeX{}, it offers to save any
1842: modified buffers.  Generally, you need to use (@code{tex-file}) twice to
1843: get the cross-references right.
1844: 
1845: @vindex tex-start-options
1846:   The value of the variable @code{tex-start-options} specifies
1847: options for the @TeX{} run.
1848: 
1849: @vindex tex-start-commands
1850:   The value of the variable @code{tex-start-commands} specifies @TeX{}
1851: commands for starting @TeX{}.  The default value causes @TeX{} to run
1852: in nonstop mode.  To run @TeX{} interactively, set the variable to
1853: @code{""}.
1854: 
1855: @vindex tex-main-file
1856:   Large @TeX{} documents are often split into several files---one main
1857: file, plus subfiles.  Running @TeX{} on a subfile typically does not
1858: work; you have to run it on the main file.  In order to make
1859: @code{tex-file} useful when you are editing a subfile, you can set the
1860: variable @code{tex-main-file} to the name of the main file.  Then
1861: @code{tex-file} runs @TeX{} on that file.
1862: 
1863:   The most convenient way to use @code{tex-main-file} is to specify it
1864: in a local variable list in each of the subfiles.  @xref{File
1865: Variables}.
1866: 
1867: @findex tex-bibtex-file
1868: @kindex C-c TAB @r{(@TeX{} mode)}
1869: @vindex tex-bibtex-command
1870:   For @LaTeX{} files, you can use Bib@TeX{} to process the auxiliary
1871: file for the current buffer's file.  Bib@TeX{} looks up bibliographic
1872: citations in a data base and prepares the cited references for the
1873: bibliography section.  The command @kbd{C-c @key{TAB}}
1874: (@code{tex-bibtex-file}) runs the shell command
1875: (@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
1876: current buffer's file.  Generally, you need to do @kbd{C-c C-f}
1877: (@code{tex-file}) once to generate the @samp{.aux} file, then do
1878: @kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
1879: (@code{tex-file}) twice more to get the cross-references correct.
1880: 
1881: @findex tex-compile
1882: @kindex C-c C-c @r{(@TeX{} mode)}
1883:   To invoke some other compilation program on the current @TeX{}
1884: buffer, type @kbd{C-c C-c} (@code{tex-compile}).  This command knows
1885: how to pass arguments to many common programs, including
1886: @file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}.  You can
1887: select your desired compilation program using the standard completion
1888: keys (@pxref{Completion}).
1889: 
1890: @node TeX Misc
1891: @subsection @TeX{} Mode Miscellany
1892: 
1893: @vindex tex-shell-hook
1894: @vindex tex-mode-hook
1895: @vindex doctex-mode-hook
1896: @vindex latex-mode-hook
1897: @vindex slitex-mode-hook
1898: @vindex plain-tex-mode-hook
1899:   Entering any variant of @TeX{} mode runs the hooks
1900: @code{text-mode-hook} and @code{tex-mode-hook}.  Then it runs either
1901: @code{plain-tex-mode-hook}, @code{doctex-mode-hook},
1902: @code{latex-mode-hook}, or @code{slitex-mode-hook}, whichever is
1903: appropriate.  Starting the @TeX{} shell runs the hook
1904: @code{tex-shell-hook}.  @xref{Hooks}.
1905: 
1906: @findex iso-iso2tex
1907: @findex iso-tex2iso
1908: @findex iso-iso2gtex
1909: @findex iso-gtex2iso
1910: @cindex Latin-1 @TeX{} encoding
1911: @cindex @TeX{} encoding
1912:   The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
1913: iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert
1914: between Latin-1 encoded files and @TeX{}-encoded equivalents.
1915: 
1916: @node HTML Mode
1917: @section SGML and HTML Modes
1918: @cindex SGML mode
1919: @cindex HTML mode
1920: @cindex mode, SGML
1921: @cindex mode, HTML
1922: @findex sgml-mode
1923: @findex html-mode
1924: 
1925:   The major modes for SGML and HTML provide indentation support and
1926: commands for operating on tags.
1927: 
1928:   HTML consists of two modes---one, a basic mode called
1929: @code{html-mode} is a slightly customized variant of SGML mode.  The
1930: other, which is used by default for HTML files, is called
1931: @code{mhtml-mode}, and attempts to properly handle Javascript enclosed
1932: in a @code{<script>} element and CSS embedded in a @code{<style>}
1933: element.
1934: 
1935: @table @kbd
1936: @item C-c C-n
1937: @kindex C-c C-n @r{(SGML mode)}
1938: @findex sgml-name-char
1939: Interactively specify a special character and insert the SGML
1940: @samp{&}-command for that character (@code{sgml-name-char}).
1941: 
1942: @item C-c C-t
1943: @kindex C-c C-t @r{(SGML mode)}
1944: @findex sgml-tag
1945: Interactively specify a tag and its attributes (@code{sgml-tag}).
1946: This command asks you for a tag name and for the attribute values,
1947: then inserts both the opening tag and the closing tag, leaving point
1948: between them.
1949: 
1950: With a prefix argument @var{n}, the command puts the tag around the
1951: @var{n} words already present in the buffer after point.  Whenever a
1952: region is active, it puts the tag around the region (when Transient
1953: Mark mode is off, it does this when a numeric argument of @minus{}1 is
1954: supplied.)
1955: 
1956: @item C-c C-a
1957: @kindex C-c C-a @r{(SGML mode)}
1958: @findex sgml-attributes
1959: Interactively insert attribute values for the current tag
1960: (@code{sgml-attributes}).
1961: 
1962: @item C-c C-f
1963: @kindex C-c C-f @r{(SGML mode)}
1964: @findex sgml-skip-tag-forward
1965: Skip across a balanced tag group (which extends from an opening tag
1966: through its corresponding closing tag) (@code{sgml-skip-tag-forward}).
1967: A numeric argument acts as a repeat count.
1968: 
1969: @item C-c C-b
1970: @kindex C-c C-b @r{(SGML mode)}
1971: @findex sgml-skip-tag-backward
1972: Skip backward across a balanced tag group (which extends from an
1973: opening tag through its corresponding closing tag)
1974: (@code{sgml-skip-tag-backward}).  A numeric argument acts as a repeat
1975: count.
1976: 
1977: @item C-c C-d
1978: @kindex C-c C-d @r{(SGML mode)}
1979: @findex sgml-delete-tag
1980: Delete the tag at or after point, and delete the matching tag too
1981: (@code{sgml-delete-tag}).  If the tag at or after point is an opening
1982: tag, delete the closing tag too; if it is a closing tag, delete the
1983: opening tag too.
1984: 
1985: @item C-c ? @var{tag} @key{RET}
1986: @kindex C-c ? @r{(SGML mode)}
1987: @findex sgml-tag-help
1988: Display a description of the meaning of tag @var{tag}
1989: (@code{sgml-tag-help}).  If the argument @var{tag} is empty, describe
1990: the tag at point.
1991: 
1992: @item C-c /
1993: @kindex C-c / @r{(SGML mode)}
1994: @findex sgml-close-tag
1995: Insert a close tag for the innermost unterminated tag
1996: (@code{sgml-close-tag}).  If called within a tag or a comment,
1997: close it instead of inserting a close tag.
1998: 
1999: @item C-c 8
2000: @kindex C-c 8 @r{(SGML mode)}
2001: @findex sgml-name-8bit-mode
2002: Toggle a minor mode in which Latin-1 characters insert the
2003: corresponding SGML commands that stand for them, instead of the
2004: characters themselves (@code{sgml-name-8bit-mode}).
2005: 
2006: @item C-c C-v
2007: @kindex C-c C-v @r{(SGML mode)}
2008: @findex sgml-validate
2009: Run a shell command (which you must specify) to validate the current
2010: buffer as SGML (@code{sgml-validate}).  (In HTML mode this key
2011: sequence runs a different command.)
2012: 
2013: @item C-c @key{TAB}
2014: @kindex C-c TAB @r{(SGML mode)}
2015: @findex sgml-tags-invisible
2016: Toggle the visibility of existing tags in the buffer.  This can be
2017: used as a cheap preview (@code{sgml-tags-invisible}).
2018: @end table
2019: 
2020: @cindex nXML mode
2021: @cindex mode, nXML
2022: @cindex mode, XML
2023: @findex nxml-mode
2024: @cindex XML schema
2025:   The major mode for editing XML documents is called nXML mode.  This
2026: is a powerful major mode that can recognize many existing XML schemas
2027: and use them to provide completion of XML elements via
2028: @kbd{M-@key{TAB}}, as well as on-the-fly XML
2029: validation with error highlighting.  To enable nXML mode in an
2030: existing buffer, type @kbd{M-x nxml-mode}, or, equivalently, @kbd{M-x
2031: xml-mode}.  Emacs uses nXML mode for files which have the extension
2032: @file{.xml}.  For XHTML files, which have the extension @file{.xhtml},
2033: Emacs uses HTML mode by default; you can make it use nXML mode by
2034: customizing the variable @code{auto-mode-alist} (@pxref{Choosing
2035: Modes}).
2036: @ifinfo
2037: nXML mode is described in its own manual: @xref{Top, nXML
2038: Mode,,nxml-mode, nXML Mode}.
2039: @end ifinfo
2040: @ifnotinfo
2041: nXML mode is described in an Info manual, which is distributed with
2042: Emacs.
2043: @end ifnotinfo
2044: 
2045: @vindex sgml-xml-mode
2046:   You may choose to use the less powerful SGML mode for editing XML,
2047: since XML is a strict subset of SGML@.  To enable SGML mode in an
2048: existing buffer, type @kbd{M-x sgml-mode}.  On enabling SGML mode,
2049: Emacs examines the buffer to determine whether it is XML; if so, it
2050: sets the variable @code{sgml-xml-mode} to a non-@code{nil} value.
2051: This causes SGML mode's tag insertion commands, described above, to
2052: always insert explicit closing tags as well.
2053: 
2054: @node Nroff Mode
2055: @section Nroff Mode
2056: 
2057: @cindex nroff
2058: @findex nroff-mode
2059: @vindex nroff-mode-hook
2060:   Nroff mode, a major mode derived from Text mode, is
2061: specialized for editing nroff files (e.g., Unix man pages).  Type
2062: @kbd{M-x nroff-mode} to enter this mode.  Entering Nroff mode runs the
2063: hook @code{text-mode-hook}, then @code{nroff-mode-hook}
2064: (@pxref{Hooks}).
2065: 
2066:   In Nroff mode, nroff command lines are treated as paragraph
2067: separators, pages are separated by @samp{.bp} commands, and comments
2068: start with backslash-doublequote.  It also defines these commands:
2069: 
2070: @findex nroff-forward-text-line
2071: @findex nroff-backward-text-line
2072: @findex nroff-count-text-lines
2073: @kindex M-n @r{(Nroff mode)}
2074: @kindex M-p @r{(Nroff mode)}
2075: @kindex M-? @r{(Nroff mode)}
2076: @table @kbd
2077: @item M-n
2078: Move to the beginning of the next line that isn't an nroff command
2079: (@code{nroff-forward-text-line}).  An argument is a repeat count.
2080: @item M-p
2081: Like @kbd{M-n} but move up (@code{nroff-backward-text-line}).
2082: @item M-?
2083: Displays in the echo area the number of text lines (lines that are not
2084: nroff commands) in the region (@code{nroff-count-text-lines}).
2085: @end table
2086: 
2087: @findex nroff-electric-mode
2088:   Electric Nroff mode is a buffer-local minor mode that can be used
2089: with Nroff mode.  To toggle this minor mode, type @kbd{M-x
2090: nroff-electric-mode} (@pxref{Minor Modes}).  When the mode is on, each
2091: time you type @key{RET} to end a line containing an nroff command that
2092: opens a kind of grouping, the nroff command to close that grouping is
2093: automatically inserted on the following line.
2094: 
2095:   If you use Outline minor mode with Nroff mode (@pxref{Outline
2096: Mode}), heading lines are lines of the form @samp{.H} followed by a
2097: number (the header level).
2098: 
2099: @node Enriched Text
2100: @section Enriched Text
2101: @cindex Enriched mode
2102: @cindex mode, Enriched
2103: @cindex enriched text
2104: @cindex WYSIWYG
2105: @cindex word processing
2106: @cindex text/enriched MIME format
2107: 
2108:   Enriched mode is a minor mode for editing formatted text files in a
2109: WYSIWYG (What You See Is What You Get) fashion.  When Enriched
2110: mode is enabled, you can apply various formatting properties to the
2111: text in the buffer, such as fonts and colors; upon saving the buffer,
2112: those properties are saved together with the text, using the MIME
2113: @samp{text/enriched} file format.
2114: 
2115:   Enriched mode is typically used with Text mode (@pxref{Text Mode}).
2116: It is @emph{not} compatible with Font Lock mode, which is used by many
2117: major modes, including most programming language modes, for syntax
2118: highlighting (@pxref{Font Lock}).  Unlike Enriched mode, Font Lock
2119: mode assigns text properties automatically, based on the current
2120: buffer contents; those properties are not saved to disk.
2121: 
2122:   The file @file{enriched.txt} in Emacs's @code{data-directory}
2123: serves as an example of the features of Enriched mode.
2124: 
2125: @menu
2126: * Enriched Mode::           Entering and exiting Enriched mode.
2127: * Hard and Soft Newlines::  There are two different kinds of newlines.
2128: * Editing Format Info::     How to edit text properties.
2129: * Enriched Faces::          Bold, italic, underline, etc.
2130: * Enriched Indentation::    Changing the left and right margins.
2131: * Enriched Justification::  Centering, setting text flush with the
2132:                               left or right margin, etc.
2133: * Enriched Properties::     The ``special text properties'' submenu.
2134: @end menu
2135: 
2136: @node Enriched Mode
2137: @subsection Enriched Mode
2138: 
2139:   Enriched mode is a buffer-local minor mode (@pxref{Minor Modes}).
2140: When you visit a file that has been saved in the @samp{text/enriched}
2141: format, Emacs automatically enables Enriched mode, and applies the
2142: formatting information in the file to the buffer text.  When you save
2143: a buffer with Enriched mode enabled, it is saved using the
2144: @samp{text/enriched} format, including the formatting information.
2145: 
2146: @findex enriched-mode
2147:   To create a new file of formatted text, visit the nonexistent file
2148: and type @kbd{M-x enriched-mode}.  This command actually toggles
2149: Enriched mode.  With a prefix argument, it enables Enriched mode if
2150: the argument is positive, and disables Enriched mode otherwise.  If
2151: you disable Enriched mode, Emacs no longer saves the buffer using the
2152: @samp{text/enriched} format; any formatting properties that have been
2153: added to the buffer remain in the buffer, but they are not saved to
2154: disk.
2155: 
2156: @vindex enriched-translations
2157:   Enriched mode does not save all Emacs text properties, only those
2158: specified in the variable @code{enriched-translations}.  These include
2159: properties for fonts, colors, indentation, and justification.
2160: 
2161: @findex format-decode-buffer
2162:   If you visit a file and Emacs fails to recognize that it is in the
2163: @samp{text/enriched} format, type @kbd{M-x format-decode-buffer}.
2164: This command prompts for a file format, and re-reads the file in that
2165: format.  Specifying the @samp{text/enriched} format automatically
2166: enables Enriched mode.
2167: 
2168:   To view a @samp{text/enriched} file in raw form (as plain text with
2169: markup tags rather than formatted text), use @kbd{M-x
2170: find-file-literally} (@pxref{Visiting}).
2171: 
2172:   @xref{Format Conversion,, Format Conversion, elisp, the Emacs Lisp
2173: Reference Manual}, for details of how Emacs recognizes and converts
2174: file formats like @samp{text/enriched}.  @xref{Text Properties,,,
2175: elisp, the Emacs Lisp Reference Manual}, for more information about
2176: text properties.
2177: 
2178: @node Hard and Soft Newlines
2179: @subsection Hard and Soft Newlines
2180: @cindex hard newline
2181: @cindex soft newline
2182: @cindex newlines, hard and soft
2183: 
2184: @findex use-hard-newlines
2185:   In Enriched mode, Emacs distinguishes between two different kinds of
2186: newlines, @dfn{hard} newlines and @dfn{soft} newlines.  You can also
2187: enable or disable this feature in other buffers, by typing @kbd{M-x
2188: use-hard-newlines}.
2189: 
2190:   Hard newlines are used to separate paragraphs, or anywhere there
2191: needs to be a line break regardless of how the text is filled; soft
2192: newlines are used for filling.  The @key{RET} (@code{newline}) and
2193: @kbd{C-o} (@code{open-line}) commands insert hard newlines.  The fill
2194: commands, including Auto Fill (@pxref{Auto Fill}), insert only soft
2195: newlines and delete only soft newlines, leaving hard newlines alone.
2196: 
2197: @c FIXME: I don't see 'unfilled' in that node.  --xfq
2198:   Thus, when editing with Enriched mode, you should not use @key{RET}
2199: or @kbd{C-o} to break lines in the middle of filled paragraphs.  Use
2200: Auto Fill mode or explicit fill commands (@pxref{Fill Commands})
2201: instead.  Use @key{RET} or @kbd{C-o} where line breaks should always
2202: remain, such as in tables and lists.  For such lines, you may also
2203: want to set the justification style to @code{unfilled}
2204: (@pxref{Enriched Justification}).
2205: 
2206: @node Editing Format Info
2207: @subsection Editing Format Information
2208: 
2209:   The easiest way to alter properties is with the @samp{Text
2210: Properties} menu.  You can get to this menu from the @samp{Edit} menu
2211: in the menu bar (@pxref{Menu Bar}), or with @kbd{C-mouse-2}
2212: (@pxref{Menu Mouse Clicks}).  Some of the commands in the @samp{Text
2213: Properties} menu are listed below (you can also invoke them with
2214: @kbd{M-x}):
2215: 
2216: @table @code
2217: @findex facemenu-remove-face-props
2218: @item Remove Face Properties
2219: Remove face properties from the region
2220: (@code{facemenu-remove-face-props}).
2221: 
2222: @findex facemenu-remove-all
2223: @item Remove Text Properties
2224: Remove all text properties from the region, including face properties
2225: (@code{facemenu-remove-all}).
2226: 
2227: @findex describe-text-properties
2228: @cindex text properties of characters
2229: @cindex overlays at character position
2230: @cindex widgets at buffer position
2231: @cindex buttons at buffer position
2232: @item Describe Properties
2233: List all text properties and other information about the character
2234: following point (@code{describe-text-properties}).
2235: 
2236: @item Display Faces
2237: Display a list of defined faces (@code{list-faces-display}).
2238: @xref{Faces}.
2239: 
2240: @item Display Colors
2241: Display a list of defined colors (@code{list-colors-display}).
2242: @xref{Colors}.
2243: @end table
2244: 
2245: @noindent
2246: The other menu entries are described in the following sections.
2247: 
2248: @node Enriched Faces
2249: @subsection Faces in Enriched Text
2250: 
2251:   The following commands can be used to add or remove faces
2252: (@pxref{Faces}).  Each applies to the text in the region if the mark
2253: is active, and to the next self-inserting character if the mark is
2254: inactive.  With a prefix argument, each command applies to the next
2255: self-inserting character even if the region is active.
2256: 
2257: @table @kbd
2258: @kindex M-o d @r{(Enriched mode)}
2259: @findex facemenu-set-default
2260: @item M-o d
2261: Remove all @code{face} properties (@code{facemenu-set-default}).
2262: 
2263: @kindex M-o b @r{(Enriched mode)}
2264: @findex facemenu-set-bold
2265: @item M-o b
2266: Apply the @code{bold} face (@code{facemenu-set-bold}).
2267: 
2268: @kindex M-o i @r{(Enriched mode)}
2269: @findex facemenu-set-italic
2270: @item M-o i
2271: Apply the @code{italic} face (@code{facemenu-set-italic}).
2272: 
2273: @kindex M-o l @r{(Enriched mode)}
2274: @findex facemenu-set-bold-italic
2275: @item M-o l
2276: Apply the @code{bold-italic} face (@code{facemenu-set-bold-italic}).
2277: 
2278: @kindex M-o u @r{(Enriched mode)}
2279: @findex facemenu-set-underline
2280: @item M-o u
2281: Apply the @code{underline} face (@code{facemenu-set-underline}).
2282: 
2283: @kindex M-o o @r{(Enriched mode)}
2284: @findex facemenu-set-face
2285: @item M-o o @var{face} @key{RET}
2286: Apply the face @var{face} (@code{facemenu-set-face}).
2287: 
2288: @findex facemenu-set-foreground
2289: @item M-x facemenu-set-foreground
2290: Prompt for a color (@pxref{Colors}), and apply it as a foreground
2291: color.
2292: 
2293: @findex facemenu-set-background
2294: @item M-x facemenu-set-background
2295: Prompt for a color, and apply it as a background color.
2296: @end table
2297: 
2298: @noindent
2299: These commands are also available via the Text Properties menu.
2300: 
2301:   A self-inserting character normally inherits the face properties
2302: (and most other text properties) from the preceding character in the
2303: buffer.  If you use one of the above commands to specify the face for
2304: the next self-inserting character, that character will not inherit the
2305: faces properties from the preceding character, but it will still
2306: inherit other text properties.
2307: 
2308:   Enriched mode defines two additional faces: @code{excerpt} and
2309: @code{fixed}.  These correspond to codes used in the text/enriched
2310: file format.  The @code{excerpt} face is intended for quotations; by
2311: default, it appears the same as @code{italic}.  The @code{fixed} face
2312: specifies fixed-width text; by default, it appears the same as
2313: @code{bold}.
2314: 
2315: @node Enriched Indentation
2316: @subsection Indentation in Enriched Text
2317: 
2318:   In Enriched mode, you can specify different amounts of indentation
2319: for the right or left margin of a paragraph or a part of a paragraph.
2320: These margins also affect fill commands such as @kbd{M-q}
2321: (@pxref{Filling}).
2322: 
2323:   The Indentation submenu of Text Properties offers commands
2324: for specifying indentation:
2325: 
2326: @table @code
2327: @kindex C-x TAB @r{(Enriched mode)}
2328: @findex increase-left-margin
2329: @item Indent More
2330: Indent the region by 4 columns (@code{increase-left-margin}).  In
2331: Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
2332: you supply a numeric argument, that says how many columns to add to the
2333: margin (a negative argument reduces the number of columns).
2334: 
2335: @item Indent Less
2336: Remove 4 columns of indentation from the region.
2337: 
2338: @item Indent Right More
2339: Make the text narrower by indenting 4 columns at the right margin.
2340: 
2341: @item Indent Right Less
2342: Remove 4 columns of indentation from the right margin.
2343: @end table
2344: 
2345: @vindex standard-indent
2346:   The variable @code{standard-indent} specifies how many columns these
2347: commands should add to or subtract from the indentation.  The default
2348: value is 4.  The default right margin for Enriched mode is controlled
2349: by the variable @code{fill-column}, as usual.
2350: 
2351: @kindex C-c [ @r{(Enriched mode)}
2352: @kindex C-c ] @r{(Enriched mode)}
2353: @findex set-left-margin
2354: @findex set-right-margin
2355:   You can also type @kbd{C-c [} (@code{set-left-margin}) and @kbd{C-c
2356: ]} (@code{set-right-margin}) to set the left and right margins.  You
2357: can specify the margin width with a numeric argument; otherwise these
2358: commands prompt for a value via the minibuffer.
2359: 
2360:   The fill prefix, if any, works in addition to the specified paragraph
2361: indentation: @kbd{C-x .} does not include the specified indentation's
2362: whitespace in the new value for the fill prefix, and the fill commands
2363: look for the fill prefix after the indentation on each line.  @xref{Fill
2364: Prefix}.
2365: 
2366: @node Enriched Justification
2367: @subsection Justification in Enriched Text
2368: @cindex justification style
2369: 
2370:   In Enriched mode, you can use the following commands to specify
2371: various @dfn{justification styles} for filling.  These commands apply
2372: to the paragraph containing point, or, if the region is active, to all
2373: paragraphs overlapping the region.
2374: 
2375: @table @kbd
2376: @kindex M-j l @r{(Enriched mode)}
2377: @findex set-justification-left
2378: @item M-j l
2379: Align lines to the left margin (@code{set-justification-left}).
2380: 
2381: @kindex M-j r @r{(Enriched mode)}
2382: @findex set-justification-right
2383: @item M-j r
2384: Align lines to the right margin (@code{set-justification-right}).
2385: 
2386: @kindex M-j b @r{(Enriched mode)}
2387: @findex set-justification-full
2388: @item M-j b
2389: Align lines to both margins, inserting spaces in the middle of the
2390: line to achieve this (@code{set-justification-full}).
2391: 
2392: @kindex M-j c @r{(Enriched mode)}
2393: @kindex M-S @r{(Enriched mode)}
2394: @findex set-justification-center
2395: @item M-j c
2396: @itemx M-S
2397: Center lines between the margins (@code{set-justification-center}).
2398: 
2399: @kindex M-j u @r{(Enriched mode)}
2400: @findex set-justification-none
2401: @item M-j u
2402: Turn off filling entirely (@code{set-justification-none}).  The fill
2403: commands do nothing on text with this setting.  You can, however,
2404: still indent the left margin.
2405: @end table
2406: 
2407: @vindex default-justification
2408:   You can also specify justification styles using the Justification
2409: submenu in the Text Properties menu.  The default justification style
2410: is specified by the per-buffer variable @code{default-justification}.
2411: Its value should be one of the symbols @code{left}, @code{right},
2412: @code{full}, @code{center}, or @code{none}; their meanings correspond
2413: to the commands above.
2414: 
2415: @node Enriched Properties
2416: @subsection Setting Other Text Properties
2417: 
2418:   The Special Properties submenu of Text Properties has entries for
2419: adding or removing four other text properties: @code{read-only},
2420: (which disallows alteration of the text), @code{invisible} (which
2421: hides text), @code{intangible} (which disallows moving point within
2422: the text), and @code{charset} (which is important for selecting a
2423: proper font to display a character).  The @samp{Remove Special} menu
2424: item removes all of these special properties from the text in the
2425: region.
2426: 
2427:   The @code{invisible} and @code{intangible} properties are not saved.
2428: 
2429: @vindex enriched-allow-eval-in-display-props
2430: @cindex security, when displaying enriched text
2431:   Enriched mode also supports saving and restoring @code{display}
2432: properties (@pxref{Display Property,,,elisp, the Emacs Lisp Reference
2433: Manual}), which affect how text is displayed on the screen, and also
2434: allow displaying images and strings that come from sources other than
2435: buffer text.  The @code{display} properties also support execution of
2436: arbitrary Lisp forms as part of processing the property for display,
2437: thus providing a means to dynamically tailor the display to some
2438: conditions that can only be known at display time.  Since execution of
2439: arbitrary Lisp opens Emacs to potential attacks, especially when the
2440: source of enriched text is outside of Emacs or even outside of your
2441: system (e.g., if it was received in an email message), such execution
2442: is by default disabled in Enriched mode.  You can enable it by
2443: customizing the variable @code{enriched-allow-eval-in-display-props}
2444: to a non-@code{nil} value.
2445: 
2446: @node Text Based Tables
2447: @section Editing Text-based Tables
2448: @cindex table mode
2449: @cindex text-based tables
2450: 
2451:   The @code{table} package provides commands to easily edit text-based
2452: tables.  Here is an example of what such a table looks like:
2453: 
2454: @smallexample
2455: @group
2456: +-----------------+--------------------------------+-----------------+
2457: |     Command     |          Description           |   Key Binding   |
2458: +-----------------+--------------------------------+-----------------+
2459: |  forward-char   |Move point right N characters   |       C-f       |
2460: |                 |(left if N is negative).        |                 |
2461: |                 |                                |                 |
2462: +-----------------+--------------------------------+-----------------+
2463: |  backward-char  |Move point left N characters    |       C-b       |
2464: |                 |(right if N is negative).       |                 |
2465: |                 |                                |                 |
2466: +-----------------+--------------------------------+-----------------+
2467: @end group
2468: @end smallexample
2469: 
2470:   When Emacs recognizes such a stretch of text as a table
2471: (@pxref{Table Recognition}), editing the contents of each table cell
2472: will automatically resize the table, whenever the contents become too
2473: large to fit in the cell.  You can use the commands defined in the
2474: following sections for navigating and editing the table layout.
2475: 
2476: @findex table-fixed-width-mode
2477:   Type @kbd{M-x table-fixed-width-mode} to toggle the automatic table
2478: resizing feature.
2479: 
2480: @menu
2481: * Table Definition::          What is a text based table.
2482: * Table Creation::            How to create a table.
2483: * Table Recognition::         How to activate and deactivate tables.
2484: * Cell Commands::             Cell-oriented commands in a table.
2485: * Cell Justification::        Justifying cell contents.
2486: * Table Rows and Columns::    Inserting and deleting rows and columns.
2487: * Table Conversion::          Converting between plain text and tables.
2488: * Table Misc::                Table miscellany.
2489: @end menu
2490: 
2491: @node Table Definition
2492: @subsection What is a Text-based Table?
2493: @cindex cells, for text-based tables
2494: 
2495:   A @dfn{table} consists of a rectangular text area which is divided
2496: into @dfn{cells}.  Each cell must be at least one character wide and
2497: one character high, not counting its border lines.  A cell can be
2498: subdivided into more cells, but they cannot overlap.
2499: 
2500:   Cell border lines are drawn with three special characters, specified
2501: by the following variables:
2502: 
2503: @table @code
2504: @vindex table-cell-vertical-char
2505: @item table-cell-vertical-char
2506: The character used for vertical lines.  The default is @samp{|}.
2507: 
2508: @vindex table-cell-horizontal-chars
2509: @item table-cell-horizontal-chars
2510: The characters used for horizontal lines.  The default is @samp{"-="}.
2511: 
2512: @vindex table-cell-intersection-char
2513: @item table-cell-intersection-char
2514: The character used for the intersection of horizontal and vertical
2515: lines.  The default is @samp{+}.
2516: @end table
2517: 
2518: @noindent
2519: The following are examples of @emph{invalid} tables:
2520: 
2521: @example
2522:    +-----+       +--+    +-++--+
2523:    |     |       |  |    | ||  |
2524:    |     |       |  |    | ||  |
2525:    +--+  |    +--+--+    +-++--+
2526:    |  |  |    |  |  |    +-++--+
2527:    |  |  |    |  |  |    | ||  |
2528:    +--+--+    +--+--+    +-++--+
2529:       a          b          c
2530: @end example
2531: 
2532: @noindent
2533: From left to right:
2534: 
2535: @enumerate a
2536: @item
2537: Overlapped cells or non-rectangular cells are not allowed.
2538: @item
2539: The border must be rectangular.
2540: @item
2541: Cells must have a minimum width/height of one character.
2542: @end enumerate
2543: 
2544: @node Table Creation
2545: @subsection Creating a Table
2546: @cindex create a text-based table
2547: @cindex table creation
2548: 
2549: @findex table-insert
2550:   To create a text-based table from scratch, type @kbd{M-x
2551: table-insert}.  This command prompts for the number of table columns,
2552: the number of table rows, cell width and cell height.  The cell width
2553: and cell height do not include the cell borders; each can be specified
2554: as a single integer (which means each cell is given the same
2555: width/height), or as a sequence of integers separated by spaces or
2556: commas (which specify the width/height of the individual table
2557: columns/rows, counting from left to right for table columns and from
2558: top to bottom for table rows).  The specified table is then inserted
2559: at point.
2560: 
2561:   The table inserted by @kbd{M-x table-insert} contains special text
2562: properties, which tell Emacs to treat it specially as a text-based
2563: table.  If you save the buffer to a file and visit it again later,
2564: those properties are lost, and the table appears to Emacs as an
2565: ordinary piece of text.  See the next section, for how to convert it
2566: back into a table.
2567: 
2568: @node Table Recognition
2569: @subsection Table Recognition
2570: @cindex table recognition
2571: 
2572: @findex table-recognize
2573: @findex table-unrecognize
2574:   Existing text-based tables in a buffer, which lack the special text
2575: properties applied by @kbd{M-x table-insert}, are not treated
2576: specially as tables.  To apply those text properties, type @kbd{M-x
2577: table-recognize}.  This command scans the current buffer,
2578: @dfn{recognizes} valid table cells, and applies the relevant text
2579: properties.  Conversely, type @kbd{M-x table-unrecognize} to
2580: @dfn{unrecognize} all tables in the current buffer, removing the
2581: special text properties and converting tables back to plain text.
2582: 
2583:   You can also use the following commands to selectively recognize or
2584: unrecognize tables:
2585: 
2586: @table @kbd
2587: @findex table-recognize-region
2588: @item M-x table-recognize-region
2589: Recognize tables within the current region.
2590: 
2591: @findex table-unrecognize-region
2592: @item M-x table-unrecognize-region
2593: Unrecognize tables within the current region.
2594: 
2595: @findex table-recognize-table
2596: @item M-x table-recognize-table
2597: Recognize the table at point and activate it.
2598: 
2599: @findex table-unrecognize-table
2600: @item M-x table-unrecognize-table
2601: Deactivate the table at point.
2602: 
2603: @findex table-recognize-cell
2604: @item M-x table-recognize-cell
2605: Recognize the cell at point and activate it.
2606: 
2607: @findex table-unrecognize-cell
2608: @item M-x table-unrecognize-cell
2609: Deactivate the cell at point.
2610: @end table
2611: 
2612:   @xref{Table Conversion}, for another way to recognize a table.
2613: 
2614: @node Cell Commands
2615: @subsection Commands for Table Cells
2616: 
2617: @findex table-forward-cell
2618: @findex table-backward-cell
2619:   The commands @kbd{M-x table-forward-cell} and @kbd{M-x
2620: table-backward-cell} move point from the current cell to an adjacent
2621: cell.  The order is cyclic: when point is in the last cell of a table,
2622: @kbd{M-x table-forward-cell} moves to the first cell.  Likewise, when
2623: point is on the first cell, @kbd{M-x table-backward-cell} moves to the
2624: last cell.
2625: 
2626: @findex table-span-cell
2627:   @kbd{M-x table-span-cell} prompts for a direction---right, left,
2628: above, or below---and merges the current cell with the adjacent cell
2629: in that direction.  This command signals an error if the merge would
2630: result in an illegitimate cell layout.
2631: 
2632: @findex table-split-cell
2633: @findex table-split-cell-vertically
2634: @findex table-split-cell-horizontally
2635: @cindex text-based tables, splitting cells
2636: @cindex splitting table cells
2637:   @kbd{M-x table-split-cell} splits the current cell vertically or
2638: horizontally, prompting for the direction with the minibuffer.  To
2639: split in a specific direction, use @kbd{M-x
2640: table-split-cell-vertically} and @kbd{M-x
2641: table-split-cell-horizontally}.  When splitting vertically, the old
2642: cell contents are automatically split between the two new cells.  When
2643: splitting horizontally, you are prompted for how to divide the cell
2644: contents, if the cell is non-empty; the options are @samp{split}
2645: (divide the contents at point), @samp{left} (put all the contents in
2646: the left cell), and @samp{right} (put all the contents in the right
2647: cell).
2648: 
2649:   The following commands enlarge or shrink a cell.  By default, they
2650: resize by one row or column; if a numeric argument is supplied, that
2651: specifies the number of rows or columns to resize by.
2652: 
2653: @table @kbd
2654: @findex table-heighten-cell
2655: @item M-x table-heighten-cell
2656: Enlarge the current cell vertically.
2657: 
2658: @findex table-shorten-cell
2659: @item M-x table-shorten-cell
2660: Shrink the current cell vertically.
2661: 
2662: @findex table-widen-cell
2663: @item M-x table-widen-cell
2664: Enlarge the current cell horizontally.
2665: 
2666: @findex table-narrow-cell
2667: @item M-x table-narrow-cell
2668: Shrink the current cell horizontally.
2669: @end table
2670: 
2671: @node Cell Justification
2672: @subsection Cell Justification
2673: @cindex justification in text-based tables
2674: 
2675:   The command @kbd{M-x table-justify} imposes @dfn{justification} on
2676: one or more cells in a text-based table.  Justification determines how
2677: the text in the cell is aligned, relative to the edges of the cell.
2678: Each cell in a table can be separately justified.
2679: 
2680: @findex table-justify
2681:   @kbd{M-x table-justify} first prompts for what to justify; the
2682: options are @samp{cell} (just the current cell), @samp{column} (all
2683: cells in the current table column) and @samp{row} (all cells in the
2684: current table row).  The command then prompts for the justification
2685: style; the options are @code{left}, @code{center}, @code{right},
2686: @code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no
2687: vertical justification).
2688: 
2689:   Horizontal and vertical justification styles are specified
2690: independently, and both types can be in effect simultaneously; for
2691: instance, you can call @kbd{M-x table-justify} twice, once to specify
2692: @code{right} justification and once to specify @code{bottom}
2693: justification, to align the contents of a cell to the bottom right.
2694: 
2695: @vindex table-detect-cell-alignment
2696:   The justification style is stored in the buffer as a text property,
2697: and is lost when you kill the buffer or exit Emacs.  However, the
2698: table recognition commands, such as @kbd{M-x table-recognize}
2699: (@pxref{Table Recognition}), attempt to determine and re-apply each
2700: cell's justification style, by examining its contents.  To disable
2701: this feature, change the variable @code{table-detect-cell-alignment}
2702: to @code{nil}.
2703: 
2704: @node Table Rows and Columns
2705: @subsection Table Rows and Columns
2706: @cindex inserting rows and columns in text-based tables
2707: 
2708: @findex table-insert-row
2709:   @kbd{M-x table-insert-row} inserts a row of cells before the current
2710: table row.  The current row, together with point, is pushed down past
2711: the new row.  To insert a row after the last row at the bottom of a
2712: table, invoke this command with point below the table, just below the
2713: bottom edge.  You can insert more than one row at a time by using a
2714: numeric prefix argument.
2715: 
2716: @c A numeric prefix argument specifies the number of rows to insert.
2717: 
2718: @findex table-insert-column
2719:   Similarly, @kbd{M-x table-insert-column} inserts a column of cells
2720: to the left of the current table column.  To insert a column to the
2721: right side of the rightmost column, invoke this command with point to
2722: the right of the rightmost column, outside the table.  A numeric
2723: prefix argument specifies the number of columns to insert.
2724: 
2725: @cindex deleting rows and column in text-based tables
2726:   @kbd{M-x table-delete-column} deletes the column of cells at point.
2727: Similarly, @kbd{M-x table-delete-row} deletes the row of cells at
2728: point.  A numeric prefix argument to either command specifies the
2729: number of columns or rows to delete.
2730: 
2731: @node Table Conversion
2732: @subsection Converting Between Plain Text and Tables
2733: @cindex text to table
2734: @cindex table to text
2735: 
2736: @findex table-capture
2737:   The command @kbd{M-x table-capture} captures plain text in a region
2738: and turns it into a table.  Unlike @kbd{M-x table-recognize}
2739: (@pxref{Table Recognition}), the original text does not need to have a
2740: table appearance; it only needs to have a logical table-like
2741: structure.
2742: 
2743:   For example, suppose we have the following numbers, which are
2744: divided into three lines and separated horizontally by commas:
2745: 
2746: @example
2747: 1, 2, 3, 4
2748: 5, 6, 7, 8
2749: , 9, 10
2750: @end example
2751: 
2752: @noindent
2753: Invoking @kbd{M-x table-capture} on that text produces this table:
2754: 
2755: @example
2756: +-----+-----+-----+-----+
2757: |1    |2    |3    |4    |
2758: +-----+-----+-----+-----+
2759: |5    |6    |7    |8    |
2760: +-----+-----+-----+-----+
2761: |     |9    |10   |     |
2762: +-----+-----+-----+-----+
2763: @end example
2764: 
2765: @findex table-release
2766:   @kbd{M-x table-release} does the opposite: it converts a table back
2767: to plain text, removing its cell borders.
2768: 
2769:   One application of this pair of commands is to edit a text in
2770: layout.  Look at the following three paragraphs:
2771: 
2772: @example
2773: table-capture is a powerful command.
2774: Here are some things it can do:
2775: 
2776: Parse Cell Items   Using row and column delimiter regexps,
2777:                    it parses the specified text area and
2778:                    extracts cell items into a table.
2779: @end example
2780: 
2781: @noindent
2782: Applying @code{table-capture} to a region containing the above text,
2783: with empty strings for the column and row delimiter regexps, creates a
2784: table with a single cell like the following one.
2785: 
2786: @smallexample
2787: @group
2788: +----------------------------------------------------------+
2789: |table-capture is a powerful command.                      |
2790: |Here are some things it can do:                           |
2791: |                                                          |
2792: |Parse Cell Items   Using row and column delimiter regexps,|
2793: |                   it parses the specified text area and  |
2794: |                   extracts cell items into a table.      |
2795: +----------------------------------------------------------+
2796: @end group
2797: @end smallexample
2798: 
2799: @noindent
2800: We can then use the cell splitting commands (@pxref{Cell Commands}) to
2801: subdivide the table so that each paragraph occupies a cell:
2802: 
2803: @smallexample
2804: +----------------------------------------------------------+
2805: |table-capture is a powerful command.                      |
2806: |Here are some things it can do:                           |
2807: +-----------------+----------------------------------------+
2808: |Parse Cell Items | Using row and column delimiter regexps,|
2809: |                 | it parses the specified text area and  |
2810: |                 | extracts cell items into a table.      |
2811: +-----------------+----------------------------------------+
2812: @end smallexample
2813: 
2814: @noindent
2815: Each cell can now be edited independently without affecting the layout
2816: of other cells.  When finished, we can invoke @kbd{M-x table-release}
2817: to convert the table back to plain text.
2818: 
2819: @node Table Misc
2820: @subsection Table Miscellany
2821: 
2822: @cindex table dimensions
2823: @findex table-query-dimension
2824:   The command @code{table-query-dimension} reports the layout of the
2825: table and table cell at point.  Here is an example of its output:
2826: 
2827: @smallexample
2828: Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
2829: @end smallexample
2830: 
2831: @noindent
2832: This indicates that the current cell is 21 characters wide and 6 lines
2833: high, the table is 67 characters wide and 16 lines high with 2 columns
2834: and 3 rows, and a total of 5 cells.
2835: 
2836: @findex table-insert-sequence
2837:   @kbd{M-x table-insert-sequence} traverses the cells of a table
2838: inserting a sequence of text strings into each cell as it goes.  It
2839: asks for the base string of the sequence, and then produces the
2840: sequence by ``incrementing'' the base string, either numerically (if
2841: the base string ends in numerical characters) or in the
2842: @acronym{ASCII} order.  In addition to the base string, the command
2843: prompts for the number of elements in the sequence, the increment, the
2844: cell interval, and the justification of the text in each cell.
2845: 
2846: @cindex table for HTML and LaTeX
2847: @findex table-generate-source
2848:   @kbd{M-x table-generate-source} generates a table formatted for a
2849: specific markup language.  It asks for a language (which must be one
2850: of @code{html}, @code{latex}, or @code{cals}), a destination buffer in
2851: which to put the result, and a table caption, and then inserts the
2852: generated table into the specified buffer.  The default destination
2853: buffer is @code{table.@var{lang}}, where @var{lang} is the language
2854: you specified.
2855: 
2856: @node Two-Column
2857: @section Two-Column Editing
2858: @cindex two-column editing
2859: @cindex splitting columns
2860: @cindex columns, splitting
2861: 
2862:   Two-column mode lets you conveniently edit two side-by-side columns
2863: of text.  It uses two side-by-side windows, each showing its own
2864: buffer.  There are three ways to enter two-column mode:
2865: 
2866: @table @asis
2867: @item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
2868: @kindex F2 2
2869: @kindex C-x 6 2
2870: @findex 2C-two-columns
2871: Enter two-column mode with the current buffer on the left, and on the
2872: right, a buffer whose name is based on the current buffer's name
2873: (@code{2C-two-columns}).  If the right-hand buffer doesn't already
2874: exist, it starts out empty; the current buffer's contents are not
2875: changed.
2876: 
2877: This command is appropriate when the current buffer is empty or contains
2878: just one column and you want to add another column.
2879: 
2880: @item @kbd{@key{F2} s} or @kbd{C-x 6 s}
2881: @kindex F2 s
2882: @kindex C-x 6 s
2883: @findex 2C-split
2884: Split the current buffer, which contains two-column text, into two
2885: buffers, and display them side by side (@code{2C-split}).  The current
2886: buffer becomes the left-hand buffer, but the text in the right-hand
2887: column is moved into the right-hand buffer.  The current column
2888: specifies the split point.  Splitting starts with the current line and
2889: continues to the end of the buffer.
2890: 
2891: This command is appropriate when you have a buffer that already contains
2892: two-column text, and you wish to separate the columns temporarily.
2893: 
2894: @item @kbd{@key{F2} b @var{buffer} @key{RET}}
2895: @itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
2896: @kindex F2 b
2897: @kindex C-x 6 b
2898: @findex 2C-associate-buffer
2899: Enter two-column mode using the current buffer as the left-hand buffer,
2900: and using buffer @var{buffer} as the right-hand buffer
2901: (@code{2C-associate-buffer}).
2902: @end table
2903: 
2904:   @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
2905: is a string that appears on each line between the two columns.  You can
2906: specify the width of the separator with a numeric argument to
2907: @kbd{@key{F2} s}; that many characters, before point, constitute the
2908: separator string.  By default, the width is 1, so the column separator
2909: is the character before point.
2910: 
2911:   When a line has the separator at the proper place, @kbd{@key{F2} s}
2912: puts the text after the separator into the right-hand buffer, and
2913: deletes the separator.  Lines that don't have the column separator at
2914: the proper place remain unsplit; they stay in the left-hand buffer, and
2915: the right-hand buffer gets an empty line to correspond.  (This is the
2916: way to write a line that spans both columns while in two-column
2917: mode: write it in the left-hand buffer, and put an empty line in the
2918: right-hand buffer.)
2919: 
2920: @kindex F2 RET
2921: @kindex C-x 6 RET
2922: @findex 2C-newline
2923:   The command @kbd{@key{F2} @key{RET}} or @kbd{C-x 6 @key{RET}}
2924: (@code{2C-newline}) inserts a newline in each of the two buffers at
2925: corresponding positions.  This is the easiest way to add a new line to
2926: the two-column text while editing it in split buffers.
2927: 
2928: @kindex F2 1
2929: @kindex C-x 6 1
2930: @findex 2C-merge
2931:   When you have edited both buffers as you wish, merge them with
2932: @kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}).  This copies the
2933: text from the right-hand buffer as a second column in the other buffer.
2934: To go back to two-column editing, use @kbd{@key{F2} s}.
2935: 
2936: @kindex F2 d
2937: @kindex C-x 6 d
2938: @findex 2C-dissociate
2939:   Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
2940: leaving each as it stands (@code{2C-dissociate}).  If the other buffer,
2941: the one not current when you type @kbd{@key{F2} d}, is empty,
2942: @kbd{@key{F2} d} kills it.
2943: