[Doc-SIG] PEP-0216

[Tony J Ibbs (Tibs)]

I wrote:
> > Meanwhile, if people can be a *little* patient, I'm writing
> > up a summary of what the (in general, pedantic) worries about
> > StructuredText were (NG addresses some of them already),

Moshe Zadka wrote:
> So please leave those worries out! We're going with ST-NG unless
>
> 1) Someone finds a *big* problem with it.
> 2) Guido dislikes it, and his coworkers don't physically beat him into
>    silence

I still want a summary of what the perceived problems have been, since I see
this as useful for the following reasons:

a. It is history. History is a Good Thing, since we can say "been there,
done that, already decided to ignore it." (and, btw, here is *why*).
b. It is useful as a potential basis for future developments - if we embrace
StructuredTextNG, I assume that we are going to want to join the
development/maintainence effort, and it would be useful to have a "group
consensus" to start that off from.

BUT it is an aside, and it is not as important as the "definition" of
current NG:

> > and also trying to firm up the *definition*
> > of StructuredText
>
> That would help a lot! I would like to include a definitive reference
> inside the PEP itself, so it could be integrated into Fred's "Documenting
> Python".

By the way, it would help me a lot if someone with CVS could extract the
current state of StructuredTextNG from the Zope2 archive for me (see

	http://www.zope.org//Members/jim/StructuredTextWiki/NGReleases

for details) so that I could look at what it currently does.

> BTW, the current output format should be th Pythonish LaTeX which is
> already used. A future additional output format is whetever is used for
> external documentation (probably XML/SGML application).

This is the sort of thing we should worry about *after* adopting a mechanism
(i.e., we take what it gives us, and if that ain't enough, *then* we add
more functionality).

> > BTW, it's not as if we're short of tools:
> >
> > 	StructuredText itself
> > 	pythondoc (when Starship is up)
> > 	Crystal
> > 	Happy-Doc
>
> We're short on *one* tool, which is strong enough to be "the" answer.

But precious close...

> In short, I'd love to see some definitive Python-extension of ST-NG,
> which would let us write documentation! If you can do a specification,
> that would be great!

Heh, pedantry-are-us (it's *loads* more fun than standards work, except when
there's only two of you doing the standard!).

> patient-is-no-different-then-lazy-here-ly y'rs, Z.

I like that...

Tibs (whose sanity can be judged by the following signature)

--
BikeCode0.2	http://www.tibsnjoan.co.uk/bikecode.html
  P: [Tibs] Tc B10 K:++ i29:30" h1.65m n1960 H+:~ v~ A+ M+ Rg-
  B: [AnthroTech]   3tRu U1c w37" Wr19:406 Mfr SAf bDh[Sachs]:C
                    G3x7 8s Lrr1B Cb[Michael] VjsX col[MidnightBlue]
  T: [BurleyD'Lite] 2c2[Thomas] f++ VsX
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)