src/site/apt/index.apt

 -----
 Doxia Eclipse IDE plugins
 -----
 Benson Margulies
 -----
 25 August 2011
 -----

Overview

  A collection of Eclipse Editors for the common file formats of
  Doxia:

  * APT

  * Confluence

  * DocBook (simple)

  * FML

  * TWiki

  * XDOC

  * XHTML

  These are made up of an OSGi bundle containing Doxia itself, plus a
  series of Eclipse plugins that provide the editors.

Tree Structure

  [doxia-osgi] builds an OSGi bundle with all of the dependencies
  that are not OSGi in their native form. Due to a Tycho limitation, you have to run mvn install
  on this before building the <<<eclipse-plugins>>> subdirectory.

  [eclipse-plugins] contains all of the other material, using Tycho to make eclipse plugins.

Build Process

  The goal here is to permit both a relatively normal Maven build
  process and active development inside Eclipse. Due to the unsettled
  state of the technologies that can connect Maven and Eclipse, what
  we have is something of a camel.

  The first task is to package Doxia in OSGi. In, perhaps, a perfect
  world, all the relevant Doxia bits-and-pieces would have independent
  OSGi metadata, and be deployed in a public P2 repository (e.g. the
  Nexus Pro at repository.apache.org). However, this would be
  considerable effort for dubious value, and further the Doxia
  components have the same package in multiple components, which
  causes 'split package' syndrome in OSGi.

  Rather than add OSGi metadata to all of the individual pieces, this
  project builds a single bundle that incorporates all of them, and
  then exports their APIs. The work is done by the
  <<<maven-bundle-plugin>>> in
  <<<doxia-osgi/org.apache.maven.doxia.eclipse.dependencies>>>.
  The POM includes all the configuration for the bundle.

  The present author does not know how all of this gets along with the 
  <<<maven-release-plugin>>>. OSGi versioning works differently from
  the usual Maven convention. Since we're not publishing via the
  deploy plugin, it's probably safest to tag, update versions, and
  release by hand. It only has to happen once per Doxia release.

  See Peter Kriens'
  explanation of the muddle with OSGi version numbers
  {{{http://www.osgi.org/blog/2011/06/negative-qualifiers.html}here}}.

  One solution goes like this: you release (e.g.) 1.0.0. Then
  set the version number to 1.0.100.qualifier, and use the
  auto-generated qualifiers. Then, to make a release, you set the
  version to (e.g.) 1.1.0. This means giving up on the third digit,
  but we don't generally use three numbers around Maven anyhow.

  The <<<p2-repository>>> directory takes the plugin and packages it
  up as a feature in a P2 repository. This is just for convenience;
  I've found that Eclipse more reliably imports projects from here
  than from the target directory where the bundle plugin operates.

  Once Doxia is 'bundled', the next problem is the Eclipse plugins
  themselves. Here, in the <<<eclipse-plugins>>> directory, the build
  uses the Tycho plugins. The Tycho plugins produce Eclipse-compatible
  OSGi bundles with a minimum of configuration. They also have a
  minimum of documentation and useful logging messages. So when things
  go wrong, it can get confusing in a hurry.

  Tycho will grab the Doxia bundle from the Maven local repository,
  but not if it is built in the same reactor. Thus, you have to run
  mvn twice: once to build doxia-osgi, and once for the plugins.

  The <<<eclipse-plugins>>> build delivers its results in
  <<<features/org.apache.maven.doxia.ide.eclipse.feature/target/site>>>. That
  is a P2 repository.

  It can be copied to any old http server and away it goes.

  I don't know why we would care to bother to make an 'update site' 
  as opposed to a P2 repo.

  Tycho is completely incompatible with the
  <<<maven-release-plugin>>>, so, again, some sort of manual procedure
  is called for.