Author: bimargulies
Date: Mon Aug 29 21:34:13 2011
New Revision: 1163019
URL: http://svn.apache.org/viewvc?rev=1163019&view=rev
Log:
More doc.
Modified:
maven/sandbox/branches/doxia-ide-eclipse-with-tycho/src/site/apt/index.apt
Modified:
maven/sandbox/branches/doxia-ide-eclipse-with-tycho/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/maven/sandbox/branches/doxia-ide-eclipse-with-tycho/src/site/apt/index.apt?rev=1163019&r1=1163018&r2=1163019&view=diff
==============================================================================
--- maven/sandbox/branches/doxia-ide-eclipse-with-tycho/src/site/apt/index.apt
(original)
+++ maven/sandbox/branches/doxia-ide-eclipse-with-tycho/src/site/apt/index.apt
Mon Aug 29 21:34:13 2011
@@ -6,10 +6,109 @@
25 August 2011
-----
-Structure
+Overview
- [org.apache.maven.doxia.eclipse.dependencies] builds an OSGi bundle with all
of the dependencies
+ 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>>> subdirectory.
+ 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.
+
+
+
+
+
+
+
+
+
- [eclipse] contains all of the other material, using Tycho to make eclipse
plugins.
