Proposed table specification (long!)

[Simon Bull]

## Teardown Table Specification

1.  Teardown Tables
    1.  The Simplest Table

2.  Basic Table Features
    1.  The Header
        a.  Basic Header
        b.  Multi-Line Header
    2.  The Title
    3.  Rows
        a.  Clean Rows
        b.  Multi-Line Rows
        c.  Ruled Rows
    4.  Columns
        a.  Clean Cols
        b.  Ruled Columns
    5.  Ruled Rows and Ruled Columns
    6.  The Footer

3.  Advanced Table Features
    1.  Cell Spans
        a.  Rowspan
        b.  Colspan
    2.  Cell Alignment
        a.  Vertical Alignment
        b.  Horizontal Alignment
    3.  Advanced Headers
    4.  Empty Cells
    5.  Nested Tables
    6.  Multiple Bodies
    7.  Vertical Table Header

4.  Putting it all Together
    1.  A Complex Markeddown Table



## 1. Teardown Tables

A table is an arrangement of terms into rows and columns.


### 1.1. The Simplest Table

Here is a very simple Teardown table with three rows and three columns
(examples are delimited by PHP Markdown Extra fence blocks throughout):

~~~~~


      Elves      Rivendell    Sindarin
      Dwarves    Erebor       Khuzdul
      Hobbits    The Shire    Westron


~~~~~

It is the *visual alignment* of terms into rows and columns which makes the
whole recognisable as a table to the reader.

It is the two leading (and trailing) line breaks which signal the beginning
(and end) of a table to the parser, however.

Additionally, we can see that:
*   A line-break indicates a row-break,
*   Any 3 or more space symbols indicates a column-break.

That is the _very least_ you need to know in order to write Teardown tables.


## 2. Basic Table Features

The "very least" is not enough to satisfy all authoring needs.  For example,
empty table cells are not supported by Simplest Table (above).

Teardown specifies a number of additional features which, combined, aim to
address all but the most tricky cases.


### 2.1.  The Header

It is very often desirable to label columns of terms with a row of headings.

If included, this row of column headings is called the "Header".

The Header is separated from the table Body by a line of equals symbols
called the "Line".

The table Header is always above the Line, and the table Body is always
below the Line.


#### 2.1.a.  Basic Header

The Header is authored as per any other row in the table Body.  It is a
series of terms at the top of a like series of aligned columns.  3 or more
space symbols denote a column-break, just as they do in the Body of the
table.

E.g.,

~~~~~


      People     Homeland     Tongue
    ====================================
      Elves      Rivendell    Sindarin
      Dwarves    Erebor       Khuzdul
      Hobbits    The Shire    Westron


~~~~~


#### 2.1.b.  Multi-Line Header

Header text can occupy more than line in the Header.  E.g.,

~~~~~


      Name of                 Spoken
      People     Homeland     Tongue
    ====================================
      Elves      Rivendell    Sindarin
      Dwarves    Erebor       Khuzdul
      Hobbits    The Shire    Westron


~~~~~

Note the single line "Homeland" column header.  Empty cells and cell spans
are discussed in section 3 (Advanced Table Features, below).  But even
disregarding section 3, a parser can count the number of characters to
determine which column the text "Spoken" belongs to.


### 2.2. The Title

It is often desirable to label a table with a title.

If included, a Title is any text between two unbroken lines of minus symbols
which precede the table itself.  E.g.,

~~~~~


    ------------------------------------
         THE PEOPLE OF MIDDLE-EARTH
    ------------------------------------

      People     Homeland     Tongue
    ====================================
      Elves      Rivendell    Sindarin
      Dwarves    Erebor       Khuzdul
      Hobbits    The Shire    Westron


~~~~~


### 2.3. Rows

Rows of columns make up the Body of a table.

#### 2.3.a.  Clean Rows

Clean rows (so called because the markdown is uncluttered) are separated by
a line-break.  E.g.,

~~~~~


      People     Homeland     Tongue
    ====================================
      Elves      Rivendell    Sindarin

      Dwarves    Erebor       Khuzdul

      Hobbits    The Shire    Westron


~~~~~

Note that the more compact form used in example 1.1 (above) is ambiguous as
to whether there are three lines of text in a single row, or a single line
of text in each of three rows.  In this example, there is no such ambiguity.


#### 2.3.b. Multi-Line Rows

Multi-lined rows are also allowed;

~~~~~


      People     Homeland     Tongue
    ====================================
      Elves      Rivendell,   Quenya,
                 Mirkwood,    Sindarin,
                 Lorien       Nandorin

      Dwarves    Erebor       Khuzdul

      Hobbits    The Shire,   Westron
                 Breeland


~~~~~

It is clear now that the compact form used in example 1.1 (above) would
unambiguously be interpreted as three lines of text in a single row.



#### 2.3.c. Ruled Rows

Ruled rows are optional, unless colspans are needed (see below).

A Ruled-Row is *followed* by a line of minus symbols in which column-breaks
are explicitly demarked by single space symbols.  E.g.,

~~~~~


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


~~~~~

The first row-rule must appear *after* the first genuine row of table Body
data.

The last row-rule is optional (unless you want a footer, see below).  If it
does appear it does so *after* the last genuine row of table Body data.  It
describes the last row _and_ makes up the bottom table edge.


### 2.4. Columns

Table data is arranged in Columns.

#### 2.4.a. Clean Cols

Clean columns (so called because the markdown is uncluttered) are implicitly
delimited by 3+ space symbols between table content text.

This is demonstrated in most of the examples above.


#### 2.4.b. Ruled Columns

Ruled columns are optional, unless rowspans are needed (see below).

A Ruled-Column is *followed* by a column of consecutive pipe symbols, in
which row breaks are explicitly demarked by an empty line.  E.g.,

~~~~~


      People   | Homeland   | Tongue
    ====================================
      Elves    | Rivendell, | Quenya,
               | Mirkwood,  | Sindarin,
               | Lorien     | Nandorin

      Dwarves  | Erebor     | Khuzdul

      Hobbits  | The Shire, | Westron
               | Breeland   |


~~~~~

Note that the column-rule extended into the table Header.

The leading (left-hand) and trailing (right-hand) column-rules are omitted
above.  However:

A leading column-rule can optionally appear *before* the first genuine
column of table Body data.  This rule, if it appears, is merely a decorative
left-hand table edge.

The last column-rule is also optional.  If it appears it does so *after* the
last genuine column of table Body data.  It describes the last column _and_
makes up the right-hand table edge.


### 2.5.  Ruled Rows and Ruled Columns

Ruled Columns can be combined with Ruled Rows like this:

~~~~~


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


~~~~~

Or, if you prefer to include the leading and trailing rules:

~~~~~


    --------------------------------------
          THE PEOPLE OF MIDDLE-EARTH
    --------------------------------------

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


~~~~~


### 2.6.  The Footer

A table can optionally include a footer.

If a footer appears, it begins exactly one blank line after the trailing
row-rule (which is also the bottom edge of the table).

The footer itself can contain any markdown (other than a nested table).

The footer is ended as soon as two empty lines (the end of table marker) are
encountered.  E.g.,

~~~~~


    --------------------------------------
          THE PEOPLE OF MIDDLE-EARTH
    --------------------------------------

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

     1. Elves have pointy ears.
     2. Dwarves wear thick beards.
     3. Hobbits have hairy feet.


~~~~~
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20110510/d8703fa7/attachment.html>