RFC: Markdown Table Syntax

[David E. Wheeler]

On Feb 26, 2009, at 11:22 PM, Yuri Takhteyev wrote:


> Why not have two different kinds of table: one where each line is a

> row, and one where rows are show explicitly with dashes. The second

> type could use ===== or something else after the header:

>

>  id  |    name     |         description          | price

> =====|=============|==============================|=======

>    1 | gizmo       | Takes care of the doohickies |   1.99

> ‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐ 

> +‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ 

> +‐‐‐‐‐‐‐‐

>   10 | dojigger    | Handles:                     | 102.98

>      |             | * gizmos                     |

>      |             | * doodads                    |

>      |             | * thingamobobs               |

>

> Would mean: a header and two rows.


I had to think about this for a few minutes, because the programmer  
side of me is rather attracted to the idea. It reduces ambiguity, and  
in this example gets out of the way. At also reduces the issue with  
white space.

The problem I can see, however, is that it forces the common cases to  
adopt the syntax required by the edge cases. In general, I think that  
tables will often *not* have multiline cells. With my proposed syntax  
that would be:

   id  |    name     |         description          |  price
‐‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐ 
+‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ 
+‐‐‐‐‐‐‐‐
     1 | gizmo       | Takes care of the doohickies |   1.99
     2 | doodad      | Collects *gizmos*            |  23.80
    10 | dojigger    | Handles stuff                | 102.98
  1024 | thingamabob | Self‐explanatory, no?        |   0.99

But if we require a separate between every row, it suddenly becomes  
much more verbose:

   id  |    name     |         description          |  price
======|=============|==============================|========
     1 | gizmo       | Takes care of the doohickies |   1.99
‐‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐ 
+‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ 
+‐‐‐‐‐‐‐‐
     2 | doodad      | Collects *gizmos*            |  23.80
‐‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐ 
+‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ 
+‐‐‐‐‐‐‐‐
    10 | dojigger    | Handles stuff                | 102.98
‐‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐ 
+‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ 
+‐‐‐‐‐‐‐‐
  1024 | thingamabob | Self‐explanatory, no?        |   0.99


Which one would you rather read? It's harder for me to scan the table,  
as all those lines start to get in the way. And it takes up nearly  
twice as much screen real estate.

I really am inspired by the example set by database client output,  
where there's just enough table layout to make it clear you're looking  
at a table, but not so much that it starts to get in the way of  
legibility. The important thing about a data is the content of the  
table, not the table itself. I should know I'm looking at a table, but  
beyond that, it should stay out of my way.

Best,

David