[Doc-SIG] reST block quotes

[David Goodger]

[fantasai]
>>> Think what may be an appropriate use of a directive?
>>> Attribution recognition or quoted blockquote recognition
>>> or not recognizing purely indented blocks as blockquotes?

[David Goodger]
>> Question: are the first two related to the last?  If so, how?

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

So, if the "diabling blockquotes" proposal is *not* accepted, the
alternative syntax wouldn't be required?  If that's not the case,
please justify them independently.  I see potential value for quoted
blockquote recognition in an email context (more below), but not for
disabling ordinary blockquotes.

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

Take another look: """Generalize the "literal block" construct to
allow blocks with a per-line quoting to avoid indentation?"""  Last
three words are the whole point.

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

Since early on there's been talk about an "Email Reader", which would
handle quoted segments of messages, signatures, and other
email-specific constructs.  Perhaps that's where effort should be
directed?  I wouldn't want to accept a proposal that was incompatible
with an Email Reader (even a future potential Email Reader).

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

If the hyperlink is subsumed into the <blockquote>'s "cite" attribute,
in all but the most cutting-edge browsers (if then) it's as good as
invisible.  If something so drastic is happening to data, I think the
markup should be much more explicit and distinctive.

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

You can do that with current reST; you would end up with nested block
quotes.  I don't get it.  Can you show me an example of how you'd like
to apply this concept to reStructuredText sources?

>>>    | 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 about an attribution without a quoted block?
> 
> No special treatment. It will be handled as it is now.

How is it handled 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.

The block quote part could require quote char + whitespace, and the
attribution could omit the whitespace.  That would disambiguate it:

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

But I still don't see the value of the attribution proposal, as
opposed to simply rendering the attribution as an ordinary paragraph.
I'd like to see a concrete example where the results would be
*useful*.  HTML's <blockquote cite="..."> doesn't seem to have
universal support.  How should attributions be handled for current
browsers (back to Netscape 4)?

Even more fundamentally, how should attributions be marked up in the
Docutils internal doctree?  I.E., what changes to the "block_quote"
element in spec/docutils.dtd?

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

That's easy to know.  What's not so easy (programmatically or to the
human eye) is to link two successive elements that don't have a
logical containing context.

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/