Proposed table specification (long!)
Gentlefolk, I have been thinking on Markdown's lack of proper table support for a long while now. Here's where I have arrived... ## I Don't Like HTML Tables It is often argued that embedded HTML is the way to markdown rich tables. Unfortunately, this contradicts the higher markdown ideal that a raw markdown document (including tables!) should be good 1. Firstly for readers, 2. Secondly for authors, 3. Lastly for parsers which don't even rate a mention because markdown is for Humans. You have probably noticed already that HTML tables are *appalling* for readers and a nightmare for authors. They are hardly good for markdown parsers either, which (not being HTML parsers) treat HTML tables as impenetrable blobs to be output as is. Where does that leave us when we want to go from markdown to PDF? ## I Do Like Monospaced Tables It is the _visual alignment_ of terms into rows and columns that enables a reader to recognise a table. Without any recognisable alignment, a reader sees a jumbled cloud of terms -- which is exactly how we see tables with a variable width font. Additionally, a raw markdown document should 1. Be sharable, and, 2. Convey the same information to every reader. A raw markdown document must therefore be rendered *equivalently* for every reader. This can only be assumed if every reader has the same text spacing, and a mono spaced is _a_ reasonable way of achieving this. With all that in mind, I offer up my Teardown table specification for your consideration (I realise it will be torn down, but nothing ventured nothing gained). Teardown offers the following over and above MultiMarkDown's table support: * Multi-line cell content, * Additional Arty syntax for titles and footers (much nicer for authors and readers), * Colspan (without meta-chars in cell content), * Rowspan, * Cell alignment (without meta-characters in content) *Please note* that I have _not_ implemented this specification. This is all just hot air produced by an author trying contribute something toward better table support for markdown. (specification to follow...) ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Proposed table specification (long!)
## Teardown Table Specification 1. Teardown Tables 1. The Simplest Table 2. Basic Table Features 1. The Header a. Basic Header b. Multi-Line Header 2. The Title 3. Rows a. Clean Rows b. Multi-Line Rows c. Ruled Rows 4. Columns a. Clean Cols b. Ruled Columns 5. Ruled Rows and Ruled Columns 6. The Footer 3. Advanced Table Features 1. Cell Spans a. Rowspan b. Colspan 2. Cell Alignment a. Vertical Alignment b. Horizontal Alignment 3. Advanced Headers 4. Empty Cells 5. Nested Tables 6. Multiple Bodies 7. Vertical Table Header 4. Putting it all Together 1. A Complex Markeddown Table ## 1. Teardown Tables A table is an arrangement of terms into rows and columns. ### 1.1. The Simplest Table Here is a very simple Teardown table with three rows and three columns (examples are delimited by PHP Markdown Extra fence blocks throughout): ~ Elves RivendellSindarin DwarvesErebor Khuzdul HobbitsThe ShireWestron ~ It is the *visual alignment* of terms into rows and columns which makes the whole recognisable as a table to the reader. It is the two leading (and trailing) line breaks which signal the beginning (and end) of a table to the parser, however. Additionally, we can see that: * A line-break indicates a row-break, * Any 3 or more space symbols indicates a column-break. That is the _very least_ you need to know in order to write Teardown tables. ## 2. Basic Table Features The very least is not enough to satisfy all authoring needs. For example, empty table cells are not supported by Simplest Table (above). Teardown specifies a number of additional features which, combined, aim to address all but the most tricky cases. ### 2.1. The Header It is very often desirable to label columns of terms with a row of headings. If included, this row of column headings is called the Header. The Header is separated from the table Body by a line of equals symbols called the Line. The table Header is always above the Line, and the table Body is always below the Line. 2.1.a. Basic Header The Header is authored as per any other row in the table Body. It is a series of terms at the top of a like series of aligned columns. 3 or more space symbols denote a column-break, just as they do in the Body of the table. E.g., ~ People Homeland Tongue Elves RivendellSindarin DwarvesErebor Khuzdul HobbitsThe ShireWestron ~ 2.1.b. Multi-Line Header Header text can occupy more than line in the Header. E.g., ~ Name of Spoken People Homeland Tongue Elves RivendellSindarin DwarvesErebor Khuzdul HobbitsThe ShireWestron ~ Note the single line Homeland column header. Empty cells and cell spans are discussed in section 3 (Advanced Table Features, below). But even disregarding section 3, a parser can count the number of characters to determine which column the text Spoken belongs to. ### 2.2. The Title It is often desirable to label a table with a title. If included, a Title is any text between two unbroken lines of minus symbols which precede the table itself. E.g., ~ THE PEOPLE OF MIDDLE-EARTH People Homeland Tongue Elves RivendellSindarin DwarvesErebor Khuzdul HobbitsThe ShireWestron ~ ### 2.3. Rows Rows of columns make up the Body of a table. 2.3.a. Clean Rows Clean rows (so called because the markdown is uncluttered) are separated by a line-break. E.g., ~ People Homeland Tongue Elves RivendellSindarin DwarvesErebor Khuzdul HobbitsThe ShireWestron ~ Note that the more compact form used in example 1.1 (above) is ambiguous as to whether there are three lines of text in a single row, or a single line of text in each of three rows. In this example, there is no such ambiguity. 2.3.b. Multi-Line Rows Multi-lined rows are also allowed; ~ People Homeland Tongue Elves Rivendell, Quenya, Mirkwood,Sindarin, Lorien Nandorin DwarvesErebor Khuzdul HobbitsThe Shire, Westron Breeland ~ It is clear now that the compact form used in example 1.1 (above) would unambiguously be interpreted as three lines of text in a single row.
Re: Proposed table specification (long!)
On Tue, May 10, 2011 at 8:31 AM, Simon Bull waysoftheea...@yahoo.com.au wrote: Gentlefolk, I have been thinking on Markdown's lack of proper table support for a long while now. Here's where I have arrived... ## I Don't Like HTML Tables It is often argued that embedded HTML is the way to markdown rich tables. Unfortunately, this contradicts the higher markdown ideal that a raw markdown document (including tables!) should be good 1. Firstly for readers, 2. Secondly for authors, 3. Lastly for parsers which don't even rate a mention because markdown is for Humans. In response to this I will quote the paragraph from the syntax rules [1] which likely gave you this impression: Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text. Note that is says easy to read, write, and edit prose -- prose not tabular data. Taking this (along with the rest of that section of the document, it is clear (to me at least) that there is no place for a table syntax in markdown. Now, if you want to implement a third party add-on, fine. And if that third party add-on becomes popular, then maybe others will add it to there implementations as well. Maybe, eventually, if a single format becomes popular enough, the community at large will accept it. Until then, I'm not interested. If you want it, go build it! [1]: http://daringfireball.net/projects/markdown/syntax#html -- \X/ /-\ `/ |_ /-\ |\| Waylan Limberg ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Proposed table specification (long!)
On May 10, 2011, at 5:31 AM, Simon Bull wrote: Gentlefolk, I have been thinking on Markdown's lack of proper table support for a long while now. Here's where I have arrived... . . . *Please note* that I have _not_ implemented this specification. This is all just hot air produced by an author trying contribute something toward better table support for markdown. I think this is a case where you'd do better writing a table preprocessor that implements your table extension. Yours is a fairly complex implementation, and there's not a painless way for people to try it out.The existing table implementation (the php markdown extra one) is kind of klunky and horrible, but the code is there and authors can actually see a working implementation before going and implementing it themselves. Yours, at least as of right now, is just documentation and not very useful for getting ones fingers into the pie. -david parsons ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Proposed table specification (long!)
Thanks for your replies gentlemen. I'm not surprised by the lack of... enthusiasm. I would like to add, in reply to Waylan's comment about prose, that markdown already includes syntax for lists, link, horizontal rules, images and so on which are not prose either. Surely markdown can only be a more useful tool with table support than without it. I agree with David's comment that the specification needs an implementation before people will take it seriously. I did, however, think it was a reasonable notion to firstly propose a solution, then have it reviewed by a meaningful authority (i.e., this list), and then think about implementing it. I will leave it to simmer a while before I go any further with it. Thanks again, Simon On Tue, May 10, 2011 at 11:37 PM, David Parsons o...@pell.portland.or.uswrote: On May 10, 2011, at 5:31 AM, Simon Bull wrote: Gentlefolk, I have been thinking on Markdown's lack of proper table support for a long while now. Here's where I have arrived... . . . *Please note* that I have _not_ implemented this specification. This is all just hot air produced by an author trying contribute something toward better table support for markdown. I think this is a case where you'd do better writing a table preprocessor that implements your table extension. Yours is a fairly complex implementation, and there's not a painless way for people to try it out.The existing table implementation (the php markdown extra one) is kind of klunky and horrible, but the code is there and authors can actually see a working implementation before going and implementing it themselves. Yours, at least as of right now, is just documentation and not very useful for getting ones fingers into the pie. -david parsons ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Proposed table specification (long!)
Additions to the MMD table syntax (which is largely based on PHP Markdown Extra) is probably one of the most common feature requests I get. My response is usually always the same - I'll update the syntax when I see a proposal that is: * easy/natural to write * easy/natural to read * easy to program a computer to parse * uncluttered I realize that beauty is in the eye of the beholder in these cases, but I have yet to see a proposal that beats the current syntax in all (or even most) of these criteria. I would love to add additional features to MMD tables (cells that span multiple rows, improved syntax for wrapping long cell contents, etc) but not at the expense of further complicating the syntax. My $.02, Fletcher -- Fletcher T. Penney fletc...@fletcherpenney.net ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Proposed table specification (long!)
Hi Fletcher, Should I assume that you mean the proposed syntax falls short in one or more of the four categories you identified? If you care to elaborate on some of these short-comings I would be very happy to alter my proposal in order to meet the needs of a wider audience. That was in fact the purpose of proposing it at all. Thanks for your comments, Simon On Wed, May 11, 2011 at 10:37 AM, Fletcher T. Penney fletc...@fletcherpenney.net wrote: Additions to the MMD table syntax (which is largely based on PHP Markdown Extra) is probably one of the most common feature requests I get. My response is usually always the same - I'll update the syntax when I see a proposal that is: * easy/natural to write * easy/natural to read * easy to program a computer to parse * uncluttered I realize that beauty is in the eye of the beholder in these cases, but I have yet to see a proposal that beats the current syntax in all (or even most) of these criteria. I would love to add additional features to MMD tables (cells that span multiple rows, improved syntax for wrapping long cell contents, etc) but not at the expense of further complicating the syntax. My $.02, Fletcher -- Fletcher T. Penney fletc...@fletcherpenney.net ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Proposed table specification (long!)
Since you asked, here are my own personal thoughts - others most likely disagree The syntax seems a bit complicated - I didn't compare, but I suspect the length of your explanation approaches or exceeds the entire Markdown syntax guide. I realize that you are trying to offer some flexibility, but that can get tricky. The other challenge is editability - with most of the complex table formats out there, it would be very tedious to actually create and subsequently modify a table by hand. I will grant you that this as much (or more) a problem with editors than the syntax. And one could create plugins for certain editors (e.g. TextMate) that could do the formatting for you. But this seems to be straying outside the bounds of what makes Markdown so great. (Again --- just my opinion) But I think the biggest issue is the monospace vs proportional font problem. This plagues every proposed table syntax out there (to my knowledge) --- tables just aren't going to look right in both font types in plain text files. Proper alignment is a key feature of tables, and it's frustrating when this is destroyed by changing the font. That said, the elastic tabstop idea proposed by Nick Gravgaard offers a tantalizing solution to this problem. In text editors that supported this concept, it would be trivially easy to align columns of text that worked for both monospace and proportional fonts. Columns would automatically realign when you changed the length of a given cell. In general, I believe there is a trade-off between simplicity and functionality. My preference is not to sacrifice (much) simplicity for the sake of functionality --- I believe MMD's table syntax is about as far down that curve as I am willing to go. Others may be on the other end of the spectrum. Where true genius comes is being able to merge simplicity with functionality (e.g. the iphone). I'm not saying a great solution for the Markdown/Table dilemma doesn't exist. I just don't think I've seen it yet. But I agree with you that continuing to generate new proposals is a good idea. F- On Tue, May 10, 2011 at 9:22 PM, Simon Bull waysoftheea...@yahoo.com.au wrote: Hi Fletcher, Should I assume that you mean the proposed syntax falls short in one or more of the four categories you identified? If you care to elaborate on some of these short-comings I would be very happy to alter my proposal in order to meet the needs of a wider audience. That was in fact the purpose of proposing it at all. Thanks for your comments, Simon -- Fletcher T. Penney fletc...@fletcherpenney.net ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Proposed table specification (long!)
On May 10, 2011, at 8:54 PM, Simon Bull wrote: Thanks for your additional comments Fletcher. If the proposed syntax overly complicated, I am very happy to simplify it. The question is whether or not the following is really complicated? Implement what you have, and then you'll have an idea if it's too complicated. Working code is the best test of the complexity of a design. -david parsons ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
