[Doc-SIG] Structuring: a summary; and an attempt at EBNF..

[Edward D. Loper]

> [nb: my personal vote is that *obviously* doctest blocks don't need
> a "::" in front of them. Their detection should be *identical* to
> the means used by doctest.py - otherwise people really *will* get
> confused... - hmm, of course, that actually doesn't work already, as
> doctest.py will happily "see" a ">>>" inside a literal block. Ho
> hum.]

I agree that the detection of ">>>" should be identical to doctest's
algorithms.  But I think that if we ever *do* manage to come up with a
standard markup language, and get a PEP accepted, etc, we could
probably get the doctest module changed so it ignores any ">>>" that's
within a literal block (it should be pretty easy to scan for that).
So I wouldn't worry about the "doctest in literal block" problem for
now.

> >  2. Literal blocks start with a paragraph that ends with "::"
> 
> Pedantry - they start with the first non-blank line *after* the "::"

Um, yeah, that's what I meant.  And actually I think we should strip
leading and trailing blank lines (but not internal blank lines) from
literal blocks.

> So::
> 
>    This here::
>
>         Is clearly OK
>

Literal block.

> but what about::
>
>     This here::
> 
>     Is this literal?

Maybe a warning, more likely an error.

> and::
> 
>     Some text.
> 
>         This here::
> 
>     Is this literal?

Maybe a warning, more likely an error.

In my EBNF, the 2nd and 3rd would be errors.

>>     and continue to the next line whose indentation is equal
>>     to or less than that of the paragraph that started them.
> 
> Surely that should (for a start) be "next non-blank line" 

Yes.. let's change it to::

  2. Literal blocks start after a paragraph that ends with "::",
     and end before the next (non-blank) line whose indentation is
     less than or equal to that of the paragraph that introduced them.

or something like that, anyway.. The language could still use some
cleaning-up.  If anyone on the group doesn't understand, say so, and
I'll try to explain it better.

> And terms like "the paragraph that started them" is why I like terms
> like "parent paragraph" - it's a lot easier to work with.

But it's not great for a 1-minute overview that's supposed to be
accessible to anyone. :) (And, actually, I would say that that's the
previous sister paragraph, not the parent, at least in the resultant
DOM tree).

> So that answers the "indentation by 0" question. But they can't be
> separated by blank lines, 'cos those are part of the literal block
> (this is *quite* important - as is preservation of the correct
> *number* of (internal) blank lines).

As I said, I think that leading and trailing blank lines should be
stripped..  (but not any internal blank lines) Do you disagree?  What
do other people think?

> Damn - I was trying not to get involved...

Don't let us drag you into this too much.. Feel free not to respond to
anything I send...  Sanity can be a nice thing.  (I've been close to
going sane, myself, a few times over the last month).

-Edward