[Doc-SIG] reST block quotes

[Beni Cherniavsky]

[I'm on the list, no need to cc: me]

On 2002-12-16, David Goodger wrote:

> 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:
>
Note that since the presence/absence of the empty lines is not going to
become meaningful (I agree that logical paragraphs are unexpressible in
rST), the will be no problem with blockquotes being lists.  Still it would
make the rules even more subtle.  The comment by Edward D. Loper (in
http://mail.python.org/pipermail/doc-sig/2001-April/001793.html):

  > No indentation is necessary. I suggest that if there *is*
  > indentation, an alternate interpretation is possible.

  When I read them, *I* don't interpret them differently (as an
  uninitiated reader).

is correct even now.  At least "every indented thing is a blockquote"
(modulo ::) is a simple rule to understand...  Consider the indeted list
idea more or less withdrawn.

>   * Allow for variant styles by interpreting indented lists as if
>     they weren't indented? ...
>
> See <http://docutils.sf.net/spec/notes.html>.
>
That's where I saw the idea before! :-)

> > 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.
>
All right, I'll defer to your judgment.

> >> 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.
>
Oh, that's to big to read ;-).  But I can figure it out from the resulting
formats.  Docbook's choice is obvious -- the logical model is richer.

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

> > Good points.But that quite precludes rST as a good typesetting
> > medium.
>
> reStructuredTextis 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.
>
Of course.  Just remembered reading somebody hoping to write his next book
in rST, so I thought that would be posible.  Quite naturally, it can't
really be expected (except for an rST write -> convert -> polish layout in
target format)...

> > 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.
>
LaTeX pseudo-screenshot (unconfirmed, memory/imagination mix ;)::

        Standalone logical
      paragraph.
  (1)
          * List that's outside the paragraph.
  (2)
          * Another item.
  (3)
        Another logical paragraph,
      containing:
  (4)
          * this list,
  (5)
      and continuing here.

The vertical spacings (1) and (3) are spaces between separate logical
paragraphs [1]_.  The spacings (4) and (5) are around a list inside a
paragraph.  These need not be equal and determining which spacing to use
is impossible without knowing logical paragraph structure.

.. [1] this is not that simple in LaTeX which uses first-line indent with
   no extra vertical space between paragraphs.  So (1) and (3) are forced
   by the minimal vertical spacing in a list and it might indeed be equal
   to (4) and (5).  However other typesetting style might hav ea
   difference (they most probably will, if they don't have use first-line
   indentation).



-- 
Beni Cherniavsky <cben@tx.technion.ac.il>