[Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness)

[Moore, Paul]

From: David Goodger [mailto:goodger@users.sourceforge.net]
> David Goodger wrote:
> >> However, a literal block isn't really the ideal way to represent an
> >> address block, is it?  I've been mulling over an idea for a "verse"
> >> directive which seems to apply here.  See
> >> http://docutils.sf.net/spec/notes.html#body-verse. What do you
> >> think?  How about that ';;' syntax?
> 
> Tony J Ibbs (Tibs) wrote:
> > As you say, the outstanding question is interpretation of 
> > inline markup within a verse - i.e., in HTML terms, is
> > it <pre> or not...
> 
> Literal blocks use <pre> exclusively and treat all whitespace and
> line breaks as significant; no inline markup is recognized.
> In "verse blocks" (semi-literal blocks; anybody have a better
> name?) only line breaks and indentation are treated differently
> from a regular paragraph; inline markup like *emphasis* is
> recognized normally.

Frankly, this seems like overkill to me. I can see what you're getting at -
there's a gap in the logical model, between completely literal blocks, and
completely interpreted text - but I don't think the gap needs to be filled.

How often is this construct likely to be used? In what contexts? (Python
docstrings? Wiki pages? I'm not sure what target applications are key for
ReST, other than Python docstrings, and doc-sig postings :-)

If you really, really, feel the need to put it in, make it a directive.
Don't invent new syntax for it. And maybe even just make it a sample
directive, not enshrined in the spec, but available as an example of how the
directive infrastructure can be extended.

This actually raises a question, which may well be covered in the
documentation - I haven't read it for a while. How does a document which
relies on a particular directive, state that fact? Just by using it? So that
if the user doesn't specify the directive (using command line flags to the
tools?) he gets a system error/warning, and works out what to do from there?
I guess that's OK, actually - we don't want to have to start documents with
blurb like::

    .. using:: image, quote, my-special-directive

That just gets silly...

Just my 2p worth.
Paul.