We will assume that you have a passing familiarity with Plone's configuration/build system, Buildout  — if not, don't worry, it should be pretty simple to follow along even if you don't. I also assume that you already have Plone and Firefox + Firebug installed.

A note about the setup

Setting up collective.xdv takes some grunt work because it has some slightly unusual dependencies. When this solution ships with Plone itself, this will of course already be handled for you. So bear with us through the install instructions — and rest safe in the knowledge that this will be much easier in the future. It's the price you pay for being on the forefront of technology — but we can promise you that it will be worth it!

The installation process involves the usual steps of

• adding collective.xdv to buildout
• running buildout
• installing collective.xdv in your Plone site

Adding collective.xdv to buildout

As the installation process is not entirely consistent across platforms yet, you'll need to follow the platform specific instructions on the following pages. It is well-worth checking the installation instructions on the collective.xdv page in the Python Package Index for the latest information on recent releases. The following pages go over the same instructions in a little more detail:

• Windows
• Mac OS X
• Linux

Running Buildout

Once you have edited your configuration file according to the platform instructions above, it's time to run Buildout, so the system can add and set up collective.xdv for you. Open a terminal window (or on Windows, start > run > cmd) and on the command line, cd to the the root of your Plone instance (same directory as buildout.cfg is located in) and run Buildout like this:

$ bin/buildout

or, if you're using Windows XP or older:

> bin\buildout

You will see output similar to this:

Getting distribution for 'collective.xdv==1.0'.
Got collective.xdv 1.0.
Getting distribution for 'dv.xdvserver'.
Got dv.xdvserver 1.0b4.
Getting distribution for 'plone.postpublicationhook'.
Got plone.postpublicationhook 1.0rc1.
Getting distribution for 'plone.app.registry'.
Got plone.app.registry 1.0a1.
Getting distribution for 'plone.synchronize'.
Got plone.synchronize 1.0b1.

If everything went according to plan, we now have collective.xdv installed. Time to start Plone and activate it for our site.

Issues and Problems

If you get errors when doing this instead of the above output, please contact the Plone support forums to get more help with your specific setup.

Especially, if you're on Mac OS X, there might be some  issues. We have been working on fixing the Mac situation for a while, and it should be fixed by the time you read this — but if it isn't, let us know!

Installation on Windows is straightforward - the following has been tested with Windows XP (SP3) and Plone 3.3.1, installed using the Windows installer.

Locate the file buildout.cfg in the root of your Plone instance directory on the file system (the default location on Windows is c:\Program Files\Plone), and open it in a text editor. Locate the section that looks like this:

# extends = http://dist.plone.org/release/3.3/versions.cfg
extends = versions.cfg
versions = versions

It may also have a URL in the "extends" section, similar to the commented-out first line, depending on whether you pull the Plone configuration from the network or locally.

To add collective.xdv to our setup, we need some slightly different versions of a couple of the packages, so we extend the base config with a version list from the good-py service, so change this part of the configuration so it looks like this:

extends = versions.cfg
          http://good-py.appspot.com/release/collective.xdv/1.0
versions = versions

What happens here is that the dependency list for collective.xdv specifies some new versions for you via the good-py URL. This way, you don't have to worry about getting the right versions, Buildout will handle it for you.

Next step is to add the actual collective.xdv add-on to the "eggs" section of buildout.cfg. Look for the section that looks like this:

eggs =
    Plone

This section might have additional lines if you have other add-ons already installed. Just add the collective.xdv on a separate line, like this:

eggs =
    Plone
    collective.xdv [Zope2.10]

The [Zope2.10] is an "extra" which, in this case, tells buildout to get some additional functionality to work with Plone 3. If you are using Plone 4 you can omit this.

The additional egg is ZPublisherEventsBackport - if buildout ignores the "extra" command, then simply add this egg to your eggs list.

Now save your buildout.cfg file and go back to the first page of this section to run buildout.

Prerequisites

At the moment, on Mac OS X, you will need to compile lxml and for this you'll need gcc. You'll find this in the XCode tools that come with your Mac CDs (but are not pre-installed). If you have upgraded your OS recently, make sure that you have also upgraded XCode.

Note: For the sake of your sanity, only try this on an up-to-date version of Plone (3.3.*) .

The buildout.cfg

Locate the file buildout.cfg in the root of your Plone instance directory on the file system, and open it in a text editor. 

The Dependencies

Locate the section that looks like this:

# extends = http://dist.plone.org/release/3.3/versions.cfg
extends = versions.cfg
versions = versions

It may also have a URL in the "extends" section, similar to the commented-out first line, depending on whether you pull the Plone configuration from the network or locally.

To add collective.xdv to our setup, we need some slightly different versions of a couple of the packages, so we extend the base config with a version list from the good-py service, so change this part of the configuration so it looks like this:

extends = versions.cfg
          http://good-py.appspot.com/release/collective.xdv/1.0
versions = versions

What happens here is that the dependency list for collective.xdv specifies some new versions for you via the good-py URL. This way, you don't have to worry about getting the right versions, Buildout will handle it for you.

The eggs

Next step is to add the actual collective.xdv add-on to the "eggs" section of buildout.cfg. Look for the section that looks like this:

eggs =
    Plone

This section might have additional lines if you have other add-ons already installed. Just add the collective.xdv on a separate line, like this:

eggs =
    Plone
    collective.xdv [Zope2.10]

The [Zope2.10] is an "extra" which, in this case, tells buildout to get some additional functionality to work with Plone 3. If you are using Plone 4 you can omit this.

The additional egg is ZPublisherEventsBackport - if buildout ignores the "extra" command, then simply add this egg to your eggs list.

lxml

Mac OSX has issues with the lxml binary egg (a requirement of collective.xdv) which can make installation of collective.xdv quite problematic. The recommended approach is to add an additional part to your buildout.cfg to specifically deal with lxml.

First of all you add the name of your new part to the parts section of buildout.cfg (by convention we call it "lxml"). If you're using the buildout.cfg that came with the installer versions of Plone, then scroll down until you find the warning about dragons, and you should find the list of parts fairly soon after that. Insert lxml fairly high up the list.

[buildout]

....

# Beyond here there be dragons!
…	
parts =
    …
    lxml
…    

Then locate a place where you can create your new part (prefaced with its name in square brackets). A good place to put it is just above your zope2 section:

[lxml]
recipe = z3c.recipe.staticlxml
egg = lxml
force = false

# This section installs the components of Zope 2.
....

 Finally you need to tell Buildout which version of lxml to use and also to get the very latest version of zc.buildout to make sure it runs the staticlxml recipe properly. You may already have a [versions] part. If not, add it to your buildout.cfg - just above your [lxml] part would be a good place.

[versions]
lxml = 2.2.2
zc.buildout =
…

 Now save your buildout.cfg and you're ready to run buildout.

Prerequisites

On Linux, you may find that you need to download and install the libxml2-dev and libxslt-dev packages for your operating system. Use your normal package manager to see if you have these and install them if not.

Note for Ubuntu 8.04 you will need libxslt1-dev.

The buildout.cfg edits

Locate the file buildout.cfg in the root of your Plone instance directory on the file system, and open it in a text editor. 

The Dependencies

Locate the section that looks like this:

# extends = http://dist.plone.org/release/3.3/versions.cfg
extends = versions.cfg
versions = versions

It may also have a URL in the "extends" section, similar to the commented-out first line, depending on whether you pull the Plone configuration from the network or locally.

To add collective.xdv to our setup, we need some slightly different versions of a couple of the packages, so we extend the base config with a version list from the good-py service, so change this part of the configuration so it looks like this:

extends = versions.cfg
          http://good-py.appspot.com/release/collective.xdv/1.0
versions = versions

What happens here is that the dependency list for collective.xdv specifies some new versions for you via the good-py URL. This way, you don't have to worry about getting the right versions, Buildout will handle it for you.

The Egg(s)

Next step is to add the actual collective.xdv add-on to the "eggs" section of buildout.cfg. Look for the section that looks like this:

eggs =
    Plone

This section might have additional lines if you have other add-ons already installed. Just add the collective.xdv on a separate line, like this:

eggs =
    Plone
    collective.xdv [Zope2.10]

The [Zope2.10] is an "extra" which, in this case, tells buildout to get some additional functionality to ensure that everything works with Plone 3. If you are using Plone 4 you can omit this.

The additional egg is ZPublisherEventsBackport - if buildout ignores the "extra" command, then simply add this egg to your eggs list.

You should now be ready to run buildout, so hop back to the overview page of this section.