[Doc-SIG] formalizing StructuredText

[Edward D. Loper]

Tibs said:
> > Can anchors appear anywhere in the document?
> 
> The original intention was for their use *as* footnotey, reference
> things at the end. Possibly in a "Reference:" clause. But on the other
> hand, I don't see why they should actually be so restricted.

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

> > 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"?  If so, I disagree.  I think they
should be a special type of heading, very similar syntactically to
labels.  So you can say::

    ..[foo] bar

or::

    ..[foo]

        para 1

        para 2

> > I would argue that it would be more appropriate to use::
> >     <oitem>
> >         <bullet>1.</bullet>
> >         <para>some text</para>
> >         <para>some more text</para>
> >     </oitem>
> 
> 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..

> Oh, big REs make anything harder to understand!

Yes, but I think that more work needs to go into making formalisms
easy to understand than implementations..

> Which again comes round to our difference in viewpoint or something -
> you want to formalise first, and that leads to knowing which documents
> are invalid. My approach (in this instance, I hasten to add - not in the
> general, nonST case) is that the user throws their text at STpy (which
> in practice means an implementation thereof) and sees if it comes out as
> they expect, with as many warnings to be given as can be if they wish
> them.

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

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

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

> Of course, I'm also biassed 'cos the Doc-SIG loop tended to fall over at
> the "formalising the spec" stage, and STpy/docutils was my attempt to
> short-circuit that - it doesn't look like it'll happen this time (what
> is it about 2001? - the types sig is active, catalogs are coming, we've
> got pydoc and soon an ST of our own)

Well, hopefully this time we'll manage to stay standing. :)

-Edward