[Doc-SIG] formalizing StructuredText

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> "paragraph with a blank line before it" is definitely *not*
> what you want, since it leaves out what I would call a paragraph
> at the beginning of a document, and
> it could potentially include any other basic block, if it happens to
> have a blank line before it (which is required for headings, etc.)).

Actually, I agree with you - it's a messy term, anyway.

> > >     * basic block = paragraph or list item or heading or label (or
> > >       table?)
> >
> > Paragraph (see above)
>
> I think this is somewhat misleading/confusing..  But I guess that's
> up to you to decide..

Again, I agree - it's an artefact of the internals. What about "text
block"?

> I guess that seems reasonable.  Within paragraphs, do you collapse
> multiple spaces into one space?

No, within lines spaces are (very carefully) left untouched, just in
case.

> > > Agreed.  Although how do you put something at zero indentation?
> > > Maybe indent from 1 space over from the preceeding paragraph?
> >
> > You don't. I've never wanted to (my problems with HTML normally come
> > from trying to do the opposite).
>
> Hm.. I'm not sure I agree with this, but I don't think it's important
> enough to get hung up on.  (I would argue that you should be able
> to put things in column 0, but that the HTML renderer should probably
> indent preformatted regions relative to everything else).

I couldn't see an easy and natural way around it, and I find it hard to
conceive of places where *I* would not want to indent, so I gave up (the
problem was actually thinking how to decide on an indentation at all,
and I was quite pleased with how predictable and useful using the
indentation relative to the "parent" or preceding paragraph was).

> > > > >     "the following is not a url":<hi>
> >
> > That's right. In this instance.
>
> So does it get rendered as is (i.e., with two quote signs, one colon
> sign, a less than sign, and a greater than sign)?

That's up to the renderer. But seriously, it gets *stored* as a node of
the DOM tree which has the text within quotes (i.e., the quotes are not
preserved) as its text, and the URL as its 'url' attribute. Thus the ST
markup (the double quotes and the colon) are not remembered.

> We should be able to print out *all* problems, not just *possible*
> problems, if the user really wants us to.  This seems very important
> to me if we want to allow for the possibility of competing
>implementations of ST.

I don't have a problem with telling the user what is wrong with a text,
I just don't understand how to quantify that. Of course, in STminus, you
have a different handle on things, but that's because you're deciding up
front what is allowable and what is not. A "more traditional" ST
approach doesn't know that.

But being able to give the user as many warnings of problems as possible
has got to be a good thing...

> The markup-nesting problem doesn't actually seem that difficult to me,
> in principle.  I propose that we allow anything to nest
> within anything,
> with the restrictions:
>   1. nothing can nest inside a literal, inline, or href url

Agreed. But please don't call it an 'href url' - that's an HTML term!

>   2. nothing can nest within itself (even with intervening levels)

Pragmatically has to be true, with non-differentiated start and end
quotes.

These two seem to me to be the sane minimum, and thus sensible.

> So the legal nestings are shown in this tree:
>
>   * literal
>   * inline
>   * emph
>      * literal

OK, OK, I believe you!

> Also, spaces must come between * and ** delimiters, so you
> can't say ***this***.

Ah, but there's no reason you shouldn't be able to *say **this***, for
instance (it's quite unambiguous).


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