[Doc-SIG] reST block quotes

[Beni Cherniavsky]

On 2002-12-15, David Goodger wrote:

> [Beni Cherniavsky]
> > I meant that:
> > - I don't myself feel the need to free up indentation (but that
> > doesn't mean that others don't).
> > - I'm not entirely happy with making empty lines around lists.It
> > takes to much real estate, especially if I make empty lines
> > between items.
>
> Something's gotta give.For zero ambiguity (within reStructuredText's
> framework), blank lines before & after lists are essential.
>
> > So I don't but then the list looks too isolated
> > from the paragraph [1]_.
> > - I understand that omitting the empty line, as is, would create an
> >   ambiguity.  It's not even clear to my eyes.
> >    - Demanding an extra space before the bullet would remove the
> >      ambiguity, I think.
>
> Too subtle, IMHO.
>
You have a point.  This proposal would work best with logical paragraphs
but I understand that's not going to happen.

> >      Currently this means a list in a blockquote
> >      or a list in the definition of a definition list, depending on
> >      presense of empty line before.
>
> Definition list only in the case of a single line before the indent.
>
> >      Both are infrequently needed, so
> >      the empty comment hack looks acceptable to me (but I'm biased).
>
> Frequently enough.
>
I meant that blockquotes/defnitions *which are bullted lists* are
infrequent.

I propose to:
 1. Put aside the logical paragraphs (I was more or less convinced by
    following arguments).
 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.
     - Since logical paragraphs are rejected, this won't be ambiguos as a
       block quote (which keeps its separating lines).
     - 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.
        - My proposed " --" marker is not too pretty::

              Foo --
                Bar

              Quux --
                Quuux

          Maybe something other would be better.  " ::=" isn't pretty
          either...

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

> > .. [1] This reminds me of a different concern I had.Some markup
> > models (LaTeX and my brain ;-) think of paragraphs as logical beasts.
>
> reStructuredText (and Docutils) treat paragraphs as physical.It
> would be impossible to reliably infer logical paragraph semantics from
> plaintext sources.

That's the biggest problem.  It would only be very clear if we require
intented first lines in logical paragraph (and then they are limited to
start with text).

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

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

> >  A paragraph could contain a list
> >   - (like this)
> >  or other things (especially blockquotes) and then continue.
> >  There are three more combinations:
> >   - The thing is part of the previous paragraph, a new paragraph
> >     starts after it.
> >
> >  - The thing can be a logical paragraph on its own.
> >
> >   - The thing starts a new paragraph.
>
> I'm not sure what "the thing" is or where you're going with this.If
> the text of your message was meant as an example of what you're
> proposing, I find it very hard to follow the structure.
>
The "thing" is a list, blockquote, or any other construct nested inside
the logical paragraph.  Yes, I tried to write in clever
form-matches-content style.  So the example is surely contrived, such
combinations are rare.  Nevertheless, you have a point - it's not very
clear.

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.

> >  Seems rare but consider a text where each quote is followed by some
> >  comments (as in emails).
>
> Not following you.
>
I was refering to a nested construct (non-text) starting the paragraph.

> >  So I want a way to represent the disctinctions.
>
> Not worth the trouble IMHO.
>
Legitimate decision -- the trouble is big indeed ;-)

> >   - Just tried putting a list in a substitution::
> >         Text |sub| text.
> >
> >         .. |sub| replace::
> >          - Foo
> >            - Bar
> >     Didn't work.
>
> Substitutions have to be phrase-level.I can't remember if the parser
> checks or not; if not, it'll go on the to-do.
>
It correcrtly complains that a substitution must be a single paragraph.

> >     (See, here I wanted the text-literal-text to form one logical
> >   paragraph).  I'm not sure it should work but it indicates the
> >     big issue -- the model that a paragraph contains no other
> >     elements must be abandoned to support this concept.
>
> And, as I said, I don't think it's worth the effort even if it were
> feasible (which I doubt).The computer doesn't really care that
>
>   <p>Beginning of paragraph</p>
>   <ul>
>       <li>item one</li>
>       <li>item two</li>
>   </ul>
>   <p>continuation of paragraph.</p>
>
> is a single logical paragraph (not to mention *this* paragraph!).
> The human reader picks it up right away though.Only if there's a
> first-line paragraph indent would it matter to the reader.
>
Good points.  But that quite precludes rST as a good typesetting medium.
I think also that the vertical spacing differs (para/list spacing smaller
than inter-para).

> > .. [2] Unrelated question: when should I use literal text (``),
> >  interpreted text (`) and no quoting?
>
> [snip]
>
> When there is a use for them, the docs will discuss them.Until
> then, it would just be confusing.It already *is* confusing, some
> would say.
>
That's why I asked :-)

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