Feature Request: Tables

[mofosyne]

Tables are used very often to help explain information that would requires multiple paragraphs into a clear concise 2d layout. The issue with making this feature optional means it won't be fully widespread. And stuff like tables and anchors are common enough to be a core standard.

A common complaint I understand about tables in markdown variants that attempts to implement this, is that it is hard to maintain. So here is some ways I think it can be simplified from "Markdown Extra" syntax for this effort.

This is Markdown Extra Syntax for tables:

 | Item      | Value |
 | --------- | -----:|
 | Computer  | $1600 |
 | Phone     |   $12 |

First example (Compress the pipe headers):

To indicate a field is a header you use |-, -| .
For header alignment: |:- left aligned -|, |- right aligned -:| |:- Centre aligned -:| .

|:- Header -:|:- Header -:|
|   Row      |   Row      |
|   Row      |   Row      |

Second Example ( CSV Input):

The second issue, is that people find it hard to have to deal with formatting the pipes. If alignment of cell data is of no concern to the user, then we should use CSV data as the inspiration.

I'm a big fan of CSV data, due to how easy it is to type. The ease of use comes from sticking to csv which most people use already, and combining it with a simplified table header.

If you still need alignment control for each cell, then you can just use the previous (but simplified) pipe tables shown above using |:, :|

|:- Year -|:- Make  -|:- Model                         -:| 
  1997,      Ford,      E350
  1999,      Chevy,    "Venture ""Extended Edition"""
  1999,      Chevy,    "Venture ""Extended Edition
  1996,      Jeep,      Grand Cherokee

 This is some other text, since the end of a table is implied by a new paragraph. 

example data from: http://en.wikipedia.org/wiki/Comma-separated_values

Essentially, just treat pipes as 'optional' for the actual cell data (which is the field that gets modified most often anyway (compared to the header). This way, we can avoid too much formatting, and heck if you are lazy, you could just remove whitespaces and it shall still be very maintainable like so:

|:- Year -|:- Make -|:- Model  -:| 
1997, Ford, E350
1999, Chevy, "Venture ""Extended Edition"" "
1999, Chevy, "Venture ""Extended Edition"" "
1996, Jeep, Grand Cherokee

The second approach is my preference. Since I believe markdown is about getting formatting out of the way of your writing.

[vyp]

See #22.

[mofosyne]

That's a shame then. At least I hope other parsing systems like markdown extra will consider this then.

[vyp]

Multimarkdown expands on markdown extra's pipe tables and allows for grouping (only colspan though I think). Pandoc's markdown allows four types of tables, including markdown extra's syntax, but doesn't include multimarkdown's grouping.

About your suggestion though. In my opinion, I think your method to suppress the pipe headers and include header/alignment information within the header cells themselves is ugly since it requires that every cell below adds more spaces to align 'prettily'. By pretty, I mean the first letters directly aligning underneath each other. I know it doesn't affect the final output since it's a pipe table, but one of the points of markdown is to be able to read the plain text fairly easily as well. These types of headers I find are much harder to read than simply including a row of hyphens. I don't think it's that difficult to include the row of hyphens.

I agree that csv is nice, but it is of my understanding that csv data is usually in separate files by themselves (i.e. not intermixed/embedded in normal text)? My point is that, how would you differentiate between a paragraph with commas and a csv table as you put it (that doesn't need alignment information in the header, as in the header also uses commas to separate cells, and the table doesn't have an alignment hyphen row)? (Remember blank lines separate paragraphs, not simply newlines.) I believe pipes are differentiated (for example between a paragraph with pipes and a pipe table in pandoc markdown) by the presence of the hyphen row.

Also, isn't the pipe character fulfilling exactly the same purpose as a comma in your csv tables, as in 'pipe separated values'? I know pipe is harder to type than comma, but I'd prefer to escape pipes in my table than every comma (for when you actually need to use a comma in a cell, which is usually much more common than pipes).

[mofosyne]

So you mean that the |:- system would basically force a 'spacing minimum'? e.g.

 |:- a -:|:- b -:|:- c -:|
 |   1   |   2   |   3   |
 |   12  |   13  |   40  |

Hmmm... I can see what you mean. I personally see the maintenance of adjusting the header with my method to be much easier however. But I can understand the need for aesthetic pleasure of textual presentation. So I will concede the need for "compressed piped headers" for standard pipe tables, and I can see how |------| is needed for row differentiation in more complex tables.

However in the case of CSV tables, compressed pipe tables is a must. Specifically for the ease of adjusting 'table headers' length, without having to readjust every column.

While csv data is usually treated as a separate file, making it inline as part of a csv table will not conflict with any other syntax. This is because a csv table, is not a table without the "compressed pipe table header", which you can think of as the 'initializer' of the table. Plus there is no point making it any more complex, since you can't format csv in any complex manner.

I have considered that the pipe table is doing the same purpose as the csv comma, however I would prefer the flexibility in not needing to worry about alignment of commas as much as pipes (pipes is much more obviously ugly when unaligned). And would appreciate the flexibility of not needing to adjust most copy pasted csv data.

e.g.

 |:- a -:|:- b -:|:- c -:|
    1   ,   2   ,   3   
    12   ,   13   ,   40  

vs

 |:- a -:|:- b -:|:- c -:|
 |   1    |   2   |   3   |
 |   12 |   13  |   40  |

I think the difference between us really depends on the situation. Do you want pretty tables? Or do you want just good enough, and fast to maintain. Markdown is about being pretty and fast to type, which sometimes is hard to do (but is way better than XML regardless in both the pretty and fast type criteria).

So in summery after taking your point into consideration:

• Need flexibility: I would go for the standard pipe markdown table, at the sacrifice of maintainability

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of pipe table syntax.

• Need maintainability: I would go for the compressed header + inline csv , at the sacrifice of flexibility of presentation

|:- Year -:|:- Make  -:|:- Model            -:| 
    1997,      Ford,       E350
    1999,      Chevy,      Venture Extended
    1996,      Jeep,       Grand Cherokee

: Demonstration of csv + compressed pipe table syntax

Previously I wanted a gradient of flexibility to maintainability. But I think the best approach is either go "Maximum Flexibility" or "Maximum Maintainability".

edit (simplified csv styled table form):

  Year    |  Make     |  Model
  1997,      Ford,        E350
  1999,      Chevy,      "Venture ""Extended Edition"""
  1999,      Chevy,      "Venture ""Extended Edition"""
  1996,      Jeep,        Grand Cherokee

[vyp]

I think the difference between us really depends on the situation. Do you want pretty tables? Or do you want just good enough, and fast to maintain.

You're right. The reason I want the prettiness is because my editor (vim) makes prettily aligned tables very easy to maintain, so why not have both? I would probably prefer the more practical option of easy to type if that wasn't the case though. And of course, I'm not arguing for the requirement of an editor that aids in such maintainence, since that sort of defeats the purpose of markdown in the first place (we want the spec to be irrespective of any editor), I'm just trying to convey why I thought it was sub-optimal, but obviously I was only considering myself.

So I guess the key point is that "pipes are much more obviously ugly when unaligned", as compared to commas. I hadn't considered that previously, but I agree. And that in addition to clarifying that csv tables require the 'compressed pipe table header', I'd agree for your csv table suggestion as an option for table syntax. That is, provided pipe tables are also included… (continued below)

---

So I'm not sure if talk.standardmarkdown.com will still be up? So I'll put the following here for now, instead of at http://talk.standardmarkdown.com/t/tables-in-pure-markdown/81/27 which is where it probably should be (you may want to reference this over there though just in case).

I'd also argue for the inclusion of the three other types of tables supported by pandoc markdown, as well as support of using a + in the hyphen line of pipe tables as produced by emacs orgtbl-mode, as pandoc markdown also supports it. Also, the grouping (colspan) feature from multimarkdown's table syntax.

So now in summary:

1. Simple
2. Multiline
3. Grid
4. CSV
5. Pipe, without the compact/compressed headers as would be used with the csv table, but with multimarkdown's grouping (colspan) feature.
   • I haven't actually seen a reason for not having multimarkdown's grouping feature in pipe tables already in pandoc's markdown though (whether in the github issues, github wiki, or in the discuss mailing list)? So it would be nice if john or someone else could specify or link to the reason for it's occlusion. And then if that exists, it could be used as a reason to keep it out of the spec here too.

This way we could probably satisfy quite a lot of needs, while still retaining fairly simple and readable syntaxes (with varying degrees of flexibility and maintainability).

Of course, I may have easily overlooked a conflict or something in supporting five different table syntaxes, or overlooked a difficult implementation detail so feel free to bring up such a case. This is only a suggestion for the future; for whenever john wants to deal with tables.

[jgm]

I'm going to close this as out of scope. There's a thread for discussing tables on the Discourse instance, but the focus in this repository is on getting the core spec and implementations into shape.