[Zope3-dev] Status of reST

[Stephan Richter]

On Friday 11 April 2003 19:44, Jeffrey P Shell wrote:
> I don't think it's over-engineered.  It's still a work in progress,
> much like Zope 3 is - with more obvious rules (I'm still spinning over
> the differences between @@foo and @@/foo.  How long until $_?).
>
> But it is very flexible, powerful, and adaptable.  And, given its
> internal complexity, it's a LOT easier to follow than Zope 3 currently
> is.  :\.

Well, I would hope so, since it id "just" a documentation tool.

> I did that trick in my initial reST work too, but it never sat
> comfortably with me.  There is this expressive framework available, and
> sidestepping it just feels wrong.  To me it always felt like "if I'm
> not using it properly, then why am I using it?"

I do not want to use it; I am forced to use it. I would prefer to just say 
HTML.format(rest, full_page=0). All the rest is boilerplate to me right now. 
I really like how simple it was to get Structured Text working.

> It turns out that Andreas Jung's code in Zope 2.7, particularly the
> 'html4zope' writer object, may return that body part anyways as the
> core return document, without the general pre/post body items even (the
> "generated by docutils" footer, etc).  That could probably be reused.

Actually, Zope 2 is where I got the current minimal code working. I will look 
into that further...

> However, there have been some significant improvements to docutils in
> recent months that are probably not incorporated into the code in the
> Zope branch, particularly in the "interpreted text roles" department.
> Some of these improvements could be very advantageous to pick back up.

What are "interpreted text roles"?

> >>    - Maintaining our own copies could be time consuming, but
> >>      too many dependencies are annoying for end users.
> >
> > We do not need to "maintain" a copy, just provide one; in fact, I
> > would not
> > change anything in our copy of docutils ever.
>
> By 'not change anything in our copy', do you mean never upgrading it
> once we start using it? 

No, just never make a change in it that is not made is the main docutils CVS; 
basically make no patches. Of course, careful upgrades should be done 
regularly.

> Or do you mean not changing any of its code,
> so that it can be upgraded with no maintenance?

Right.

> Docutils is flexible
> enough to allow custom components (readers, writers, whatever) outside
> of the docutils tree (I don't know why Andreas put 'html4zope' in the
> Zope 2.7 'lib/python/docutils/writers' directory - that does make
> updates hard).

Right, I would move it out.

> By 'maintaining our own copy', I did not mean that we make any
> modifications inside the docutils/ tree and then maintain them.  My
> concern was just updating it in timely fashion from the primary source,
> at least until the docutils release management system changes and there
> are solid release points to run on.

Right.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training