[Doc-SIG] Structuring: a summary; and an attempt at EBNF..
Edward D. Loper
edloper@gradient.cis.upenn.edu
Fri, 20 Apr 2001 00:32:38 EDT
> [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