[Doc-SIG] reST block quotes
Beni Cherniavsky
cben@techunix.technion.ac.il
Mon, 16 Dec 2002 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>