[Doc-SIG] reST block quotes

[David Goodger]

Beni Cherniavsky wrote:
> I meant that blockquotes/defnitions *which are bullted lists* are
> infrequent.

And I understood it in that way.  That situation is not rare; I've
written definition list items where the definition is just a bullet
list.  Block quotes containing just a list are also quite common,
depending on writing style, and are the subject of a "to-do?" item:

    * Allow for variant styles by interpreting indented lists as if
      they weren't indented? ...

See <http://docutils.sf.net/spec/notes.html>.

> I propose to:
...
>  2. Allow the indented non-separated list as an equivallent syntax
>     alternative.  See what people end up using more.  It's not ideal
>     but I prefer it over the current.

Sorry, I don't.  There's not enough value to justify the cost.

>      - It will be ambiguos sometimes with a definition list.  If
>        something is too subtle, it's the definition list (IMHO) so I
>        propose to require some marker at the end of the definition
>        term.

I don't want to add complexity to a construct which currently works
fine, just to enable a dubious optimization.

>         - This allows for more than one line of definition terms.
>           Could be abused then for e.g. Q&A which I'm not sure is
>           good.

There are related entries in the to-do:

    * Allow very long titles (on two or more lines)?

    * And for the sake of completeness, should definition list terms
      be allowed to be very long (two or more lines) also?

They'll stay in the to-do list until somebody presents a good enough
case for their implementation (and ideally, a patch as well).

>> The debate over physical model (a paragraph is a block in the
>> document flow) vs. logical model (paragraphs can contain lists and
>> block quootes and equations and others) has been around for a long
>> time and I don't see any resolution.
> 
> OK, I'll search the archives.

The debate I mentioned wasn't on this list (at least, not
exclusively).  It's a debate among document system designers that's
been going on as long as there has been markup (XML, SGML, GML before
it, perhaps others).  DocBook chose one path, HTML and OpenOffice.org
and Docutils another.

>> Personally, I prefer the physical model, not least because it
>> results in a much simpler DTD.  The logical model opens up a big
>> can of worms.
>
> That's true.  I want that can :) -- but only it it could be
> represented in a clean way.

The can of worms is that the logical model *cannot* be represented in
a clean way.

> The big problem is that it takes away too much of the inter-line
> spacing freedom.  People won't observe it because indeed the human
> reader can see it anyway.

I think the current situation is a good compromise (StructuredText
required blank lines between *each* list item!).  I think blank lines
help readability, and omitting them harms it.

> Good points.  But that quite precludes rST as a good typesetting
> medium.

reStructuredText is a limited medium.  Every markup strikes a balance
between readability and functionality; reStructuredText is heavy on
readability.  If your functionality needs are greater than what it
provides, there are plenty of other choices out there.  We can't have
everything.

> I think also that the vertical spacing differs (para/list
> spacing smaller than inter-para).

If I understand you correctly, that's a rendering issue.  I'm not sure
I do understand correctly though; please elaborate more & include
examples in future.

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