add support for colspan/rowspan in tables

[QuietMisdreavus]

Resolves rdar://97739626

Overview and syntax

This PR updates the tables extension to support column span and row span. The design is inspired by the discussion in this CommonMark Forum thread discussing table syntax, as well as precedent set by existing implementations.

Column span is indicated by placing empty cells (with no spaces) after the spanning cell:

| one | two |
| --- | --- |
| hello    ||

Screenshot of rendered result

Row span is indicated by placing a caret in cells that should be spanned over:

| one | two   |
| --- | ---   |
| big | small |
| ^   | small |

Screenshot of rendered result

These can be combined by indicating column span on cells with the row span indicator:

| one | two | three |
| --- | --- | ----- |
| big      || small |
| ^        || small |

Screenshot of rendered result

This is a slight breaking change in syntax for tables which wrote empty cells without a space. These cells will now be treated as having column span.

API modifications

A new option flag, CMARK_OPT_TABLE_SPANS, has been added to enable the new syntax. (This was done since there is a slight breakage for existing tables with zero-width cells, which currently are parsed as empty cells.) If this option is absent while parsing, no spanning information is parsed, and the new data fields return their default value.

Table cell nodes have accessor functions to get/set their column span and row span. These are stored in the node's opaque pointer, which is allocated and freed by the table extension. A span value of zero indicates that this cell is being spanned over in the given dimension. When rendering to HTML or other output format that support spanning, these cells should be omitted. Wrapper libraries that use the cmark AST directly (like Swift-Markdown) will need to use these new values to handle spanning information.

A new option flag, CMARK_OPT_TABLE_ROWSPAN_DITTO, has been added to change the row-span sigil from a caret character to a double-quote (or "ditto mark"). This can be set from the cmark-gfm-bin binary via a new flag, --table-rowspan-ditto.

The spec document has been updated to add new cases for column span and row span. These outputs have been verified via make test.

A new accessor function on nodes, cmark_node_nth_child, has been added to return the N'th child of the given node. (This is used in the table extension when handling row span.)

HTML, XML, and CommonMark output has been updated to reflect the spanning syntax and output. (I don't know the LaTeX or troff format for cell spanning, so i haven't updated those. 😅)

[franklinsch]

Should declaring row-spans using caret also be opt-in?

[QuietMisdreavus]

Are you suggesting adding an option(s) to enable spanning behavior in the first place?

[franklinsch]

Right, I'm wondering if it should be so that existing Markdown content isn't affected by this change, e.g., the test in extensions.txt below

[QuietMisdreavus]

Unfortunately, if i make spans "opt-in" in this way, there's no way to enable that per-test in the spec documents. So my choices are to either not document it in the spec document, or turn them on for all the spec tests and have the change to extensions.txt regardless. I could see about setting up a new test scaffold just for table spans, but that would complicate the PR more and feel a bit like overkill.

[QuietMisdreavus]

@franklinsch I looked into whether i could add a new test file or flag to use to selectively enable table spans on a specific test file, and it will require changing the python wrapper used in the tests to include a hardcoded option constant that is optionally turned on or off. I'm not comfortable adding a copy/pasted constant to the Python code, since i don't know of a way to automatically populate values from C constants in Python. If we still want to have the table spans be fully optional, we effectively cannot document them. (The tests would need to move into api_test instead of being hosted in the spec docs.) Since i would like to generate and host the spec document for swift-cmark eventually, it would be unfortunate to completely miss this important feature.

[QuietMisdreavus]

In addition, if we add more options like this, i would prefer it if something like swiftlang/swift-markdown#23 landed alongside it so that users of swift-markdown can use more than just what its default settings are.

[franklinsch]

I'm concerned that if we're going to be breaking existing content here. Clients that use this library directly would see a change in behaviour right, at least compared to the upstream fork? This is something that we can enable by default for DocC, though. Or am I missing something?

[QuietMisdreavus]

Clients that use Swift-Markdown or Swift-DocC will also see a change in behavior. However, i've already implemented the code change locally to use an option, so i can at least finish the job and move the tests into api_test. I'll push up the change today. (I still want that Swift-Markdown change to land, though, so people who use Swift-Markdown directly can avoid the content breakage.)

[franklinsch]

Same question for col spans.

[daniel-grumberg]

LGTM

[QuietMisdreavus]

I've pushed a new commit which adds the option CMARK_OPT_TABLE_SPANS, which enables the new behavior. Because the new syntax is being hidden behind an option, i had to move the tests out of the spec doc and into api_test. I've verified that everything still passes with make test.

[franklinsch]

Looks great, thanks!