[kramdown-users] RFC: Table syntax proposal

Shawn Van Ittersum svicalifornia at gmail.com
Wed Dec 30 08:14:43 EST 2009

Hi Thomas,

Thanks for writing this draft. I'm excited to see support for  
simplified table syntax coming to kramdown.

While I appreciate the support for advanced features such as footer  
rows and multiple table bodies, most tables have only a single body  
and one row of header cells. I proposed the shortened separator row  
syntax ( |- ) to make the common use case simpler and faster to type:

| header | cells |
| body | cells |

It's not clear from your specs whether this would be supported by  
kramdown. It would be disappointing if the shortened separator syntax  
is only used for multiple-body separation, when most tables don't have  
multiple bodies.

I propose that the row(s) above the first separator row shall be  
header rows, and that the shortened separator format suffice for this  

[sent from mobile phone]

On Dec 30, 2009, at 3:41 PM, Eric Sunshine <sunshine at sunshineco.com>  

> Hi Thomas,
> On 12/30/2009 2:52 AM, Thomas Leitner wrote:
>> There are three different line types that can be used in a table:
>> * A *table row* is started with a pipe character, optionally indented
>> up to three spaces, and then the text of the first table cell.
> It would perhaps be a good idea to state that header, footer, and  
> normal rows are all "table rows". Without this knowledge, it is a  
> bit confusing reading the next several paragraphs since (at least  
> for me) the assumption here is that "table row" is just a normal  
> (non-header, non-footer) row.
>> Additional table cells can be added by using the pipe character and
>> then the text of the next table.
> Should this sentence end "next cell" rather than "next table"?
>> * A *header line* is started with a pipe character, optionally  
>> indented
>> up to three spaces.
> When I read "header line", I think of the actual row containing the  
> text of the header cells. Perhaps different terminology would be  
> appropriate, such as "header control", "header directive", or even  
> better "header separator".
>> This starts the first part (corresponds to the
>> first table columen) and all other pipe character on the line (except
>> at the end of a header line) start another part corresponding to a
>> table column.
> This description is difficult to follow. It probably needs a from- 
> scratch rewrite. If combined with the existing text which follows  
> it, it could be clarified along the lines of: "Each column starts  
> with a pipe character, followed by one or more optional spaces and  
> an optional colon ...", etc.
> Also, note the misspelled "column" as "columen".
>> Each part starts with one or more optional spaces and
>> an optional colon, followed by one or more dashes and finally an
>> optional colon and another set of one or more optional spaces. For
>> example:
> It is confusing to read about colons without knowing their purpose  
> or even if they will be described later. Just before "For example:",  
> perhaps insert "Colons control column alignment, as explained below."
>> * A *separator line* is started with a pipe character, optionally
>> indented up to three spaces, followed by at least one dash and then
>> any number and combination of pipes, pluses and dashes. For example:
> In addition to the above, it might be a good idea to state  
> explicitly that separator lines are intentionally free-form and need  
> not match columns of other rows or indeed have any columns, thus  
> simplifying table creation and maintenance.
>> A table is specified by an optional separator line, one or more table
>> rows, an optional header line, zero or more table rows, optionally
>> interspersed with separator lines, and an optional trailing separator
>> line.
> I might suggest starting this paragraph with "Given the above  
> components, a table is constructed by..."
>> * If the table has a trailing separator line and there is at least  
>> one
>> separator line between table rows, all table rows between the last
>> separator line and the trailing separator line are considered to
>> contain table footer cells.
>> * Multiple table body parts can be created by using separator  
>> lines. In
>> such cases it is advised to *not* use a trailing separator line
>> sothat a table footer is not created accidentally.
> This behavior seems somewhat counter-intuitive and may have a high  
> "surprise factor". I can imagine people tripping over this, getting  
> footer rows unexpectedly. Perhaps there should be some explicit  
> mechanism for triggering footer rows?
> Note also typographical error "sothat" rather than "so that".
> -- ES
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

More information about the kramdown-users mailing list