Tables

[John MacFarlane]

>  - A table should look like a table in plain text

>  - It must be easy to create

>  - It must be flexible about how much text can go in a cell

>  - It shouldn't force you to use a fixed-width font


I agree with the comment that the first and last desiderata are in
tension. Since one of the guiding goals of markdown is to be *readable*,
I decided in pandoc to go for the first and forget about the last. So,
here's what a simple table looks like in pandoc -- pretty much just how
you'd naturally write it in a plain text email (assuming you use a
fixed-width font):


  Right     Left     Center     Default   
-------     ------ ----------   -------   
     12     12        12            12    
    123     123       123          123    
      1     1          1             1    

Table:  Demonstration of simple table syntax.


As you can see, these simple tables also allow the user to specify the
alignment of columns, and allow the user to specify a caption, all
without anything that looks like markup. (I suppose the
English-centricism of the caption syntax is objectionable. It would also
be nice to have more flexibility in indicating borders. So there's room
for improvement on this model.)

Another desideratum is that table cells should not be limited
to one line.  So pandoc also allows tables like this:


-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

Table: Here's the caption. It, too, may span
multiple lines.


In fact, an even more general table syntax is needed, and eventually
pandoc will probably support reStructuredText-style box tables, which
allow arbitrary block-level elements in cells.

Your comment suggested that you think this is too much work for the
writer. But John Gruber has emphasized that markdown is meant to be a
format that is easy on the *reader* (as well as the writer); markdown
documents should look good on their own, without any conversion to
another format. None of the table syntaxes that don't force a fixed width
font really satisfy that, in my view.  So that's the rationale behind
pandoc's table syntax -- though I certainly understand why others made
different decisions.

Best,
John


+++ Daniel Winterstein [Feb 19 09 09:16 ]:

> @John: Thank you for pointing me to those table syntax ideas. They are

> all sensible, but look like hard work for the user.

> 

> Since there is no standard, I'd like to suggest a couple of

> possibilities and get people's comments.

> 

> Design goals:

> 

>  - A table should look like a table in plain text

>  - It must be easy to create

>  - It must be flexible about how much text can go in a cell

>  - It shouldn't force you to use a fixed-width font

> 

> Suggestion 1:

> 

>  - A table begins with a header row where columns are separated by |s.

> It ends with a blank line.

>  - It can optionally include lines of -----s, which are ignored when

> generating html

>  - Within a table, columns are separated by either a tab or 3 or more

> spaces. Actual alignment of text is up to the user. Alignment varies

> of course depending on font. In my examples below, I have aligned the

> columns _for my email editor_.

>  - If you want more control over a particular cell or row, you can use

> an html cell or row

>  - If you need more control than that, use an html table

> 

> Example:

> 

> | Wine			       | Tasting notes		

> --------------------------------------------------------

> Black Stump Bordeaux 	peppermint flavoured Burgundy

> Sydney Syrup 		        ranks among the world's best sugary wines

> Château Blue		        lingering afterburn

> Old Smokey 1968		compares favourably to a Welsh claret

> 1970 Coq du Rod Laver	recommended by the Australian Wino Society

> Melbourne Old-and-Yellow	a good fighting wine is, which is

> particularly heavy and best suited for hand-to-hand combat.

> <td colspan='2' class='caption'>Table: Lesser Australian wines</td>

> 

> 

> Idea 2: Use a table tag to mark a table block. If the contents are not

> html, then convert them

> 

> <table class='my-table-css'>

> Wine			                Tasting notes		

> Château Chunder		a fine wine which really opens up the sluices at both ends.

> Sydney Syrup 		        ranks among the world's best sugary wines

> Château Blue		        lingering afterburn

> Old Smokey 1968		compares favourably to a Welsh claret

> 1970 Coq du Rod Laver	recommended by the Australian Wino Society

> Melbourne Old-and-Yellow	a good fighting wine is, which is

> particularly heavy and best suited for hand-to-hand combat.

> </table>

> 

> Pros: can provide class information and border settings.

> 

> 

> Idea 3: Use a caption at the end of the table to mark a table block,

> with empty captions being allowed.

> Example:

> 

> Wine			                Tasting notes		

> Black Stump Bordeaux 	peppermint flavoured Burgundy

> Sydney Syrup 		        ranks among the world's best sugary wines

> Château Blue		        lingering afterburn.

> Old Smokey 1968		compares favourably to a Welsh claret

> 1970 Coq du Rod Laver	recommended by the Australian Wino Society

> Melbourne Old-and-Yellow	a good fighting wine is, which is

> particularly heavy and best suited for hand-to-hand combat.

> Table: Lesser Australian wines

> 

> 

> What do you think?

> Regards,

> Daniel

> _______________________________________________

> Markdown-Discuss mailing list

> Markdown-Discuss at six.pairlist.net

> http://six.pairlist.net/mailman/listinfo/markdown-discuss

>