[kramdown-users] RFC: Table syntax proposal

Eric Sunshine sunshine at sunshineco.com
Wed Dec 30 03:41:15 EST 2009

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 

> 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

More information about the kramdown-users mailing list