[Doc-SIG] Block quotes

[Alan Jaffray]

On Sun, 11 Nov 2001, David Goodger wrote:
> Alan Jaffray wrote:
> > What if any section of text
> > 
> > 1) where every line starts with the same prefix, either ">" or "> "
> > 2) with blank lines after it
> > 3) with either blank lines, or a line ending with a colon, before it
> > 
> > were treated as a block quote?
> 
> I think an "email Reader" is appropriate, to establish context.

This worries me a bit.  To what extent are we going to be dependent on
known context?

I'd like a user to be able to copy text out of email, stick it on a web
site or in a docstring or on a Wiki, and have the software do the right
thing knowing only that it's reStructuredText, not that it's rST-for-email
as opposed to rST-for-python or rST-for-wikis or whatever.

> Your rules handle one construct found in email messages. But there's
> another one, just as important: RFC822 headers.

Let me clarify - having a usable natural markup for email *bodies* would
seem to be a common goal.  I don't need a markup for email headers.  
RFC822 is a format in itself, and plenty of tools exist for it already,
so it seems unnecessary for rST to concern itself with it.

(I tend to think of the "document" of an email message as being the body,
while the headers are more akin to metadata about that document and its
delivery through the mail system; the document is what needs markup.)

> Also, there are signatures, usually (but not always) preceded by
> "-- " on a line by itself.

It's impossible to handle signatures anywhere close to reliably.  Even
if you follow that informal standard, which many (like me) don't, the
trailing whitespace will often be munged in transit.

Fortunately, it's not very important to do so; it doesn't affect the
usability of the text.  The same is not true of email quotes.  Making
this message into valid rST would be a major pain.

> > This "does the right thing" with most common email quoting, and I'm having
> > trouble thinking of an example where it would result in ambiguity.
> 
> Doctest blocks? ::
> 
>     >>> print ">>> hello"
>     >>> hello
> 
> Contrived, yes, but possible.

Ah!  I knew I was forgetting something.

This actually brings up something else I was thinking about, and I swear
I'm not just bringing it up because it affects the email quote thing. :-)
 
Do doctest blocks really belong in core rST?  As a construct which is
only used in one appplication, they seem like a prime candidate for an
application-specific directive::

    .. doctest::
       >>> print ">>> hello"
       >>> hello

For anyone who intends to use reStructuredText for purposes other than
documenting Python code, doctest blocks are just language clutter, even
aside from the ambiguity issues.  (It'd be lovely for Java programmers
if rST could recognize javadoc comments, for instance, but surely we'd
never consider putting that in the core spec...)

Alan