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

[Felix Wiemann]

David Goodger wrote:

> Beni Cherniavsky wrote:
>
>> 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!

IMO that's a little bit unobious.

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

Comma syntax should be allowed, too, in order to allow the user to avoid
trouble when changing the column order.

> Probably " - " (space dash space) as a separator would be better,
> since "foo-baz" could be a legitimate field name.  Or " ... " (space
> ellipsis space).

Or maybe both.  (Maybe also ' .. '.  I've seen this somewhere, just
don't recall now.)

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

Or some text to indicate that there is a colspan.  E.g.:

+-------+---------+
| Input | Output  |
+---+---+---------+
| A | B | A and B |
+===+===+=========+
| 0 | 0 | 0       |
+---+---+         |
| 0 | 1 |         |
+---+---+         |
| 1 | 0 |         |
+---+---+---------+
| 1 | 1 | 1       |
+---+---+---------+

would be rendered as:

.. field-list-table::
   :header: 2

   - :a: Input
     :b: :colspan:
     :and: Output

   - :a: A
     :b: B
     :and: A and B

   - :a: 0
     :b: 0
     :and: 0

   - :a: 0
     :b: 1
     :and: :rowspan:

   - :a: 1
     :b: 0
     :and: :rowspan:

   - :a: 1
     :b: 1
     :and: 1

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

It's a little bit hackish.  I'd prefer something like :colspan: or
:rowspan:.

>> 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?

Better ':header: 1', as David suggested.  But apart from that it looks
good.

Agreed to all the rest of your and also David Priest's posting.  Looks
all very promising...

-- 
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.

<http://www.ososo.de/>