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

[Beni Cherniavsky]

With reference to the `list-table`__ directive idea::

    .. list-table::

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

__ 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 find this list completely unreadable -
to see what's the meaning of "1499" I must note that it's the second
field, go back to the top and find the second field there
("Quantity").  I things don't line up one under the other, some other
reminder is necessary.

There is a natural way in reST to provide such clues: field lists!  I
therefore propose a field-list-table directive.  To separate the table
lines one from the other (adjacent field lists would just be treated
as one), the natural idea is making a bulleted list of field lists::

    .. field-list-table::
        :header:
            - :treat: Treat
              :quantity: Quantity
              :descr: Description

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

        - :treat: Crunchy Frog!
          :quantity: 1499
          :descr: If we took the bones out, it wouldn't be crunchy,
                  now would it?

Header rows
-----------

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?).  A separate header row also allows shorter field
names and doesn't force one to rewrite the whole table when the header
text changes.

How it the header separated from the table?  A transition (``-----``)
would look good (I think) but is not allowed in this position by the
current document parser (which is not entirely prohibitive - it's not
a change to the document model because it will not be left in the
document as a transition).  I showed a ``:header:`` directive option
which is simple but perhaps sub-optimal.  Other ideas would be
welcome.

Why there is a bullet under ``:header:``?  Recall that a table's
header can consist of several rows.  We can make it optional for the
common case.

How is column order determined?  From the order of fields in the first
header row.  Field order in all other rows is ignored.  As a
side-effect, this allows trivial re-arrangement of columns.

Spans
-----

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

    - :foo: abc
      :bar: def
      :baz: ghi

    - :foo, bar: quux
      :baz: qux

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.

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

    - :foo-baz: quuux

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 ;-).  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.

Another way would be to require an explicit continuation marker
(``...``/``-"-``/``"``?) in all but the first row of a spanned field.
If implemented, the same marker should also be supported in simple
tables, which lack on row-spanning abilities.

Header column idea
------------------

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.  This has
just as many rights to existance as a header row, but I don't think it
should be introduced unless we find a syntax for it in ascii-art
tables first...  Besides, such syntax has drawbacks: it's limited to a
single column and a single paragraph fitting on one source line.

-- 
Beni Cherniavsky <cben at users.sf.net>
Note that I can only read emails on week-ends.