reStructuredText: Tables
language: "reStructuredText"
No wrapping is attempted on the contents of tables. They are left as-is.
Grid tables
Grid tables are detected by a line that starts and ends with +, with 3 - inbetween,
and then a second line with the same indent, that starts with |. Lines after that must
start with | or +, and be at the same indent.
+---+ ¦ +---+ ¦
| a | ¦ | a | ¦
+---+ ¦ -> +---+ ¦
¦ ¦
normal paragraph normal ¦
¦ paragraph ¦
An indented grid table (ie: in a blockquote) is fine.
+---+ ¦ +---+ ¦
| a | ¦ | a | ¦
+---+ ¦ -> +---+ ¦
¦ ¦
normal paragraph normal ¦
¦ paragraph ¦
Like everything else, grid tables can't interrupt a paragraph at the same indent. Everything will be treated as normal paragraph text.
normal paragraph normal ¦
+---+ ¦ -> paragraph +---+¦
| a | ¦ | a | +---+ ¦
+---+ ¦ ¦
At a different indent does work (though may give a warning)
normal paragraph normal ¦
+---+ ¦ paragraph ¦
| a | ¦ -> +---+ ¦
+---+ ¦ | a | ¦
¦ +---+ ¦
normal paragraph normal ¦
+---+ ¦ paragraph ¦
| a | ¦ -> +---+ ¦
+---+ ¦ | a | ¦
¦ +---+ ¦
A table ends as soon as a line is encountered that doesn't start with | or + or has a
different indent. A normal paragraph can therefore come directly after a table (with a
warning).
+---+ ¦ +---+ ¦
| a | ¦ | a | ¦
+---+ ¦ -> +---+ ¦
normal paragraph normal ¦
¦ paragraph ¦
If a line that looks like the start of a table is followed by a line that doesn't continue the table, the first line is ignored.
+---+ ¦ +---+ ¦
normal paragraph -> normal ¦
¦ paragraph ¦
Simple tables
Simple tables begin with a line that contains 2 sets of at least one = character,
separated by at least one space. They end if a line at the same indent begins with = and
has a blank line following.
===== ===== ======= ¦ ===== ===== ======= ¦
A B A and B ¦ A B A and B ¦
===== ===== ======= ¦ ===== ===== ======= ¦
False False False ¦ -> False False False ¦
True False False ¦ True False False ¦
False True False ¦ False True False ¦
True True True ¦ True True True ¦
===== ===== ======= ¦ ===== ===== ======= ¦
It doesn't matter to us whether the table is malformed or not since the result is the same: it's not wrapped.
A table doesn't need a header. Text after the table is wrapped as normal (#45).
aaa bbb ¦ -> aaa bbb ccc ¦
ccc ¦
¦ ======= ======= ¦
======= ======= ¦ This is ¦
This is ¦ ======= ======= ¦
======= ======= ¦
¦ ddd eee fff ¦
ddd eee ¦
fff ¦
A complete table because a blank line comes after the 2nd = =.
= = ¦ = = ¦
= = ¦ = = ¦
¦ -> ¦
normal ¦ normal text ¦
text ¦ ¦
If the closing line is followed by a blank line, its only conditions are:
- It must not be indented
- It must consist only of = and whitespace characters
= = ¦ = = ¦
= = ¦ = = ¦
¦ -> ¦
still ¦ still ¦
in table ¦ in table ¦
= = ¦ = = ¦
= % ¦ = % ¦
¦ -> ¦
still ¦ still ¦
in table ¦ in table ¦
= = ¦ = = ¦
= ¦ = ¦
¦ -> ¦
normal ¦ normal text ¦
text ¦ ¦
= = ¦ = = ¦
==== ¦ ==== ¦
¦ -> ¦
normal ¦ normal text ¦
text ¦ ¦
An internal line of =s may be present as long it is not followed as a blank line. This
denotes the end of the table header. If this line is present, then the next valid line of
=s will unconditionally end the table, meaning a blank line after is not needed.
=== === === ¦ === === === ¦
in1 in2 out ¦ in1 in2 out ¦
=== === === ¦ === === === ¦
1 2 5 ¦ -> 1 2 5 ¦
3 1 5 ¦ -> 3 1 5 ¦
=== === === ¦ === === === ¦
normal ¦ normal text ¦
text ¦ ¦
= = ¦ = = ¦
= = ¦ = = ¦
= = ¦ -> = = ¦
normal ¦ normal text ¦
text ¦ ¦
Like the closing line, these can be any line of =s, eg one without spaces (as in docutils).
=== === ¦ -> === === ¦
in1 in2 ¦ in1 in2 ¦
=== === ¦ === === ¦
1 2 ¦ 1 2 ¦
======== ¦ ======== ¦
normal ¦ normal text ¦
text ¦
=== === ¦ -> === === ¦
in1 in2 ¦ in1 in2 ¦
======== ¦ ======== ¦
1 2 ¦ 1 2 ¦
=== === ¦ === === ¦
normal ¦ normal text ¦
text ¦
A line of =s that's indented more than the table isn't one of its border lines.
= = ¦ -> = = ¦
a b ¦ a b ¦
= = ¦ = = ¦
c d ¦ c d ¦
= = ¦ = = ¦
¦ ¦
normal ¦ normal text ¦
text ¦
As in docutils, an internal line of =s that's followed by a blank line ends the table, even
if it was meant to end the header. The lines after it are then a paragraph.
= = ¦ -> = = ¦
a b ¦ a b ¦
= = ¦ = = ¦
¦ ¦
c d ¦ c d e f ¦
e f ¦
The rest of the way a simple table works cannot currently be supported by Rewrap. It scans following lines (possibly the whole document) for a closing line, and if none is found, gives lines back to be processed as other blocks
Indented
Simple tables may be indented (inside a blockquote or other container).
Whenever a line is encountered with a lesser indent, it terminates the table.
·= = ¦ ·= = ¦
a b ¦ -> a b text ¦
text ¦ ¦