[Doc-SIG] reST block quotes

2002年12月16日 01:24:34 +0200 (IST)

On 2002年12月15日, David Goodger wrote:
> Beni Cherniavsky wrote:
> ... a bunch of email-related details omitted
>> Yes, there are many thorny issues wrt Email context.That's why I
> don't want to make any premature decisions, and why I invite anyone
> who's interested to look into the issues.
>All right, I'll start thinking about the emails I write "how will this
interact with rST?" ;-) Of course this is biased since I already use many
parts of rST in emails.
> > If you ask my personal opinion, I'm quite happy with reST's current
> > style (perhaps modulo allowing indented bulleted lists instead of
> > empty lines but I'm not settled on it).
>> Not following you.Can you elaborate please?
>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. 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. 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. Both are infrequently needed, so
 the empty comment hack looks acceptable to me (but I'm biased).
 - I'm sure I saw this discussed somewhere already but I can't find it in
 ``alternatives.txt`` [2]_...
.. [1] This reminds me of a different concern I had. Some markup models
 (LaTeX and my brain ;-) think of paragraphs as logical beasts. 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.
 Seems rare but consider a text where each quote is followed by some
 comments (as in emails).
 Most markup models (HTML, current rST) treat a paragraph as an atomic
 piece of text. Any other construct terminates it. But look at any
 book - it's not so! LaTeX renders a new paragraph indented and a
 resumed paragraph without indentation. Math formula "dysplays" are
 another example for things that could be part of a paragraph...
 So I want a way to represent the disctinctions.
 - As you see, the space-before-bullet format allows to express it for
 lists. However blockquotes are not discernable from definition
 lists then
 (if the paragraph above would be one-line).
 - I'm not sure how to solve it. Scanning the spec, it seems that
 only blockquotes create problems. Maybe some explicit
 blockquote-marking syntax is needed after all. This time an empty
 comment won't cut it. But I don't see a good one. Then maybe a
 definition list should be explicit. How about terminating each
 definition line with " --" (removed in the output)?
 - Just tried putting a list in a substitution::
 Text |sub| text.
 .. |sub| replace::
 - Foo
 - Bar
 Didn't work. (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.
.. [2] Unrelated question: when should I use literal text (``),
 interpreted text (`) and no quoting?
 - What's the red line between an identifier and a piece of Python
 code? If I refer to variable `foo` that's interpreted; if I refer
 to ``a() + b()``, that should probably be literal; what about
 `m.bar` where m is not a class or variable in current scope but
 conventionally stands for any "Matcher" object (there are many
 matcher classes) in some library I'm writing?
 - Should I put all filenames in literal quotes? To a human it's
 already discernible when there is an extension (foo.py) so I'm not
 sure.
 - Generally the docs (including the PEPs) need some more discussion on
 where actually to use interpreted text...
-- 
Beni Cherniavsky <cben@tx.technion.ac.il>