org-tutorials/tables.org

   1 #+TITLE:      Org tutorial for tables
   2 #+AUTHOR:     Bastien
   3 #+EMAIL:      bzg AT altern DOT org
   4 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   5 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   6 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   7 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   org-tutorial
  11
  12 # This file is released by its authors and contributors under the GNU
  13 # Free Documentation license v1.3 or later, code examples are released
  14 # under the GNU General Public License v3 or later.
  15
  16 [[file:../index.org][{Back to Worg's index}]]
  17
  18 This tutorial briefly describes the use of tables with Org.  You can
  19 freely improve this tutorial by editing [[file:../index.org][Worg]].
  20
  21 * Creating a table
  22
  23 ** While typing
  24
  25 The easiest way to create a table is to directly type the "|" character
  26 at the beginning of a line, or after any amount of white space.  This
  27 will put you in the first field of an atomic table.
  28
  29 : | This is the content of the first cell
  30
  31 Once you've finished editing this cell, you can jump to the next one by
  32 pressing =TAB=.  Since the row you just started only contains one cell,
  33 the next cell is really the first cell of the next row.
  34
  35 : | This is the content of the first cell |
  36 : | < Here I am after pressing TAB        |
  37
  38 ** By creating the structure and filling it
  39
  40 You can also create a table from scratch with =C-c |=.  You will be
  41 asked for the structure of the table, the default being 5x2 (see
  42 =org-table-default-size=), five columns and two rows:
  43
  44 : |   |   |   |   |   |
  45 : |---+---+---+---+---|
  46 : |   |   |   |   |   |
  47
  48 Then you can jump from one field to another with the =TAB= key (jump to
  49 the /next/ cell) or =S-<TAB>= (jump to the /previous/ cell).  =RET= will
  50 jump to the to the next cell in the same colum, and create a new column
  51 if there is no such cell (or if the next row is beyond a separator
  52 line.)
  53
  54 ** By converting a region into a table
  55
  56 Org provides useful ways of converting a region into a table.  For this,
  57 select a region and press =C-c |=.  For example, press =C-c |= on this:
  58
  59 : some, comma, separated, values
  60
  61 will automagically produce this:
  62
  63 : | some | comma | separated | values |
  64
  65 Usually, this command should be smart enough to guess what is the field
  66 separator for the region.  If each line of the active region contains a
  67 =TAB= or a comma, it will assume this is the separator.
  68
  69 - If you want to force the comma as a field separator, press =C-u C-c |=.
  70
  71 - If you want to force TAB as a field separator, press =C-u C-u C-c |=.
  72
  73 - If you want to force a specific number of spaces -- say 3 -- use =C-u 3 C-c |=.
  74
  75 * Editing the structure of a table
  76
  77 Editing table with Org is pure magic.
  78
  79 ** Moving rows/columns
  80
  81 Let's say for example that you have this basic table:
  82
  83 : | A | B | C |
  84 : | 1 | 2 | 3 |
  85 : | a | b | c |
  86
  87 With the cursor in the A field, pressing =M-<right>= will move the A
  88 column to the right:
  89
  90 : | B | A | C |
  91 : | 2 | 1 | 3 |
  92 : | b | a | c |
  93
  94 With the cursor in the first row, pressing =M-<down>= will move the
  95 first row down:
  96
  97 : | 1 | 2 | 3 |
  98 : | A | B | C |
  99 : | a | b | c |
 100
 101 ** Inserting rows/columns
 102
 103 Prefixed with the Shift key, these command will /insert/ a new column or
 104 a new row, instead of moving it.  For example, with the cursor initially
 105 in the =B= cell, =S-M-<right>= will insert a new column between =A= and
 106 =B=
 107
 108 : | A |   | B | C |
 109 : | 1 |   | 2 | 3 |
 110 : | a |   | b | c |
 111
 112 ... leaving the cursor in the newly created column.
 113
 114 And =S-M-<down>= when cursor is in the first row will insert a new row
 115 at the beginning of the table:
 116
 117 : |   |   |   |
 118 : | A | B | C |
 119 : | 1 | 2 | 3 |
 120 : | a | b | c |
 121
 122 * Narrowing the visible part of a column
 123
 124 Sometimes cells can get really wide.  If you want to restrict the width
 125 visible width of a cell, you need to add a new row to your table.
 126
 127 : | <10>             | <15>                        |
 128 : | A very wide cell | Another very very wide cell |
 129
 130 Pressing =C-c C-c= on this table will update the display so that the
 131 first and second columns are respectively narrowed to 10 and 15
 132 characters:
 133
 134 : | <10>     | <15>            |
 135 : | A very=> | Another very => |
 136
 137 When columns are narrowed, it might be useful to temporarily see the
 138 content of a cell with =C-u <TAB>= (or =C-u C-c `=) or to edit the
 139 content in a separate window with =C-c `=.
 140
 141 * Preparing tables for export
 142
 143 This table :
 144
 145 : | A | B |
 146 : | 1 | 2 |
 147
 148 will be exported like this:
 149
 150 | A | B |
 151 | 1 | 2 |
 152
 153 ** Adding a table header
 154
 155 This table :
 156
 157 : | A | B |
 158 : |---+---|
 159 : | 1 | 2 |
 160
 161 will be exported like this:
 162
 163 | A | B |
 164 |---+---|
 165 | 1 | 2 |
 166
 167 The horizontal line separating the two rows tells the exporter to
 168 consider the first line is the table header.
 169
 170 ** Grouping columns
 171
 172 You can group columns like this:
 173
 174 : |   |  N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
 175 : |---+----+-----+-----+-----+---------+------------|
 176 : | / | <> |   < |     |   > |       < |          > |
 177 : | # |  1 |   1 |   1 |   1 |       1 |          1 |
 178 : | # |  2 |   4 |   8 |  16 |  1.4142 |     1.1892 |
 179 : | # |  3 |   9 |  27 |  81 |  1.7321 |     1.3161 |
 180 : |---+----+-----+-----+-----+---------+------------|
 181
 182 Here is the output:
 183
 184 |   |  N | N^2 | N^3 | N^4 | sqrt(n) | sqrt(N) |
 185 |---+----+----+----+----+---------+---------|
 186 | / | <> |  < |    |  > |       < |       > |
 187 | # |  1 |  1 |  1 |  1 |       1 |       1 |
 188 | # |  2 |  4 |  8 | 16 |  1.4142 |  1.1892 |
 189 | # |  3 |  9 | 27 | 81 |  1.7321 |  1.3161 |
 190 |---+----+----+----+----+---------+---------|
 191
 192
 193
 194
 195
 196
 197
 198
 199