[Doc-SIG] reST block quotes

[fantasai]

David Goodger wrote:
> [fantasai]
>
> So you'd like to be able to turn off block quote recognition?  It
> could be done, probably without too much pain, but care would have to
> be taken with other uses of indentation (list items, definition
> lists, etc.).

Certainly.

>>>What would the result look like?
>>
>><blockquote cite="http://www.docbook.org/tdg/en/html/attribution.html">
>>    An Attribution identifies the source to whom a BlockQuote
>>    or Epigraph is ascribed.
>></blockquote>
> 
> I tried looking at this code in a browser, MSIE 5.1.4/MacOS.  Not
> state of the art, but the best I have at hand.  The "cite" attribute
> didn't actually do anything.  What is it supposed to do?  (How is a
> user agent supposed to render a "cite" attribute?)

What the UA is supposed to do isn't really specified. Mozilla
provides access to it through the Properties item on the
context menu. The URI can, however, also be made available
with stylesheets and/or scripting.

>>>>An option could require the pipe quoting or another
>>>>symbol (e.g. '>') and just treat indented blocks as
>>>>regular text.
>>>
>>>I think this may be an appropriate use of a directive.
>>
>>Think what may be an appropriate use of a directive?
>>Attribution recognition or quoted blockquote recognition
>>or not recognizing purely indented blocks as blockquotes?
> 
> Question: are the first two related to the last?  If so, how?

Disabling blockquotes altogether isn't a good idea, so
if one were to disable indent block -> blockquote, one
should provide an alternative syntax.

Recognizing an attribution syntax is independent of
either of those.

 > Something similar to the "quoted blockquote recognition" idea
 > has already been documented, although as a literal block
 > alternative; see <http://docutils.sf.net/spec/notes.html> and
 > search for "per-line quoting".

It wouldn't interfere, as that requires a literal block
start sequence. That literal block example, btw, really
should be handled as two blockquotes, one inside the
other, since that's what it *is*.

> A "quoted-blockquote" directive could easily be constructed:
> 
>     Some ordinary text.
>     
>     .. quoted-blockquote::
>     
>         | Block quote text
>         | goes here.
> 
> (Although I'm not sure if this is what you mean, or has any value.)

Adding a directive like that defeats the purpose. I might as
well just write

.. blockquote::
      Block quote text goes here. There's no need for a symbol
      because it's already distinguished from a merely indented
      block.

The quoting syntax I'm using, though, is very common and so
it's non-intrusive as well as intuitive and unambiguous.
(It also allows cut & paste from emails without modification.)

> A "cite" directive might only be valid inside a block quote, and would
> add a "cite" attribute to the block quote element itself.  If it was
> useful or popular enough, it could grow special syntax.  I don't know
> if "--" at the beginning of the paragraph is enough though; I already
> use that style and would be surprised if hyperlinks after "--"
> disappeared from the rendered form.

Why would hyperlinks disappear? Inline markup is recognized
after the "-- ".

> As for turning off indentation->blockquotes, that could be a
> pragma-type directive, but would require some changes to the parser to
> support it.  I'm not convinced of its usefulness.  Can you provide
> some use cases?

Yeah. I just hand-converted an HTML file to plaintext
today to post to a mailing list. I indented every section
underneath its header. e.g.

Heading

   paragraph

   Subheading

     paragraph

     paragraph

   Subheading

     example

     paragraph

I would like to be able to do that in an reST doc.

>>   | An Attribution identifies the source to whom a
>>   | BlockQuote or Epigraph is ascribed.
>>
>>   -- DocBook: The Definitive Guide
>>      <http://www.docbook.org/tdg/en/html/attribution.html>
>>
>>would result in this:
>>
>><blockquote cite="http://www.docbook.org/tdg/en/html/attribution.html">
>>    An Attribution identifies the source to whom a BlockQuote
>>    or Epigraph is ascribed.
>>    <address class="attribution">DocBook: The Definitive Guide</address>
>></blockquote>
> 
> The markup seems problematic to me.  There are two separate constructs
> there, which aren't obviously related.  What if there's a quoted block
> without an attribution?

If there's no attribution, it doesn't get an attribution.
Parsing continues as usual.

>  What about an attribution without a quoted block? 

No special treatment. It will be handled as it is now.

> If they were joined into one construct, it would be easier to
> digest:
> 
>     | An Attribution identifies the source to whom a
>     | BlockQuote or Epigraph is ascribed.
>     |
>     | -- DocBook: The Definitive Guide
>     |    <http://www.docbook.org/tdg/en/html/attribution.html>

That could be construed as quoting the citation. That is,
the quoted text has an attribution, and you're quoting
that attribution. I think this would actually be more
difficult to parse, because one would have to know
whether this "attribution" is the last block of the
blockquote to determine whether or not it gets parsed
as an attribution.

~fantasai