Project tools

Wiki

Articles and Books

How do I...

Document Editing on Small Devices - XMerge

Project Owner: Svante Schubert
(Please use the provided mailing lists for discussion of the XML based file format and related issues.)

Overview

The goals of the Document Editing on Small Devices project is to:

Allow for the editing of rich format documents on small devices, using 3rd party applications native to the device to do the editing.
Support the most widely used small devices, namely:

Palm
PocketPC

Provide the ability to merge edits made in the small device's lossy format back into the original richer format document maintaining it's original style.
Take advantage of the open and well defined OpenOffice.org XML document format.
Provide a framework with the ability to have plugin-able Convert, Diff and Merge implementations. It should be possible determine a converter's capabilities at run-time.

The XMerge SDK provides a Java-based framework for converting documents between different formats using conversion plugins to read and write each format. More about what plugins are available can be found in the plugin section below.

In addition to format conversion, the XMerge SDK provides a framework for merging changes in one document format (usually a simpler or lower quality format) into an original document (typically in a richer format). The benefit of merging is that richer styles or content in the original document are retained, while the edits made to the simpler format can be applied or merged into the original document.

To meet these goals there are two significant interfaces in XMerge:

the Conversion API's, used by applications to use a supported format conversion
the Plugin SPI, which is used by developers who want to add conversion support for a new document format.

All plugins are designed to support the OpenOffice.org XML file format on one side and the device format on the other, the framework is able to support "chaining" of conversions, also known as an "Any-to-Any" conversion, eg. convert from a Palm document to a PocketPC document through the intermediate OpenOffice.org XML file format.

News and updates

Mobile Device Support in OpenOffice
The Mobile Device Support Pack for OpenOffice 1.0 is now available. Grab it here
This mini-install integrates XMerge plugins into OpenOffice using the upcoming XmlFilterAdapter. Try it out and let us know how it goes.
ActiveSync and OpenOffice
ActiveSync Support has been added. You can now sync OpenOffice Writer and Calc documents to and from a Pocket PC device. ActiveSync will automatically invoke XMerge plugins to perform the appropriate conversions. You can get the filter from the downloads section.
Nokia Communication Word Processor Format Support
Nick Richards has taken on the writing of a plugin for the PsiWord format. PsiWord is the format used by the word processor on the Nokia 9210 Communicator, the Symbian based PDA/phone and other PDA's running the EPOC OS.
Nick is looking for others to help in writing the plugin, so if you can spare the time he can be reached at nedrichards@openoffice.org
Writer2LaTeX XMerge Plugin
Henrik Just has now implemented his Writer2LaTeX converter as an XMerge plugin. This means that now his converter can now be used as an OpenOffice.org export filter as well as being able to perform standalone command line conversions. For more information and the latest versions, visit Henrik's web-page.

Proposed future projects

Synchronisation support for devices, could be any of the following:

Application on small device that pulls down a document in desired format and synchronises back.
Desktop synchronisation integration (eg. HotSync).

New plugins for other small document formats.
Enhancements to existing plugins
Alternate implementations to the diff and merge engines
Support for OpenOffice.org presentations.
Provision of a parser independent "XMLWriter". This would in theory allow XMerge to work with any XML parser with DOM level 2 support.

Plugins

Platform	Plug-in Name	Description	Current Status
Any	XSLT	The XSLT plug-in, makes use of the Xalan XSLT processor, in order to translate an xml document to and from a specified xml/xhtml format.	Source Available
Palm	AportisDoc	Plugin for editing StarWriter documents in the AportisDoc format originally developed by Aportis Technology Corporation. However Aportis as of 31st Dec 2002 were acquired by UltraSoft. There are still many palm applications that use the Aportisdoc format. This plugin supports merging of textual changes.	Source Available
Palm	MiniCalc	Sample implementation for editing StarCalc spreadsheets with MiniCalc on the Palm. This plugin supports merging of textual changes.	Source Available
PocketPC	Pocket Word	Support of editing text documents through PocketWord	Source Available
PocketPC	Pocket Excel	Support for editing spreadsheets in PocketExcel	Source Available

*Follow links for more information and screen-shots.

Documentation and Resources

Document	Summary	Format and Size
Documentation for the XMerge SDK
XMerge Document Conversion SDK	A developer's guide for the XMerge SDK. Describes how to use the client API, implement plugins, testing and installing plug-ins.	PDF, 180K
XSLT Plugin Implementation	Describes the XSLT converter plugin, how to use it and also how to implement further XSLT plugins.	PDF, 11K
XMerge JavaDocs	Generated from JavaDoc comments in the sources.	ZIP, 364K

Building XMerge

The following document describes the process for building the OpenOffice.org XMerge project, either standalone or as part of the OpenOffice.org build environment.

Requirements

The following tools are necessary in order to build the XMerge project.

Note: Java 1.4 includes the Crimson XML parser and Xalan. If using Java 1.4 the only requirement is Ant.

N.B. Xalan 2.3 splits the XSLT classes between two JAR files. The build environment expects the XSLT classes to be contained in xalan.jar only.

Obtaining the source

The source for XMerge is maintained under CVS control as part of the XML project.

See the XML Project's Source page for information on obtaining and contributing to source code.

If using CVS, setup your CVS access according to the Source page and checkout the xmerge module.

  % cvs -d:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs co oo/xml/xmerge

The source can also be downloaded as a ZIP file here.

Building in a Standalone Environment

To build XMerge in a standalone environment, copy all of the jar files mentioned above and the Xalan-J archive into a directory.

You will need to include the Ant binary directory in your PATH. Ant requires that the JAVA_HOME variable also be set.

Wrapper scripts have been provided to execute the build. On a UNIX based system use:

    % build_xmerge -jars <jar_location> [-debug | optimize]

and on Windows use :

    C:\XMerge> build_xmerge.bat -jars <jar_location> [-debug | -optimize]

where <jar_location> is the directory containing the required JAR files.

Note: If using Java 1.4 the jar file location can be given as any directory as Java 1.4 includes the XML and XSLT class files.

The scripts also support building a debug version and an optimized version. Simply specify -debug or -optimize as options. These options are mutually exclusive. If both are set, the first one encountered will be used for build purposes.

Building as part of OpenOffice.org

Setup your OpenOffice.org build environment as detailed in the OpenOffice.org build documents.

To build XMerge, you will also need to copy the Ant and Xalan-J Jar files into your solver's bin directory, e.g. ${SOLARVER}/642/{platform}/bin.

Once these files are present simply execute the build:

    % build

The build will execute and JAR files and documentation will be contained in a platform-named directory created in the xmerge directory.

Running the Test Driver command-line utility

Once the sources have been built, you can test the plugins using the test Driver command-line utility.

To this you will need to know the location of all the JAR files that were built, this will vary depending on the mechanism used to build. You will also need the location of the JAR files that you downloaded as stated in the Requirements section above.

Once you have all of this, you execute the test Driver as follows:

    % java -cp <jar_location> org.openoffice.xmerge.test.Driver -from <mime-type> -to <mime-type> [-merge <original file>] <file>...

The from and to mime-types to use will depend on the type of documents being converted. The "-merge" option is only usable when converting from the device format to the OpenOffice.org document.

The free and open productivity suite