[kramdown-users] RFC: Table syntax proposal, try 2
sunshine at sunshineco.com
Thu Dec 31 05:36:47 EST 2009
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.
More information about the kramdown-users