[kramdown-users] RFC: Table syntax proposal
sunshine at sunshineco.com
Wed Dec 30 03:41:15 EST 2009
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,
> 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
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 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".
More information about the kramdown-users