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