[Doc-SIG] reST block quotes

[David Goodger]

fantasai wrote:
> ok, so there's a problem with the blockquote syntax
> that was one of the first things I noticed: The syntax
> relies exclusively on indentation.

That's not a problem, that's a *feature*. :)

> This means one can't use indentation for other things--like
> indenting sections to make the document structure easier to grasp.

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

> 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.  What
would the result look like?

> So, I'd like to have reST take something like that
> (URIs might need something to distinguish them from,
> say, people) and translate it into appropriate markup.

What would that be?

> An option could require the pipe quoting or another
> symbol (e.g. '>') and just treat indented blocks as
> regular text.
> 
> (I'd gotten the symbol-quoting part to work last year,
> but ran into some trouble with the attribution (I was
> using a different syntax) and put everything aside for
> later.)
> 
> So, what do you think?

I think this may be an appropriate use of a directive.  Directives
offer an easy way to experiment with new features without requiring
new general syntax.  If a feature is useful enough and has appropriate
and unambiguous syntax, it could become a general feature.

Please flesh out the spec more.

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