Pre-indexing Eclipse Help documentation

build.xml

<?xml version="1.0" encoding="UTF-8"?>

<project name="root" basedir="." default="index">
  <property environment="env"/>
  <property name="output.dir" value="${env.DITA_HOME}/out"/>
  
  <target name="index" unless="skip.index">
    <!--
    Use org.eclipse.ant.core.antRunner to call the current build file.
    I'm unsure as to why this is necessary, but if it's not done like this, the
    <taskdef> below doesn't work.
    -->
    <java dir="${eclipse.home}" maxmemory="1024m" fork="true"
      classname="org.eclipse.core.launcher.Main">
      <!-- org.dita.pdf2/fop/lib contains all Xalan JARs that the build indexer needs to parse XML files -->
      <jvmarg value="-Djava.endorsed.dirs=${env.DITA_HOME}/plugins/org.dita.pdf2/fop/lib"/>
      <arg line="-application org.eclipse.ant.core.antRunner"/>
      <arg line="-buildfile ${ant.file} build-help-index"/>
      <arg line="-Doutput.dir=${output.dir}"/>
      <classpath>
        <fileset dir="${eclipse.home}/plugins">
          <include name="org.eclipse.equinox.launcher_*.jar"/>
        </fileset>
      </classpath>
    </java>
  </target>

  <target name="build-help-index">
    <taskdef name="buildHelpIndex" classname="org.eclipse.help.internal.base.ant.BuildHelpIndex"/>
    <!--
    @destination *MUST* be the DITA-OT output directory (that is, the directory
    that contains both plugin.xml and the HTML files that are indexed).
    Otherwise Eclipse can't find the HTML files for indexing and the process
    will fail.
    -->
    <buildHelpIndex manifest="${output.dir}/plugin.xml" destination="${output.dir}"/>
  </target>
</project>

eclipse-plugins.txt

com.ibm.icu_4.4.2.v20110823.jar
com.jcraft.jsch_0.1.44.v201101211721.jar
javax.el_2.2.0.v201108011116.jar
javax.servlet.jsp_2.2.0.v201112011158.jar
javax.servlet_3.0.0.v201112011016.jar
org.apache.ant_1.8.3.v201301120609
org.apache.commons.logging_1.0.4.v201101211617.jar
org.apache.jasper.glassfish_2.2.2.v201112011158.jar
org.apache.lucene.analysis_2.9.1.v201101211721.jar
org.apache.lucene.core_2.9.1.v201101211721.jar
org.apache.lucene_2.9.1.v201101211721.jar
org.eclipse.ant.core_3.2.401.v20121204-161613.jar
org.eclipse.core.commands_3.6.0.N20120213-2000.jar
org.eclipse.core.contenttype_3.4.100.N20120213-2000.jar
org.eclipse.core.expressions_3.4.300.N20120213-2000.jar
org.eclipse.core.filesystem_1.3.200.N20120213-2000.jar
org.eclipse.core.jobs_3.5.200.N20120213-2000.jar
org.eclipse.core.resources_3.8.0.N20120213-2000.jar
org.eclipse.core.runtime.compatibility_3.2.100.N20120213-2000.jar
org.eclipse.core.runtime_3.8.0.N20120213-2000.jar
org.eclipse.core.variables_3.2.600.v20120521-2012.jar
org.eclipse.equinox.app_1.3.100.N20120213-2000.jar
org.eclipse.equinox.common_3.6.100.N20120213-2000.jar
org.eclipse.equinox.http.jetty_3.0.0.N20120213-2000.jar
org.eclipse.equinox.http.registry_1.1.100.N20120213-2000.jar
org.eclipse.equinox.http.servlet_1.1.300.N20120213-2000.jar
org.eclipse.equinox.http.servletbridge_1.0.200.v20111010-1614.jar
org.eclipse.equinox.jsp.jasper.registry_1.0.200.N20120213-2000.jar
org.eclipse.equinox.jsp.jasper_1.0.300.N20120213-2000.jar
org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar
org.eclipse.equinox.preferences_3.5.0.N20120213-2000.jar
org.eclipse.equinox.registry_3.5.200.N20120213-2000.jar
org.eclipse.equinox.servletbridge.extensionbundle_1.2.0.jar
org.eclipse.help.base_3.6.100.v201202132000.jar
org.eclipse.help.webapp_3.6.100.N20120213-2000.jar
org.eclipse.help_3.6.0.N20120213-2000.jar
org.eclipse.jdt.core_3.8.1.N20120213-2000.jar
org.eclipse.osgi.services_3.3.0.N20120213-2000.jar
org.eclipse.osgi_3.8.0.N20120213-2000.jar
org.eclipse.text_3.5.200.N20120213-2000.jar
org.eclipse.update.configurator_3.3.100.N20120213-2000.jar

Eclipse.md

Pre-indexing Eclipse Help documentation

Foreword

After hours of Googling and banging my head against a wall, I finally managed to pre-index an Eclipse Help documentation plugin using just Ant and a minimal Eclipse distribution.

A heads up: the information here is somewhat skewed towards DITA-OT users, but I'm sure it's mostly useful even if you don't use DITA-OT.

Prerequisites

Your Eclipse Help plugin's plugin.xml must look something like this:

<?xml version="1.0" encoding="utf-8"?>

<plugin>
   <extension point="org.eclipse.help.toc">
      <toc file="toc.xml" primary="true"/>
      <index path="index"/>
   </extension>
   <extension point="org.eclipse.help.index">
      <index file="index.xml"/>
   </extension>
</plugin>

The key is <index path="index"/>. DITA-OT does not add this element by default, so you need to create a plugin that overrides org.dita.eclipsehelp/xsl/map2pluginImpl.xsl and adds that element. Maybe DITA-OT should even add it by default?

Furthermore, you need a certain, minimal set of Eclipse JAR plugins in $ECLIPSE_HOME/plugins to run org.eclipse.help.internal.base.ant.BuildHelpIndex, which is the Java class that does the indexing. See eclipse-plugins.txt for a list of plugins that worked for me on Eclipse 3.8. You might possibly be able to trim down the list of plugins even further, but eclipse-plugins.txt has a set that will allow you to pre-index and run the Help System.

Also, I'm fairly sure you need to have something like this in your product plugin's plugin_customization.ini for things to work correctly:

org.eclipse.help.base/locales=en

Once that's sorted out, you can use the targets in build.xml to pre-index a documentation plugin that's in the folder specified in the output.dir Ant property. Remember: this folder must contain plugin.xml (with <index path="index"/> as specified above) and the documentation HTML files.

If the pre-indexing process is successful, a folder called index will appear in output.dir, after which you can package the whole thing into a JAR file and deploy it into Eclipse Help System.

java7-osx-build.xml

<!--
This is an alternative "index" target that works for me on Java 7 on OS X but
doesn't seem to work e.g. on Java 6 / Ubuntu. Retained here in case it helps
someone, but the "index" target in the build.xml file above should work on
both OS/Java combinations.
-->
<target name="index">
  <!--
  Use org.eclipse.ant.core.antRunner to call the current build file.
  I'm unsure as to why this is necessary, but if it's not done like this, the
  <taskdef> below doesn't work.
  -->
  <java dir="${env.ECLIPSE_HOME}" classname="org.eclipse.core.launcher.Main" fork="true">
    <!--
    Again, I can't give a technical explanation for why this JVM argument is
    necessary, but if it's not used, JAXP will throw a bunch of errors
    related to its FEATURE_SECURE_PROCESSING feature and the index building
    process will fail.

    This does mean that you need to have xercesImpl.jar and xml-apis.jar, but
    if you're using DITA-OT, that's not a problem since they come with
    DITA-OT.
    -->
    <jvmarg
      value="-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
    <!--
    This is needed when building on OS X, at least; otherwise the process will
    throw an SWT Invalid Thread Access error. Probably not necessary on other
    platforms.
    -->
    <jvmarg value="-XstartOnFirstThread"/>
    <arg line="-application org.eclipse.ant.core.antRunner"/>
    <!-- Call the "build-help-index" target below with Eclipse Ant Runner -->
    <arg line="-buildfile ${ant.file} build-help-index"/>
    <classpath>
      <fileset dir="${env.ECLIPSE_HOME}/plugins">
        <include name="org.eclipse.equinox.launcher_*.jar"/>
      </fileset>
      <!--
      Needed because we specify Xerces as the DocumentBuilderFactory above.
      -->
      <fileset dir="${env.DITA_HOME}/lib">
        <include name="xercesImpl.jar"/>
        <include name="xml-apis.jar"/>
      </fileset>
    </classpath>
  </java>
</target>