[Doc-SIG] Block quotes
David Goodger
goodger@users.sourceforge.net
Mon, 12 Nov 2001 22:38:48 -0500
> 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