[Doc-SIG] Email Reader (was Re: reST block quotes)

[Benja Fallenstein]

Hi David, hi Beni,

David Goodger wrote:

>Beni Cherniavsky wrote:
>  
>
>>The second goal opens a can of worms -- free text is too free to
>>parse automatically and needs corrections.
>>    
>>
>
>I suspect that an actual application for an Email Reader must present
>itself before we can make these decisions.  IOW, what's the use case?
>I don't know that there's much value in supporting email in general,
>but I do know there would be much pain.
>

I've been idly pondering ReST email before, so I have my own ideas about 
this :-)

I don't think that parsing arbitrary incoming emails as ReST makes much 
sense-- it'd be like running all .txt files on my harddisk through the 
ReST tools. I wouldn't want to use this on any emails but those 
explicitly written as ReST.

The applications I envision are two flavors of email user agent (for 
reading & writing email):

- A text-based client, which would provide tools for composing ReST 
e-mails, most notably a syntax validator (so that you don't accidentally 
send emails that cannot be read because they aren't ReST); this would 
send emails as text/vnd.python.rst or so.
- A graphical client, which would render text/vnd.python.rst e-mails 
graphically, and allow for graphical composing of ReST e-mails, like 
Mozilla's HTML email composer.

This would finally allow me to use hyperlinks, variable-width fonts, 
italics etc.pp. in composing & reading e-mail, without worrying about 
unreadable font size settings, people complaining about HTML mail bloat, 
people turning off HTML mail (like me :) ), or readability on text 
terminals; instead, I'd know that any email client would get something 
it can read, w/o bloat, and people with a graphical ReST mail reader 
would see the mail the way I typed it (modulo preferences like font or 
text size).

The difficult question is how to do quoting; I think (contrary to what 
some people seem to be saying here) that quoting should not generally be 
done through literal blocks-- I think quoting of non-ReST mails should 
be, but quoting of ReST mails should preserve the formatting of the 
quoted mail. Also I think that quoting should be done through the 
commonplace ">" syntax; this is simply the most wide-spread variant, and 
forcing something else down peoples' throats seems wrong. To 
disambiguify from doctest blocks, choosing the ">" + space syntax as 
required for ReSTmail seems good.

To discriminate between literal and non-literal quotings, I'd suggest:

I wrote:
 > foo
 > bar

for non-literal quoting, and

I wrote::
 > foo
 > bar

for literal quoting.

More to the point, the rules would be as follows:

- A block where each line is prefixed by "> " (angle bracket + space) is 
*quoted*.
- A block where all but the first line is quoted by "> " is *quoted with 
source given*.
- If the first line in a "quoted with source given" block ends in a 
double colon, this quoted block and all following quoted blocks 
*without* source given would also be literal blocks.
- If the first line does not end in a double colon, this quoted block 
and all following ones w/o source would just be quoted, not literal blocks.
- (If there's a quoted block w/o source, and there is no quoted block 
with source above, that block would be just quoted, not literal.)

Here's an example:

=== snip ===
 > Blabla

Foo wrote::
 > Bla, *baz*
 > Foo

Then, bar wrote:
 > Foo, *blaabla*!
=== /snip ===

This could then become something like:

=== snip ===
<quoted>
<quote>
Blabla
</quote>
</quoted>
<quoted>
<source>
Foo wrote:
</source>
<quote>
<literal>
Bla, *baz*
Foo
</literal>
</quote>
</quoted>
<quoted>
<source>
Then, bla wrote:
</source>
<quote>
Foo, <em>blablaa</em>!
</quote>
</quoted>
=== /snip ===

- Benja