[Doc-SIG] field-list-table better idea than list-table

[David Goodger]

Beni Cherniavsky wrote:
 > With reference to the `list-table`__ directive idea::
...
 > __ http://docutils.sourceforge.net/docs/dev/todo.html#body-list-table
 >
 > I think it's a sub-optimal idea because it tries to find an
 > alternative representation for a table's *layout* instead of
 > representing its *meaning*.

I'd say it's an alternative representation of a table's structure.  A
table is a 2D matrix, equivalent to a list of lists.  There's no
semantic meaning in the ASCII-art table syntax either.

I just thought of an alternative: use enumerated lists instead of
bulleted lists for the table cells::

     .. list-table::

         * 1. Treat
           2. Quantity
           3. Description
         * 1. Albatross!
           2. 299
           3. On a stick!
         * 1. Crunchy Frog!
           2. 1499
           3. If we took the bones out, it wouldn't be crunchy,
              now would it?

That gives much better correspondence between cells in the same
column.  I think that were only field-list-tables available, a lot of
users would use the equivalent degenerate case::

     .. field-list-table::
         :header:
             - :1: Treat
               :2: Quantity
               :3: Description
         ...

 > There is a natural way in reST to provide such clues: field lists!
 > I therefore propose a field-list-table directive.

It's a good idea.  A bit verbose, but much more readable.

 > Why have a separate header row?  We cannot in general extract it from
 > the used field names because a field name cannot contain everything
 > one might put in a table cell (although we can offer the option for
 > the simpler cases?).

Best not to put the header data under the ":header:" directive option.
The ":header:" option could contain either an integer (the number of
header rows, default 1), or some flag like "fields".  Then the table
data looks much more consistent (all data at one level).

So these two tables would be equivalent::

     .. field-list-table::
         :header: 1

         - :treat: Treat
           :quantity: Quantity
           :descr: Description

         - :treat: Albatross!
           :quantity: 299
           :descr: On a stick!

     .. field-list-table::
         :header: fields

         - :Treat: Albatross!
           :Quantity: 299
           :Description: On a stick!

 > A separate header row also allows shorter field names and doesn't
 > force one to rewrite the whole table when the header text changes.

Good point.

 > How is the header separated from the table?

Could use multiple lists to obviate the need for a ":header:" option::

     .. field-list-table::

         * :treat: Treat
           :quantity: Quantity
           :descr: Description

         - :treat: Albatross!
           :quantity: 299
           :descr: On a stick!

 > How is column order determined?  From the order of fields in the
 > first header row.

What if there's no header?  I'd say the first row's field list
(regardless whether it's a header or body row) should determine the
field names and column order.

 > Field order in all other rows is ignored.  As a side-effect, this
 > allows trivial re-arrangement of columns.

That's neat.

 > Column-spans are easy: just specify several field names together,
 > separated by, say, a comma::

Range syntax is better than list syntax (IOW, no commas).

 > For big column-spans, it might be convenient to specify only the
 > first and last fields::
 >
 >     - :foo-baz: quuux

For small ones also, I think.  Probably " - " (space dash space) as a
separator would be better, since "foo-baz" could be a legitimate field
name.  Or " ... " (space ellipsis space).

 > In non-adjacent columns are specified in this way, we should either
 > report an error or duplicate the value into each span of adjacent
 > columns.  I think I like the later more - a "logical span" approach.

Too clever, I think.  Would duplicate cells ever be used?

Sometimes in a table, the first header row contains spans.  It may be
necessary to provide a way to specify the column field names
independently of data rows.  A directive option would do it.

 > By using named fields, it becomes possible to omit fields in some
 > rows without losing track of things, which is important if we want
 > to allow row-spans (anybody who edited an HTML table with spans will
 > know what I mean ;-).

Yes, that would work.

 > One possible syntax for row-spans is to simply treat any row where a
 > field is missing as a row-span from the last row where it appeared.
 > Leaving a field empty is still possible by writing a field with
 > empty content.  But perhaps this is too implicit.

Too implicit.

 > Another way would be to require an explicit continuation marker
 > (``...``/``-"-``/``"``?) in all but the first row of a spanned
 > field.

Empty comments could work ("..").

 > If implemented, the same marker should also be supported in simple
 > tables, which lack on row-spanning abilities.

Interesting.

 > Another natural variant is to allow a description list with field
 > lists as descriptions::
 >
 >     .. field-list-table::
 >         :header:
 >             Treat
 >                 :quantity: Quantity
 >                 :descr: Description
 >
 >         Albatross!
 >             :quantity: 299
 >             :descr: On a stick!
 >
 >         Crunchy Frog!
 >             :quantity: 1499
 >             :descr: If we took the bones out, it wouldn't be crunchy,
 >                     now would it?
 >
 > which would make the whole first column a header column.

That wouldn't allow for empty cells or row spans in the first column
though.  But it's a limitation that we could live with, like those of
simple tables.

 > This has just as many rights to existance as a header row,

There's a name for a header column: "stub".

 > but I don't think it should be introduced unless we find a syntax
 > for it in ascii-art tables first...

Easy to make one up:

+------------------------++------------+----------+----------+
| Header row, column 1   || Header 2   | Header 3 | Header 4 |
| (header rows optional) ||            |          |          |
+========================++============+==========+==========+
| body row 1, column 1   || column 2   | column 3 | column 4 |
+------------------------++------------+----------+----------+
| body row 2             || Cells may span columns.          |
+------------------------++------------+---------------------+
| body row 3             || Cells may  | - Table cells       |
+------------------------++ span rows. | - contain           |
| body row 4             ||            | - body elements.    |
+------------------------++------------+----------+----------+
| body row 5             || Cells may also be     |          |
|                        || empty: ``-->``        |          |
+------------------------++-----------------------+----------+

 > Besides, such syntax has drawbacks: it's limited to a
 > single column and a single paragraph fitting on one source line.

But that suits the vast majority of tables written.  Not a big issue,
just another limitation.

Good ideas!

-- 
David Goodger <http://python.net/~goodger>