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

[Tony J Ibbs (Tibs)]

Goodger, David wrote:
> (As an aside: where does this term "colourizing" come from?

I think it may have been mind-pollution from my initial looking at STNG
code (it's probably the only thing that remained! - certainly none of
the algorithms).

If it *does* come from ST, it *may* have been around in the Doc-SIG for
a while (I think the initial few messages of Doc-SIG went something
like:

1. I'm here - who else is?
2. What are we doing?
3. Here's setext
4. Here's StructuredText (that was Jim Fulton)
5. Yuck - why not use (I think it was TeX) - that one was me...

There were doubtless a few other messages mixed in there, too...)

I use the term interchangably with "markup", and although the latter is
probably more standard a term, I quite like it (as to whether one is
"colourising" in the IDE sense, well, that would be one use of the
resultant information). I'm sure there's probably some half-assed pun in
the back of things, but I can't see it for the nonce.

I probably hadn't come across its use in that manner before, either
(although colour analogies in data structures are not new things).

Edward has certainly tended to use "inline markup" when he's being
formal, I believe.

(of course, it's also nice to use a word whose spelling is unlikely to
be agreed on - but that's an incidental benefit...)

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

Whilst I'm here...
>  2. Literal blocks start with a paragraph that ends with "::"

Pedantry - they start with the first non-blank line *after* the "::"
paragraph, *if* it is indented more than that paragraph (and presumably
in Edward's terms, a relatively unindented paragraph after a "::"
paragraph would be an error - unless he wants to allow indentation 0).

So::

    This here::

        Is clearly OK

but what about::

    This here::

    Is this literal?

and::

    Some text.

        This here::

    Is this literal?

In the first case, we're OK. In the second, it's either non-literal (and
for Edward an error?), or literal with indentation 0. In the third, it's
clearly non-literal - but does Edward want an error or not?

>     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" (and possibly
even "next non-blank line following a blank line", for pedantry).

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

>  Literal blocks should be indented and separated by blank lines.

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

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

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)