[Doc-SIG] going awry

[Ken Manheimer]

On Thu, 29 Mar 2001, Guido van Rossum 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. :-)  It's horrid unless the rules are very clear and simple,
> and there's a really easy way to turn ST's heuristics off -- and not
> just in literal blocks (which are only half the solution).

I think it makes sense to have an easy way (a really easy way:) to turn ST
interpretation off for arbitrary extents - something like shell hereis,
perhaps.  It's also interesting to focus on using STwhatever to describe
STwhatever.  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?  I don't know.  I think with
reasonable escapes it could be easy, though.

(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.  Eg, a hereis
style delimiter that looks like: 

  ...
  [Unformatted passage follows, until "End of unformatted passage"]

 *text fragment* indicates <em>emphasis</em> formatting

  [End of unformatted passage]

For want of any insight on a double-duty formalism for single-character
escapes, i'd be inclined to go with '\' or character doubling...)

> > There are some specific things about ST that *would* be nice to fix, and
> > being free to do that (by dictatorial fiat) is a Good Thing. But I think
> > throwing out the whole thing is not - it's been 5 years, dammit.
> 
> You know, that *could* mean that the problem is simply intractable,
> and that we'd all do better by admitting that the only two real
> options are real plain text or real markup...

Look at the history.  The problems have come up in coming to agreement
about a reasonably scoped effort for a lightweight language - and then in
avoiding the temptation to invent a new markup language from scratch.  
(It's lightweight, it must be easy to formulate, right?-)

Recentaly we *did* seem to actually be making progress!  There was some
kind of agreement about where to start, with a leg-up on a viable though
crufty language, and some genuine progress towards rectifying the
problems!  (Thanks, thanks, thanks, edward and tony!!)  I hope those
efforts keep on track.

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

Ken
klm@digicool.com