[kramdown-users] RFC: Table syntax proposal, try 2

[Eric Sunshine]

Hi Thomas,

On 12/31/2009 3:25 AM, Thomas Leitner wrote:
> * A *table row* is started with a pipe character, optionally indented
>    up to three spaces, and then the text of the first table cell.
>    Additional table cells can be added by using the pipe character and
>    then the text of the next table cell.

Rephrase: Rather than "Additional table cells...", say "Subsequent table 
cells consist of a pipe character followed by the cell text."

> * A *header separator line* is started with a pipe character -- which
>    starts the first column --, optionally indented up to three spaces,
>    followed by one or more optional spaces/tabs and an optional colon,
>    followed by one or more dashes and finally an optional colon and
>    another set of one or more optional spaces/tabs. Each other column
>    also starts with a pipe character and follows the same syntax as the
>    first column. The colons are used for aligning the content of each
>    column, as explained below.

This description is still difficult to follow. One way to simplify it 
dramatically would be to describe normal separator lines first, and then 
describe header separators as: "A header separator line is like a normal 
separator line, except..." and then describe the colons.

> The header separator
> line and the normal separator lines need not match the columns of any
> other table line intentionally to speed up and simplify table creation
> and maintenance.

Somewhat awkward. Rephrase: "To simplify table creation and maintenance, 
header and normal separator lines need not specify the same number of 
columns as table rows; even "|-" is a valid separator."

> * If the table contains a header separator line, all table rows until
>    the header line are considered to contain table header cells. The
>    colons of a header line are used for *aligning the columns*:

The alignment discussion probably ought to be incorporated directly into 
the "header separator line" description above. It is confusing to place 
it so far from the initial mention of colons, and there does not seem to 
be a good reason to separate the two.

> The above example table is rather time-consuming to create without the
> help of an ASCII table editor. However, the table syntax is flexible
> and the following table is equivalent to the one above but doesn't look
> as nice:

Probably drop "but doesn't look as nice". The aesthetic disparity is 
apparent implicitly by anyone looking at the example.

-- ES