Re: [Docutils-users] Re: Images as tables

[David G. <go...@py...>]

[David Goodger]
>> ... currently.  If we generalize the "figure" directive as is being
>> discussed in the "figure that is not an image" thread, we can (and
>> should) generalize the "table" directive too.

[Felix Wiemann]
> Nope, that's not a good idea:
>
> * It's not orthogonal -- we'd have two directives for one job.

I disagree.  The "figure" and "table" directives would be associated
with two different sequences, and the embellishment would be
different.  But read on.

> * It makes the "table" directive so generic that it cannot have
>   table-specific options anymore.  See also
>   <http://docutils.sf.net/docs/dev/todo.html#unify-tables>.

That's too strong a statement.  If a table directive had exclusively
non-table content, *and* it had table-specific options, the result
could be considered an error.  But say the directive contained some
non-table content, a table, some other stuff, and finally another
table.  Any table-specific options could apply to the first table and
ignore the rest, by definition (i.e. it would be documented that way).

But I'd much rather implement a new, clean, generic system than patch
the existing directives.

We should perhaps take a hint from the way DocBook handles these
things.  DocBook had both formal (with title & sequence numbering) and
informal (no title, no number) elements for table, figure, example,
equation, and paragraph.  Implementing DocBook's solution would be
overkill for Docutils, but we can adopt the kernel of the idea.  I
propose the following:

1. The current directives (table, figure) should remain "informal": no
   sequence numbering.  They (and only they!) still handle table- and
   figure-specific options.  They may have titles/captions, but that
   is orthogonal to numbering.

2. We implement a new directive, "sequence", that declares new object
   sequences, their high-level rendering (title or caption,
   embellishment style), and relationships to other sequences
   (i.e. what sequence triggers a reset).  This has already been
   discussed in this thread.

3. The resulting sequence can be specified independently, by one or
   more new "formal" directives (perhaps "titled" and "captioned";
   specific names and functionality TBD).  These will handle sequence
   numbering and titles/captions.

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