OpenOffice to TWiki Add-On

OpenOffice2TWikiAddOn (OO2TWiki? ) allows you to convert OpenOffice.org (and StarOffice and KOffice 1.4) documents into TWiki topics. It brings together several disjointed ideas into one server-side plugin. Most Microsoft Office documents can be imported by using OpenOffice.org as an intermediary step, and this task is now much easier with the Document Converter Wizard that comes with OpenOffice.org 2.0.

As StarOffice is simply the commercial version of OpenOffice.org, the two products will be referred to as OpenOffice.org. Both OpenOffice.org 2.0 and KOffice 1.4 (can) use the OASIS standard document format.

This add-on has only been tested with the Cairo version of TWiki. We have made no attempt to determine if it will run on earlier versions.

Note: This plugin does XML translations of your source document which can cause extremely high load on the server and may take several minutes to complete even on a fast server. You may consider presenting a read-only mirror of your TWiki site to the public and only using this plugin in a private mirror.

Usage

• An OpenOffice.org document can be converted by substituting convert for view in the topic URL. The topic part of 'Web/Topic' URL will be the parent topic of the new topic resulting from the document conversion.
• To make it even easier for novice TWiki users to use, you can add a link (like edit and attach) to your view.tmpl to convert a document and save it as a topic below the current page (using the current topic as the new topic's parent). The line to add to your skin template is:
  • <a href="%SCRIPTURLPATH%/convert%SCRIPTSUFFIX%/%WEB%/%TOPIC%">Convert</a>

You may still need to do some minor modifications of the new topic after uploading. See the Frequently Asked Questions section for hints.

Documents can be uploaded several times with full revision control of the topic and any attachments extracted from the document.

Configuring the Plugin

The plugin uses XSLT stylesheets that should be attached to this help topic. The plugin decides which stylesheet to use based on the file extension of the uploaded document.

• Add the debug flag to the TWikiPreferences topic and set it to 'on' if you wish to enable debugging of the plugin:
  • Set OO2TWIKI? _DEBUG = on

Frequently Asked Questions

How do I get the best results?

Make it clean and keep it clean. Most formatting oddities come from poorly formatted source documents, especially MS Word documents. If you are converting from MS Word, a few minutes reformatting in OpenOffice can save ages reformatting the TWiki markup. I often use 'Default Formatting' (from the right-click context menu) to reset the formatting.

How do I get my code source to appear in <verbatim> blocks?

You should use the paragraph style 'Preformatted Text' for any lines you want to be tagged <verbatim> in the TWiki topic. You may need to select 'All Styles' in the drop-down list of the Stylist.

How do I get my code source to appear inline as monospaced text?

You should use the character style 'Source Text' for any text you want to appear monospaced in the TWiki topic. You may need to select 'All Styles' in the drop-down list of the Stylist (and click the Character Styles icon).

All of my text is run together

Check your source document. It's possible that the entire document is one big table. Otherwise, it may be using a different XML namespace to the stylesheet. Try saving it as .sxw instead of .odt or vice versa.

Why does it take such a long time to run?

That's the nature of XSLT. It's a procedural language that uses lots of deep recursion. I have had documents take over three and a half minutes to complete.

I waited for ages and eventually got a browser timeout. What happened?

Chances are, the server will finish processing your request and if you view (or search for) your new topic it will be there. Your browser just decided it couldn't wait any longer for a response.

Why does the convert/upload page look like a normal Attach page?

Because it uses the attach template. I find TWiki's template system very confusing and find it frustrating to have to build a new template for every skin when a new plugin does something different. Therefore I use the normal Attach template and replace some of the text. It would be trivial to change the plugin to use its own template if you prefer - just change "attachnew" in OO2TWiki.pm to the name of your new convert template.

Why don't some of my images appear?

There are a few possibilities:

1. They were embedded as something other than GIF, PNG or JPEG. They should still be attached to the topic though. If you manually convert and upload them as PNG, they will "magically" appear.
   
2. They were created using WordArt or drawing functions in the word processor. You should be able to copy and paste the image into an OpenOffice Draw document and export it to PNG. You will need to link it to the page when you upload it.
   
3. They were not embedded in the document and use external links. Check the HTML page source to see what your browser is trying to request.

There is a PNG/GIF/JPEG image attached but it doesn't get displayed in the topic. Where did it come from?

It was probably embedded in the headers or footers of the original or used as a background image on a master page. Header and footer text is not converted at this stage but that may change in the future.

Why does the plugin name use 2 instead of To?

Because it was developed using OpenOffice.org 2.0 beta (m104-m113) and I wanted to emphasize that. The coders have done a lot of work in enhancing the MS Word import filters so you will naturally get a better conversion with OpenOffice.org 2.0.

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this add-on. The following instructions are for the administrator who installs the add-on on the server where TWiki is running.

• Install xsltproc from http://www.xmlsoft.org/XSLT (part of libxslt)
• Download the ZIP file from the Add-on Home (see below)
• Unzip OpenOffice2TWikiAddOn.zip in your TWiki installation directory. Content:

  File:	Description:
  data/TWiki/OpenOffice2TWikiAddOn.txt	Add-on topic
  data/TWiki/OpenOffice2TWikiAddOn.txt,v	Add-on topic repository
  pub/TWiki/OpenOffice2TWikiAddOn/sxw.xslt	XSLT stylesheet for converting OpenOffice 1.0 Text Document (.sxw) to TWiki
  pub/TWiki/OpenOffice2TWikiAddOn/odt.xslt	XSLT stylesheet for converting OpenDocument Text (.odt) to TWiki
  bin/convert	Add-on script
  lib/TWiki/Contrib/OO2TWiki.pm	Add-on perl package

• Adjust the script ownership to match your webserver configuration (e.g. chown nobody convert) if needed.
• Make sure the script is executable (e.g chmod 755 convert).
• Adjust the perl path in the convert script to match your perl installation location.
• Add the variable $xsltprocCmd = /path/to/xsltproc; to your lib/TWiki.cfg file so TWiki can find the location of the xsltproc executable. Look for $fgrepCmd.
• Test if the installation was successful:
  • Try uploading an OpenOffice document with the following link to Sandbox/WebHome
  • If it doesn't work, check your webserver logs for any problems. The most common issue is probably an xsltproc installation problem.

Known Bugs

• Formatting transformations are not complete. Please help with the XSLT stylesheets if you know anything about XML.
• Vertically merged table cells sometimes break table formatting.

Add-On History

• Version 0.1 (26 Jul 2005)
  • Initial version

Add-On Info

Related Topics: TWikiAddOns

-- TWiki:Main/WadeTurland - 26 Jul 2005