[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: emacs documentation
|
From: |
Eli Zaretskii |
|
Subject: |
Re: emacs documentation |
|
Date: |
Sat, 23 Oct 2004 23:34:11 +0200 |
> Date: Sat, 23 Oct 2004 21:25:59 +0200
> From: "Eli Zaretskii" <address@hidden>
> Cc: address@hidden, address@hidden, address@hidden
>
> > From: Richard Stallman <address@hidden>
> > Date: Sat, 23 Oct 2004 14:48:39 -0400
> > Cc: address@hidden, Tak Ota <address@hidden>
> >
> > Would someone who knows Texinfo like to work on translating the
> > table.el documentation? It is only around 400 lines long--not
> > a very big job.
>
> I'll do it.
Done. Below is the Texinfo source that I added to the end of
text.texi and committed the result. Please and modify at will.
@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 WYSIWYG
text-based tables. Here is an example of such a table:
@smallexample
+-----------------+--------------------------------+-----------------+
| Command | Description | Key Binding |
+-----------------+--------------------------------+-----------------+
| 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 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.
@menu
* Table Definition:: What is a text based table.
* Table Creation:: How to create a 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 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?
Look at the following examples of valid tables 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.
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:
@table @code
@vindex table-cell-vertical-char
@item table-cell-vertical-char
Holds the character used for vertical lines. The default value is
@samp{|}.
@vindex table-cell-horizontal-char
@item table-cell-horizontal-char
Holds the character used for horizontal lines. The default value 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{+}.
@end table
@noindent
Based on this definition, the following five tables are examples of invalid
tables:
@example
+-----+ +-----+ +--+ +-++--+ ++
| | | | | | | || | ++
| +-+ | | | | | | || |
| | | | +--+ | +--+--+ +-++--+
| +-+ | | | | | | | +-++--+
| | | | | | | | | || |
+-----+ +--+--+ +--+--+ +-++--+
a b c d e
@end example
>From left to right:
@enumerate a
@item
Nested cells are not allowed.
@item
Overlapped cells or non-rectangular cells are not allowed.
@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?
@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 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.
@node Table Recognition
@subsection Table Recognition
@cindex 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 revert 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,
enable or disable individual tables, and enable/disable individual
cells. These commands are:
@table @kbd
@findex table-recognize-region
@item M-x table-recognize-region
Recognize tables within the current region and activate them.
@findex table-unrecognize-region
@item M-x table-unrecognize-region
Deactivate tables within the current region.
@findex table-recognize-table
@item M-x table-recognize-table
Recognize the table under point and activate it.
@findex table-unrecognize-table
@item M-x table-unrecognize-table
Deactivate the table under point.
@findex table-recognize-cell
@item M-x table-recognize-cell
Recognize the cell under point and activate it.
@findex table-unrecognize-cell
@item M-x table-unrecognize-cell
Deactivate the cell under point.
@end table
For another way of converting text into tables, see @ref{Table
Conversion}.
@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
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.
@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.
@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}.
@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 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.
@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.
@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.
@end table
@node Cell Justification
@subsection Cell Justification
@cindex cell text justification
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.
@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
@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.
@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 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}.
@node Row Commands
@subsection Commands for Table Rows
@cindex table row commands
@cindex insert row in table
@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, i.e.@: 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. 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.
@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
@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
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.
@node Table Conversion
@subsection Conversion 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. Look at the numbers below. The numbers are
horizontally separated by a comma and vertically separated by a
newline character.
@example
1, 2, 3, 4
5, 6, 7, 8
, 9, 10
@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:
@example
+-----+-----+-----+-----+
|1 |2 |3 |4 |
+-----+-----+-----+-----+
|5 |6 |7 |8 |
+-----+-----+-----+-----+
| |9 |10 | |
+-----+-----+-----+-----+
@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.
@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):
@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.
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.
@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!!
@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. |
| |
|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. |
+-----------------------------------------------------------------+
@end example
@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
+-----------------------------------------------------------------+
|@samp{table-capture} is a powerful command however mastering its |
|power requires some practice. Here is a list of items what 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. |
+---------------------+-------------------------------------------+
@end example
@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}.
@node Measuring Tables
@subsection Analyzing Table Dimensions
@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:
@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.
@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.
@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
@address@hidden, where @var{lang} is the language you
specified.