professional services and in-depth knowledge

Generating Eclipse Help from a Trac Wiki with Mylyn WikiText

It is pragmatic to automate the engineering process wherever it is possible. The Mylyn WikiText project assists us to generate project documentation with its great support to convert lightwight markup (Textile, MediaWiki, TracWiki, TWiki, Confluence) to a lot of formats (HTML, DocBook, OASIS DITA, Eclipse help, XSL-FO). Here are the steps to generate Eclipse Help from a Trac Wiki.

This example assumes that the documentation is located in a single page (UserGuide).

  • Create a Plug-in Project for the help.
  • Create a help, a libs, and a temp folder in it.
  • Copy the navigation images (home.gif, next.gif, prev.gif) from any other Eclipse Help to help/images.
  • Copy the Mylyn WikiText libaries to libs.
  • Define the following help extension (plugin.xml):
    <?xml version="1.0" encoding="UTF-8"?>
    <?eclipse version="3.4"?>
    <plugin>
      <extension point="org.eclipse.help.toc">
            <toc file="help/UserGuide-toc.xml" primary="true"/>
      </extension>
    </plugin>
  • Include the following artifacts into the binary build (build.properties):
    bin.includes = META-INF/,\
                   help/,\
                   plugin.xml
  • Create the following ant script (build.xml):
    <project name="example" default="doc" basedir=".">
      <path id="wikitext.tasks.classpath">
        <fileset dir="libs">
          <include name="org.eclipse.mylyn.wikitext.*core*.jar"/>
        </fileset>
      </path>
      <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties"/>
      <target name="doc">
        <!-- fetch the trac page in raw format -->
        <get src="http://trac-server.net/wiki/UserGuide?format=txt"
            dest="help/UserGuide.tracwiki"/>
        <!-- fetch the attachments -->
        <exec executable="/usr/bin/wget" dir="temp">
          <arg line="-r -l 1 http://trac-server.net/attachment/wiki/UserGuide/" />
        </exec>
        <!-- copy the attachments -->
        <copy todir="help">
            <fileset dir="temp/trac-server.net/raw-attachment/wiki/UserGuide">
              <exclude name="**/*.html"/>
            </fileset>
        </copy>
        <wikitext-to-eclipse-help markupLanguage="TracWiki"
            title="User Guide"
            multipleOutputFiles="true"
            formatoutput="true"
            navigationImages="true"
            defaultAbsoluteLinkTarget="doc_external">
            <fileset dir="${basedir}">
              <include name="help/*.tracwiki"/>
            </fileset>
        </wikitext-to-eclipse-help>
      </target>
    </project>
  • Execute the script!