[Docutils-develop] Re: "container"

[Felix W. <Fel...@gm...>]

David Goodger wrote:

> Felix Wiemann wrote:
>
>> I'd like to raise my concerns about how you added it:
>>
>> * There was thread about that where I objected to the container
>>   element, and the last posting was written by you.
>
> In that last message (the "Multiple Elements With class directive"
> thread on docutils-users), I provided two opportunities.

OK, it's partly my fault.  Sorry.

> [...]
>
> It seems silly to make a branch for a sandbox.

Why?  That's what we have the sandboxes below the trunk directory.

> 26 days wasn't long enough?  Even if you were away at EuroOSCON, you
> have participated in plenty of other discussions since.

I don't work through my email in chronologic order, by the way.  Do you?

[Policy discussions off-list.  Keeping the technical stuff on the list.]

> The real difference [between "class" and "container"] is that the
> "container" element can be used for further processing and rendering,
> such as putting a box around the contents.  The "class" directive can
> only be applied to multiple individual elements, but not to a group of
> elements.

My problem with the current "container" implementation is that it's not
clear that the argument is a class.  (Whereas with the "class" directive
it is.)

So I'd prefer to see either one of the following solutions:

1. Remove the "container" directive and make the "class" directive add a
   container around its contents.

   The logic of the class directive would then be "apply the class to the
   contents as a whole" (using a container) instead of the current
   implementation "apply the class to each contained element".

   This would mean we don't have to add another directive ("container"),
   thus avoiding adding more and more directives.

2. Make the class of the "container" directive optional, making the
   class an option.

   This would have the disadvantage that the syntax becomes a bit more
   unwieldy since you'd have to write::

       .. container::
          :class: handout

          ... contents ...

  However, the advantages are that it's explicit, and you can have a
  container without a class.  I can actually see use cases for that:

  * For a presentation I want all elements inside a section to be
    displayed sequentially.  So I could write::

        Slide Title
        ===========

        At first only the slide title is displayed.  When I press
        space-bar, this paragraph is displayed.

        Next time I press space-bar, this paragraph is displayed.

        .. container::

           Next time I press space-bar, two paragraphs are displayed!

           This is the second paragraph and it's displayed together with
           the previous one.

       This is the last paragraph on the slide.

  * Another use case: I remember someone asking for a possibility to add
    set an ID on every paragraph, for whatever reason.

    Now given that possibility, you might want to set an ID on two
    paragraphs that belong together, like so::

        This paragraph gets an ID.

        This one, too.

        .. container::

           These two paragraphs get an ID combined.

           This is because the ID is set on the container element.

        Last paragraph.

  This solution is also more orthogonal: The "class" directive is for
  setting a class, and the "container" directive is for creating a
  container.  Neither of both forces you to do the other thing.

I think the second solution (making the class optional for "container")
is *slightly* better, but I'd like to hear your opinion.

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR