PEP 287: reStructuredText Standard Docstring Format

[Richard Jones]

On Wed, 3 Apr 2002 11:09, Peter Hansen wrote:
> Paul Rubin wrote:
> > David Goodger <goodger at users.sourceforge.net> writes:
> > > Here's a serious proposal, safe to post now that April Fool's is over.
> > > Please read & comment.
> >
> > Man, I thought it was an April fools joke when I saw it last night.
> > All those `different` :kinds: 'of' "quoting" are much more confusing
> > than explicit markup.  So I think it's better to use explicit markup.
>
> I had the same impression.  I was reading it for the first time,
> as I showed it to a coworker who was interested.  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?

For most people, the first quarter or third of the quick reference (inline 
markup, sections, lists, literals) is plenty enough documentation.

   http://structuredtext.sf.net/docs/quickref.html

The rest of the spec is for advanced use only.


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


    Richard