[Doc-SIG] reST block quotes

[David Goodger]

[fantasai]
>>>The [blockquote] syntax relies exclusively on indentation.
>>>
>>>This means one can't use indentation for other things--like
>>>indenting sections to make the document structure easier to grasp.

[David Goodger]
>> Not true.  Indentation is used in many local contexts, such as list
>> items.  In the documentation philosophy embodied in reStructuredText,
>> section structure through indentation is a *misfeature*.  See "Section
>> Structure via Indentation" in
>> <http://docutils.sf.net/spec/rst/problems.html>, and "Questions &
>> Answers", item 3, in <http://docutils.sf.net/spec/pep-0258.html>.

[fantasai]
> I *know* that, and that's why I'm particularly glad reST
> doesn't use indentation for structure like STX does. But
> because of the blockquote syntax, it doesn't let me use
> indentation as text formatting. Document structure is
> easier to see if the sections are indented. I would like
> to be able to indent sections of reST without triggering
> *any* markup construct.

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

>>> The other problem is that attributions don't seem to
>>> be recognized. It would be nice to put uris in HTML's
>>> 'cite' attribute and mark up just regular attributions
>>> as such.
>>>
>>>  | An Attribution identifies the source to whom a
>>>  | BlockQuote or Epigraph is ascribed.
>>>
>>>  -- http://www.docbook.org/tdg/en/html/attribution.html
>>
>> I don't see this as a problem either.  It's new functionality.
> 
> I apologize for my inappropriate use of English vocabulary.

:)

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

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

Any of those could be, but I was specifically referring to attribution
recognition and possibly quoted blockquote recognition.  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".

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

The "attribution recognition" idea could be done with a "cite" (or
whatever) directive, something like this:

    Some ordinary text.
    
        A block quote.
        
        .. cite:: This is some citation text, ending with a URI.
           <http://www.example.org/>

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.

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?

>> Please flesh out the spec more.

Thank you.

> So, this:
> 
>    | 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?  What about an attribution without a quoted
block?  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>

This syntax would make a block quote difficult to maintain, almost as
bad as a grid table.  I don't see its value.  Use cases?

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