[kramdown-users] RFC: Table syntax proposal
Shawn Van Ittersum
svicalifornia at gmail.com
Wed Dec 30 08:14:43 EST 2009
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
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
>> 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
> 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
> 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
>> 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
More information about the kramdown-users