emacs documentation

[Tak Ota]

Hello,

Attached is a preliminary version of emacs document that describes how
to use lisp/textmodes/table.el package.  It is written by Paul
Georgief based on my minimum documentation in the original lisp source
code.

Our intention is to place it as one of the subsections under "Commands
for Human Languages" section.  Unfortunately neither Paul or I know
how to write texinfo source so the document is in plain ASCII text.
Could someone please compile it into texinfo source and incorporate
into man directory?  Thank you.

-Tak

Commands for Human Languages


* Text based Table::    Editing text based tables in WYSIWYG fashion.

  Table mode provides an easy and intuitive way to create and edit WYSIWYG
text-based tables.  Below is an example of such a table:

+-----------------+--------------------------------+-----------------+
|     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.                          |                 |
+-----------------+--------------------------------+-----------------+


  Table mode allows the contents of the above table 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 contets
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:


* Definition::          What is a text based table.

  Look at the following examples of valid tables as a reference while
you read this section:

              +--+----+---+     +-+     +--+-----+
              |  |    |   |     | |     |  |     |
              +--+----+---+     +-+     |  +--+--+
              |  |    |   |             |  |  |  |
              +--+----+---+             +--+--+  |
                                        |     |  |
                                        +-----+--+

  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-cell-vertical-char'      Holds the character used for vertical lines.  
                                The default value is `|'.  

`table-cell-horizontal-char'    Holds the character used for horizontal
                                lines.  The default value is `-'.  

`table-cell-intersection-char'  Holds the character used at where
                                horizontal line and vertical line meet.  
                                The default value is `+'.

Based on this definition, the following five tables are examples of invalid
tables:

   +-----+    +-----+       +--+    +-++--+    ++
   |     |    |     |       |  |    | ||  |    ++
   | +-+ |    |     |       |  |    | ||  |
   | | | |    +--+  |    +--+--+    +-++--+
   | +-+ |    |  |  |    |  |  |    +-++--+
   |     |    |  |  |    |  |  |    | ||  |
   +-----+    +--+--+    +--+--+    +-++--+
     (1)        (2)        (3)        (4)      (5)

>From left to right: 1) Nested cells are not allowed.  2) Overlapped cells or
nonrectangular cells are not allowed.  3) The border must be rectanglular.
4) Cells must have a minimum width/height of one character.  5) Same as 4.


* Table Creation::      How to create a table.

  The command to create a table is `table-insert'.  When called interactively
the function 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 space or comma, 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.

`table-insert'  Create and insert a table.


* Table Recognition::   How to activate and deactivate tables.

  A table can be automatically recognized within an emacs buffer by issuing the
`table-recognize' command.  Emacs scans the current buffer, recognizes valid
table cells, and attaches appropriate text properties to allow for table
editing.  The converse operation, `table-unrecognize' is used to remove the 
special
text properties and revert the buffer back to plain text.  

  An optional numeric prefix argument can preceed the `table-recognize' command.
If this value is negative, tables in the buffer become inactive.  This is
equivalent to issuing `table-unrecognize'.

  Similar functions exist to: 1) Enable or disable tables within a region, 2)
Enable or disable individual tables, and 3) Enable individual cells.  These
commands are given here:

`table-recognize-region'     Recognizes tables within the current region and
                             activates them.

`table-unrecognize-region'   Deactivates tables within the current region.

`table-recognize-table'      Recognizes a table under point and activates it.

`table-unrecognize-table'    Deactivates a table under point.

`table-recognize-cell'       Recognizes a cell under point and activates it.

`table-unrecognize-cell'     Deactivates a cell under point.


* Cell Operation::      Special operation in a table cell.

  The command `table-forward-cell' and `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,
issuing `table-forward-cell' moves point to the first cell in the table.
Likewise `table-backward-cell' from the first cell in a table moves point to the
last cell in the table.

  The command `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 `table-split-cell' splits the current cell vertically or
horizontally.  This command is a wrapper to the direction specific commands
`table-split-cell-vertically' and `table-split-cell-horizontally'.

  The command `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. 

  The command `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: `split', `left', or `right'.
`split' splits the contents at point literally while the `left' and `right' 
options
move the entire contents into the left or right cell respectively.

  The next four commands enlarge or shrink a cell.  These commands can take
numeric arguments (see Arguments) to specify how many columns or rows to enlarge
or shrink a particular table.

  `table-heighten-cell' enlarges the current cell vertically.

  `table-shorten-cell' shrinks the current cell vertically.

  `table-widen-cell' enlarges the current cell horizontally.

  `table-narrow-cell' shrinks the current cell horizontally.


* Cell Justification::  Justifying cell contents.

  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 `table-justify' requests the user to specify what to justify: a
`cell',`column', or `row'.  The `cell' options sets the justification only to
the current cell.  The `column' or `row' options set the justification to all
the cells within a column or row respectively.  The command then requsts the
user to enter which justification to apply: `left', `center', `right', `top',
`middle', `bottom', or `none'.  The options `left', `center' and `right' specify
horizontal justification while the options `top', `middle', `bottom' and 'none'
specify vertical justification.  The vertical justification `none' effectively
removes vertical justification while horizontal justification must be one of
`left', `center' or `right'.  Horizontal justification and vertical
justification are specified independently.

  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 alleviate this shortcoming the command `table-recognize'
and other recognition commands 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 set nil to the customizable
variable `table-detect-cell-alignment'.


* Row Operation::       Manipulating Rows of table cell.

  The command `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.  When a numeric prefix argument is present it specifies the
number of rows to insert.  Note that in order to insert rows after the last row
at the bottom of a table, point must be placed below the table, which is outside
of the table, prior to invoking this command.

  The command `table-delete-row' deletes a row of cells at point.  When
a numeric prefix argument is present it specifies the number of rows to
delete.


* Column Operation::    Manipulating Columns of table cell.

  The command `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, point must be placed to the right side of the right most
column, which is outside of the table, prior to invoking this command.

  A command `table-delete-column' deletes a column of cells at point.  When a
numeric prefix argument is present it specifies the number of rows to delete.


* Fixed Width Mode::    Fixing cell width.

  The command `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.  In normal mode the cell width expands automatically in order to
prevent a word from being folded into multiple lines.  As a default the fixed
width mode is turned off.


* Text/Table Conversion::  Converting between plain text and table.

  The command `table-capture' captures plain text in a region and turn it into a
table.  Unlike `table-recognize' 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.

1, 2, 3, 4
5, 6, 7, 8
, 9, 10

When `table-capture' is applied to the above three line region, the region can
be turned into the next table,

+-----+-----+-----+-----+
|1    |2    |3    |4    |
+-----+-----+-----+-----+
|5    |6    |7    |8    |
+-----+-----+-----+-----+
|     |9    |10   |     |
+-----+-----+-----+-----+

where `,' is used for a column delimiter egexp and a newline is used
for a row delimiter regexp and cells are left justified and minimum
cell width is 5.

  The command `table-release' does the opposite of `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 the combination
`table-capture' and `table-release' is to edit a text in layout.  Look at the
following three paragraphs (the latter two are indented with header lines):

`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.

Applying `table-capture' to a region containing the above three
paragraphs with empty strings for column delimiter regexps and row
delimiter regexp, creates a table with a single cell like the
following one.

+-----------------------------------------------------------------+
|`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.                                      |
+-----------------------------------------------------------------+

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.

+-----------------------------------------------------------------+
|`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.                                      |
+---------------------+-------------------------------------------+

By applying `table-release', which does the opposite process, the
contents become once again plain text.  `table-release' works as
a companion command to `table-capture'.


* Measuring Table::     Analyzing table dimension.

  The command `table-query-dimension' analyzes a table structure and
reports information regarding its dimension.  In case of the above example
table, the output from the `table-query-dimension' is:

Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5

This indicates that the current cell is 21 character wide and 6 lines high, the
entire table is 67 characters wide end 16 lines hight.  The table has 2 columns
and 3 rows.  It has total of 5 cells since the first row has a spanned cell.


* Sequence of Cells::   Operation on sequence of cells.

  The command `table-insert-sequence' inserts a string into each cell.  Each
string is a part of a sequence i.e. a series of incrementing integer numbers.


* Source Generation::   Generating table source in a language.
`table-generate-source'


* Compatibility::       Potential issues with other modes.