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

[Moore, Paul]

From: David Goodger [mailto:goodger@users.sourceforge.net]
> Perhaps you'd feel differently if you needed to use it?

Oh, certainly. I wasn't implying otherwise - just noting that we have to
take care not to include "the kitchen sink" just because someone wants it.
The recent discussion on python-dev was lukewarm, and I got the sense that
part of the issue was "why does it need to be so complicated?"
 
> > How often is this construct likely to be used? In what contexts?
> 
> Richard Jones wanted a snailmail address in a document.

That's a valid case. Two points - first, with this use case in mind, "verse"
is a dreadful name. I can't think of a good one, though. And the second
point is why can't this be handled with a literal block? I can't imagine
needing markup in an address. Is it just because literal blocks are
displayed in a fixed-width font, and so don't "look right"?

As I said, I see the value of this, but I think that we need to clarify the
aims somewhat.

As a related point, I personally would prefer ``*emphasis*`` to be bold, not
italic, as this is the usage I see most frequently in E-Mail. However, I
accept that reST is addressing logical content, rather than layout, and as
such, the way the logical construct is formatted is the role of the backend,
not the document source. (This is a *good thing* - the alternative leads to
<font> tags...)

Given this premiss, I would ask again, what is the *logical* construct
involved here? Logically, the gap in functionality is the lack of any way of
including markup in a "literal" block. In other words, a
linebreak-preserving construct where markup is still respected. This is the
construct I fail to see the use for - I wouldn't need markup in a snailmail
address, so that use case doesn't mandate this.

On the other hand, there is a definite point to the layout issue of wanting
a "literal" construct which formats like running text, but with linebreaks
preserved. And yes, there is a "logical" value to such a construct - but
it's hard to put a name to it, and hence to understand its logical
significance (as opposed to its layout significance - "I want a literal
block of text here, but it looks funny if I use a real literal block which
displays in Courier")

> of every time I've had to use a line break in Word, or <br> in HTML, I
> believe the construct has merit.

Agreed - but Word linebreaks and <br> tags are inherently formatting
directives, not structural ones. That's the distinction I'm trying to make.

> > If you really, really, feel the need to put it in, make it a
> > directive. Don't invent new syntax for it.
> 
> I agree.  Syntax can be added later if called for.

And at least as importantly, if you use a directive, you're *forced* to
think up a decent name for it! Verse doesn't work for 99% of the real life
use cases, and its a PR disaster ("look - this thing is clearly a kitchen
sink design - who ever needs to quote verse in Python docstrings???") Quote
is a little better, but still has unsuitable overtones (in LaTeX, IIRC, the
quote environment uses smaller, slanted text, which is a common convention
for "real" quotes).

> I think that, similarly to modules in Python's library, directives
> that are "standard" will be used, but directives that need to be
> separately installed won't.  I'd like to build a rich variety of
> standard directives, and document them all in "reStructuredText
> Directives":

OK, that fits with the Python library concept. If you make it clear that
"library directives" are extensions, not part of "core" reST, then I have no
problem with this. It's the bloat question and PR issues again, though.

Thanks for listening - as I said, I'm not against the construct per se, but
I would like to see a clearer picture of the logic behind it...

Paul.