[Docutils-develop] indented class directives

[Guenter M. <mi...@us...>]

Dear David, dear Docutils developers,

trying to tackle bug 266 http://sourceforge.net/p/docutils/bugs/266/
I came across an interesting feature of the class directive:

The rST specs say:

  The "class" directive sets the "classes" attribute value on its content
  or on the first immediately following non-comment element.
  
  -- http://docutils.sourceforge.net/docs/ref/rst/directives.html#id14

This is also true, if the class directive is "nested" at the end of an
indented text block.

------------------------------------------------------------------------

Example:

  a block quote
  
  .. class:: indented
  
Section with class argument
===========================

  .. class:: second indented
  
paragraph with second class argument, following an empty block-quote


This implementation detail allows the "classification" of individual list
items -- except the first:

* unordered list

  .. class:: classy item
  
* second item, with class argument

definition list:

first term:
  fist def
  
  .. class:: for the second dl item
  
second term:
  second def
    
See the XML or pseudoXML output to find the "classified" second item.

.. note::
   :class: directive example

   even classes set in a directive-block apply not to the containing object
   (here a note) but the next one, transgressing the "container limit".
   
   .. class:: html writer problem
    
The HTML writer currently ignores the class values of definition list items,
as there is no matching HTML element but only <dt> and <dd>.

------------------------------------------------------------------------

The current behaviour is in accordance to the specification, there is no
discussion of nesting level or indentation so "the first immediately
following non-comment element" may also be outside the scope of object
containing the "class" directive.

However, it is non-intuitive, as "normally", indented blocks signify content
that belongs together.

The question now is:

How to proceed from the current situation:

a) document the current behaviour with an example in directives.txt?

b) change the behaviour: ignore and warn or throw an error, if a "class"
   directive is not followed by an object at the same or a nested level
   (sibling or child of current object).
    
   This would also mean, that class and name arguments can not be set for
   individual list items (as an inherent limitation of rST's simple
   markup syntax).
    
c) leave it as an undocumented feature.
   
The HTML writer currently ignores the class values of definition list items,
as there is no matching HTML element but only <dt> and <dd>.

In case a) and c), I suggest a <div> element for definition list items that
have class or id/name set.

Günter