Re: [Docutils-users] policy for new directives (was Using blockquote element for quotes)

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

[William Dode]
 > I found them in docbook :
 >
 > exergue = epigraph
 > chapeau = highlights
 > inter-titre = bridgehead

Thanks.  It really helps to have common terminology to use, and a
standard to refer to.

It seems to me that epigraph/exergue and highlights/chapeau are
variations on block quotes.  The implementation will use "class"
attributes to differentiate.  I've added an "attribution" element to
block quotes, and I'll add a directive for it too.

[David Goodger]
 >> I suspect the "class" directive may be able to handle these cases
 >> easily.
 >
 > But a generic class attribute will not change a lot from doing a
 > customized directive like i did (really easy).

The advantage of the "class" attribute/directive is that the *next*
time somebody needs a specialized construct, they won't need to write
a directive.  Adding support may be as simple as editing the
stylesheet.  Touching less code is better.

Implementing using a "class" directive::

     ordinary text

         .. class:: epigraph

         Structured text is really a great idea for certain situations;
         reST is a much better implementation of the idea than any
         versions I've seen before.

         .. attribution:: Guido van Rossum on Python-Dev, 2002-04-04

Implementing using an "epigraph" directive::

     ordinary text

     .. epigraph::

         Structured text is really a great idea for certain situations;
         reST is a much better implementation of the idea than any
         versions I've seen before.

         .. attribution:: Guido van Rossum on Python-Dev, 2002-04-04

Note the position of the initial directive.  In the first example,
it's *inside* the block quote, while in the second, it *introduces*
it.  The advantage of the dedicated directive is that the
"attribution" parsing could be built-in::

     ordinary text

     .. epigraph::

         Structured text is really a great idea for certain situations;
         reST is a much better implementation of the idea than any
         versions I've seen before.

         -- Guido van Rossum on Python-Dev, 2002-04-04

Perhaps the attribution parsing could become an integral part of block
quote parsing?  (Iff the last paragraph begins with "--", it becomes
an attribution.  Any issues?)  This goes back to Paul Moore's initial
"Using blockquote element for quotes" post (2003-04-18).

[re: intertitre/bridgehead]
 > I think it's more like a body element, just a different paragraph.

Yes, I think so too.  I think it warrants a new doctree element
though.  I don't like the name "bridgehead", because it has nothing
whatsoever to do with the dictionary definition (m-w.com):

     1 a : a fortification protecting the end of a bridge nearest an
     enemy b : an area around the end of a bridge
     2 : an advanced position seized in hostile territory

But if we can't come up with a clearly superior term, we should use
"bridgehead" because of DocBook precedent.  I can't find any
authoritative reference.  The best I can find in `The Chicago Manual
of Style` is "subhead".  Any ideas?

 > epigraph and highlights are generaly in begin of a section but i
 > don't see reason to don't let us use it everywhere.

OK

 > like you will see in the code, exergue is generaly a
 > FixedTextElement. <pre>

I don't see any reason to limit it this way.  If it's useful enough,
an "epigraph" directive could grow a "line-block" option.

 > please comment on my code, i really don't know if it's "the good
 > way"...

They're fine, if all you want is single-paragraph contents.  I think
epigraph/exergue and highlights/chapeau should be containers, based on
block_quote.  The HTML Wrier code is fine too.

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv