[Doc-SIG] reST block quotes

[David Goodger]

[Beni Cherniavsky]
> 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.

It's the parts of email messages not part of reStructuredText that
are interesting.

[Beni Cherniavsky]
>>> 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).

[David Goodger]
>> Not following you.  Can you elaborate please?

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

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

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

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

>    Seems rare but consider a text where each quote is followed by some
>    comments (as in emails).

Not following you.

>    So I want a way to represent the disctinctions.

Not worth the trouble IMHO.

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

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

> .. [2] Unrelated question: when should I use literal text (``),
>    interpreted text (`) and no quoting?

Interpreted text hasn't really been implemented yet.  Its main client
will be the Python Source Reader, which is a work in progress.

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

`m.bar` would generate a warning or error.  The identifier must be in
the current namespace, with possible exceptions for stdlib modules.
In the case you're describing, I'd use inline literals ``m.bar``.

>     - Should I put all filenames in literal quotes?

Up to you and your document's context.

>     - Generally the docs (including the PEPs) need some more
>       discussion on where actually to use interpreted text...

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.

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/