Extended table syntax for MyST

[chrisjsewell]

trafficstars

Might be useful, to handle e.g. multi-line/row/column cells etc, see e.g.

• RST tables: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables
• Pandoc tables: https://pandoc.org/MANUAL.html#tables

Also I quite like list-tables: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table

Basically what is a good balance between readability, usability, functionality, external support?

[damianavila]

Mmm... this is hard... I quite like the list-table... but it does not look like one and that could an issue from the readability perspective. I imagine most? of the people being more comfortable with something looking like a table such as the RST or the Pandoc ones (pandoc feels cleaner if I have to choose between both options) but I am not sure about that assumption given that I do not know yet the community preferences.

[choldgraf]

My vote would be for rST-style tables, because this is also the same (I believe) as grid tables in pandoc and thus would be a single table syntax that works across rST, MyST, and Pandoc.

I wonder if we could create a markdown-it-tables package that could add each of these tables syntax as optional choices as well, and it could be extended iteratively over time to provide more choices for people (potentially by people other than us, if they wanted that functionality enough).

We already have support for list tables when MyST is used in Sphinx, right?

[chrisjsewell]

My only issue with the rST/grid-style tables is that they look good for the "simple" examples, but when you come to actually write them, its a pain and then if you have line wrapping for moderately wide tables they just become a mess. Basically good in principle, maybe not so much in principle

[choldgraf]

@chrisjsewell yeah I agree - to be honest that's where I end up using list-table. I find it the easier to use for "complicated" tables (e.g. really long ones where you'd have to reformat 40 table rows every time you edited a cell)

[chrisjsewell]

Yeh just thought I'd see if anyone had any other good ideas.

Well list-table is now part of: https://executablebooks.github.io/markdown-it-docutils/ (at the bottom of the example), and so you will be able to preview them in the VS Code extension etc 😄

[72757373656c6c]

The "multi-line/row/column cells" would be very useful. Currently users have two options. They can either code html (I'm not sure how that works for other builders) or use the rst grid table.

I recently found a third option, linuxdoc flat-table. It combines the ease of use of the list-table and adds column and row spanning.

In asciidoc.py, table cells could be prefixed with attributes, including colspan.rowspan.

I don't need spanning so much in the table body, but definitely in the heading.

For multi-line, <br> seems to work in the table variations so users can do something like:

* - `-f script-file`<br>
    `--file=script-file`

| `-f script-file`<br>`--file=script-file` |

rst grid table

+-----------+-----------+---------+-------------------+-----------------+
|           |         Before      |         After     |                 |
|           +-----------+---------+-----------+-------+                 |
|   cmd     | pattern   | hold    | pattern   | hold  | [P]rint/[C]ycle |
+===========+===========+=========+===========+=======+=================+
| :kbd:``x` | a         | b       | b         | a     |                 |
+-----------+-----------+---------+-----------+-------+-----------------+

linuxdoc

```{eval-rst}
.. flat-table::
   :header-rows: 2
   :widths: 1 2 2 2 2 1
   :class: my-class
   :name: my-flat-table

   * - :rspan:`1` cmd
     - :cspan:`1` Before
     - :cspan:`1` After
     - :rspan:`1` [P]rint/[C]ycle

   * - pattern
     - hold
     - pattern
     - hold

   * - :kbd:`x`
     - a
     - b
     - b
     - a
     -

asciidoc.py

[width="100%",cols="^.^1d,4*^.^2l,^.^1l",frame="all",options="",caption=""]
|===============================================================================
1.2+s|cmd         2+^.^s|Before             2+^.^s|After     s|[P]rint/[C]ycle
          h|pattern    h|hold         h|pattern  h|hold       |
     |x    |a           |b             |b         |a          |