@c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001, 2002, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Text, Programs, Indentation, Top
@chapter Commands for Human Languages
that you edit with Emacs is text, in this sense of the word. The other
meaning is more restrictive: a sequence of characters in a human language
for humans to read (possibly after processing by a text formatter), as
-opposed to a program or commands for a program.
+opposed to a program or binary data. This chapter is concerned with
+editing text in the narrower sense.
Human languages have syntactic/stylistic conventions that can be
supported or used to advantage by editor commands: conventions involving
@end iftex
For text which contains embedded commands for text formatters, Emacs
-has other major modes, each for a particular text formatter. Thus, for
+has other major modes, each for a particular formatter. Thus, for
input to @TeX{}, you would use @TeX{}
@iftex
-mode (@pxref{TeX Mode}).
+mode (@pxref{TeX Mode,,@TeX{} Mode}).
@end iftex
-@ifinfo
+@ifnottex
mode.
-@end ifinfo
-For input to nroff, use Nroff mode.
+@end ifnottex
+For input to groff or nroff, use Nroff mode.
Instead of using a text formatter, you can edit formatted text in
WYSIWYG style (``what you see is what you get''), with Enriched mode.
@xref{Formatted Text}.
@end iftex
+@cindex ASCII art
+ If you need to edit pictures made out of text characters (commonly
+referred to as ``ASCII art''), use @kbd{M-x edit-picture} to enter
+Picture mode, a special major mode for editing such pictures.
+@iftex
+@xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}.
+@end iftex
+@ifnottex
+@xref{Picture Mode}.
+@end ifnottex
+
+
@cindex skeletons
@cindex templates
@cindex autotyping
@item M-@@
Mark the end of the next word (@code{mark-word}).
@item M-t
-Transpose two words or drag a word across other words
+Transpose two words or drag a word across others
(@code{transpose-words}).
@end table
repeat counts. @kbd{M-f} with a negative argument moves backward, and
@kbd{M-b} with a negative argument moves forward. Forward motion
stops right after the last letter of the word, while backward motion
-stops right before the first letter.@refill
+stops right before the first letter.
@kindex M-d
@findex kill-word
@kindex M-DEL
@kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
point. It kills everything from point back to where @kbd{M-b} would
-move to. If point is after the space in @w{@samp{FOO, BAR}}, then
-@w{@samp{FOO, }} is killed. (If you wish to kill just @samp{FOO}, and
-not the comma and the space, use @kbd{M-b M-d} instead of
-@kbd{M-@key{DEL}}.)
+move to. For instance, if point is after the space in @w{@samp{FOO,
+BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just
+@samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead
+of @kbd{M-@key{DEL}}.
@c Don't index M-t and transpose-words here, they are indexed in
@c fixit.texi, in the node "Transpose".
containing point with the following word. The delimiter characters between
the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
-more on transposition and on arguments to transposition commands.
+more on transposition.
@kindex M-@@
@findex mark-word
scan for the place to put the mark. In Transient Mark mode, this command
activates the mark.
- The word commands' understanding of syntax is completely controlled by
-the syntax table. Any character can, for example, be declared to be a word
-delimiter. @xref{Syntax}.
+ The word commands' understanding of word boundaries is controlled
+by the syntax table. Any character can, for example, be declared to
+be a word delimiter. @xref{Syntax}.
@node Sentences
@section Sentences
The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and
@code{forward-sentence}) move to the beginning and end of the current
sentence, respectively. They were chosen to resemble @kbd{C-a} and
-@kbd{C-e}, which move to the beginning and end of a line. Unlike them,
-@kbd{M-a} and @kbd{M-e} if repeated or given numeric arguments move over
-successive sentences.
+@kbd{C-e}, which move to the beginning and end of a line. Unlike
+them, @kbd{M-a} and @kbd{M-e} move over successive sentences if
+repeated.
Moving backward over a sentence places point just before the first
character of the sentence; moving forward places point right after the
There is also a command, @kbd{C-x @key{DEL}}
(@code{backward-kill-sentence}), for killing back to the beginning of a
sentence. This command is useful when you change your mind in the
-middle of composing text.@refill
+middle of composing text.
The sentence commands assume that you follow the American typist's
convention of putting two spaces at the end of a sentence; they consider
followed by the end of a line or two spaces, with any number of
@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between.
A sentence also begins or ends wherever a paragraph begins or ends.
+It is useful to follow this convention, because it makes a distinction
+between periods that end a sentence and periods that indicate
+abbreviations; that enables the Emacs sentence commands to distinguish,
+too. These commands do not stop for periods that indicate abbreviations.
-@vindex sentence-end
- The variable @code{sentence-end} controls recognition of the end of
-a sentence. If non-@code{nil}, it is a regexp that matches the last
-few characters of a sentence, together with the whitespace following
-the sentence. If the value is @code{nil}, the default, then Emacs
-computes the regexp according to various criteria. The result is
-normally similar to the following regexp:
-
-@example
-"[.?!][]\"')]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
-@end example
-
-@noindent
-This example is explained in the section on regexps. @xref{Regexps}.
-
- If you want to use just one space between sentences, you should
-set @code{sentence-end} to this value:
+@vindex sentence-end-double-space
+ If you want to use just one space between sentences, you can set the
+variable @code{sentence-end-double-space} to @code{nil} to make the
+sentence commands stop for single spaces. However, this mode has a
+drawback: there is no way to distinguish between periods that end
+sentences and those that indicate abbreviations. For convenient and
+reliable editing, we therefore recommend you follow the two-space
+convention. The variable @code{sentence-end-double-space} also
+affects filling (@pxref{Fill Commands}) in related ways.
-@example
-"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
-@end example
+@vindex sentence-end
+ The variable @code{sentence-end} controls how to recognize the end
+of a sentence. If non-@code{nil}, it is a regexp that matches the
+last few characters of a sentence, together with the whitespace
+following the sentence. If the value is @code{nil}, the default, then
+Emacs computes the regexp according to various criteria such as the
+value of @code{sentence-end-double-space}. @xref{Regexp Example}, for
+a detailed explanation of one of the regular expressions Emacs uses
+for this purpose.
-@noindent
-You should also set the variable @code{sentence-end-double-space} to
-@code{nil} so that the fill commands expect and leave just one space at
-the end of a sentence. Note that this makes it impossible to
-distinguish between periods that end sentences and those that indicate
-abbreviations.
+@vindex sentence-end-without-period
+ Some languages do not use periods to indicate the end of a sentence.
+For example, sentences in Thai end with a double space but without a
+period. Set the variable @code{sentence-end-without-period} to
+@code{t} in such cases.
@node Paragraphs
@section Paragraphs
@findex backward-paragraph
@findex forward-paragraph
- The Emacs commands for manipulating paragraphs are also Meta keys.
+ The Emacs commands for manipulating paragraphs are also on Meta keys.
@table @kbd
@item M-@{
@kbd{M-@{} moves to the beginning of the current or previous
paragraph, while @kbd{M-@}} moves to the end of the current or next
paragraph. Blank lines and text-formatter command lines separate
-paragraphs and are not considered part of any paragraph. In Indented
-Text mode, but not in Text mode, an indented line also starts a new
-paragraph. (If a paragraph is preceded by a blank line, these
-commands treat that blank line as the beginning of the paragraph.)
+paragraphs and are not considered part of any paragraph. If there is
+a blank line before the paragraph, @kbd{M-@{} moves to the blank line,
+because that is convenient in practice.
+
+ In Text mode, an indented line is not a paragraph break. If you
+want indented lines to have this effect, use Paragraph-Indent Text
+mode instead. @xref{Text Mode}.
In major modes for programs, paragraphs begin and end only at blank
-lines. This makes the paragraph commands continue to be useful even
-though there are no paragraphs per se.
+lines. This makes the paragraph commands useful, even though there
+are no paragraphs as such in a program.
- When there is a fill prefix, then paragraphs are delimited by all lines
-which don't start with the fill prefix. @xref{Filling}.
+ When you have set a fill prefix, then paragraphs are delimited by
+all lines which don't start with the fill prefix. @xref{Filling}.
@kindex M-h
@findex mark-paragraph
@menu
* Auto Fill:: Auto Fill mode breaks long lines automatically.
-* Refill:: Keeping paragraphs filled.
* Fill Commands:: Commands to refill paragraphs and center lines.
* Fill Prefix:: Filling paragraphs that are indented
or in a comment, etc.
* Adaptive Fill:: How Emacs can determine the fill prefix automatically.
+* Refill:: Keeping paragraphs filled.
+* Longlines:: Editing text with very long lines.
@end menu
@node Auto Fill
@subsection Auto Fill Mode
@cindex Auto Fill mode
@cindex mode, Auto Fill
-@cindex word wrap
@dfn{Auto Fill} mode is a minor mode in which lines are broken
automatically when they become too wide. Breaking happens only when
cannot merge lines. So editing in the middle of a paragraph can result in
a paragraph that is not correctly filled. The easiest way to make the
paragraph properly filled again is usually with the explicit fill commands.
-@ifinfo
+@ifnottex
@xref{Fill Commands}.
-@end ifinfo
+@end ifnottex
Many users like Auto Fill mode and want to use it in all text files.
The section on init files says how to arrange this permanently for yourself.
@xref{Init File}.
-@node Refill
-@subsection Refill Mode
-@cindex refilling text, word processor style
-@cindex modes, Refill
-@cindex Refill minor mode
-
- Refill minor mode provides support for keeping paragraphs filled as
-you type or modify them in other ways. It provides an effect similar
-to typical word processor behavior. This works by running a
-paragraph-filling command at suitable times.
-
- When you are typing text, only characters which normally trigger
-auto filling, like the space character, will trigger refilling. This
-is to avoid making it too slow. Apart from self-inserting characters,
-other commands which modify the text cause refilling.
-
- The current implementation is preliminary and probably not robust.
-We expect to improve on it.
-
- To toggle the use of Refill mode in the current buffer, type
-@kbd{M-x refill-mode}.
-
@node Fill Commands
@subsection Explicit Fill Commands
@findex fill-region
To refill many paragraphs, use @kbd{M-x fill-region}, which
-divides the region into paragraphs and fills each of them.
+finds the paragraphs in the region and fills each of them.
@findex fill-region-as-paragraph
@kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h}
for finding paragraph boundaries (@pxref{Paragraphs}). For more
control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
-everything between point and mark. This command deletes any blank lines
-within the region, so separate blocks of text end up combined into one
-block.@refill
+everything between point and mark as a single paragraph. This command
+deletes any blank lines within the region, so separate blocks of text
+end up combined into one block.
@cindex justification
- A numeric argument to @kbd{M-q} causes it to @dfn{justify} the text as
-well as filling it. This means that extra spaces are inserted to make
-the right margin line up exactly at the fill column. To remove the
-extra spaces, use @kbd{M-q} with no argument. (Likewise for
+ A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text
+as well as filling it. This means that extra spaces are inserted to
+make the right margin line up exactly at the fill column. To remove
+the extra spaces, use @kbd{M-q} with no argument. (Likewise for
@code{fill-region}.) Another way to control justification, and choose
-other styles of filling, is with the @code{justification} text property;
-see @ref{Format Justification}.
+other styles of filling, is with the @code{justification} text
+property; see @ref{Format Justification}.
@kindex M-s @r{(Text mode)}
@cindex centering
the distinction between these two ways of using a period, the fill
commands do not break a line after a period followed by just one space.
-@vindex sentence-end-double-space
If the variable @code{sentence-end-double-space} is @code{nil}, the
fill commands expect and leave just one space at the end of a sentence.
Ordinarily this variable is @code{t}, so the fill commands insist on
If the variable @code{colon-double-space} is non-@code{nil}, the
fill commands put two spaces after a colon.
-@vindex sentence-end-without-period
- Some languages do not use period to indicate end of sentence. For
-example, a sentence in Thai text ends with double space but without a
-period. Set the variable @code{sentence-end-without-period} to
-@code{t} to tell the sentence commands that a period is not necessary.
-
@vindex fill-nobreak-predicate
- The variable @code{fill-nobreak-predicate} specifies additional
-conditions for where line-breaking is allowed. Its value is either
-@code{nil} or a Lisp function; the function is called with no
-arguments, and if it returns a non-@code{nil} value, then point is not
-a good place to break the line. Two standard functions you can use are
+ The variable @code{fill-nobreak-predicate} is a hook (an abnormal
+hook, @pxref{Hooks}) specifying additional conditions where
+line-breaking is not allowed. Each function is called with no
+arguments, with point at a place where Emacs is considering breaking
+the line. If a function returns a non-@code{nil} value, then that's
+a bad place to break the line. Two standard functions you can use are
@code{fill-single-word-nobreak-p} (don't break after the first word of
a sentence or before the last) and @code{fill-french-nobreak-p} (don't
break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}).
@findex set-fill-prefix
To specify a fill prefix for the current buffer, move to a line that
starts with the desired prefix, put point at the end of the prefix,
-and give the command @w{@kbd{C-x .}}@: (@code{set-fill-prefix}).
-That's a period after the @kbd{C-x}. To turn off the fill prefix,
-specify an empty prefix: type @w{@kbd{C-x .}}@: with point at the
-beginning of a line.@refill
+and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period
+after the @kbd{C-x}.) To turn off the fill prefix, specify an empty
+prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line.
When a fill prefix is in effect, the fill commands remove the fill
-prefix from each line before filling and insert it on each line after
-filling. Auto Fill mode also inserts the fill prefix automatically when
-it makes a new line. The @kbd{C-o} command inserts the fill prefix on
-new lines it creates, when you use it at the beginning of a line
-(@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes the
-prefix (if it occurs) after the newline that it deletes
+prefix from each line of the paragraph before filling and insert it on
+each line after filling. (The beginning of the first line of the
+paragraph is left unchanged, since often that is intentionally
+different.) Auto Fill mode also inserts the fill prefix automatically
+when it makes a new line. The @kbd{C-o} command inserts the fill
+prefix on new lines it creates, when you use it at the beginning of a
+line (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes
+the prefix (if it occurs) after the newline that it deletes
(@pxref{Indentation}).
For example, if @code{fill-column} is 40 and you set the fill prefix
automatically by setting the variable @code{adaptive-fill-function} to a
function. This function is called with point after the left margin of a
line, and it should return the appropriate fill prefix based on that
-line. If it returns @code{nil}, that means it sees no fill prefix in
-that line.
+line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets
+a chance to find a prefix.
+
+@node Refill
+@subsection Refill Mode
+@cindex refilling text, word processor style
+@cindex modes, Refill
+@cindex Refill minor mode
+
+ Refill minor mode provides support for keeping paragraphs filled as
+you type or modify them in other ways. It provides an effect similar
+to typical word processor behavior. This works by running a
+paragraph-filling command at suitable times.
+
+ To toggle the use of Refill mode in the current buffer, type
+@kbd{M-x refill-mode}. When you are typing text, only characters
+which normally trigger auto filling, like the space character, will
+trigger refilling. This is to avoid making it too slow. Apart from
+self-inserting characters, other commands which modify the text cause
+refilling.
+
+ The current implementation is preliminary and not robust. You can
+get better ``line wrapping'' behavior using Longlines mode.
+@xref{Longlines}. However, Longlines mode has an important
+side-effect: the newlines that it inserts for you are not saved to
+disk, so the files that you make with Longlines mode will appear to be
+completely unfilled if you edit them without Longlines mode.
+
+@node Longlines
+@subsection Long Lines Mode
+@cindex refilling text, word processor style
+@cindex modes, Long Lines
+@cindex word wrap
+@cindex Long Lines minor mode
+
+ Long Lines mode is a minor mode for @dfn{word wrapping}; it lets you
+edit ``unfilled'' text files, which Emacs would normally display as a
+bunch of extremely long lines. Many text editors, such as those built
+into many web browsers, normally do word wrapping.
+
+@findex longlines-mode
+ To enable Long Lines mode, type @kbd{M-x longlines-mode}. If the
+text is full of long lines, this will ``wrap'' them
+immediately---i.e., break up to fit in the window. As you edit the
+text, Long Lines mode automatically re-wraps lines by inserting or
+deleting @dfn{soft newlines} as necessary (@pxref{Hard and Soft
+Newlines}.) These soft newlines won't show up when you save the
+buffer into a file, or when you copy the text into the kill ring,
+clipboard, or a register.
+
+@findex longlines-auto-wrap
+ Word wrapping is @emph{not} the same as ordinary filling
+(@pxref{Fill Commands}). It does not contract multiple spaces into a
+single space, recognize fill prefixes (@pxref{Fill Prefix}), or
+perform adaptive filling (@pxref{Adaptive Fill}). The reason for this
+is that a wrapped line is still, conceptually, a single line. Each
+soft newline is equivalent to exactly one space in that long line, and
+vice versa. However, you can still call filling functions such as
+@kbd{M-q}, and these will work as expected, inserting soft newlines
+that won't show up on disk or when the text is copied. You can even
+rely entirely on the normal fill commands by turning off automatic
+line wrapping, with @kbd{C-u M-x longlines-auto-wrap}. To turn
+automatic line wrapping back on, type @kbd{M-x longlines-auto-wrap}.
+
+@findex longlines-show-hard-newlines
+ Type @kbd{RET} to insert a hard newline, one which automatic
+refilling will not remove. If you want to see where all the hard
+newlines are, type @kbd{M-x longlines-show-hard-newlines}. This will
+mark each hard newline with a special symbol. The same command with a
+prefix argument turns this display off.
+
+ Long Lines mode does not change normal text files that are already
+filled, since the existing newlines are considered hard newlines.
+Before Long Lines can do anything, you need to transform each
+paragraph into a long line. One way is to set @code{fill-column} to a
+large number (e.g., @kbd{C-u 9999 C-x f}), re-fill all the paragraphs,
+and then set @code{fill-column} back to its original value.
@node Case
@section Case Conversion Commands
This is convenient when you have just typed a word in the wrong case: you
can give the case conversion command and continue typing.
- If a word case conversion command is given in the middle of a word, it
-applies only to the part of the word which follows point. This is just
-like what @kbd{M-d} (@code{kill-word}) does. With a negative argument,
-case conversion applies only to the part of the word before point.
+ If a word case conversion command is given in the middle of a word,
+it applies only to the part of the word which follows point. (This is
+comparable to what @kbd{M-d} (@code{kill-word}) does.) With a
+negative argument, case conversion applies only to the part of the
+word before point.
@kindex C-x C-l
@kindex C-x C-u
Text mode turns off the features concerned with comments except when
you explicitly invoke them. It changes the syntax table so that
single-quotes are considered part of words. However, if a word starts
-with single-quotes, then these are treated as a prefix for purposes
-such as capitalization. That is, @kbd{M-c} will convert
-@samp{'hello'} into @samp{'Hello'}, as expected.
+with single-quotes, these are treated as a prefix for purposes such as
+capitalization. That is, @kbd{M-c} will convert @samp{'hello'} into
+@samp{'Hello'}, as expected.
@cindex Paragraph-Indent Text mode
@cindex mode, Paragraph-Indent Text
@findex paragraph-indent-text-mode
@findex paragraph-indent-minor-mode
If you indent the first lines of paragraphs, then you should use
-Paragraph-Indent Text mode rather than Text mode. In this mode, you do
-not need to have blank lines between paragraphs, because the first-line
-indentation is sufficient to start a paragraph; however paragraphs in
-which every line is indented are not supported. Use @kbd{M-x
-paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x
-paragraph-indent-minor-mode} to enter an equivalent minor mode, for
-instance during mail composition.
+Paragraph-Indent Text mode rather than Text mode. In this mode, you
+do not need to have blank lines between paragraphs, because the
+first-line indentation is sufficient to start a paragraph; however
+paragraphs in which every line is indented are not supported. Use
+@kbd{M-x paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x
+paragraph-indent-minor-mode} to enable an equivalent minor mode in
+situations where you can't change the major mode---in mail
+composition, for instance.
@kindex M-TAB @r{(Text mode)}
- Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} as
-the command @code{ispell-complete-word}, which performs completion of
-the partial word in the buffer before point, using the spelling
-dictionary as the space of possible words. @xref{Spelling}.
+ Text mode, and all the modes based on it, define @kbd{M-@key{TAB}}
+as the command @code{ispell-complete-word}, which performs completion
+of the partial word in the buffer before point, using the spelling
+dictionary as the space of possible words. @xref{Spelling}. If your
+window manager defines @kbd{M-@key{TAB}} to switch windows, you can
+type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.
@vindex text-mode-hook
Entering Text mode runs the hook @code{text-mode-hook}. Other major
@code{text-mode-hook} can look at the value of @code{major-mode} to see
which of these modes is actually being entered. @xref{Hooks}.
-@ifinfo
+@ifnottex
Emacs provides two other modes for editing text that is to be passed
through a text formatter to produce fancy formatted printed output.
@xref{Nroff Mode}, for editing input to the formatter nroff.
-@xref{TeX Mode}, for editing input to the formatter TeX.
+@xref{TeX Mode,,@TeX{} Mode}, for editing input to the formatter TeX.
Another mode is used for editing outlines. It allows you to view the
text at various levels of detail. You can view either the outline
headings alone or both headings and text; you can also hide some of the
headings at lower levels from view to make the high level structure more
visible. @xref{Outline Mode}.
-@end ifinfo
+@end ifnottex
@node Outline Mode
@section Outline Mode
outline-mode} to switch to Outline mode as the major mode of the current
buffer.
- When Outline mode makes a line invisible, the line does not appear on
-the screen. The screen appears exactly as if the invisible line were
-deleted, except that an ellipsis (three periods in a row) appears at the
-end of the previous visible line (only one ellipsis no matter how many
-invisible lines follow).
+ When Outline mode makes a line invisible, the line does not appear
+on the screen. The screen appears exactly as if the invisible line
+were deleted, except that an ellipsis (three periods in a row) appears
+at the end of the previous visible line. (Multiple consecutive
+invisible lines produce just one ellipsis.)
Editing commands that operate on lines, such as @kbd{C-n} and
@kbd{C-p}, treat the text of the invisible line as part of the previous
outlines.
* Visibility: Outline Visibility. Commands to control what is visible.
* Views: Outline Views. Outlines and multiple views.
-* Foldout:: Folding editing.
+* Foldout:: Folding means zooming in on outlines.
@end menu
@node Outline Format
deeper heading lines and their body lines is called a @dfn{subtree}.
@vindex outline-regexp
- You can customize the criterion for distinguishing heading lines
-by setting the variable @code{outline-regexp}. Any line whose
-beginning has a match for this regexp is considered a heading line.
-Matches that start within a line (not at the left margin) do not count.
-The length of the matching text determines the level of the heading;
-longer matches make a more deeply nested level. Thus, for example,
-if a text formatter has commands @samp{@@chapter}, @samp{@@section}
-and @samp{@@subsection} to divide the document into chapters and
-sections, you could make those lines count as heading lines by
-setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}.
-Note the trick: the two words @samp{chapter} and @samp{section} are equally
+ You can customize the criterion for distinguishing heading lines by
+setting the variable @code{outline-regexp}. (The recommended ways to
+do this are in a major mode function or with a file local variable.)
+Any line whose beginning has a match for this regexp is considered a
+heading line. Matches that start within a line (not at the left
+margin) do not count.
+
+ The length of the matching text determines the level of the heading;
+longer matches make a more deeply nested level. Thus, for example, if
+a text formatter has commands @samp{@@chapter}, @samp{@@section} and
+@samp{@@subsection} to divide the document into chapters and sections,
+you could make those lines count as heading lines by setting
+@code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note
+the trick: the two words @samp{chapter} and @samp{section} are equally
long, but by defining the regexp to match only @samp{chap} we ensure
that the length of the text matched on a chapter heading is shorter,
-so that Outline mode will know that sections are contained in chapters.
-This works as long as no other command starts with @samp{@@chap}.
+so that Outline mode will know that sections are contained in
+chapters. This works as long as no other command starts with
+@samp{@@chap}.
@vindex outline-level
- You can change the rule for calculating the level of a heading line
-by setting the variable @code{outline-level}. The value of
-@code{outline-level} should be a function that takes no arguments and
-returns the level of the current heading. Some major modes such as C,
-Nroff, and Emacs Lisp mode set this variable and @code{outline-regexp}
-in order to work with Outline minor mode.
+ You can explicitly specify a rule for calculating the level of a
+heading line by setting the variable @code{outline-level}. The value
+of @code{outline-level} should be a function that takes no arguments
+and returns the level of the current heading. The recommended ways to
+set this variable are in a major mode command or with a file local
+variable.
@node Outline Motion
@subsection Outline Motion Commands
similarly backward. Both accept numeric arguments as repeat counts. The
names emphasize that invisible headings are skipped, but this is not really
a special feature. All editing commands that look for lines ignore the
-invisible lines automatically.@refill
+invisible lines automatically.
@findex outline-up-heading
@findex outline-forward-same-level
you can undo right past them. Making lines visible or invisible is simply
not recorded by the undo mechanism.
+ Many of these commands act on the ``current'' heading line. If
+point is on a heading line, that is the current heading line; if point
+is on a body line, the current heading line is the nearest preceding
+header line.
+
@table @kbd
-@item C-c C-t
-Make all body lines in the buffer invisible (@code{hide-body}).
-@item C-c C-a
-Make all lines in the buffer visible (@code{show-all}).
+@item C-c C-c
+Make the current heading line's body invisible (@code{hide-entry}).
+@item C-c C-e
+Make the current heading line's body visible (@code{show-entry}).
@item C-c C-d
-Make everything under this heading invisible, not including this
+Make everything under the current heading invisible, not including the
heading itself (@code{hide-subtree}).
@item C-c C-s
-Make everything under this heading visible, including body,
+Make everything under the current heading visible, including body,
subheadings, and their bodies (@code{show-subtree}).
@item C-c C-l
-Make the body of this heading line, and of all its subheadings,
+Make the body of the current heading line, and of all its subheadings,
invisible (@code{hide-leaves}).
@item C-c C-k
-Make all subheadings of this heading line, at all levels, visible
-(@code{show-branches}).
+Make all subheadings of the current heading line, at all levels,
+visible (@code{show-branches}).
@item C-c C-i
-Make immediate subheadings (one level down) of this heading line
-visible (@code{show-children}).
-@item C-c C-c
-Make this heading line's body invisible (@code{hide-entry}).
-@item C-c C-e
-Make this heading line's body visible (@code{show-entry}).
+Make immediate subheadings (one level down) of the current heading
+line visible (@code{show-children}).
+@item C-c C-t
+Make all body lines in the buffer invisible (@code{hide-body}).
+@item C-c C-a
+Make all lines in the buffer visible (@code{show-all}).
@item C-c C-q
Hide everything except the top @var{n} levels of heading lines
(@code{hide-sublevels}).
@kindex C-c C-c @r{(Outline mode)}
@kindex C-c C-e @r{(Outline mode)}
Two commands that are exact opposites are @kbd{C-c C-c}
-(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They are
-used with point on a heading line, and apply only to the body lines of
-that heading. Subheadings and their bodies are not affected.
+(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They apply
+to the body lines directly following the current heading line.
+Subheadings and their bodies are not affected.
@findex hide-subtree
@findex show-subtree
@kindex C-c C-s @r{(Outline mode)}
@kindex C-c C-d @r{(Outline mode)}
@cindex subtree (Outline mode)
- Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) and
-@kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is
-on a heading line, and both apply to all the lines of that heading's
-@dfn{subtree}: its body, all its subheadings, both direct and indirect, and
-all of their bodies. In other words, the subtree contains everything
-following this heading line, up to and not including the next heading of
-the same or higher rank.@refill
+ Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree})
+and @kbd{C-c C-s} (@code{show-subtree}). Both apply to the current
+heading line's @dfn{subtree}: its body, all its subheadings, both
+direct and indirect, and all of their bodies. In other words, the
+subtree contains everything following the current heading line, up to
+and not including the next heading of the same or higher rank.
@findex hide-leaves
@findex show-branches
A little weaker than @code{show-branches} is @kbd{C-c C-i}
(@code{show-children}). It makes just the direct subheadings
visible---those one level down. Deeper subheadings remain invisible, if
-they were invisible.@refill
+they were invisible.
@findex hide-body
@findex show-all
@kindex C-c C-a @r{(Outline mode)}
Two commands have a blanket effect on the whole file. @kbd{C-c C-t}
(@code{hide-body}) makes all body lines invisible, so that you see just
-the outline structure. @kbd{C-c C-a} (@code{show-all}) makes all lines
-visible. These commands can be thought of as a pair of opposites even
-though @kbd{C-c C-a} applies to more than just body lines.
+the outline structure (as a special exception, it will not hide lines
+at the top of the file, preceding the first header line, even though
+these are technically body lines). @kbd{C-c C-a} (@code{show-all})
+makes all lines visible. These commands can be thought of as a pair
+of opposites even though @kbd{C-c C-a} applies to more than just body
+lines.
@findex hide-sublevels
@kindex C-c C-q @r{(Outline mode)}
@cindex @TeX{} mode
@cindex La@TeX{} mode
@cindex Sli@TeX{} mode
+@cindex Doc@TeX{} mode
@cindex mode, @TeX{}
@cindex mode, La@TeX{}
@cindex mode, Sli@TeX{}
+@cindex mode, Doc@TeX{}
@findex tex-mode
@findex plain-tex-mode
@findex latex-mode
@findex slitex-mode
+@findex doctex-mode
- @TeX{} is a powerful text formatter written by Donald Knuth; it is also
-free, like GNU Emacs. La@TeX{} is a simplified input format for @TeX{},
-implemented by @TeX{} macros; it comes with @TeX{}. Sli@TeX{} is a special
-form of La@TeX{}.@footnote{Sli@TeX{} is obsoleted by the @samp{slides}
-document class in recent La@TeX{} versions.}
+ @TeX{} is a powerful text formatter written by Donald Knuth; it is
+also free software, like GNU Emacs. La@TeX{} is a simplified input
+format for @TeX{}, implemented by @TeX{} macros; it comes with @TeX{}.
+Sli@TeX{} is a special form of La@TeX{}.@footnote{Sli@TeX{} is
+obsoleted by the @samp{slides} document class and other alternative
+packages in recent La@TeX{} versions.} Doc@TeX{} (@file{.dtx}) is a
+special file format in which the La@TeX{} sources are written,
+combining sources with documentation.
Emacs has a special @TeX{} mode for editing @TeX{} input files.
It provides facilities for checking the balance of delimiters and for
invoking @TeX{} on all or part of the file.
@vindex tex-default-mode
- @TeX{} mode has three variants, Plain @TeX{} mode, La@TeX{} mode, and
-Sli@TeX{} mode (these three distinct major modes differ only slightly).
-They are designed for editing the three different formats. The command
-@kbd{M-x tex-mode} looks at the contents of the buffer to determine
-whether the contents appear to be either La@TeX{} input or Sli@TeX{}
-input; if so, it selects the appropriate mode. If the file contents do
-not appear to be La@TeX{} or Sli@TeX{}, it selects Plain @TeX{} mode.
-If the contents are insufficient to determine this, the variable
+ @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode,
+Sli@TeX{} mode, and Doc@TeX{} mode (these distinct major modes differ
+only slightly). They are designed for editing the four different
+formats. The command @kbd{M-x tex-mode} looks at the contents of the
+buffer to determine whether the contents appear to be either La@TeX{}
+input, Sli@TeX{}, or Doc@TeX{} input; if so, it selects the
+appropriate mode. If the file contents do not appear to be La@TeX{},
+Sli@TeX{} or Doc@TeX{}, it selects Plain @TeX{} mode. If the contents
+are insufficient to determine this, the variable
@code{tex-default-mode} controls which mode is used.
When @kbd{M-x tex-mode} does not guess right, you can use the commands
-@kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, and @kbd{M-x
-slitex-mode} to select explicitly the particular variants of @TeX{}
-mode.
+@kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, @kbd{M-x slitex-mode},
+and @kbd{doctex-mode} to select explicitly the particular variants of
+@TeX{} mode.
@menu
* Editing: TeX Editing. Special commands for editing in TeX mode.
C-f} command (@code{tex-view}).
@item C-c C-q
Show the printer queue (@code{tex-show-print-queue}).
+@item C-c C-c
+Invoke some other compilation command on the entire current buffer
+(@code{tex-compile}).
@end table
@findex tex-buffer
you can do so by setting the values of the variables @code{tex-run-command},
@code{latex-run-command}, @code{slitex-run-command},
@code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and
-@code{tex-show-queue-command}. You @emph{must} set the value of
-@code{tex-dvi-view-command} for your particular terminal; this variable
-has no default value. The other variables have default values that may
+@code{tex-show-queue-command}. The default values may
(or may not) be appropriate for your system.
Normally, the file name given to these commands comes at the end of
Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
you see that its output is no longer useful. Using @kbd{C-c C-b} or
-@kbd{C-c C-r} also kills any @TeX{} process still running.@refill
+@kbd{C-c C-r} also kills any @TeX{} process still running.
@findex tex-region
@kindex C-c C-r @r{(@TeX{} mode)}
For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
file for the current buffer's file. Bib@TeX{} looks up bibliographic
citations in a data base and prepares the cited references for the
-bibliography section. The command @kbd{C-c TAB}
+bibliography section. The command @kbd{C-c @key{TAB}}
(@code{tex-bibtex-file}) runs the shell command
(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
current buffer's file. Generally, you need to do @kbd{C-c C-f}
(@code{tex-file}) once to generate the @samp{.aux} file, then do
-@kbd{C-c TAB} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
+@kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
(@code{tex-file}) twice more to get the cross-references correct.
+@findex tex-compile
+@kindex C-c C-c @r{(@TeX{} mode)}
+ To invoke some other compilation program on the current @TeX{}
+buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows
+how to pass arguments to many common programs, including
+@file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can
+select your desired compilation program using the standard completion
+keys (@pxref{Completion}).
+
@node TeX Misc
@subsection @TeX{} Mode Miscellany
Run a shell command (which you must specify) to validate the current
buffer as SGML (@code{sgml-validate}).
-@item C-x TAB
+@item C-c TAB
@kindex C-c TAB @r{(SGML mode)}
@findex sgml-tags-invisible
Toggle the visibility of existing tags in the buffer. This can be
@vindex sgml-xml-mode
SGML mode and HTML mode support XML also. In XML, every opening tag
must have an explicit closing tag. When @code{sgml-xml-mode} is
-non-@code{nil}, SGML mode (and HTML mode) always insert explicit
+non-@code{nil}, SGML mode and HTML mode always insert explicit
closing tags. When you visit a file, these modes determine from the
file contents whether it is XML or not, and set @code{sgml-xml-mode}
accordingly, so that they do the right thing for the file in either
@cindex soft newline
@cindex newlines, hard and soft
+@cindex use-hard-newlines
In formatted text, Emacs distinguishes between two different kinds of
-newlines, @dfn{hard} newlines and @dfn{soft} newlines.
+newlines, @dfn{hard} newlines and @dfn{soft} newlines. (You can enable
+or disable this feature separately in any buffer with the command
+@code{use-hard-newlines}.)
Hard newlines are used to separate paragraphs, or items in a list, or
anywhere that there should always be a line break regardless of the
@subsection Faces in Formatted Text
The Faces submenu lists various Emacs faces including @code{bold},
-@code{italic}, and @code{underline}. Selecting one of these adds the
-chosen face to the region. @xref{Faces}. You can also specify a face
-with these keyboard commands:
+@code{italic}, and @code{underline} (@pxref{Faces}). These menu items
+operate on the region if it is active and nonempty. Otherwise, they
+specify to use that face for an immediately following self-inserting
+character. Instead of the menu, you can use these keyboard commands:
@table @kbd
-@kindex M-g d @r{(Enriched mode)}
+@kindex M-o d @r{(Enriched mode)}
@findex facemenu-set-default
-@item M-g d
-Set the region, or the next inserted character, to the @code{default} face
-(@code{facemenu-set-default}).
-@kindex M-g b @r{(Enriched mode)}
+@item M-o d
+Remove all @code{face} properties from the region (which includes
+specified colors), or force the following inserted character to have no
+@code{face} property (@code{facemenu-set-default}).
+@kindex M-o b @r{(Enriched mode)}
@findex facemenu-set-bold
-@item M-g b
-Set the region, or the next inserted character, to the @code{bold} face
-(@code{facemenu-set-bold}).
-@kindex M-g i @r{(Enriched mode)}
+@item M-o b
+Add the face @code{bold} to the region or to the following inserted
+character (@code{facemenu-set-bold}).
+@kindex M-o i @r{(Enriched mode)}
@findex facemenu-set-italic
-@item M-g i
-Set the region, or the next inserted character, to the @code{italic} face
-(@code{facemenu-set-italic}).
-@kindex M-g l @r{(Enriched mode)}
+@item M-o i
+Add the face @code{italic} to the region or to the following inserted
+character (@code{facemenu-set-italic}).
+@kindex M-o l @r{(Enriched mode)}
@findex facemenu-set-bold-italic
-@item M-g l
-Set the region, or the next inserted character, to the @code{bold-italic} face
-(@code{facemenu-set-bold-italic}).
-@kindex M-g u @r{(Enriched mode)}
+@item M-o l
+Add the face @code{bold-italic} to the region or to the following
+inserted character (@code{facemenu-set-bold-italic}).
+@kindex M-o u @r{(Enriched mode)}
@findex facemenu-set-underline
-@item M-g u
-Set the region, or the next inserted character, to the @code{underline} face
-(@code{facemenu-set-underline}).
-@kindex M-g o @r{(Enriched mode)}
+@item M-o u
+Add the face @code{underline} to the region or to the following inserted
+character (@code{facemenu-set-underline}).
+@kindex M-o o @r{(Enriched mode)}
@findex facemenu-set-face
-@item M-g o @var{face} @key{RET}
-Set the region, or the next inserted character, to the face @var{face}
-(@code{facemenu-set-face}).
+@item M-o o @var{face} @key{RET}
+Add the face @var{face} to the region or to the following inserted
+character (@code{facemenu-set-face}).
@end table
- If you use these commands with a prefix argument---or, in Transient Mark
-mode, if the region is not active---then these commands specify a face
-to use for any immediately following self-inserting input.
-@xref{Transient Mark}. This applies to both the keyboard commands and
-the menu commands.
+ With a prefix argument, all these commands apply to an immediately
+following self-inserting character, disregarding the region.
- Specifying the @code{default} face also resets foreground and
-background color to their defaults.(@pxref{Format Colors}).
+ A self-inserting character normally inherits the @code{face}
+property (and most other text properties) from the preceding character
+in the buffer. If you use the above commands to specify face for the
+next self-inserting character, or the next section's commands to
+specify a foreground or background color for it, then it does not
+inherit the @code{face} property from the preceding character; instead
+it uses whatever you specified. It will still inherit other text
+properties, though.
- Any self-inserting character you type inherits, by default, the face
-properties (as well as most other text properties) of the preceding
-character. Specifying any face property, including foreground or
-background color, for your next self-inserting character will prevent
-it from inheriting any face properties from the preceding character,
-although it will still inherit other text properties. Characters
-inserted by yanking do not inherit text properties.
+ Strictly speaking, these commands apply only to the first following
+self-inserting character that you type. But if you insert additional
+characters after it, they will inherit from the first one. So it
+appears that these commands apply to all of them.
Enriched mode defines two additional faces: @code{excerpt} and
@code{fixed}. These correspond to codes used in the text/enriched file
If you specify a color with a prefix argument---or, in Transient
Mark mode, if the region is not active---then it applies to any
-immediately following self-inserting input. @xref{Transient Mark}.
-Otherwise, the command applies to the region.
+immediately following self-inserting input. Otherwise, the command
+applies to the region.
Each color menu contains one additional item: @samp{Other}. You can use
this item to specify a color that is not listed in the menu; it reads
@findex facemenu-set-foreground
@findex facemenu-set-background
- There are no key bindings for specifying colors, but you can do so
+ There are no predefined key bindings for specifying colors, but you can do so
with the extended commands @kbd{M-x facemenu-set-foreground} and
@kbd{M-x facemenu-set-background}. Both of these commands read the name
of the color with the minibuffer.
Normally, Emacs knows when you are editing formatted text because it
recognizes the special annotations used in the file that you visited.
-However, there are situations in which you must take special actions
-to convert file contents or turn on Enriched mode:
+However, sometimes you must take special actions to convert file
+contents or turn on Enriched mode:
@itemize @bullet
@item
@cindex table mode
@cindex text-based tables
- Table Mode provides an easy and intuitive way to create and edit WYSIWYG
+ Table mode provides an easy and intuitive way to create and edit WYSIWYG
text-based tables. Here is an example of such a table:
@smallexample
+@group
+-----------------+--------------------------------+-----------------+
| Command | Description | Key Binding |
+-----------------+--------------------------------+-----------------+
| |end of buffer, stop and signal | |
| |error. | |
+-----------------+--------------------------------+-----------------+
+@end group
@end smallexample
- Table Mode allows the contents of the table such as this one to be
+ Table mode allows the contents of the table such as this one to be
easily manipulated by inserting or deleting characters inside a cell.
A cell is effectively a localized rectangular edit region and edits to
a cell do not affect the contents of the surrounding cells. If the
@node Table Definition
@subsection What is a Text-based Table?
- Look at the following examples of valid tables as a reference while
-you read this section:
+ Keep the following examples of valid tables in mind as a reference
+while you read this section:
@example
+--+----+---+ +-+ +--+-----+
+-----+--+
@end example
- A table consists of a rectangular frame and the contents inside the
-frame. A table's cells must be at least one character wide and one
-character high with two adjacent cells sharing a boarder line. A cell
-can be subdivided into multiple rectangular cells but cannot nest or
-overlap.
+ A table consists of a rectangular frame whose inside is divided into
+cells. Each cell must be at least one character wide and one
+character high, not counting its border lines. A cell can be
+subdivided into multiple rectangular cells, but cells cannot overlap.
- Both the table frame and cell border lines must consist of one of
-three special characters. The variables that hold these characters
-are described below:
+ The table frame and cell border lines are made of three special
+characters. These variables specify those characters:
@table @code
@vindex table-cell-vertical-char
@enumerate a
@item
-Nested cells are not allowed.
-@item
Overlapped cells or non-rectangular cells are not allowed.
@item
+Same as a.
+@item
The border must be rectangular.
@item
Cells must have a minimum width/height of one character.
@findex table-insert
The command to create a table is @code{table-insert}. When called
interactively, it asks for the number of columns, number of rows, cell
-width and cell height. The number of columns is a number of cells
-within the table's width. The number of rows is the number of cells
-within the table's height. The cell width is a number of characters
-that fit within a cell width. The cell height is a number of lines
-within cell height. While the number of columns and number of rows
-must be an integer number, the cell width and the cell height can be
-either an integer number (when the value is constant across the table)
-or a series of integer numbers, separated by spaces or commas, where
-each number corresponds to each cell width within a row from left to
-right or each cell height within a column from top to bottom.
+width and cell height. The number of columns is the number of cells
+horizontally side by side. The number of rows is the number of cells
+vertically within the table's height. The cell width is a number of
+characters that each cell holds, left to right. The cell height is a
+number of lines each cell holds. The cell width and the cell height
+can be either an integer (when the value is constant across the table)
+or a series of integer, separated by spaces or commas, where each
+number corresponds to the next cell within a row from left to right,
+or the next cell within a column from top to bottom.
@node Table Recognition
@subsection Table Recognition
@findex table-recognize
@findex table-unrecognize
- Table Mode maintains special text properties in the buffer to allow
+ Table mode maintains special text properties in the buffer to allow
editing in a convenient fashion. When a buffer with tables is saved
to its file, these text properties are lost, so when you visit this
file again later, Emacs does not see a table, but just formatted text.
table-recognize} command. It scans the current buffer, recognizes
valid table cells, and attaches appropriate text properties to allow
for table editing. The converse command, @code{table-unrecognize}, is
-used to remove the special text properties and revert the buffer back
+used to remove the special text properties and convert the buffer back
to plain text.
- An optional numeric prefix argument can precede the
-@code{table-recognize} command. If the argument is negative, tables
-in the buffer become inactive. This is equivalent to invoking
-@code{table-unrecognize}.
-
- Similar functions exist to enable or disable tables within a region,
+ Special commands exist to enable or disable tables within a region,
enable or disable individual tables, and enable/disable individual
cells. These commands are:
The commands @code{table-forward-cell} and
@code{table-backward-cell} move point from the current cell to an
adjacent cell forward and backward respectively. The order of the
-cell is wrapped. When point is positioned in the last cell of a
-table, typing @kbd{M-x table-forward-cell} moves point to the first
-cell in the table. Likewise @kbd{M-x table-backward-cell} from the
-first cell in a table moves point to the last cell in the table.
+cells is cyclic: when point is in the last cell of a table, typing
+@kbd{M-x table-forward-cell} moves to the first cell in the table.
+Likewise @kbd{M-x table-backward-cell} from the first cell in a table
+moves to the last cell.
@findex table-span-cell
- The command @code{table-span-cell} spans the current cell into one
-of the four directions---right, left, above or below---and merges the
-current cell with the adjacent cell. It does not allow directions to
-which spanning does not produce a legitimate cell.
+ The command @code{table-span-cell} merges the current cell with the
+adjacent cell in a specified direction---right, left, above or below.
+You specify the direction with the minibuffer. It does not allow
+merges which don't result in a legitimate cell layout.
@findex table-split-cell
@cindex text-based tables, split a cell
The command @code{table-split-cell} splits the current cell
vertically or horizontally. This command is a wrapper to the
direction specific commands @code{table-split-cell-vertically} and
-@code{table-split-cell-horizontally}.
+@code{table-split-cell-horizontally}. You specify the direction with
+a minibuffer argument.
@findex table-split-cell-vertically
The command @code{table-split-cell-vertically} splits the current
@findex table-split-cell-horizontally
The command @code{table-split-cell-horizontally} splits the current
cell horizontally and creates a pair of cells right and left of where
-point is located. If the subject cell to split is not empty the user
-is asked how to handle the cell contents. The three options are:
-@code{split}, @code{left}, or @code{right}. @code{split} splits the
-contents at point literally while the @code{left} and @code{right}
-options move the entire contents into the left or right cell
-respectively.
+point is located. If the cell being split is not empty, this asks you
+how to handle the cell contents. The three options are: @code{split},
+@code{left}, or @code{right}. @code{split} splits the contents at
+point literally, while the @code{left} and @code{right} options move
+the entire contents into the left or right cell respectively.
@cindex enlarge a table cell
@cindex shrink a table cell
- The next four commands enlarge or shrink a cell. These commands
-accept numeric arguments (@pxref{Arguments}) to specify how many
-columns or rows to enlarge or shrink a particular table.
+ The next four commands enlarge or shrink a cell. They use numeric
+arguments (@pxref{Arguments}) to specify how many columns or rows to
+enlarge or shrink a particular table.
@table @kbd
@findex table-heighten-cell
of cell contents is subject to the specified justification.
@findex table-justify
- The command @code{table-justify} requests the user to specify what
-to justify: a cell,a column, or a row. If you select cell
-justification, this command sets the justification only to the current
-cell. Selecting column or row justification set the justification to
-all the cells within a column or row respectively. The command then
-requests the user to enter which justification to apply: @code{left},
-@code{center}, @code{right}, @code{top}, @code{middle}, @code{bottom},
-or @code{none}. The options @code{left}, @code{center}, and
+ The command @code{table-justify} ask you to specify what to justify:
+a cell, a column, or a row. If you select cell justification, this
+command sets the justification only for the current cell. Selecting
+column or row justification sets the justification for all the cells
+within a column or row respectively. The command then ask you which
+kind of justification to apply: @code{left}, @code{center},
+@code{right}, @code{top}, @code{middle}, @code{bottom}, or
+@code{none}. Horizontal justification and vertical justification are
+specified independently. The options @code{left}, @code{center}, and
@code{right} specify horizontal justification while the options
@code{top}, @code{middle}, @code{bottom}, and @code{none} specify
vertical justification. The vertical justification @code{none}
-effectively removes vertical justification while horizontal
-justification must be one of @code{left}, @code{center}, or
-@code{right}. Horizontal justification and vertical justification are
-specified independently.
+effectively removes vertical justification. Horizontal justification
+must be one of @code{left}, @code{center}, or @code{right}.
@vindex table-detect-cell-alignment
Justification information is stored in the buffer as a part of text
convenience feature (turned on by default). During table recognition,
the contents of a cell are examined to determine which justification
was originally applied to the cell and then applies this justification
-to the the cell. This is a speculative algorithm and is therefore not
+to the cell. This is a speculative algorithm and is therefore not
perfect, however, the justification is deduced correctly most of the
-time. If you desire to disable this feature, customize the variable
-@code{table-detect-cell-alignment} to set it to @code{nil}.
+time. To disable this feature, customize the variable
+@code{table-detect-cell-alignment} and set it to @code{nil}.
@node Row Commands
@subsection Commands for Table Rows
pushed down after the newly inserted row. A numeric prefix argument
specifies the number of rows to insert. Note that in order to insert
rows @emph{after} the last row at the bottom of a table, you must
-place point below the table, i.e.@: outside the table, prior to
+place point below the table---that is, outside the table---prior to
invoking this command.
@cindex delete row in table
@cindex insert column in table
@findex table-insert-column
The command @code{table-insert-column} inserts a column of cells to
-the left of the current row in a table. The current column where
-point is located at is pushed right of the newly inserted column. To
-insert a column to the right side of the right most column, place
-point to the right of the rightmost column, which is outside of the
-table, prior to invoking this command. A numeric prefix argument
-specifies the number of columns to insert.
+the left of the current row in a table. This pushes the current
+column to the right. To insert a column to the right side of the
+rightmost column, place point to the right of the rightmost column,
+which is outside of the table, prior to invoking this command. A
+numeric prefix argument specifies the number of columns to insert.
@cindex delete column in table
A command @code{table-delete-column} deletes a column of cells at
@findex table-fixed-width-mode
The command @code{table-fixed-width-mode} toggles fixed width mode
-on and off. When the fixed width mode is turned on, editing inside a
+on and off. When fixed width mode is turned on, editing inside a
cell never changes the cell width; when it is off, the cell width
expands automatically in order to prevent a word from being folded
-into multiple lines. By default, the fixed width mode is turned off.
-
+into multiple lines. By default, fixed width mode is disabled.
@node Table Conversion
@subsection Conversion Between Plain Text and Tables
Recognition}), the original text does not have a table appearance but
may hold a logical table structure. For example, some elements
separated by known patterns form a two dimensional structure which can
-be turned into a table. Look at the numbers below. The numbers are
-horizontally separated by a comma and vertically separated by a
-newline character.
+be turned into a table.
+
+ Here's an example of data that @code{table-capture} can operate on.
+The numbers are horizontally separated by a comma and vertically
+separated by a newline character.
@example
1, 2, 3, 4
@end example
@noindent
-When you invoke @kbd{M-x table-capture} on the above three-line
-region, the region can be turned into the next table:
+Invoking @kbd{M-x table-capture} on that text produces this table:
@example
+-----+-----+-----+-----+
@end example
@noindent
-where @samp{,} is used for a column delimiter regexp, a newline is
-used for a row delimiter regexp, cells are left justified, and minimum
-cell width is 5.
+The conversion uses @samp{,} for the column delimiter and newline for
+a row delimiter, cells are left justified, and minimum cell width is
+5.
@findex table-release
The command @code{table-release} does the opposite of
lines):
@example
-@samp{table-capture} is a powerful command however mastering its power
-requires some practice. Here is a list of items what it can do.
+@samp{table-capture} is a powerful command, but mastering its
+power requires some practice. Here are some things it can do:
Parse Cell Items By using column delimiter regular
expression and raw delimiter regular
@c The first line's right-hand frame in the following two examples
@c sticks out to accommodate for the removal of @samp in the
@c produced output!!
-@example
+@smallexample
+@group
+-----------------------------------------------------------------+
-|@samp{table-capture} is a powerful command however mastering its |
-|power requires some practice. Here is a list of items what it |
-|can do. |
+|@samp{table-capture} is a powerful command, but mastering its |
+|power requires some practice. Here are some things it can do: |
| |
|Parse Cell Items By using column delimiter regular |
| expression and raw delimiter regular |
| the specified region is placed in that |
| cell. |
+-----------------------------------------------------------------+
-@end example
+@end group
+@end smallexample
@noindent
By splitting the cell appropriately we now have a table consisting of
paragraphs occupying its own cell. Each cell can now be edited
independently without affecting the layout of other cells.
-@example
+@smallexample
+-----------------------------------------------------------------+
-|@samp{table-capture} is a powerful command however mastering its |
-|power requires some practice. Here is a list of items what it |
-|can do. |
+|@samp{table-capture} is a powerful command, but mastering its |
+|power requires some practice. Here are some things it can do: |
+---------------------+-------------------------------------------+
|Parse Cell Items |By using column delimiter regular |
| |expression and raw delimiter regular |
| |the specified region is placed in that |
| |cell. |
+---------------------+-------------------------------------------+
-@end example
+@end smallexample
@noindent
By applying @code{table-release}, which does the opposite process, the
@cindex table in language format
@cindex table for HTML and LaTeX
@findex table-generate-source
-The command @code{table-generate-source} generates a table formatted
+ The command @code{table-generate-source} generates a table formatted
for a specific markup language. It asks for a language (which must be
one of @code{html}, @code{latex}, or @code{cals}), a destination
buffer where to put the result, and the table caption (a string), and