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

[Edward D. Loper]

> Do Doctest blocks have to be preceeded by "::"? I.E, are Doctest
> blocks simply a special case of literal blocks, or are they detected
> by indentation & ">>> " alone?

I would say that they're detected by indentation and ">>>" alone (and
should be separated by leading and trailing blank lines).  That's to
be consistant with the doctest module.  We could also say that they
have to appear in literal blocks, but then I'd want the parser to
generate a warning whenever it sees a paragraph that starts with
">>>".

> Why should lists be indented? What's wrong with
> 
> - a list
> - like this?

In theory, *either* indentation *or* separation by a blank line would
suffice.  In fact, right now my parser would accept your example with
a warning.  I think that we should enforce both because it makes the
docstrings easier to read, and is more consistant.  The one problem
with this is if you want to include a list directly after a literal
block.  There's no way to do it if lists are required to be indented.
Maybe we could allow it in that case. :)

> No indentation is necessary. I suggest that if there *is*
> indentation, an alternate interpretation is possible.

When I read them, *I* don't interpret them differently (as an
uninitiated reader).  So I don't think we should be encoding any
semantic content in the difference, if we *do* allow unindented lists.
Doing so seems to me to go against the principle of making sure that
the uninitiated can understand the docstring..

Well, actually, there is one obvious interpretation: actually indent
the list in the output.  But I don't think that we should be giving
people that much control over the output.  If they *need* that much
control, they should be using LaTeX or something like it..  I like to
*think* that the markup language we're talking about is mainly a
semantic one..

> As an aside: where does this term "colourizing" come from? 

I picked it up here on doc-sig (or maybe on some page that I was
pointed to from here).  I'll try to remember to talk about "inline
markup" or "local markup" or "intraparagraph markup" or some such when
writing up a PEP (if we ever get there...).