#+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
#+TITLE:      Org tutorial for tables
#+AUTHOR:     Bastien
#+EMAIL:      bzg AT altern DOT org
#+LANGUAGE:   en
#+PRIORITIES: A C B
#+CATEGORY:   org-tutorial

[[file:../index.org][{Back to Worg's index}]]

This tutorial briefly describes the use of tables with Org.  You can
freely improve this tutorial by editing [[file:~/org/worg/index.org][Worg]].

* Creating a table

** While typing

The easiest way to create a table is to directly type the "|" character
at the beginning of a line, or after any amount of white space.  This
will put you in the first field of an atomic table.

: | This is the content of the first cell

Once you've finished editing this cell, you can jump to the next one by
pressing =TAB=.  Since the row you just started only contains one cell,
the next cell is really the first cell of the next row.

: | This is the content of the first cell |
: | < Here I am after pressing TAB        |

** By creating the structure and filling it

You can also create a table from scratch with =C-c |=.  You will be
asked for the structure of the table, the default being 5x2 (see
=org-table-default-size=), five columns and two rows:

: |   |   |   |   |   |
: |---+---+---+---+---|
: |   |   |   |   |   |

Then you can jump from one field to another with the =TAB= key (jump to
the /next/ cell) or =S-<TAB>= (jump to the /previous/ cell).  =RET= will
jump to the to the next cell in the same colum, and create a new column
if there is no such cell (or if the next row is beyond a separator
line.)

** By converting a region into a table

Org provides useful ways of converting a region into a table.  For this,
select a region and press =C-c |=.  For example, press =C-c |= on this:

: some, comma, separated, values

will automagically produce this:

: | some | comma | separated | values |

Usually, this command should be smart enough to guess what is the field
separator for the region.  If each line of the active region contains a
=TAB= or a comma, it will assume this is the separator.

- If you want to force the comma as a field separator, press =C-u C-c |=.

- If you want to force TAB as a field separator, press =C-u C-u C-c |=.

- If you want to force a specific number of spaces -- say 3 -- use =C-u 3 C-c |=.

* Editing the structure of a table

Editing table with Org is pure magic.

** Moving rows/columns

Let's say for example that you have this basic table:

: | A | B | C |
: | 1 | 2 | 3 |
: | a | b | c |

With the cursor in the A field, pressing =M-<right>= will move the A
column to the right:

: | B | A | C |
: | 2 | 1 | 3 |
: | b | a | c |

With the cursor in the first row, pressing =M-<down>= will move the
first row down:

: | 1 | 2 | 3 |
: | A | B | C |
: | a | b | c |

** Inserting rows/columns

Prefixed with the Shift key, these command will /insert/ a new column or
a new row, instead of moving it.  For example, with the cursor initially
in the =B= cell, =S-M-<right>= will insert a new column between =A= and
=B=

: | A |   | B | C |
: | 1 |   | 2 | 3 |
: | a |   | b | c |

... leaving the cursor in the newly created column.

And =S-M-<down>= when cursor is in the first row will insert a new row
at the beginning of the table:

: |   |   |   |
: | A | B | C |
: | 1 | 2 | 3 |
: | a | b | c |

* Narrowing the visible part of a column

Sometimes cells can get really wide.  If you want to restrict the width
visible width of a cell, you need to add a new row to your table.

: | <10>             | <15>                        |
: | A very wide cell | Another very very wide cell |

Pressing =C-c C-c= on this table will update the display so that the
first and second columns are respectively narrowed to 10 and 15
characters:

: | <10>     | <15>            |
: | A very=> | Another very => |

When columns are narrowed, it might be useful to temporarily see the
content of a cell with =C-u <TAB>= (or =C-u C-c `=) or to edit the
content in a separate window with =C-c `=.

* Preparing tables for export

This table :

: | A | B |
: | 1 | 2 |

will be exported like this:

| A | B |
| 1 | 2 |

** Adding a table header

This table :

: | A | B |
: |---+---|
: | 1 | 2 |

will be exported like this:

| A | B |
|---+---|
| 1 | 2 |

The horizontal line separating the two rows tells the exporter to
consider the first line is the table header.

** Grouping columns

You can group columns like this:

: |   |  N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
: |---+----+-----+-----+-----+---------+------------|
: | / | <> |   < |     |   > |       < |          > |
: | # |  1 |   1 |   1 |   1 |       1 |          1 |
: | # |  2 |   4 |   8 |  16 |  1.4142 |     1.1892 |
: | # |  3 |   9 |  27 |  81 |  1.7321 |     1.3161 |
: |---+----+-----+-----+-----+---------+------------|

Here is the output:

|   |  N | N^2 | N^3 | N^4 | sqrt(n) | sqrt(N) |
|---+----+-----+-----+-----+---------+---------|
| / | <> |   < |     |   > |       < |       > |
| # |  1 |   1 |   1 |   1 |       1 |       1 |
| # |  2 |   4 |   8 |  16 |  1.4142 |  1.1892 |
| # |  3 |   9 |  27 |  81 |  1.7321 |  1.3161 |
|---+----+-----+-----+-----+---------+---------|