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

Goodger, David dgoodger@atsautomation.com
Thu, 19 Apr 2001 09:41:38 -0400

[Edward D. Loper]
> I figured I'd give a summary of all the structuring features that
> I think we've agreed on, so we can tentatively take those as
> a given.  If anyone objects, please say so..

OK, I'll bite!

>   3. Doctest blocks start with ">>> " and continue to the next blank
>      line.  Doctest blocks should be indented and separated by blank
>      lines. 

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?

>   4. Lists should be indented and separated by blank lines.

Why should lists be indented? What's wrong with

- a list
- like this?

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

>   7. Colorizing takes place entirely within paragraphs, and does not
>      interact with structuring.

(As an aside: where does this term "colourizing" come from? It was first
used on Doc-SIG by Tibs last November. I've otherwise never seen it used in
this sense wrt markup. I have seen it used in the sense of syntax colouring
(i.e. IDEs changing the colour of text in code). I believe the correct term
here would be something like "inline markup" or "mixed markup".)