[Zope3-dev] Status of reST

[Jeffrey P Shell]

On Friday, April 11, 2003, at 08:34  AM, Stephan Richter wrote:

> On Wednesday 09 April 2003 13:11, Jeffrey P Shell wrote:
>> I would like to, but time is the bastard.  There are some important
>> issues that need clearing first anyways:
>>
>> Docutils Dependency: do we keep a copy of docutils in our repository
>> and update as needed?  There's still no real release process beyond
>> nightly 'builds' for docutils (I think the last release is the very
>> antiquated 0.2).  It's probably better *not* to put docutils in the
>> source tree, but there are still some API change possibilities.  I
>> doubt we'll do any *heavily* customized parsers or writers, so this
>> isn't a huge issue.
>
> Zope 2 contains a docutils copy. We could do the same or require an 
> additional
> installation step, which would not be that great. I have implemented 
> ReST in
> for the zwiki for Z3 product and require the user to install docutils
> thenselves.
>
> The problem is that docutils is just over-engineered...as Jim always 
> says,
> premature generalization is bad. We only need a really small subset of 
> all
> this framework.

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.  :\.

>> reST sandbox works: There are a couple of useful tools in the reST
>> "sandbox" contributed by various people using docutils.  There are a
>> couple that may be of interest to us, particularly Bill Bumgarner's
>> 'DocArticle' writer, which generates HTML that doesn't depend on the
>> docutils stylesheet.
>
> I use the sandbox as is. I have not written a special formatter object 
> for
> ZWiki. I used in fact Simon's trick to strip of everything outside the 
> body
> tag.

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?"

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

>> The docutils stylesheet is great and yields
>> beautiful standalone documents, but it can create problems when being
>> used to generate HTML that needs to integrate with other HTML.  There
>> is also a clever Wiki parser that finds potential wiki names during
>> reST's processing/parsing time, which can sidestep potential
>> double-processing (a situation that can occur in regular ZWiki).  
>> There
>> are some other useful works in the sandbox as well, along with some
>> stuff I've already written to return the body of a document using
>> reST's DOM-ish API's, allowing the content to be used in any content
>> system.
>
> Cool.
>
>> My concerns here are:
>>
>>    - A lot of useful work has already been done by other people
>>      that we could use.
>
> Could you give a list of useful tools and modules? I really think we 
> do not
> that much. We should not make the integration of reST a major project 
> in
> itself. It should be dead-simple to use, just like ZPT and DTML.

Bill Bumgarner's DocArticle module is of some interest.  It's written 
to generate HTML that conforms to O'Reilly's article submission 
guidelines, which means that it doesn't use the Docutils stylesheet (in 
fact, it uses no stylesheet).

We could use the regular reST html4css1 output and use the stylesheet 
definitions it expects, but this does take some careful work.  reST 
still wants to be a single document and not necessarily integrated with 
a surrounding web site framework.  I've done a couple of hacky 
integration works in the past (once for Plone, which I never did get 
looking right - the fonts were always bigger than other Plone content; 
once for Roundup, in which I had a bit more success).

>>    - It's all published under different open source licenses.
>
> That is a major issue for us! I would prefer to use tools only under 
> one
> additional license. What are the various license schemes?

The only one of real issue is Bill Bumgarner's DocArticle code, which 
is under the MIT license, I think.

>>    - 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?  Or do you mean not changing any of its code, 
so that it can be upgraded with no maintenance?  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).

If you're saying "never ever upgrade," I think that's a little extreme. 
  Would you recommend anybody building a Zope 3 app off of today's code 
to never ever ever upgrade?  Docutils has plenty of tests.  Combining 
its tests and adding tests to cover our usage of it, I imagine that it 
could be updated about as well as anything else.

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.

>> I'm not sure what to do about these two issues (which is all basically
>> one big dependency issue).  I think reST has more than enough benefits
>> to offer us, but there are still a couple of hurdles to deal with
>> first. :\
>
> Let's figure out the licenses; once we agree on something, I think we 
> should
> just add reST to the repository. We really need it at a lot of places.
>


Jeffrey P Shell, jeffrey@cuemedia.com