[Docutils-develop] Re: ETA for an API frozen release?

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

On Wed, 30 Oct 2002 1:57 pm, David Goodger wrote:
> Richard Jones wrote:
> > I realise the API won't be frozen for eternity, but it'll make early
> > adoption much easier.
>
> ...
>
> > Being able to recommend to users that they use version 0.3.x, which has a
> > frozen API and possibly even a maintenance cycle, would make life a lot
> > easier.
> >
> > As far as I'm concerned, the API freeze could happen _today_.
>
> Although I sympathize and appreciate your predicament, I don't want to
> freeze the API because there's so much yet to be done.  I still consider
> this to be an experimental work in progress, and a learning experience. 
> I'm always learning more about the problem domain.
>
> Maybe there's a middle ground.  I've committed to getting a working
> PySource Reader for the 0.3 release, but there hasn't been much progress
> there yet. Perhaps an interim 0.2.x release that we can base tools on?

Actually, that's pretty much what I was thinking about. I didn't necessarily 
mean to freeze the API for ever, just for one release that can be labelled 
"0.2.x" or "0.3.x".

> I think the project is too young to pursue parallel stable/maintenance and
> development/experimental branches.  I wouldn't want to take on that kind of
> chore.

That's a fair call, really.

>  How do you handle this type of situation with RoundUp or other
> projects?

I've made a lot more releases with Roundup, and as a consequence I have to 
produce upgrading information for people who actually follow through the 
changing API etc.

> Why don't you bring this up on docutils-develop?  Maybe some of the other
> developers/consultants will have some ideas.  Feel free to quote anything
> here.

Actually, I misfired with the original email - it was _supposed_ to go to 
docutils-develop ;)

> > The ZReST product is broken at the moment, and I've received two
> > emails about it.
>
> I'll take a look and see if I can fix it.  Can you forward the reports
> you've received?  Any details you can add would help.

AFAICT it's an options thing. The errors are things like:

  Publisher instance has no attribute 'set_options'
  Publisher instance has no attribute 'options'

... that sort of thing :)

>  I may even use it as
> an excuse to learn a bit about Zope.  Like how to install it. ;-)

In short:

1. download the 2.5.1 source from zope.org
2. make a directory like /usr/local/zope
3. unpack the source in that directory
4. make a directory /usr/local/zope/instance
5. ... and another couple: instance/var and instance/Products
6. symlink the ZReST directory from the docutils source to instance/Products
7. make a script called "start" in /usr/local/zope/instance containing::

    #! /bin/sh
    reldir=`dirname $0`
    export INSTANCE_HOME=`cd $reldir; pwd`
    exec /usr/bin/python2 \
         /export/zope/Zope-2.5.1-src/z2.py \
         -D "$@"

8. ./start

That'll start the server on port 8080, attached to the current terminal, with 
some logging going to the terminal and some additional debug output when 
errors occur. Remove the "-D" (debug) in the start script to have it detach 
and lose that other stuff.

The full range of options that the start script will accept are given in the 
Zope source "z2.py" script, at the top.

> > Though it'd be nice to get HTML production sans <html>/<head>/<body>
> > wrapper tags so the ZReST product could produce fragments.
>
> You can get that now.  Use the NullOutput class for destination, or throw
> away the string returned from StringOutput (copy & modify the
> publish_string function), and access the html4css1 Writer's
> "body_pre_docinfo", "docinfo", and "body" attributes (all lists of
> strings).  Just add them together and ''.join() them.

Yeah, that makes sense. Sorry, it's been several projects since I last looked 
at that stuff :(

> > Don't ask much, do I? :)
>
> Find me a good sponsor and I'd be able to *give* much more. :)

That one's outta my hands, I'm afraid :)

     Richard