Is there an agreed best practice to represent tables in textual format?

Question

Question: In the UX community, is there an agreed best practice to represent table data in textual format?

Desired outcome: If the answer is yes, then I would propose pushing for support in Commonmark.

Background

I’m writing most of my documents in Markdown. It’s mostly great, with one of the biggest caveats being lack of native support for tables (HTML is allowed).

On the other hand, Textile has rich, native table support, based upon using the | character, like so:

|_. Col 1 |_. Col2 |
|   A1    |   B1   |
|   A2    |   B2   |

The Confluence wiki has a similar setup:

|| Col 1 || Col 2 ||
|  A1    |  B1    |
|  A2    |  B2    |

Wikipedia’s suggested markup is quite different:

{| class="wikitable"
|-
! Col 1
! Col 2
|-
| A1
| B1
|-
| A2
| B2
|} 

They also allow the use of !! and || for new cells without line breaks.

Over at Commonmark (the Markdown standardisation effort), there’s a long debate on how tables should best be represented as text. To facilitate that discussion, I’m wondering if anyone has actually researched the subject, and if yes, was a conclusion reached? Is there a best practice the UX community could propose for CommonMark?

Answer 1

There is no "agreed best practice" in this, so I can't give you a definitive answer. However, I've had to deal with exactly this and had to do some user testing on a number of styles.

The style that won out was GitHub flavoured markdown, which is both easy to learn, easy to read, and easy to use. My only wish would be that saving automatically aligned the marker bars | between columns, and that the text in them would align left, right, or centred depending on the markdown written. However this is more about the implementation of the editing interface than that of the specification.

The one weak point with GitHub flavoured markdown is sub-tables. I haven't seen any decent solution for this yet, and I'm not convinced that it is absolutely necessary in the first place.

Answer 2

I’m writing most of my documents in Markdown ... one of the biggest caveats being lack of native support for tables

MultiMarkdown supports tables like this (as per GitHub flavored Markdown)

| Heading1 | Heading2 |
|----------|----------|
| Apples   |  27      |
| Oranges  |  31      |

Some MultiMarkdown processors allow elaborations on this theme.

---

Since switching to Markdown, I rather miss the table style from Grutatxt which allows multi-line table cells. This is really useful for tables where cells contain long paragraphs of descriptive text.

+----------------+----------------------+-----------+
| Band Name      | Album Name           | Number of |
|                |                      | Songs     |
+----------------+----------------------+-----------+
| Dead Can Dance | A Passage in Time    | 16        |
+----------------+----------------------+-----------+
| Bel Canto      | White-Out Conditions | 10        |
+----------------+----------------------+-----------+
| Depeche Mode   | Speak and Spell      | 16        |
+----------------+----------------------+-----------+
| Love Spirals   | Temporal             | 13        |
| Downwards      |                      |           |
+----------------+----------------------+-----------+

Grutatxt only supports column-spanning, not row-spanning of cells.

I’m wondering if anyone has actually researched the subject, and if yes, was a conclusion reached? Is there a best practice the UX community could propose for CommonMark?

Would it be unacceptable to support several different table markup styles? Each has their advantages.

Pandoc supports multiple styles and uses a terminology that I find helpful

• Simple tables
• Multiline tables
• Grid tables
• Pipe tables

Answer 3

The goal of the Creole project is a standard syntax for wikis.

In the finished Creole 1.0 spec, this is the markup for tables:

|=Heading Col 1 |=Heading Col 2         |
|Cell 1.1       |Two lines\\in Cell 1.2 |
|Cell 2.1       |Cell 2.2               |

• All cells are separated by single pipes.
• Leading spaces are permitted before the first cell of a row and trailing spaces are permitted at the end of a line.
• The ending pipe is optional.
• Equal sign directly following pipe defines a header.
• Headers can be arranged horizontally or vertically.

On the Tables page it says that it’s only a "very basic table syntax, with no alignment", and it "only contains a notion for creating headings and forced line breaks". Its discussion page might contain some valuable insight. (The page Complex Tables Proposal does not contain much.)

On the page List Of Table Markups they listed which table syntaxes various wikis use. On the page Tables Reasoning they compared/grouped the syntaxes (it doesn’t contain many details though).