Confluence wiki to Eclipse Help the easy way – Scroll FTW

How cool would it be to write your documentation and online help content in Confluence wiki and convert it to Eclipse Help format at will? The K15t Software guys have just announced the latest version of Scroll Wiki Exporter, Scroll 1.2, including a new exporter for Eclipse Help and JavaHelp.

So I tried it. It works. 🙂

Why am I focusing on the Eclipse Help conversion?

It just so happens that Atlassian, where I work, has a product called the Atlassian Eclipse Connector. It’s an Eclipse plugin. At the moment, we write and publish the documentation for that product on our Confluence wiki, along with all our other documentation.

I’m wondering whether we could export the docs to Eclipse Help format and ship them with the connector, so that developers can use the documentation inside the Eclipse IDE. After all, that’s where people are using the connector itself.

Getting Confluence and Scroll

Download Confluence and install it, following the installation and setup guide. You can get a free 30-day trial licence or a free personal licence. I’m using Confluence 3.2.1. Actually, it’s the rather verbosely named 3.2.1_01. 😉 and it’s the most recent version of Confluence at time of writing.

Scroll Wiki Exporter is a plugin for Confluence wiki, supplied by an independent company called K15t Software. You can get a free 30-day trial licence for Scroll too. Follow the installation guide to download and install the Scroll plugin into Confluence.

Hint: For some reason, I could not find the Scroll plugin using the Confluence “Plugin Repository” option. I used the alternative option — download the JAR file from the Scroll web site, then upload it into Confluence via the “Plugins” option in the Confluence Administration Console.

Writing your topics

The Scroll team provide some useful tips for getting the best out of Scroll. For example, you can see how Scroll handles heading levels and check the supported Confluence macros and wiki markup. See the Scroll authoring guide.

Using Scroll to export Confluence pages to PDF and DocBook

A while ago I wrote a post with some pretty screenshots about using Scroll to export wiki content to PDF and DocBook. You can still do this with the new version of Scroll, of course!

Exporting to Eclipse Help format

Once you have installed the Scroll plugin into Confluence, you will see a new item in the Confluence “Tools” dropdown menu, called “Scroll Wiki Exporter”:

Confluence wiki to Eclipse Help the easy way

Click that option to see the Scroll export screen. At the top, it shows the title of the wiki page you were on when you clicked the “Scroll Wiki Exporter” menu option. In my case, the page is named “Atlassian Connector for Eclipse”. This will also be the top page in the tree that the exporter will process. Your output file will contain this page and all its children:

Confluence wiki to Eclipse Help the easy way

Go to the “Formatting” tab and select “EclipseHelp (*.jar)” as your format:

Confluence wiki to Eclipse Help the easy way

Click the “Export” button at the bottom of the screen, and wait a while. When the export has finished, a new screen will appear offering you the output file for download:

Confluence wiki to Eclipse Help the easy way

Hint: If you are using Windows,  you may find that the file is automatically renamed from a “.jar” to a “.zip” file. Change the extension back to “.jar”.

The output

What you get is a JAR containing the files required by the Eclipse platform, to be able to incorporate your help files into the Eclipse IDE. The JAR file has a name corresponding to the title of the page you selected, plus the version of the page. For example, my JAR file was called:

Atlassian_Connector_for_Eclipse-37.jar

Looking inside the JAR (it’s just like a zip file) you see:

• A top-level folder. Mine was called “com.example.plugin_37”.
• A “download” folder, containing an “attachments” folder and a lot of numbered folders. This is where you’ll find your Confluence screenshots, images and other files that were attached to your wiki pages.
• An “images” folder with the stock Confluence icons.
• A “plugin.xml” file, defining the help plugin to Eclipse.
• A “toc.xml” file, defining the table of contents to Eclipse.
• A number of HTML files containing the content from your wiki pages.
• An HTML file called “index.html”, which is the top level of your HTML tree. Click this one if you want to view your help files in your browser. 🙂

Here’s what the extracted JAR looks like in Windows Explorer:

Confluence wiki to Eclipse Help the easy way

Here’s what one of the pages looks like when viewed in Firefox browser. Note that the annotated screenshot on the page comes from a Gliffy diagram in Confluence. It’s exported as a PNG file in the Eclipse Help format. FTW! Gliffy is a plugin you can use to draw awesome diagrams on your wiki pages, so it’s great that Scroll is able to export Gliffy diagrams too.

Confluence wiki to Eclipse Help the easy way

Putting the help file into Eclipse

When doing things properly, you will need to associate your help file with the Eclipse plugin that it’s documenting, and hook up the context-sensitive help links too. The Eclipse documentation guidelines have all the details.

For a quick thrill, you can simply extract the files from the JAR file and copy them into your Eclipse “plugins” folder. I’m using Eclipse 3.5 (Galileo) on Windows Vista. My “plugins” folder is at this location:

C:\Program Files\Eclipse 3.5 Galileo\plugins

I copied my “com.example.plugin_37” folder and all its children into the “plugins” folder. With huge anticipation, I started Eclipse and clicked “Help”. Ta da! ♪♫♬

Confluence wiki to Eclipse Help the easy way

(Click the above image to see a larger version.)

The “Contents” panel on the left shows the default 5 help topics that come with Eclipse, followed by mine. My set of help topics is the one called “Atlassian Connector for Eclipse“. For the sceptics 😉 here’s an even bigger screenshot showing the full Eclipse SDK with the help window open:

Confluence wiki to Eclipse Help the easy way

Other points of interest

One thing I was concerned about was the performance hit on a Confluence instance, if random people start exporting the content to various formats, and in particular to PDF as its conversion is known to be a bit of a resource hog. The Scroll guys have thought of this, of course. Their documentation explains that Scroll uses the Confluence “export space” permission, so you can limit the number of people who can do the export and make sure they know the possible performance considerations.

Scroll happily converted my {toc} macros into links, and made useful decisions about dividing content into help topics.

Things to investigate further

I did all this investigation and experimentation in the course of an Atlassian FedEx Day. That’s when we get 24 hours to do something cool. (I blogged about another FedEx Day a while ago.) There’s only so much time in a FedEx Day, so there are still some things to follow up on.

I encountered a slight problem with my Gliffy diagram. The export itself worked, converting the diagram to a .png file. When you view the HTML files via a web browser you can see the Gliffy diagram. (There’s a screenshot above.) But when you view the same page in Eclipse, the image is missing. The .png file is in a “temp” folder within the JAR, so maybe Eclipse Help can’t find it there. I’m sure the Scroll team will know the answer. Here’s the location within my JAR file:

download/temp/mypic.png

Scroll offers a macro and a label that you can use to exclude pages and text from the export. I haven’t tried them, but they look very useful.

To make the help files really useful within Eclipse, we’ll need to hook up the context-sensitive help from our Eclipse Connector plugin to the relevant topics in our help plugin. Then we could ship the help plugin along with the Eclipse Connector plugin itself. I haven’t looked at this yet.

Conclusion

Scroll’s conversion to Eclipse Help looks very useful. I’ll recommend to our Eclipse Connector development team that we follow up on it. 🙂

♩♪♫♬♭