In our usage of tables in Hoedown, we are struggling with very wide tables that
result because there is no mechanism for splitting cell contents across
multiple lines. This patch provides a flexible way of splitting cell contents
across multiple rows, with two basic components (continued rows and optional
row separators). These two components can be used together to accomplish the
task in a couple different styles, according to the discretion of the document
author.
We considered many types of syntax in developing this proposal, and settled on
this one as being the simplest, most lightweight extension of existing tables,
that still felt like good Markdown. Please see the following document for a
more complete justification of the choices made, along with many alternatives
syntaxes considered:
https://github.com/jasharpe/hoextdown/wiki/Multiline-Table-Syntax-Extension
Summary of changes (again, see the linked document above for details and
detailed examples):
Introduce a new --multiline-tables flag to enable this extension.
Single logical table rows (including the header) can be extended to multiple
physical table rows by using a colon prefix and separators on subsequent
lines ("continued rows"). For example:
| foo | bar |
: baz : bat :
| --- | --- |
| foo | bar |
: baz : bat :
| foo | bar |
(Note that the special colon separator is necessary in order to make the row
separators optional.)
Rows may optionally be separated by row separator lines, in order to enhance
readability when using continued rows. Small example (the benefit is more
obvious for very large tables):
For now, rows that span multiple physical lines are still parsed with
parse_inline - however, this could easily be extended in the future to
parse_block should this be desired.
Summary of implementation changes:
For the most part, all significant changes have been guarded by the
--multiline-tables flag, however, a couple of minor changes were made outside
these sections (these will make more sense after reading the patch):
Header row contents are copied to another buffer, and then to
parse_table_row, in order to avoid passing in attributes to parse_table_row.
Cell contents are copied to another buffer, and then sent to parse_inline, in
order to concatenate the cell values from the main row and the following
continued rows.
These changes should have a very minor affect on users who don't use
--multiline-tables.
I've introduced an extensive multiline table test suite to verify this change.
I've also added additional table tests (the existing ones were pretty sparse)
to make sure nothing is broken.
Please let me know if you have concerns about adding this as an extension in Hoextdown.
kjdev
commented
8 years ago
(Further details here: https://github.com/jasharpe/hoextdown/wiki/Multiline-Table-Syntax-Extension)
In our usage of tables in Hoedown, we are struggling with very wide tables that result because there is no mechanism for splitting cell contents across multiple lines. This patch provides a flexible way of splitting cell contents across multiple rows, with two basic components (continued rows and optional row separators). These two components can be used together to accomplish the task in a couple different styles, according to the discretion of the document author.
We considered many types of syntax in developing this proposal, and settled on this one as being the simplest, most lightweight extension of existing tables, that still felt like good Markdown. Please see the following document for a more complete justification of the choices made, along with many alternatives syntaxes considered: https://github.com/jasharpe/hoextdown/wiki/Multiline-Table-Syntax-Extension
Summary of changes (again, see the linked document above for details and detailed examples):
Single logical table rows (including the header) can be extended to multiple physical table rows by using a colon prefix and separators on subsequent lines ("continued rows"). For example:
(Note that the special colon separator is necessary in order to make the row separators optional.)
Rows may optionally be separated by row separator lines, in order to enhance readability when using continued rows. Small example (the benefit is more obvious for very large tables):
Summary of implementation changes:
For the most part, all significant changes have been guarded by the --multiline-tables flag, however, a couple of minor changes were made outside these sections (these will make more sense after reading the patch):
These changes should have a very minor affect on users who don't use --multiline-tables.
I've introduced an extensive multiline table test suite to verify this change. I've also added additional table tests (the existing ones were pretty sparse) to make sure nothing is broken.
Please let me know if you have concerns about adding this as an extension in Hoextdown.
Thanks!
(Further details here: https://github.com/jasharpe/hoextdown/wiki/Multiline-Table-Syntax-Extension)