[Doc-SIG] going awry

[Tony J Ibbs (Tibs)]

Guido wrote:
> > Have you tried to use ST to document a language that
> > happens to place a special meaning on most of the ST
> > special characters?  (Like ST itself. :-)

Erm - yes...

I'm sorry, I'm *not* engaged in a *piss Guido off for the sake of it*
contest, but seriously you (Guido) have come in in the middle of a
debate (yes, because we asked you nicely, and the *fact* you've come in
is bearing interesting fruit), and that inevitably means that you've
missed a lot of discussions which have already happened.

(by the way, my (mild) complaint about Python meetings *wasn't* that
they kick-start things - it was the opposite. If a group is working (at
large) on a problem and a smaller disjoint group meet together at the
con, then that smaller group can have a *very* intense discussion and
may divert the efforts. But they weren't necessarily the people who were
involved in the first place, who now have no idea what has happened
because they couldn't make the con. Do you see what I'm saying (and yes,
it is a whine!))

One of my prime (in the back of my mind) considerations is that I should
be able to write the docs for <whatever this is> in itself. Believe it
or not, the main reason I don't *do* that (after all, I already *have* a
tool to turn it into HTML) is that it doesn't yet support tables, and I
have no *intention* of trying to sort out tables in this round of work -
they're just too fiddly to implement (cf embedded markup, which is easy
to do, but too fiddly to bother with in the near future)).

Ken Manheimer wrote:
> I think it makes sense to have an easy way (a really easy
> way:) to turn ST interpretation off for arbitrary extents

That sounds like it might be a different idea than what was being
discussed the other week. Edward Loper proposed being able to escape the
quote character(s), but after a quick discussion between he, me and
Edward Welbourne, we realised that it needed more leisurely thought than
we had mindspace for. It's a difficult problem, *especially* in the
context of docstrings, where use of backslash (the "obvious in the
Python world" character) to escape things can get really rather messy.

> There's a bit of a scope question in the latter, though -
> would such a document be larger/more comprehensive than the kinds of
> things we're concerned with in docstrings?

Yes - look at the size of fat.html! However, it's still worth bearing in
mind, if only as a stress test. I don't think, however, that it's
something to worry about at this stage.

I'll say again what I always say - in the ST world (yes, I know) it's
not been enough of a problem to force a solution yet, and (as Edward
pointed out) in "real life" in docstrings one can work around it without
doing *too* much damage to the text one is writing.

Personally, I'm not after perfection, just something that does what I
want almost all of the time (which I thought was sort-of Pythonic).

> (Re escapes - i'd like to see such things done keeping jim's original
> intent that the motivations for structured text gestures make
> sense in the context of the raw text as well as for their
interpretation.

That is *very* important to me, too. It's another stopper on sorting
this out now, though...

> Recentaly we *did* seem to actually be making progress!

Erm - well, I thought so, and so did Edward Loper.

> (I'm not sure what documentation you have and haven't had
> identified - i don't have the URL for edward's STminus EBNF
> specification, or tibs' stpy site - i'm hoping someone will
> chime in with them, in case those are what you need...)

It's now of historical interest, but the stpy spec (which I didn't point
out to Guido 'cos I was about to produce a new release - I'm still
wanting to get the alpha of the software out the door, if I ever get
time - and anyway, it's been announced regularly enough on Doc-SIG over
the last while) is at

	http://www.tibsnjoan.co.uk/docutils/status.html

(actually, that's the status for the *previous*, out of date even before
all this stuff, version of the tool, but it has pointers to other
things).

STminus is/was at

	http://www.cis.upenn.edu/~edloper/pydoc/stminus.html

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