Introduction

This page contains information about Maven and the entire ebxmlrr project site, which includes the old ebxmlrr 2.1 release as well as the newest freebXML 3.0 (OMAR module) - the site is generated at once, for all.

Maven works on projects. Ultimately, a project is a directory with a fixed structure and a few configuration files, see http://maven.apache.org/reference/dirlayout.html.

The ebxmlrr top-level CVS modules (ebxmlrr, jaxr, ...) map very well to the Maven project layout, i.e. every module we have is a separate project.

Installation

  1. Checkout the customized Maven package from CVS, module maven. Make sure it is in the same directory tree as the other ebxmlrr modules.
  2. Set the environment variable MAVEN_HOME to your maven directory.
  3. Add maven/bin to your PATH. (If you are on Unix, you have to set the executable flag on the scripts manually.)

Documentation

The maven module contains the Maven executables and the documentation for the ebxmlrr front web site. Maven uses an internal tool named reactor to support multi-project builds. The maven project for ebxmlrr is customized to use the reactor and iterate through the existing projects, build their web sites and then build a front-end web site that ties it all together.

ebxmlrr 2.1

The ebxmlrr 2.1 documentation is stored in maven/xdocs/2.1 and its subdirectories. Accompanying pictures are stored in the image subdirectories. When you add a document, you need to add a link to the file maven/templates/navigation.xml. The templates directory contains xdocs that consolidate the information from all projects. The reactor fills in the assembled information into the templates and writes them to the xdocs directory where they can be processed like all the other xdocs.

The component documentation (ebxmlrr server, client) is automatically created. If you want to write component specific documents, they can be stored in module/xdocs.

The format of the xdocs is explained here: http://jakarta.apache.org/site/jakarta-site-tags.html. The format is very close to XHTML. If you need to convert HTML documentation into xdocs, Maven provides the html2xdoc tool. Just set maven.html2xdoc.dir in the file project.properties to the directory with your HTML file and run maven html2xdoc. The result is written to target/generated-xdocs.

freebXML Registry 3.0 (OMAR)

The freebXML Registry Team has taken a different approach for OMAR and the docs are written in plain vanilla HTML and then automatically converted to xdocs to be integrated with the site. The rational was to make it easier to create docs - everybody know how to write basic HTML - and at the same time have some kind of (false) WYSIWYG effect when writting documentation.

The documentation is under omar module, at docs/3.0 .

HTML Generation

  1. cd to MAVEN_HOME
  2. Convert omar module docs to xdocs with: maven html2xdoc
  3. Fix generated files dual XML Declaration and copy images (bugs in html2xdoc?) with: ant fix.html2xdocs
  4. Execute maven site.

WARNING: Please don't use maven site:deploy unless you a) customized project.properties in all projects, b) want to overwrite the contents of http://ebxmlrr.sourceforge.net/.

For "1 file" updates (i.e, fix to a single page in the docs), the fastest way is to execute:

maven html2xdoc; ant fix.html2xdocs; maven site

Then upload the file with scp:

scp target/docs/path-to-file/file.html myUser@shell.sourceforge.net:/home/groups/e/eb/ebxmlrr/htdocs/path-to-file/file.html

maven site takes appr. 15 minutes to run on my machine. When you use it the first time, it will download several MB of libraries from the net.

Repository

Maven needs to be able to compile the ebxmlrr source code in order to run its reports on the code. That requires that all libraries that are used by ebxmlrr are specified in the dependencies section of the project.xml file of each project. Maven tries to download all libraries from http://ebxmlrr.sourceforge.net/maven/repository/.

If you add a new library or a new library version, the library needs to be uploaded to SourceForge first. Currently, that requires to log into the SourceForge shell account, create the necessary repository subdirectories and then copy the library with scp.