[kramdown-users] RFC: Table syntax proposal

[Thomas Leitner]

Hi,

I have written the documentation for a possible table syntax and would
like to know opinions. The syntax is based on the table syntax of PHP
Markdown Extra, with some small differences. If the syntax
documentation is okay, I will implement it and will release kramdown
0.4.0 shortly thereafter.

Here is the current table syntax text:

----------------------------------------------------------------------
## Tables

> This syntax feature is not part of the original Markdown syntax. The
> syntax is based on the one from the [PHP Markdown Extra] package.
{: .markdown-difference}

Sometimes one wants to include simple tabular data in a kramdown
document for which using a full-blown HTML table is just too much.
kramdown supports this with a simple syntax for ASCII tables.

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.
  Additional table cells can be added by using the pipe character and
  then the text of the next table. One may optionally use a pipe
  character at the the end of a table row line. Literal pipe characters
  need to be escaped. For example:

      | First cell|Second cell|Third cell
      | First | Second | Third |

* A *header line* is started with a pipe character, optionally indented
  up to three spaces. 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. 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:

      |---|---|---|
      | :-: |:------| ---:|

* 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:

      |----|----|
      |----+----|
      |-

Trailing spaces or tabs are ignored in all cases.

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.

The meaning of all the different line types and their usage is
explained using the following example:

    |-----------------+------------+-----------------+----------------|
    | Default aligned |Left aligned| Center aligned  | Right aligned  |
    | --------------- |:-----------| :-------------: | -------------: |
    | First body part |Second cell | Third  cell     | fourth cell    |
    | Second line     |foo         | **strong**      | baz            |
    | Third line      |quux        | baz             | bar            |
    |-----------------+------------+-----------------+----------------|
    | Second body     |            |                 |                |
    | 2 line          |            |                 |                |
    |-----------------+------------+-----------------+----------------|
    | Footer line     |            |                 |                |
    |-----------------+------------+-----------------+----------------|

* The starting separator line is optional and can be used when creating
  a nice visual table.

* Table cells in table rows can only contain a single line of text, no
  multiline text is supported. The text of a table cell is parsed as
  span level elements.

* If the table contains a header 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*: if there is no
  colon, the column uses the default alignment, if there is a colon
  only before the dashes, the column is left aligned, if there are
  colons before and after the dashes, the column is center aligned and
  if there is only a colon after the dashes, the column is right
  aligned.

* 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.

> The table syntax differs from the one used in [PHP Markdown Extra] as
> follows:
>
> * kramdown tables have to begin with a pipe character, this is
> optional in [PHP Markdown Extra].
> * kramdown tables do not need to have a table header.
> * kramdown tables can be visually structured using separator lines.
{: .markdown-difference}
----------------------------------------------------------------------

-- Thomas