[Doc-SIG] Structured Text

[Goodger, David]

> here's an awkward case::
> 
> 	1. This is a list item::
> 
> 	    This is some literal text (see the '::' above)
> 
>       I can't make this paragraph a "child" of the list item.
> 
> My intent is to make the third para a child of the first (so it won't
> terminate the list). But I can't do that

My approach is to think about it two-dimensionally, in X-Y space:

    1. This is a list item::

           This is some literal text (see the '::' above)

       I can't make this paragraph a "child" of the list item.

The "I" lines up with the "T" in the first line. A block diagram helps:

    +----+------------------------------------+
    | 1. | (list item)                        |
    +----| +----------------------+           |
         | | (paragraph)          |           |
         | | This is a list item: |           |
         | +----------------------+           |
         |   +------------------------------+ |
         |   | (code block)                 | |
         |   | This is some literal text... | |
         |   +------------------------------+ |
         | +----------------------+           |
         | | (paragraph)          |           |
         | | I can't make this... |           |
         | +----------------------+           |
         +------------------------------------+

The indentation of the code block is just for emphasis (unless you want
paragraphs to contain body elements, a subject for intense debate ;-).

I once wrote a (huge, ugly, Perl) program which parsed syntax diagrams drawn
using ASCII with line-drawing extensions (similar to the diagram above), and
translated them into valid SGML. StructuredText is similar: it's ordinary
text with a horizontal dimension. Basically, it's graphical text. Like a
bitmap, but characters instead of pixels. Thinking in terms of dissection
into blocks is very useful.

HTH,

/DG

P.S. I haven't disappeared; just incredibly busy. I'm still lurking on the
list.