PEP 287: reStructuredText Standard Docstring Format

[Peter Hansen]

Richard Jones wrote:
> 
> On Wed, 3 Apr 2002 11:09, Peter Hansen wrote:
> > By the time we'd
> > scrolled through the ReStructured Text documentation I had to say
> > to him, "Hmm... that's so bloody complicated it might be easier
> > writing XML tags directly.  Sort of defeats the purpose of structured
> > text, doesn't it?"
> >
> > When structured text becomes so complicated to type that one has to
> > actually work at it, and it needs a large manual to use, it has
> > become too unwieldy to be useful.
> 
> Are you sure you aren't confusing comprehensive (and, unlike most STX-alike
> documentation formats out there, well-designed) with complicated?

Yes, you're right, I was.  My apologies.  On rereading with a more
thoughtful eye, and ignoring the bulk of the links on the site and
focusing on the quickref only, I conclude after brief practice 
that I would have little trouble using it effectively.  

I would suggest an even shorter version of the quickref, focused on 
only those items needed in 80% of embedded documentation.  It does
_look_ complicated at first.

> > My suggestion would be go with a simpler Structured Text for the 80%
> > of documentation needs it, and allow an escape to DocBook or
> > something for more complicated docs...
> 
> So we'd have to learn DocBook, or some other [SG|X|HT]ML layout? I'd
> guarantee that the STX version is going to be much easier to edit and
> maintain (without purchasing Frame, that is ;)

Actually, that would be entirely unnecessary.  You would only 
need to do that if you wanted complex documentation.  Since
we don't want Structured Text to be so complex that it 
could really handle that kind of documentation, an escape 
mechanism would still be needed for something that ugly.
But why would anyone want to embed such complex documentation?
(Yes, I know all about Web and Weave.)

-Peter