Tables vs fenced code blocks, when is something “common”?


#1

Like everyone else I have been keeping my eye on the discussion on adopting tables as part of the CommonMark spec. But the thought expressed in this topic’s title was really sparked when I read Dr Drang’s YAMF (linked to here by @ComplexPoint) and Joe Rosensteel’s Legitimate Text Processing linked there.

Several major contributors to the CommonMark spec have written in to say it has its roots in currently existing Markdown implementations, e.g. “this project is focused on codifying core markdown features”. John specifically states he “explored differences between markdown implementations extensively using [babelmark 2][bm]”. Yet some real changes were taken in as part of CommonMark, @stuartpb addressed this previously, and as Drang and Rosensteel point out code fences are especially noticeable.

So why exactly were fenced code blocks included? Have they become a de facto standard simply because of being included in some of the biggest implementations? Is it because the contributors to CommonMark had some personal preference for it? (Which would really make this their flavour rather than a core set of rules.)

I ran a little snippet of Markdown through [Babelmark][bm] to look for table support, using the example table from the tables discussion:

| Header  | Another header |
|---------|----------------|
| field 1 | something      |
| field 2 | something else |

``` html
<!doctype HTML>

I disregarded whether the info string was parsed correctly for the code block and looked only for `pre` and `code`. For the table I disregarded header markup and was simply looking if a table was made.

Results:

    | Implementation                        | Tables | Fences |
    |---------------------------------------|--------|--------|
    | showdown 0.3.1                        | No     | Yes    |
    | marked 0.2.6                          | No     | Yes    |
    | cheapskate 0.1.0.1                    | No     | Yes    |
    | Markdown.pl 1.0.1                     | No     | No     |
    | Markdown.pl 1.0.2b8                   | No     | No     |
    | lunamark 0.2                          | No     | No     |
    | RedCarpet 2.1.1                       | No     | No     |
    | pandoc (strict) 1.13.1                | No     | No     |
    | pandoc 1.13.1                         | Yes    | Yes    |
    | RDiscount 1.6.8                       | Yes    | No     |
    | PHP Markdown 1.0.2                    | No     | No     |
    | Python-Markdown 2.4                   | No     | No     |
    | cebe/markdown 1.0.0-dev               | No     | No     |
    | Maruku 0.7.2                          | Yes    | No     |
    | PHP Markdown Extra 1.2.8              | Yes    | Yes    |
    | Maruku (Math-Enabled) 0.7.3.beta1     | Yes    | No     |
    | Minima 0.8.0a2_20130826               | No     | Yes    |
    | kramdown 1.2.0                        | Yes    | No     |
    | Blackfriday                           | Yes    | Yes    |
    | Haskell markdown package 0.1.7        | No     | Yes    |
    | Parsedown 1.0                         | Yes    | Yes    |
    | s9e\TextFormatter (Fatdown/PHP)       | No     | No     |
    | cebe/markdown GFM 1.0.0-dev           | Yes    | Yes    |
    | cebe/markdown MarkdownExtra 1.0.0-dev | Yes    | Yes    |


* Tables: 10/24
* Fences: 11/24

This begs the question, again, why were fenced code blocks accepted in CommonMark but are tables fervently rejected as being an extension to the original syntax?

---

While I was writing all this, @ComplexPoint opened [a new topic based on the same premise](http://talk.commonmark.org/t/call-it-yamf-leaven-the-brand-sell-it-on-its-merits-not-its-name/410).

[bm]: http://johnmacfarlane.net/babelmark2/

Tables in pure Markdown
Statistical Analysis of Markdown Usage?
#2

I agree. Since they changed the name from Standard Markdown to Common Markdown, the philosophy of Common Markdown much change to match.

I envision markdown to be something that can encompass the most common usage of writing a typical document. Tables and fenced blocks of codes are both in common usage in the net. Especially tables, since office workers are not coders who need fenced blocks (and thus has the voice and the power to push that view), but they have just as much right in consideration for the common markdown feature set.

Also, is anchor reference common? I seen it in markdown extra.

 ## The Site ##    {#the-site}

edit:

hmmmm according to babelmark

  • 6 x <h1 id="test">markdown</h1>
  • 18 x <h1>markdown {#test}</h1>
  • 1 x <h1 id="markdowntest">markdown {#test}</h1>

#3

This has nothing to do with the name change. That’s just a lucky coincidence. Everything I have linked and quoted was written before the name change, including the philosophy that Common Markdown “is focused on codifying core Markdown features”.

I wouldn’t say so, like you already showed in your edit. Funny enough, 4 of those 6 that support it also support creating an ID without any extra syntax:

## The Site

Will be transformed by showdown, pandoc, Maruku, and kramdown into the following HTML (excuse the regex):

<h2 id="the[-_]?site">The Site</h2>

#4

More practically, the question is

When does the average internet user, when typing words into a text box on the Internet, need to use a full-blown table?

And the answer to that is

really, really rarely

Compare with: bold. italic. header. link. quote. etc … and yes, code.


#5

I don’t necessarily disagree with this, but I would like to see evidence of this stance.

Part of the issue is that adding tables to markup tends to be challenging especially for the average internet user, and in many cases there is no support for tables whatsoever, so other approaches are taken: code blocks with tabular data, images of tabular data, lists, links to the data, etc.

Asking when a user “needs to use a table” is almost a red herring because without support they will find a way around the issue. I think it’s more appropriate to ask a question along the lines of:

When does the average internet user, when typing words into a text box on the internet, want to display tabular data?

I don’t know the answer to that question.


#6

Tables are needed quite a lot in various sorts of writing. If you look at writing in general, and not writing by programmers, I’ll bet tables are much more common than highlighted source code.

It’s important not to limit ourselves to thinking of CommonMark as something used for “text boxes on the internet.” I write lots of long documents, lecture notes, and letters in Markdown, and this is becoming increasingly common for academics. Lots of people now write scientific papers using Markdown. I know people who write novels in Markdown.

So I think tables are very, very important. My main reason for leaving them out at the preliminary stage is that it’s important to get it right, and the design space is huge. Pandoc supports four different kinds of Markdown tables (simple, mulitline, pipe, grid), each with its own advantages and disadvantages.

The kind of pipe table most implementations support is okay for simple things, but isn’t very flexible. Each table row has to fit on one line of the source, which is a huge restriction. You can’t have block-level content in table cells (e.g. lists, code blocks, multiple paragraphs). You can’t specify relative column widths. There’s no way to have cells spanning rows or columns. Some implementations provide ways to do these things at the expense of very ugly syntax that goes against the “readable source” spirit of Markdown. So it’s hard to know how to get the right balance. There are some good ideas in the thread on this forum about table syntax, and this is something we should revisit soon, after 1.0, along with math and maybe footnotes and definition lists.


#7

Totally agreed, I just feel there is little evidence of urgency around tables being so important that they need to be built into the foundation under the house…


#8

Just to clarify, are we creating a CommonMark core spec based on

(1) John Gruber’s Markdown,
(2) Basic implementations of John Gruber’s Markdown,
(3) As many Markdown versions as possible, including extended flavors like GitHub, Markdown Extra, and Multimarkdown,
(4) Other?

If (1) or (2), it seems to me that tables and fences – useful as they are – should be in extensions only.

If (3), then core could include the most compatible syntaxes (simple pipe-type tables and triple-backtick fences), with extensions for more flexible syntax and advanced features.


Tables in pure Markdown
#9

The answer to your list is 1+2+4. The rationale is explained a number of places, can you please clarify what exactly it is you read, and why it didn’t answer your question?


#10

http://commonmark.org

“We propose a standard, unambiguous syntax specification for Markdown… One of our major goals is to strongly specify Markdown, and to eliminate the many old inconsistencies and ambiguities that made using Markdown so difficult.”

But how are inconsistencies resolved? Is the goal to specify a “least common denominator” (fewer features, stricter syntax, but highly compatible with existing flavors) or a “greatest common multiple” (many features, more flexible syntax, but compatible with fewer flavors)?

I had assumed it was the “least common denominator” approach, but including fenced code blocks doesn’t seem consistent with that.


#11

We can consider “code blocks” to be a single feature and “tables” to be a single feature. If we do, then the decision to include only the former is consistent with the goal of the core spec to represent features of the original Markdown spec. Conceptually it is easier to communicate these broader feature categories than specific syntax variations that someone new to Markdown may not be aware of.