Proposed table specification (long!)

[Simon Bull]

## 3. Advanced Table Features


### 3.1. Cell Spans

Rowspans and colspans appear relatively infrequently.  However, it is nice
to know that your markdown implementation supports these if/when the need
arises.


#### 3.1.a. Colspan

To make use of colspans the author must use Ruled Rows (as described above).

Thereafter it is a simple matter to merge two adjacent table cells by
omitting the explicit space denoted col-break between them.  E.g.,

~~~~~


    |  People   | Homeland   | Tongue    |
     ====================================
    |  Elves    | Rivendell, | Quenya,   |
    |           | Mirkwood,  | Sindarin, |
    |           | Lorien     | Nandorin  |
     ----------- ------------ -----------
    |  Dwarves  | THESE CELLS ARE MERGED |
     ----------- ------------------------
    |  Hobbits  | The Shire, | Westron   |
    |           | Breeland   |           |
     ----------- ------------ -----------


~~~~~

Note that the row-rule _below_ "THESE CELLS ARE MERGED" is continuous.
I.e., it does *not* contain a space.


#### 3.1.b.  Rowspan

To make use of rowspans the author must use Ruled Columns (as described
above).

Thereafter it is a simple matter to merge two adjacent table cells by
omitting the explicit space denoted row-break between them.  E.g.,

~~~~~


    |  People   | Homeland   | Tongue    |
     ====================================
    |  Elves    | Rivendell, | Quenya,   |
    |           | Mirkwood,  | Sindarin, |
    |           | Lorien     | Nandorin  |
     ----------- ------------ -----------
    |  Dwarves  | Erebor     | THESE     |
     ----------- ------------  TWO CELLS |
    |  Hobbits  | The Shire, | ARE       |
    |           | Breeland   | MERGED    |
     ----------- ------------ -----------


~~~~~

Note that the Column-Rule _after_ "THESE TWO CELLS ARE MERGED" is
continuous.  I.e., it does *not* contain a break.



### 3.2. Cell Alignment

The author has already provided the desired text alignment in the original
(mono spaced) markdown text.

It is therefore plausible for a parser to derive cell alignment by comparing
the amount of leading and trailing white space in each table cell of each
row and each column.

Given this there is no genuine need for the author to provide further parser
hints.  Moreover, there is a greater incentive to abstain from polluting the
markdown with parser metadata, as this degrades the readers' experience of
the document.


### 3.3. Advanced Headers

A table Header can include any of the row and column features of the table
Body, including multiple rows of text, rowspan and colspan.

The only notable difference is that a Row-Rule is _above_ the row it
describes in the Header, rather than _below_ it (as it would be in the table
Body).

~~~~~


     ----------- ------------------------
    |  ROWSPAN  |   COLSPAN IN HEADER    |
    |    IN     |------------ -----------
    |  HEADER   | Homeland   | Tongue    |
     ====================================
    |  Elves    | Rivendell, | Quenya,   |
    |           | Mirkwood,  | Sindarin, |
    |           | Lorien     | Nandorin  |
     ----------- ------------ -----------
    |  Dwarves  | Erebor     | Khuzdul   |
     ----------- ------------ -----------
    |  Hobbits  | The Shire, | Westron   |
    |           | Breeland   |           |
     ----------- ------------ -----------


~~~~~


### 3.4. Empty Cells

Empty cells are explicitly supported if the author chooses to use Ruled
Columns and Ruled Rows (see above).

Otherwise, it is left to the parser to decide if white space represents an
empty cell or not.  Whether or not the parser counts leading and trailing
white spaces around cell content to make this judgement if left to the
implementation.


### 3.5. Nested Tables

Nested tables are not explicitly supported.


### 3.6. Multiple Table Bodies

The (first) table Body begins immediatley after the Line separating the
Header for the table content, e.g., "=======".

In fact, it is perfectly legal to insert one _or more_ Lines, so long as
each is followed by at least one row of genuine data.  E.g.,

~~~~~


     ----------- ------------ -----------
    |  People   | Homeland   | Tongue    |
     ====================================
    |  Elves    | Rivendell, | Quenya,   |
    |           | Mirkwood,  | Sindarin, |
    |           | Lorien     | Nandorin  |
     ----------- ------------ -----------
    |  Dwarves  | Erebor     | Khuzdul   |
     ----------- ------------ -----------
    |  Hobbits  | The Shire, | Westron   |
    |           | Breeland   |           |
     ====================================
    |  Men      | Andor,     | Westron   |
    |           | Gondor     |           |
     ----------- ------------ -----------
    |  Orcs     | Angbad,    | The Black |
    |           | Mordor     | Speak     |
     ----------- ------------ -----------


~~~~~

Cell spanning is not permitted across Bodies.



### 3.7. Vertical Table Header

It is legal to orient the Header vertically (at the table left) rather than
horizontally (at the table top).

This is achieved with a verticial Line demarked by an unbroken column of two
continuous pipe symbols "||" or a unbroken column of ligature symbols  "?"
(unicode 05F0).  E.g.,

~~~~~


     -----------  ------------ --------- ------------
    |   Race    || Elves      | Dwarves | Hobbits    |
     -----------||------------ --------- ------------
    |  Homeland || Rivendell, | Khuzdul | The Shire, |
    |           || Mirkwood,  |         | Breeland   |
    |           || Lorien     |         |            |
     -----------||------------ - ------- ------------
    |  Tongue   || Quenya,    | Erebor  | Westron    |
    |           || Sindarin,  |         |            |
    |           || Nandorin   |         |            |
     -----------  ------------ --------- ------------


~~~~~


## 4. Putting it all Together

### 4.1. A Complex Marked down Table

Here is a real life example from "Men & Magic" by Gary Gygax and Dave
Arneson, 1974.

This table includes
* Title,
* Rowspan (in header),
* Colspan (in header),
* Footer

~~~~~


  ----------------------------------------------------------------------
                      ATTACK MATRIX 1: MEN ATTACKING
  ----------------------------------------------------------------------

  ------- ---------------------- ---------------------------------------
  Target |                      |  20 Sided Die Score to Hit by Level*
  Armor  |                      |----- ----- ----- ------- ------- -----
  Class  | Description          | 1-3 | 4-6 | 7-9 | 10-12 | 13-15 | 16+
  ======================================================================
     2   | Plate Armor & Shield |  17 |  15 |  12 |   10  |    8  |  5
     3   | Plate Armor          |  16 |  14 |  11 |    9  |    7  |  4
     4   | Chainmail & Shield   |  15 |  13 |  10 |    8  |    6  |  3
     5   | Chainmail            |  14 |  12 |   9 |    7  |    5  |  2
     6   | Leather & Shield     |  13 |  11 |   8 |    6  |    4  |  1
     7   | Leather              |  12 |  10 |   7 |    5  |    3  |  1
     8   | Shield only          |  11 |   9 |   6 |    4  |    2  |  1
     9   | No Armor             |  10 |   8 |   5 |    3  |    1  |  1
  ------- ---------------------- ----- ----- ----- ------- ------- -----

  * Fighting-Men: Magic-Users advance in steps based on five levels/group
    (1-5, 6-10, etc.), and Clerics in steps based on four levels/group
    (1-4, 5-8, etc.).  Normal Men equal 1st level fighters.


~~~~~

Yes, it's modestly complicated.  Now imagine trying to read it (or *write
it*) in HTML.



That is all.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20110510/0a3dfff9/attachment-0001.htm>