[Doc-SIG] formalizing StructuredText

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> So, if I understand correctly, this ST::
>
>     This is a [test]
>     ..[test] of local references
>
> Would be rendered in HTML as::
>
>     <p>
>         This is a <a href="#test">[test]</a>
>     </p>
>     <p>
>         <a name="test">[test]</a> of local references
>     </p>
>
> ?  I'm not sure how you'd render it in LaTeX..

Well, I don't trust all that whitespace after your <p> tags, but apart
from that, yes.

LaTeX has its own way of doing things. The best one could do, I believe,
without some non-negligible effort, would be something like::

	This is a test\xref{test}

	\label{test} test of local references

which would use numbers in place of the '{test}' in the actual document
(and the "label" is invisible). To use the names, one would need to
write more sophisticated code. Which is why it sometimes isn't too
worthwhile worrying about renderers. Avid use of '\setcounter' would
probably allow one to do something, but on the whole I would either (a)
give up and let LaTeX do what it wants, or (b) use TeX and write
something myself.

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

> Do they have to be their own paragraphs?

They have to occur at the start of a paragraph. They are markup, though,
not structure.

> Can anchors be treated as footnotes (e.g., by LaTeX)?

I don't know. Probably a presentation issue.

> What can their contents be?  E.g., can they contain a list item::

Again, I don't know. I wouldn't be *too* upset if we said "just a simple
paragraph".

> Are we expecting people to *want* to link into a document from
> outside?  I can't see ever having any use for that when writing
> API docs...

I don't have a use for it, myself, directly.

> > A tool like TeX would need some untangling of the
> > '#this' to just 'this' for use in its '\xref', but that's hardly
> > difficult.
>
> Hm.. maybe I just don't know enough LaTeX. :)

Well, actually, I think I was misremembering (see above) - it's a while
since I've used LaTeX.

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


> Also, what would your "flattening" do with::
>
>     1. some text
>
>        some more text
>
>            even more indented

It would, erm, flatten the first (list item contains para), and put a
block around the second (para contains para - presumably the user had a
reason). Consistency, hobgoblins, etc.

> Can these nest arbitrarily deeply, if they keep indenting?

As above.

> > STNG has its own REs. They don't make much sense to me (or
> didn't last
> > time I looked at them). In some cases, they just didn't
> work very well.
> > Oh well.
>
> Well, then, we should convince them to change them! :)

I shan't say no...

> > But I don't see why *formalising* it is a problem?
>
> It's just nice to have formalisms that don't contain big
> difficult-to-explain regular expressions.  It makes the
> formalism harder to understand.

Oh, big REs make anything harder to understand!

> Anything whose meaning is not defined by the formalism is invalid.  It
> should be possible for a user to ask a tool to tell them if they use
> any invalid forms -- that way, they are guaranteed that what they
> have written will be interpreted as specified by the *formalism*,
> regardless of which implementation/tool they happen to be
> using (unless
> that tool has a bug).  And given a formalism, it is possible to detect
> invalid forms in a principled way.

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

STminus *will* have a formalism, and it may even be a formalism for
STpy - but both of those are new things.

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)

Anyway, must go

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