[Doc-SIG] Block quotes

[David Goodger]

> On Sun, 11 Nov 2001, David Goodger wrote:
>> I think an "email Reader" is appropriate, to establish context.

Alan Jaffray wrote:
> This worries me a bit.  To what extent are we going to be dependent on
> known context?

Depending on the ambiguity otherwise, possibly considerably.

> 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.

Reasonable, to certain extent. Eventually, ambiguity rears its ugly head.

>> 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.

That depends on how much of the email message you copy, doesn't it? If
the copying includes the "To:", "From:", "Date:", and "Subject:" headers as
well, we'd want those converted as well (to field lists). That absolutely
requires context.

>> 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.

True. But an email Reader could easily match a "^-- ?$" pattern within 10
lines of the end of the text, requiring the author or user to ensure that
"--" is placed there properly. Useful.

>>> 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? ::

> Ah!  I knew I was forgetting something.

Look at the first of the three quote blocks above. Looks just like a doctest
block, don't it?

> 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::

Yes, they belong in core rST, but perhaps turned off by default, since email
quoting would probably have a bigger audience. However, I would imagine that
some email messages would have both constructs. Tricky.

No, not as an application-specific directive, for the simple reason that the
"Python source docstrings" and "Writings about Python" applications are the
most important to reStructuredText at present. But it might be a directive
in another context, such as the "Email Reader".

> (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...)

I get your meaning, but that's not a valid comparison. The text has to be
*extracted* from the comments before it can be processed, which is clearly
the responsibility of the Java Source Reader.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net