[Doc-SIG] formalizing StructuredText

[Tony J Ibbs (Tibs)]

> Tibs said:
> > > Can anchors appear anywhere in the document?

Edward Loper wrote:
> I vote for only allowing them at the end, because they confuse
> me otherwise. :)  What do other people think?

Well, I know David Goodger was trying to invent something *like* these
anchors to allow him to navigate round a document. I suspect it's
something I'm agnostic on, and would thus not choose to pronounce on...

> > > Do they have to be their own paragraphs?
> >
> > They have to occur at the start of a paragraph. They are
> markup, though, not structure.
>
> Um.  I'm not sure exactly how you're using those two terms.  You mean
> they're what I would call "local formatting" or "coloring" and not
> "global formatting" or "structring"?

Yes. But I agree it's a dodgy issue distinguishing a paragraph that has
an item that can only occur at the start from an element that is "named"
by that occurrence. It may well be they *should* be more structurey, if
they are required so to act (and that would also make it easier to allow
them to start a new paragraph, which we *might* want to do).

> > Hmm. My original model for the DOM tree was XHTML, and that
> > is not how that works. Doesn't mean my model is a GOOD one, mind
you...
>
> Hm.  I'd rather use a good model. :)  But how we convert it to an
> XML document isn't really a fundamental issue, so I'll just leave
> it be for now..

XML isn't, but the choice of DOM is - the reason for choosing DOM was so
that an interface between parser and user could be established that was
well understood, and could be maniplulated easily with Python available
tools. The "magic" behind the DOM creation could then be done by any of
a series of tools, provided they all produced the same sort of DOM tree
(i.e., use the same or similar DTD). I thus see STpy as mapping directly
to a DTD (or XML-Schema, or name your poison).

Given DOM, XHTML seems a natural example to choose (although I do find
it a bit odd in places).

The DOM thing is an important point...

(I'll have to make sure the PEP stresses that).

> The problem I have with your approach is that it assumes:
>    1. There is one cannonical tool, or all tools work exactly
> the same.
>    2. The tools won't change over time

Which is what the DOM thing is partly meant to address - but I see you
are talking about a different bit of the "approach".

> I think that we may be setting ourselves up for annoying problems
> down the road, in terms of people wanting backwards compatibility
> so they won't have to rewrite doc strings.  Witness how much of a
> problem backwards compatibility can be for Python in introducing
> things like nested scopes..
>
> Other people *have* successfully defined (formalized) documentation
> languages (javadoc, pod), so I don't see why we can't do the same,
> in principle..

No, our problem is that ST *is* defined, but informally. Retrofitting a
formalism onto an informal standard *is* a problem, 'cos people have
different understandings of how that informal standard will work. As
such, docutils takes the "code it and see how it works" approach (Python
as formalism), whilst you're taking the "think about it hard and see
what it should do" approach (more traditional formalism).

But we're both stuck with the format *essentially* already being defined
for us.

> > The reason for this approach with docutils is mainly that ST doesn't
> > *have* a formalism, and for me the best way of working out what it's
> > meant to be doing has been to work with an implementation.
>
> Which is reasonable.  But I think that you should be at least working
> *towards* a formalism..

Well, give me a chance to finish writing the documentation!

Seriously, STpy *is* defined, but it is done in less formal language
than EBNF. docutils has been used to inform me as to what sensible
decisions and behaviour might be, but it is not the definition. I assume
that someone could take STpy and produce EBNF from it. I hope.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)