[Doc-SIG] reST block quotes

[Beni Cherniavsky]

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>