[Doc-SIG] reST block quotes
Beni Cherniavsky
cben@techunix.technion.ac.il
Mon, 16 Dec 2002 12:57:59 +0200 (IST)
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>