@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Text, Programs, Indentation, Top
+@node Text
@chapter Commands for Human Languages
@cindex text
@cindex manipulating text
the file contains ordinary text, use Text mode, which customizes Emacs
in small ways for the syntactic conventions of text. Outline mode
provides special commands for operating on text with an outline
-structure.
+structure. Org mode extends Outline mode and turn Emacs into a
+full-fledged organizer: you can manage TODO lists, store notes and
+publish them in many formats.
+
@iftex
@xref{Outline Mode}.
@end iftex
@cindex mode, nXML
@findex nxml-mode
Emacs has other major modes for text which contains ``embedded''
-commands, such as @TeX{} and La@TeX{} (@pxref{TeX Mode}); HTML and
-SGML (@pxref{HTML Mode}); XML (@pxref{Top,The nXML Mode
-Manual,,nxml-mode, nXML Mode}); and Groff and Nroff (@pxref{Nroff
-Mode}).
+commands, such as @TeX{} and @LaTeX{} (@pxref{TeX Mode}); HTML and
+SGML (@pxref{HTML Mode}); XML
+@ifinfo
+(@pxref{Top,The nXML Mode Manual,,nxml-mode, nXML Mode});
+@end ifinfo
+@ifnotinfo
+(see the nXML mode Info manual, which is distributed with Emacs);
+@end ifnotinfo
+and Groff and Nroff (@pxref{Nroff Mode}).
@cindex ASCII art
If you need to edit pictures made out of text characters (commonly
* Case:: Changing the case of text.
* Text Mode:: The major modes for editing text files.
* Outline Mode:: Editing outlines.
-* TeX Mode:: Editing input to the formatter TeX.
+* Org Mode:: The Emacs organizer.
+* TeX Mode:: Editing TeX and LaTeX files.
* HTML Mode:: Editing HTML and SGML files.
-* Nroff Mode:: Editing input to the formatter nroff.
-* Enriched Text:: Editing text ``enriched'' with fonts, colors, etc.
+* Nroff Mode:: Editing input to the nroff formatter.
+* Enriched Text:: Editing text "enriched" with fonts, colors, etc.
* Text Based Tables:: Commands for editing text-based tables.
* Two-Column:: Splitting text columns into separate windows.
@end menu
following page delimiter in the region is to ensure that.
A numeric argument to @kbd{C-x C-p} specifies which page to go to,
-relative to the current one. Zero means the current page. One means
-the next page, and @minus{}1 means the previous one.
+relative to the current one. Zero means the current page, one
+the next page, and @minus{}1 the previous one.
@kindex C-x l
@findex count-lines-page
specified width. Emacs does filling in two ways. In Auto Fill mode,
inserting text with self-inserting characters also automatically fills
it. There are also explicit fill commands that you can use when editing
-text leaves it unfilled.
+text.
@menu
* Auto Fill:: Auto Fill mode breaks long lines automatically.
newline as the end of a sentence; a period followed by just one space
indicates an abbreviation, not the end of a sentence. Accordingly,
the fill commands will not break a line after a period followed by
-just one space. If you change the variable
-@code{sentence-end-double-space} to a non-@code{nil} value, the fill
-commands will break a line after a period followed by one space, and
-put just one space after each period. @xref{Sentences}, for other
-effects and possible drawbacks of this.
+just one space. If you set the variable
+@code{sentence-end-double-space} to @code{nil}, the fill commands will
+break a line after a period followed by one space, and put just one
+space after each period. @xref{Sentences}, for other effects and
+possible drawbacks of this.
@vindex colon-double-space
If the variable @code{colon-double-space} is non-@code{nil}, the
@kindex C-c C-f @r{(Outline mode)}
@kindex C-c C-b @r{(Outline mode)}
@kindex C-c C-u @r{(Outline mode)}
- The commands @kbd{C-c C-f} (@code{outline-forward-same-level}) and
-@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
-heading line to another visible heading at the same depth in the
-outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves backward to
-another heading that is less deeply nested.
+ @kbd{C-c C-f} (@code{outline-forward-same-level}) and @kbd{C-c C-b}
+(@code{outline-backward-same-level}) move from one heading line to
+another visible heading at the same depth in the outline. @kbd{C-c
+C-u} (@code{outline-up-heading}) moves backward to another heading
+that is less deeply nested.
@node Outline Visibility
@subsection Outline Visibility Commands
@end itemize
@end table
+@c FIXME not marked as a user variable
@vindex foldout-mouse-modifiers
You can specify different modifier keys (instead of
@kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if
To use the Foldout package, you can type @kbd{M-x load-library
@key{RET} foldout @key{RET}}; or you can arrange for to do that
-automatically by putting this in your init file (@pxref{Init File}):
+automatically by putting the following in your init file:
@example
(eval-after-load "outline" '(require 'foldout))
@end example
+@node Org Mode
+@section Org Mode
+@cindex organizer
+@cindex planner
+@findex Org mode
+@findex mode, Org
+
+@findex org-mode
+ Org mode is a variant of Outline mode for using Emacs as an
+organizer and/or authoring system. Files with names ending in the
+extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}).
+To explicitly switch to Org mode, type @kbd{M-x org-mode}.
+
+ In Org mode, as in Outline mode, each entry has a heading line that
+starts with one or more @samp{*} characters. @xref{Outline Format}.
+In addition, any line that begins with the @samp{#} character is
+treated as a comment.
+
+@kindex TAB @r{(Org Mode)}
+@findex org-cycle
+ Org mode provides commands for easily viewing and manipulating the
+outline structure. The simplest of these commands is @key{TAB}
+(@code{org-cycle}). If invoked on a heading line, it cycles through
+the different visibility states of the subtree: (i) showing only that
+heading line, (ii) showing only the heading line and the heading lines
+of its direct children, if any, and (iii) showing the entire subtree.
+If invoked in a body line, the global binding for @key{TAB} is
+executed.
+
+@kindex S-TAB @r{(Org Mode)}
+@findex org-shifttab
+ Typing @key{S-TAB} (@code{org-shifttab}) anywhere in an Org mode
+buffer cycles the visibility of the entire outline structure, between
+(i) showing only top-level heading lines, (ii) showing all heading
+lines but no body lines, and (iii) showing everything.
+
+@kindex M-<up> @r{(Org Mode)}
+@kindex M-<down> @r{(Org Mode)}
+@kindex M-<left> @r{(Org Mode)}
+@kindex M-<right> @r{(Org Mode)}
+@findex org-metaup
+@findex org-metadown
+@findex org-metaleft
+@findex org-metaright
+ You can move an entire entry up or down in the buffer, including its
+body lines and subtree (if any), by typing @kbd{M-<up>}
+(@code{org-metaup}) or @kbd{M-<down>} (@code{org-metadown}) on the
+heading line. Similarly, you can promote or demote a heading line
+with @kbd{M-<left>} (@code{org-metaleft}) and @kbd{M-<right>}
+(@code{org-metaright}). These commands execute their global bindings
+if invoked on a body line.
+
+ The following subsections give basic instructions for using Org mode
+as an organizer and as an authoring system. For details, @pxref{Top,
+The Org Mode Manual, Introduction, org, The Org Manual}.
+
+@menu
+* Org Organizer:: Managing TODO lists and agendas.
+* Org Authoring:: Exporting Org buffers to various formats.
+@end menu
+
+@node Org Organizer
+@subsection Org as an organizer
+@cindex TODO item
+@cindex Org agenda
+
+@kindex C-c C-t @r{(Org Mode)}
+@findex org-todo
+@vindex org-todo-keywords
+ You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c
+C-t} (@code{org-todo}) anywhere in the entry. This adds the keyword
+@samp{TODO} to the heading line. Typing @kbd{C-c C-t} again switches
+the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword
+entirely, and so forth. You can customize the keywords used by
+@kbd{C-c C-t} via the variable @code{org-todo-keywords}.
+
+@kindex C-c C-s @r{(Org Mode)}
+@kindex C-c C-d @r{(Org Mode)}
+@findex org-schedule
+@findex org-deadline
+ Apart from marking an entry as TODO, you can attach a date to it, by
+typing @kbd{C-c C-s} (@code{org-schedule}) in the entry. This prompts
+for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}),
+and then adds the tag @samp{SCHEDULED}, together with the selected
+date, beneath the heading line. The command @kbd{C-c C-d}
+(@code{org-deadline}) has the same effect, except that it uses the tag
+@code{DEADLINE}.
+
+@kindex C-c [ @r{(Org Mode)}
+@findex org-agenda-file-to-front
+@vindex org-agenda-files
+ Once you have some TODO items planned in an Org file, you can add
+that file to the list of @dfn{agenda files} by typing @kbd{C-c [}
+(@code{org-agenda-file-to-front}). Org mode is designed to let you
+easily maintain multiple agenda files, e.g.@: for organizing different
+aspects of your life. The list of agenda files is stored in the
+variable @code{org-agenda-files}.
+
+@findex org-agenda
+ To view items coming from your agenda files, type @kbd{M-x
+org-agenda}. This command prompts for what you want to see: a list of
+things to do this week, a list of TODO items with specific keywords,
+etc.
+@ifnottex
+@xref{Agenda Views,,,org, The Org Manual}, for details.
+@end ifnottex
+
+@node Org Authoring
+@subsection Org as an authoring system
+@cindex Org exporting
+
+@findex org-export
+@kindex C-c C-e @r{(Org mode)}
+ You may want to format your Org notes nicely and to prepare them for
+export and publication. To export the current buffer, type @kbd{C-c
+C-e} (@code{org-export}) anywhere in an Org buffer. This command
+prompts for an export format; currently supported formats include
+HTML, @LaTeX{}, OpenDocument (@file{.odt}), and PDF. Some formats,
+such as PDF, require certain system tools to be installed.
+
+@vindex org-publish-project-alist
+ To export several files at once to a specific directory, either
+locally or over the network, you must define a list of projects
+through the variable @code{org-publish-project-alist}. See its
+documentation for details.
+
+ Org supports a simple markup scheme for applying text formatting to
+exported documents:
+
+@example
+- This text is /emphasized/
+- This text is *in bold*
+- This text is _underlined_
+- This text uses =a teletype font=
+
+#+begin_quote
+``This is a quote.''
+#+end_quote
+
+#+begin_example
+This is an example.
+#+end_example
+@end example
+
+ For further details, @ref{Exporting,,,org, The Org Manual}, and
+@ref{Publishing,,,org, The Org Manual}.
+
@node TeX Mode
@section @TeX{} Mode
@cindex @TeX{} mode
-@cindex La@TeX{} mode
+@cindex @LaTeX{} mode
@cindex Sli@TeX{} mode
@cindex Doc@TeX{} mode
@cindex mode, @TeX{}
-@cindex mode, La@TeX{}
+@cindex mode, @LaTeX{}
@cindex mode, Sli@TeX{}
@cindex mode, Doc@TeX{}
@findex tex-mode
Emacs provides special major modes for editing files written in
@TeX{} and its related formats. @TeX{} is a powerful text formatter
written by Donald Knuth; like GNU Emacs, it is free software.
-La@TeX{} is a simplified input format for @TeX{}, implemented using
+@LaTeX{} is a simplified input format for @TeX{}, implemented using
@TeX{} macros. Doc@TeX{} is a special file format in which the
-La@TeX{} sources are written, combining sources with documentation.
-Sli@TeX{} is an obsolete special form of La@TeX{}.@footnote{It has
+@LaTeX{} sources are written, combining sources with documentation.
+Sli@TeX{} is an obsolete special form of @LaTeX{}.@footnote{It has
been replaced by the @samp{slides} document class, which comes with
-La@TeX{}.}
+@LaTeX{}.}
@vindex tex-default-mode
- @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode,
+ @TeX{} mode has four variants: Plain @TeX{} mode, @LaTeX{} mode,
Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ
only slightly, and are designed for editing the four different
formats. Emacs selects the appropriate mode by looking at the
@itemize @bullet
@item
Bib@TeX{} mode is a major mode for Bib@TeX{} files, which are commonly
-used for keeping bibliographic references for La@TeX{} documents. For
+used for keeping bibliographic references for @LaTeX{} documents. For
more information, see the documentation string for the command
@code{bibtex-mode}.
@item
-The Ref@TeX{} package provides a minor mode which can be used in
-conjunction with La@TeX{} mode to manage bibliographic references.
+The Ref@TeX{} package provides a minor mode which can be used with
+@LaTeX{} mode to manage bibliographic references.
@ifinfo
@xref{Top,The Ref@TeX{} Manual,,reftex}.
@end ifinfo
point, and inserts two newlines to start a new paragraph. It outputs
a message in the echo area if any mismatch is found. @kbd{M-x
tex-validate-region} checks a region, paragraph by paragraph. The
-errors are listed in an @samp{*Occur*} buffer; you can use the usual
+errors are listed in an @file{*Occur*} buffer; you can use the usual
Occur mode commands in that buffer, such as @kbd{C-c C-c}, to visit a
particular mismatch (@pxref{Other Repeating Search}).
to work with them.
@node LaTeX Editing
-@subsection La@TeX{} Editing Commands
+@subsection @LaTeX{} Editing Commands
- La@TeX{} mode provides a few extra features not applicable to plain
+ @LaTeX{} mode provides a few extra features not applicable to plain
@TeX{}:
@table @kbd
@item C-c C-o
-Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position
+Insert @samp{\begin} and @samp{\end} for @LaTeX{} block and position
point on a line between them (@code{tex-latex-block}).
@item C-c C-e
-Close the innermost La@TeX{} block not yet closed
+Close the innermost @LaTeX{} block not yet closed
(@code{tex-close-latex-block}).
@end table
@findex tex-latex-block
-@kindex C-c C-o @r{(La@TeX{} mode)}
- In La@TeX{} input, @samp{\begin} and @samp{\end} tags are used to
+@kindex C-c C-o @r{(@LaTeX{} mode)}
+ In @LaTeX{} input, @samp{\begin} and @samp{\end} tags are used to
group blocks of text. To insert a block, type @kbd{C-c C-o}
(@code{tex-latex-block}). This prompts for a block type, and inserts
the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a
@vindex latex-block-names
When entering the block type argument to @kbd{C-c C-o}, you can use
the usual completion commands (@pxref{Completion}). The default
-completion list contains the standard La@TeX{} block types. If you
+completion list contains the standard @LaTeX{} block types. If you
want additional block types for completion, customize the list
variable @code{latex-block-names}.
@findex tex-close-latex-block
-@kindex C-c C-e @r{(La@TeX{} mode)}
- In La@TeX{} input, @samp{\begin} and @samp{\end} tags must balance.
+@kindex C-c C-e @r{(@LaTeX{} mode)}
+@findex latex-electric-env-pair-mode
+ In @LaTeX{} input, @samp{\begin} and @samp{\end} tags must balance.
You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an
@samp{\end} tag which matches the last unmatched @samp{\begin}. It
also indents the @samp{\end} to match the corresponding @samp{\begin},
and inserts a newline after the @samp{\end} tag if point is at the
-beginning of a line.
+beginning of a line. The minor mode @code{latex-electric-env-pair-mode}
+automatically inserts an @samp{\end} or @samp{\begin} tag for you
+when you type the corresponding one.
@node TeX Print
@subsection @TeX{} Printing Commands
The buffer's @TeX{} variant determines what shell command @kbd{C-c
C-b} actually runs. In Plain @TeX{} mode, it is specified by the
variable @code{tex-run-command}, which defaults to @code{"tex"}. In
-La@TeX{} mode, it is specified by @code{latex-run-command}, which
+@LaTeX{} mode, it is specified by @code{latex-run-command}, which
defaults to @code{"latex"}. The shell command that @kbd{C-c C-v} runs
to view the @file{.dvi} output is determined by the variable
@code{tex-dvi-view-command}, regardless of the @TeX{} variant. The
@findex tex-recenter-output-buffer
@kindex C-c C-l @r{(@TeX{} mode)}
The terminal output from @TeX{}, including any error messages,
-appears in a buffer called @samp{*tex-shell*}. If @TeX{} gets an
+appears in a buffer called @file{*tex-shell*}. If @TeX{} gets an
error, you can switch to this buffer and feed it input (this works as
in Shell mode; @pxref{Interactive Shell}). Without switching to this
buffer you can scroll it so that its last line is visible by typing
If @samp{%**start of header} does not appear within the first 100 lines of
the buffer, @kbd{C-c C-r} assumes that there is no header.
- In La@TeX{} mode, the header begins with @samp{\documentclass} or
+ In @LaTeX{} mode, the header begins with @samp{\documentclass} or
@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
-are commands that La@TeX{} requires you to use in any case, so nothing
+are commands that @LaTeX{} requires you to use in any case, so nothing
special needs to be done to identify the header.
@findex tex-file
@findex tex-bibtex-file
@kindex C-c TAB @r{(@TeX{} mode)}
@vindex tex-bibtex-command
- For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
+ For @LaTeX{} 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 @key{TAB}}
@kindex C-c / @r{(SGML mode)}
@findex sgml-close-tag
Insert a close tag for the innermost unterminated tag
-(@code{sgml-close-tag}). If called from within a tag or a comment,
-close this element instead of inserting a close tag.
+(@code{sgml-close-tag}). If called within a tag or a comment,
+close it instead of inserting a close tag.
@item C-c 8
@kindex C-c 8 @r{(SGML mode)}
@file{.xml}. For XHTML files, which have the extension @file{.xhtml},
Emacs uses HTML mode by default; you can make it use nXML mode by
customizing the variable @code{auto-mode-alist} (@pxref{Choosing
-Modes}). nXML mode is described in its own manual: @xref{Top, nXML
+Modes}).
+@ifinfo
+nXML mode is described in its own manual: @xref{Top, nXML
Mode,,nxml-mode, nXML Mode}.
+@end ifinfo
+@ifnotinfo
+nXML mode is described in an Info manual, which is distributed with
+Emacs.
+@end ifnotinfo
@vindex sgml-xml-mode
You may choose to use the less powerful SGML mode for editing XML,
@cindex nroff
@findex nroff-mode
- Nroff mode is a mode like Text mode but modified to handle nroff commands
-present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
-differs from Text mode in only a few ways. All nroff command lines are
-considered paragraph separators, so that filling will never garble the
-nroff commands. Pages are separated by @samp{.bp} commands. Comments
-start with backslash-doublequote. Also, three special commands are
-provided that are not in Text mode:
+@vindex nroff-mode-hook
+ Nroff mode, a major mode derived from Text mode, is
+specialized for editing nroff files (e.g.@: Unix man pages). Type
+@kbd{M-x nroff-mode} to enter this mode. Entering Nroff mode runs the
+hook @code{text-mode-hook}, then @code{nroff-mode-hook}
+(@pxref{Hooks}).
+
+ In Nroff mode, nroff command lines are treated as paragraph
+separators, pages are separated by @samp{.bp} commands, and comments
+start with backslash-doublequote. It also defines these commands:
@findex forward-text-line
@findex backward-text-line
@end table
@findex electric-nroff-mode
- The other feature of Nroff mode is that you can turn on Electric Nroff
-mode. This is a minor mode that you can turn on or off with @kbd{M-x
+ Electric Nroff mode is a buffer-local minor mode that can be used
+with Nroff mode. To toggle this minor mode, type @kbd{M-x
electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
-time you use @key{RET} to end a line that contains an nroff command that
-opens a kind of grouping, the matching nroff command to close that
-grouping is automatically inserted on the following line. For example,
-if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
-this inserts the matching command @samp{.)b} on a new line following
-point.
+time you type @key{RET} to end a line containing an nroff command that
+opens a kind of grouping, the nroff command to close that grouping is
+automatically inserted on the following line.
- If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
-heading lines are lines of the form @samp{.H} followed by a number (the
-header level).
-
-@vindex nroff-mode-hook
- Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
-the hook @code{nroff-mode-hook} (@pxref{Hooks}).
+ If you use Outline minor mode with Nroff mode (@pxref{Outline
+Mode}), heading lines are lines of the form @samp{.H} followed by a
+number (the header level).
@node Enriched Text
@section Enriched Text
These margins also affect fill commands such as @kbd{M-q}
(@pxref{Filling}).
- The Indentation submenu of Text Properties provides four commands
+ The Indentation submenu of Text Properties offers commands
for specifying indentation:
@table @code
still indent the left margin.
@end table
+@vindex default-justification
You can also specify justification styles using the Justification
submenu in the Text Properties menu.
-
-@vindex default-justification
The default justification style is specified by the per-buffer
variable @code{default-justification}. Its value should be one of the
symbols @code{left}, @code{right}, @code{full}, @code{center}, or
within the text). The @samp{Remove Special} menu item removes all of
these special properties from the text in the region.
- The @code{invisible} and @code{intangible} properties are @emph{not}
-saved in the text/enriched format. The @code{read-only} property is
-saved, but it is not a standard part of the text/enriched format, so
-other editors may not respect it.
+ The @code{invisible} and @code{intangible} properties are not saved.
@node Text Based Tables
@section Editing Text-based Tables
@cindex table mode
@cindex text-based tables
- Table mode provides an easy and intuitive way to create and edit
-text-based tables. Here is an example of such a table:
+ The @code{table} package provides commands to easily edit text-based
+tables. Here is an example of what such a table looks like:
@smallexample
@group
| forward-char |Move point right N characters | C-f |
| |(left if N is negative). | |
| | | |
-| |On reaching end of buffer, stop | |
-| |and signal error. | |
+-----------------+--------------------------------+-----------------+
| backward-char |Move point left N characters | C-b |
| |(right if N is negative). | |
| | | |
-| |On attempt to pass beginning or | |
-| |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
-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
-contents do not fit into a cell, then the cell is automatically
-expanded in the vertical and/or horizontal directions and the rest of
-the table is restructured and reformatted in accordance with the
-growth of the cell.
+ When Emacs recognizes such a stretch of text as a table
+(@pxref{Table Recognition}), editing the contents of each table cell
+will automatically resize the table, whenever the contents become too
+large to fit in the cell. You can use the commands defined in the
+following sections for navigating and editing the table layout.
+
+@findex table-fixed-width-mode
+ Type @kbd{M-x table-fixed-width-mode} to toggle the automatic table
+resizing feature.
@menu
* Table Definition:: What is a text based table.
* Table Recognition:: How to activate and deactivate tables.
* Cell Commands:: Cell-oriented commands in a table.
* Cell Justification:: Justifying cell contents.
-* Row Commands:: Manipulating rows of table cell.
-* Column Commands:: Manipulating columns of table cell.
-* Fixed Width Mode:: Fixing cell width.
+* Table Rows and Columns:: Inserting and deleting rows and columns.
* Table Conversion:: Converting between plain text and tables.
-* Measuring Tables:: Analyzing table dimension.
* Table Misc:: Table miscellany.
@end menu
@node Table Definition
@subsection What is a Text-based Table?
+@cindex cells, for text-based tables
- Keep the following examples of valid tables in mind as a reference
-while you read this section:
+ A @dfn{table} consists of a rectangular text area which is divided
+into @dfn{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 more cells, but they cannot overlap.
-@example
- +--+----+---+ +-+ +--+-----+
- | | | | | | | | |
- +--+----+---+ +-+ | +--+--+
- | | | | | | | |
- +--+----+---+ +--+--+ |
- | | |
- +-----+--+
-@end example
-
- 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.
-
- The table frame and cell border lines are made of three special
-characters. These variables specify those characters:
+ Cell border lines are drawn with three special characters, specified
+by the following variables:
@table @code
@vindex table-cell-vertical-char
@item table-cell-vertical-char
-Holds the character used for vertical lines. The default value is
-@samp{|}.
+The character used for vertical lines. The default is @samp{|}.
@vindex table-cell-horizontal-chars
@item table-cell-horizontal-chars
-Holds the characters used for horizontal lines. The default value is
-@samp{"-="}.
+The characters used for horizontal lines. The default is @samp{"-="}.
@vindex table-cell-intersection-char
@item table-cell-intersection-char
-Holds the character used at where horizontal line and vertical line
-meet. The default value is @samp{+}.
+The character used for the intersection of horizontal and vertical
+lines. The default is @samp{+}.
@end table
@noindent
-Based on this definition, the following five tables are examples of invalid
-tables:
+The following are examples of @emph{invalid} tables:
@example
- +-----+ +-----+ +--+ +-++--+ ++
- | | | | | | | || | ++
- | +-+ | | | | | | || |
- | | | | +--+ | +--+--+ +-++--+
- | +-+ | | | | | | | +-++--+
- | | | | | | | | | || |
- +-----+ +--+--+ +--+--+ +-++--+
- a b c d e
+ +-----+ +--+ +-++--+
+ | | | | | || |
+ | | | | | || |
+ +--+ | +--+--+ +-++--+
+ | | | | | | +-++--+
+ | | | | | | | || |
+ +--+--+ +--+--+ +-++--+
+ a b c
@end example
+@noindent
From left to right:
@enumerate a
@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.
-@item
-Same as d.
@end enumerate
@node Table Creation
-@subsection How to Create a Table?
+@subsection Creating a Table
@cindex create a text-based table
@cindex table creation
@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 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.
+ To create a text-based table from scratch, type @kbd{M-x
+table-insert}. This command prompts for the number of table columns,
+the number of table rows, cell width and cell height. The cell width
+and cell height do not include the cell borders; each can be specified
+as a single integer (which means each cell is given the same
+width/height), or as a sequence of integers separated by spaces or
+commas (which specify the width/height of the individual table
+columns/rows, counting from left to right for table columns and from
+top to bottom for table rows). The specified table is then inserted
+at point.
+
+ The table inserted by @kbd{M-x table-insert} contains special text
+properties, which tell Emacs to treat it specially as a text-based
+table. If you save the buffer to a file and visit it again later,
+those properties are lost, and the table appears to Emacs as an
+ordinary piece of text. See the next section, for how to convert it
+back into a table.
@node Table Recognition
@subsection Table Recognition
@findex table-recognize
@findex table-unrecognize
- 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.
-To resurrect the table text properties, issue the @kbd{M-x
-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 convert the buffer back
-to plain text.
-
- Special commands exist to enable or disable tables within a region,
-enable or disable individual tables, and enable/disable individual
-cells. These commands are:
+ Existing text-based tables in a buffer, which lack the special text
+properties applied by @kbd{M-x table-insert}, are not treated
+specially as tables. To apply those text properties, type @kbd{M-x
+table-recognize}. This command scans the current buffer,
+@dfn{recognizes} valid table cells, and applies the relevant text
+properties. Conversely, type @kbd{M-x table-unrecognize} to
+@dfn{unrecognize} all tables in the current buffer, removing the
+special text properties and converting tables back to plain text.
+
+ You can also use the following commands to selectively recognize or
+unrecognize tables:
@table @kbd
@findex table-recognize-region
@item M-x table-recognize-region
-Recognize tables within the current region and activate them.
+Recognize tables within the current region.
+
@findex table-unrecognize-region
@item M-x table-unrecognize-region
-Deactivate tables within the current region.
+Unrecognize tables within the current region.
+
@findex table-recognize-table
@item M-x table-recognize-table
Recognize the table at point and activate it.
+
@findex table-unrecognize-table
@item M-x table-unrecognize-table
Deactivate the table at point.
+
@findex table-recognize-cell
@item M-x table-recognize-cell
Recognize the cell at point and activate it.
+
@findex table-unrecognize-cell
@item M-x table-unrecognize-cell
Deactivate the cell at point.
@end table
- For another way of converting text into tables, see @ref{Table
-Conversion}.
+ @xref{Table Conversion}, for another way to recognize a table.
@node Cell Commands
@subsection Commands for Table Cells
@findex table-forward-cell
@findex table-backward-cell
- 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
-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.
+ The commands @kbd{M-x table-forward-cell} and @kbd{M-x
+table-backward-cell} move point from the current cell to an adjacent
+cell. The order is cyclic: when point is in the last cell of a table,
+@kbd{M-x table-forward-cell} moves to the first cell. Likewise, when
+point is on the first cell, @kbd{M-x table-backward-cell} moves to the
+last cell.
@findex table-span-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.
+ @kbd{M-x table-span-cell} prompts for a direction---right, left,
+above, or below---and merges the current cell with the adjacent cell
+in that direction. This command signals an error if the merge would
+result in an illegitimate cell layout.
@findex table-split-cell
-@cindex text-based tables, split a cell
-@cindex split table 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}. You specify the direction with
-a minibuffer argument.
-
@findex table-split-cell-vertically
- The command @code{table-split-cell-vertically} splits the current
-cell vertically and creates a pair of cells above and below where
-point is located. The content in the original cell is split as well.
-
@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 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. They use numeric
-arguments (@pxref{Arguments}) to specify how many columns or rows to
-enlarge or shrink a particular table.
+@cindex text-based tables, splitting cells
+@cindex splitting table cells
+ @kbd{M-x table-split-cell} splits the current cell vertically or
+horizontally, prompting for the direction with the minibuffer. To
+split in a specific direction, use @kbd{M-x
+table-split-cell-vertically} and @kbd{M-x
+table-split-cell-horizontally}. When splitting vertically, the old
+cell contents are automatically split between the two new cells. When
+splitting horizontally, you are prompted for how to divide the cell
+contents, if the cell is non-empty; the options are @samp{split}
+(divide the contents at point), @samp{left} (put all the contents in
+the left cell), and @samp{right} (put all the contents in the right
+cell).
+
+ The following commands enlarge or shrink a cell. By default, they
+resize by one row or column; if a numeric argument is supplied, that
+specifies the number of rows or columns to resize by.
@table @kbd
@findex table-heighten-cell
@item M-x table-heighten-cell
Enlarge the current cell vertically.
+
@findex table-shorten-cell
@item M-x table-shorten-cell
Shrink the current cell vertically.
+
@findex table-widen-cell
@item M-x table-widen-cell
Enlarge the current cell horizontally.
+
@findex table-narrow-cell
@item M-x table-narrow-cell
Shrink the current cell horizontally.
@node Cell Justification
@subsection Cell Justification
-@cindex cell text justification
+@cindex justification in text-based tables
- You can specify text justification for each cell. The justification
-is remembered independently for each cell and the subsequent editing
-of cell contents is subject to the specified justification.
+ The command @kbd{M-x table-justify} imposes @dfn{justification} on
+one or more cells in a text-based table. Justification determines how
+the text in the cell is aligned, relative to the edges of the cell.
+Each cell in a table can be separately justified.
@findex table-justify
- 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. Horizontal justification
-must be one of @code{left}, @code{center}, or @code{right}.
+ @kbd{M-x table-justify} first prompts for what to justify; the
+options are @samp{cell} (just the current cell), @samp{column} (all
+cells in the current table column) and @samp{row} (all cells in the
+current table row). The command then prompts for the justification
+style; the options are @code{left}, @code{center}, @code{right},
+@code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no
+vertical justification).
+
+ Horizontal and vertical justification styles are specified
+independently, and both types can be in effect simultaneously; for
+instance, you can call @kbd{M-x table-justify} twice, once to specify
+@code{right} justification and once to specify @code{bottom}
+justification, to align the contents of a cell to the bottom right.
@vindex table-detect-cell-alignment
- Justification information is stored in the buffer as a part of text
-property. Therefore, this information is ephemeral and does not
-survive through the loss of the buffer (closing the buffer and
-revisiting the buffer erase any previous text properties). To
-countermand for this, the command @code{table-recognize} and other
-recognition commands (@pxref{Table Recognition}) are equipped with a
-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 cell. This is a speculative algorithm and is therefore not
-perfect, however, the justification is deduced correctly most of the
-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
-@cindex table row commands
-
-@cindex insert row in table
+ The justification style is stored in the buffer as a text property,
+and is lost when you kill the buffer or exit Emacs. However, the
+table recognition commands, such as @kbd{M-x table-recognize}
+(@pxref{Table Recognition}), attempt to determine and re-apply each
+cell's justification style, by examining its contents. To disable
+this feature, change the variable @code{table-detect-cell-alignment}
+to @code{nil}.
+
+@node Table Rows and Columns
+@subsection Table Rows and Columns
+@cindex inserting rows and columns in text-based tables
+
@findex table-insert-row
- The command @code{table-insert-row} inserts a row of cells before
-the current row in a table. The current row where point is located is
-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---that is, outside the table---prior to
-invoking this command.
-
-@cindex delete row in table
-@findex table-delete-row
- The command @code{table-delete-row} deletes a row of cells at point.
-A numeric prefix argument specifies the number of rows to delete.
-
-@node Column Commands
-@subsection Commands for Table Columns
-@cindex table column commands
-
-@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. 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
-point. A numeric prefix argument specifies the number of columns to
-delete.
-
-@node Fixed Width Mode
-@subsection Fix Width of Cells
-@cindex fix width of table cells
+ @kbd{M-x table-insert-row} inserts a row of cells before the current
+table row. The current row, together with point, is pushed down past
+the new row. To insert a row after the last row at the bottom of a
+table, invoke this command with point below the table, just below the
+bottom edge. You can insert more than one row at a time by using a
+numeric prefix argument.
-@findex table-fixed-width-mode
- The command @code{table-fixed-width-mode} toggles fixed width mode
-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, fixed width mode is disabled.
+@c A numeric prefix argument specifies the number of rows to insert.
+
+@findex table-insert-column
+ Similarly, @kbd{M-x table-insert-column} inserts a column of cells
+to the left of the current table column. To insert a column to the
+right side of the rightmost column, invoke this command with point to
+the right of the rightmost column, outside the table. A numeric
+prefix argument specifies the number of columns to insert.
+
+@cindex deleting rows and column in text-based tables
+ @kbd{M-x table-delete-column} deletes the column of cells at point.
+Similarly, @kbd{M-x table-delete-row} deletes the row of cells at
+point. A numeric prefix argument to either command specifies the
+number of columns or rows to delete.
@node Table Conversion
-@subsection Conversion Between Plain Text and Tables
+@subsection Converting Between Plain Text and Tables
@cindex text to table
@cindex table to text
@findex table-capture
- The command @code{table-capture} captures plain text in a region and
-turns it into a table. Unlike @code{table-recognize} (@pxref{Table
-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.
+ The command @kbd{M-x table-capture} captures plain text in a region
+and turns it into a table. Unlike @kbd{M-x table-recognize}
+(@pxref{Table Recognition}), the original text does not need to have a
+table appearance; it only needs to have a logical table-like
+structure.
- 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.
+ For example, suppose we have the following numbers, which are
+divided into three lines and separated horizontally by commas:
@example
1, 2, 3, 4
+-----+-----+-----+-----+
@end example
-@noindent
-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
-@code{table-capture}. It releases a table by removing the table frame
-and cell borders. This leaves the table contents as plain text. One
-of the useful applications of @code{table-capture} and
-@code{table-release} is to edit a text in layout. Look at the
-following three paragraphs (the latter two are indented with header
-lines):
+ @kbd{M-x table-release} does the opposite: it converts a table back
+to plain text, removing its cell borders.
+
+ One application of this pair of commands is to edit a text in
+layout. Look at the following three paragraphs (the latter two are
+indented with header lines):
@example
table-capture is a powerful command.
Here are some things it can do:
-Parse Cell Items By using column delimiter regular
- expression and raw delimiter regular
- expression, it parses the specified text
- area and extracts cell items from
- non-table text and then forms a table out
- of them.
-
-Capture Text Area When no delimiters are specified it
- creates a single cell table. The text in
- the specified region is placed in that
- cell.
+Parse Cell Items Using row and column delimiter regexps,
+ it parses the specified text area and
+ extracts cell items into a table.
@end example
@noindent
-Applying @code{table-capture} to a region containing the above three
-paragraphs, with empty strings for column delimiter regexp and row
-delimiter regexp, creates a table with a single cell like the
-following one.
-
-@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!!
+Applying @code{table-capture} to a region containing the above text,
+with empty strings for the column and row delimiter regexps, creates a
+table with a single cell like the following one.
+
@smallexample
@group
-+-------------------------------------------------------------+
-|table-capture is a powerful command. |
-|Here are some things it can do: |
-| |
-|Parse Cell Items By using column delimiter regular |
-| expression and raw delimiter regular |
-| expression, it parses the specified text |
-| area and extracts cell items from |
-| non-table text and then forms a table out |
-| of them. |
-| |
-|Capture Text Area When no delimiters are specified it |
-| creates a single cell table. The text in |
-| the specified region is placed in that |
-| cell. |
-+-------------------------------------------------------------+
++----------------------------------------------------------+
+|table-capture is a powerful command. |
+|Here are some things it can do: |
+| |
+|Parse Cell Items Using row and column delimiter regexps,|
+| it parses the specified text area and |
+| extracts cell items into a table. |
++----------------------------------------------------------+
@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.
+We can then use the cell splitting commands (@pxref{Cell Commands}) to
+subdivide the table so that each paragraph occupies a cell:
@smallexample
-+--------------------------------------------------------------+
-|table-capture is a powerful command. |
-|Here are some things it can do: |
-+------------------+-------------------------------------------+
-|Parse Cell Items |By using column delimiter regular |
-| |expression and raw delimiter regular |
-| |expression, it parses the specified text |
-| |area and extracts cell items from |
-| |non-table text and then forms a table out |
-| |of them. |
-+------------------+-------------------------------------------+
-|Capture Text Area |When no delimiters are specified it |
-| |creates a single cell table. The text in |
-| |the specified region is placed in that |
-| |cell. |
-+------------------+-------------------------------------------+
++----------------------------------------------------------+
+|table-capture is a powerful command. |
+|Here are some things it can do: |
++-----------------+----------------------------------------+
+|Parse Cell Items | Using row and column delimiter regexps,|
+| | it parses the specified text area and |
+| | extracts cell items into a table. |
++-----------------+----------------------------------------+
@end smallexample
@noindent
-By applying @code{table-release}, which does the opposite process, the
-contents become once again plain text. @code{table-release} works as
-a companion command to @code{table-capture}.
+Each cell can now be edited independently without affecting the layout
+of other cells. When finished, we can invoke @kbd{M-x table-release}
+to convert the table back to plain text.
-@node Measuring Tables
-@subsection Analyzing Table Dimensions
-@cindex table dimensions
+@node Table Misc
+@subsection Table Miscellany
+@cindex table dimensions
@findex table-query-dimension
- The command @code{table-query-dimension} analyzes a table structure
-and reports information regarding its dimensions. In case of the
-above example table, the @code{table-query-dimension} command displays
-in echo area:
+ The command @code{table-query-dimension} reports the layout of the
+table and table cell at point. Here is an example of its output:
@smallexample
Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
@end smallexample
@noindent
-This indicates that the current cell is 21 character wide and 6 lines
-high, the entire table is 67 characters wide and 16 lines high. The
-table has 2 columns and 3 rows. It has a total of 5 cells, since the
-first row has a spanned cell.
+This indicates that the current cell is 21 characters wide and 6 lines
+high, the table is 67 characters wide and 16 lines high with 2 columns
+and 3 rows, and a total of 5 cells.
-@node Table Misc
-@subsection Table Miscellany
-
-@cindex insert string into table cells
@findex table-insert-sequence
- The command @code{table-insert-sequence} inserts a string into each
-cell. Each string is a part of a sequence i.e.@: a series of
-increasing integer numbers.
+ @kbd{M-x table-insert-sequence} inserts a string into each cell.
+Each string is a part of a sequence i.e.@: a series of increasing
+integer numbers.
-@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
-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
-then inserts the generated table in the proper syntax into the
-destination buffer. The default destination buffer is
-@code{table.@var{lang}}, where @var{lang} is the language you
-specified.
+ @kbd{M-x 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 in
+which to put the result, and a table caption, and then inserts the
+generated table into the specified buffer. The default destination
+buffer is @code{table.@var{lang}}, where @var{lang} is the language
+you specified.
@node Two-Column
@section Two-Column Editing
@cindex splitting columns
@cindex columns, splitting
- Two-column mode lets you conveniently edit two side-by-side columns of
-text. It uses two side-by-side windows, each showing its own
-buffer.
-
- There are three ways to enter two-column mode:
+ Two-column mode lets you conveniently edit two side-by-side columns
+of text. It uses two side-by-side windows, each showing its own
+buffer. There are three ways to enter two-column mode:
@table @asis
@item @kbd{@key{F2} 2} or @kbd{C-x 6 2}