%META:TOPICINFO{author="DuncanKinnear" date="1197322231" format="1.1" version="1.3"}%
---+!! !OpenOffice to TWiki Add-On

<nop>%TOPIC% (OO2TWiki) allows you to convert [[http://www.openoffice.org][OpenOffice.org]] (and [[http://www.sun.com/software/star/staroffice/index.xml][StarOffice]] and [[http://www.koffice.org][KOffice]] 1.4) documents into TWiki topics. It brings together several disjointed ideas into one server-side add-on. 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 [[http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office][OASIS standard document format]].

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

%RED% %X% __Note:__ This add-on 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 (although this seems to have improved since this statement was made in 2005).%ENDCOLOR% It will tie up one of your processors at 100% utilisation for somewhere between a few seconds and several minutes. You may consider presenting a read-only mirror of your TWiki site to the public and only using this add-on in a private mirror.

---++ Usage

   * An !OpenOffice.org document can be converted by substituting =view= for =convert= 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:
      * =&lt;a href="%<nop>SCRIPTURLPATH%/convert%<nop>SCRIPTSUFFIX%/%<nop>WEB%/%<nop>TOPIC%"&gt;Convert&lt;/a&gt;=

You may still need to do some minor modifications of the new topic after uploading. See the [[#Frequently_Asked_Questions][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 Add-on

The add-on uses XSLT stylesheets that should be attached to this help topic. The add-on decides which stylesheet to use based on the file extension of the uploaded document. For example, a file ending with the extension '.odt' will use the stylesheet named 'odt.xslt' which should be attached to this topic. Therefore you can enhance/fix/upgrade the stylesheets without needing webmaster privileges.

   * Add the debug flag to the TWiki.TWikiPreferences topic and set it to 'on' if you wish to enable debugging of the add-on:
      * Set OO2TWIKI_DEBUG = off

---++ 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 &lt;verbatim&gt; blocks?* : You should use the paragraph style 'Preformatted Text' for any lines you want to be tagged &lt;verbatim&gt; in the TWiki topic. You may need to select 'All Styles' in the drop-down list of the Stylist. If you already have a preformatted text style with a different name, you can use 'Edit -> Find &amp; Replace' then check 'Search for Styles' to replace the old style with 'Preformatted Text'. Why? Because if you ever choose to import a web page back into !OpenOffice, it will assign the style 'Preformatted Text' to anything between &lt;pre&gt; tags.
   $ *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 add-on 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:%BR%
      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.%BR%
      1 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 manually add a link to it in the topic text when you upload it.%BR%
      1 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 add-on name use 2 instead of To?* : Because it was developed using !OpenOffice.org 2.0 beta (m104-m118) 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.

---++ Add-on 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 ==%TOPIC%.zip== in your TWiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Add-on topic |
     | ==data/TWiki/%TOPIC%.txt,v== | Add-on topic repository |
     | ==pub/TWiki/%TOPIC%/sxw.xslt== | XSLT stylesheet for converting !OpenOffice 1.0 Text Document (.sxw) to TWiki |
     | ==pub/TWiki/%TOPIC%/sxi.xslt== | XSLT stylesheet for converting !OpenOffice 1.0 Presentation (.sxi) to TWiki |
     | ==pub/TWiki/%TOPIC%/odt.xslt== | XSLT stylesheet for converting !OpenDocument Text (.odt) to TWiki |
     | ==pub/TWiki/%TOPIC%/odp.xslt== | XSLT stylesheet for converting !OpenDocument Presentations (.odp) 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.*
   * %X% Add the line =$TWiki::cfg{xsltprocCmd} = '/usr/bin/xsltproc';= to your =lib/LocalSite.cfg= file so TWiki can find the location of the xsltproc executable.
   * Test if the installation was successful:
      * Try uploading an !OpenOffice document with the following [[%SCRIPTURL%/convert/Sandbox/WebHome][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.
   * Attempts at determining Object and !ObjectReplacements file formats are pitiful.
   * Special characters are not translated properly.

---++ Add-On History
   * Version 0.4 (11 Dec 2007)
      * Fixed extraction of multiple embedded images, and fixed creation of link on parent topic

   * Version 0.3 (08 Aug 2007)
      * Ported to 4.1.2

   * Version 0.1 (26 Jul 2005)
      * Initial version

---++ Add-On Info

   * Set SHORTDESCRIPTION = Convert <nop>OpenOffice, <nop>StarOffice and KOffice documents into TWiki topics

| Add-on Author: | TWiki:Main/WadeTurland %BR% Credit should also go to anyone who suggested an idea on TWiki:Codev/OpenOfficeIntegration, especially TWiki:Main/BradDixon, updated for Dakar by TWiki:Main/KoenMartens |
| Add-on Version: | 11 Dec 2007 (v0.4) |
| Change History: | See Add-On History section above |
| CPAN Dependencies: | File::Temp, Archive::Zip |
| Other Dependencies: | xsltproc (part of libxslt from http://www.xmlsoft.org/XSLT) |
| Perl Version: | 5.005 or above |
| License: | GPL |
| Add-on Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
| Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
| Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |


__Related Topics:__ %TWIKIWEB%.TWikiAddOns

-- TWiki:Main/WadeTurland - 6 Aug 2005%BR%

<!-- vim:noet:sw=3:ts=3:tw=0
-->

%META:FILEATTACHMENT{name="sxw.xslt" attr="" comment="XSLT stylesheet for !OpenOffice 1.0 Text" date="1122427637" path="sxw.xslt" size="39312" user="WadeTurland" version="1.1"}%
%META:FILEATTACHMENT{name="odt.xslt" attr="" comment="XSLT stylesheet for !OpenDocument Text" date="1122426784" path="odt.xslt" size="39035" user="WadeTurland" version="1.1"}%
%META:FILEATTACHMENT{name="odp.xslt" attr="" comment="XSLT stylesheet for !OpenDocument Presentations" date="1122477565" path="odp.xslt" size="42670" user="WadeTurland" version="1.1"}%
%META:FILEATTACHMENT{name="OpenOffice2TWikiAddOnStressTest.odt" attr="" comment="!OpenOffice 2.0 stress test" date="1122426652" path="OpenOffice2TWikiAddOnStressTest.odt" size="56252" user="WadeTurland" version="1.1"}%
%META:FILEATTACHMENT{name="OpenOffice2TWikiAddOnStressTest.sxw" attr="" comment="!OpenOffice 1.0 stress test" date="1122426681" path="OpenOffice2TWikiAddOnStressTest.sxw" size="54104" user="WadeTurland" version="1.1"}%
%META:FILEATTACHMENT{name="OpenOffice2TWikiAddOnStressTest.odp" attr="" comment="!OpenOffice 2.0 Presentation Stress Test" date="1122477634" path="OpenOffice2TWikiAddOnStressTest.odp" size="12849" user="WadeTurland" version="1.1"}%
%META:REVCOMMENT{ncomments="0"}%
