1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
Tables
======
In contrast to HTML, LaTeX does not support line-breaks in tables with
"automatic" column widths. Each cell has just one line, paragraphs are
merged (the writer emits a warning).
.. table:: problems with "auto" widths
:widths: auto
+-----------+------------------+
| 11 | first paragraph |
| | |
| | second paragraph |
+-----------+------------------+
| content | 22 |
| with | |
| linebreak | |
+-----------+------------------+
To provide for arbitrary cell content, the LaTeX writer defaults to
specifying column widths computed from the source column widths. This
works sufficiently in many cases:
.. table:: a table with multi-paragraph multi-column cells
+----------+--------------+---------------------------------+-----------+
| test | **bold hd** | multicolumn 1 | *emph hd* |
| | | | |
| | | With a second paragraph | |
+----------+--------------+--------------+--------+---------+-----------+
| multicolumn 2 | cell | cell | cell | cell |
| | | | | |
| With a second paragraph | | | | |
+----------+--------------+--------------+--------+---------+-----------+
| cell | multicolumn 3 (one line, | cell | cell | cell |
| | but very very very very | | | |
| | very looooong) | | | |
+----------+--------------+--------------+--------+---------+-----------+
| cell | cell | cell | Short multicolumn 4 |
+----------+--------------+--------------+------------------------------+
A problem with the source-derived column widths is that simple tables
often use no padding while grid tables without padding look cramped:
.. table:: simple table, not padded in the source
=== = = =
A B C D
=== = = =
100 2 3 4
EUR b c d
=== = = =
.. table:: grid table, padded cells
+-----+---+---+---+
| A | B | C | D |
+=====+===+===+===+
| 100 | 2 | 3 | 4 |
+-----+---+---+---+
| EUR | b | c | d |
+-----+---+---+---+
For better typographic results, setting the `width` and/or
`widths` options of the `table directive`_ is recommended.
.. table:: grid table, auto-width columns
:widths: auto
+-----+---+---+---+
| A | B | C | D |
+=====+===+===+===+
| 100 | 2 | 3 | 4 |
+-----+---+---+---+
| EUR | b | c | d |
+-----+---+---+---+
.. table:: table with multi-row header and "auto" column-widths
:widths: auto
+------------+-------------------+
| XXX | Variable Summary |
| +-------------------+
| | Description |
+============+===================+
| multi-column cell |
+--------------------------------+
The `width` option overrides "auto" `widths` as standard LaTeX tables
don't have a global width setting:
.. table:: This table has `widths` "auto" (ignored) and `width` 60%.
:widths: auto
:width: 60%
=== = = =
A B C D
=== = = =
100 2 3 4
EUR b c d
=== = = =
.. _table directive:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table
Nested tables
-------------
+-----------------------------------------+-----------------+
| Lorem ipsum dolor sit amet, consectetur | adipisicing elit|
+-----------------------------------------+-----------------+
| .. table:: | cell 1, 2 |
| :align: right | |
| :name: nested table | |
| | |
| +-----+-----+ | |
| | 1 | 2 | | |
| +-----+-----+ | |
+-----------------------------------------+-----------------+
| table width depends on parent column | same table |
| | |
| .. table:: | |
| :align: center | |
| | |
| +-----+-----+ | +-----+-----+ |
| | 1 | 2 | | | 1 | 2 | |
| +-----+-----+ | +-----+-----+ |
| | |
| better use "auto" widths, see below | in narrow column|
+-----------------------------------------+-----------------+
| .. table:: | cell 3, 2 |
| :align: right | |
| :widths: auto | |
| | |
| +-----+-----+ | |
| | 1 | 2 | | |
| +-----+-----+ | |
| | |
| definition: | |
| list | |
+-----------------------------------------+-----------------+
TODO
----
* Tables with multi-paragraph multi-row cells currently fail due to a
LaTeX limitation (see https://sourceforge.net/p/docutils/bugs/225/).
* Tweak vertical spacing in table cells containing multiple elements.
See also ``test/functional/input/data/latex-problematic.rst``.
|
