Pre-indexing documentation
When user searches help contents of a product, the search is performed
within a documentation index. By default, this index is created
on the first invocation of help search, but can be pre-built and delivered
to the user with each plug-in, since 3.1, or as a complete index for a product. This
prevents
indexing
from
occurring
on
the user machine and lets the user obtain first search results faster.
Building a documentation index for a plug-in.
To build an index follow the steps:
- add an
index element to the org.eclipse.help.toc
extension in a documentation plug-in, to specify directory where
index will exist, for example
<extension
point="org.eclipse.help.toc">
<index
path="index">
</index>
</extension>
- Add the
help.buildHelpIndex ANT task to the build.xml file in
the plugin project by adding the lines below. A build.xml file can be created
by right clinking on MANIFEST.MF in the package explorer and selecting the
menu item PDE Tools/Create Ant Build File. This example build the index for
the default locale and also for "nl/fr". This should be modified to match the
locales which you are using.<target name="build.index" description="Builds search index for the plug-in: org.eclipse.platform.doc.user." if="eclipse.running">
<help.buildHelpIndex manifest="plugin.xml" destination="."/>
<help.buildHelpIndex manifest="plugin.xml" destination="nl/fr"/>
</target>
- create an index by building the target "build.index". The ant task must be
run in the same JRE as the workspace. To do this right click on build.xml,
select the menu item Run As/Ant build... the ant dialog will appear. On the
targets tab check only "build.index" and on the JRE tab select the radio
button "Run in the same JRE as the workspace". When you hit the
"Run" button the indexes will be built.
Building an index for a product
Per-product index is a one aggregate index of all documentation in the product.
It should be used in scenarios in which the set of documentation plug-ins is
not changing. For example an info-center installation will benefit
from per-product
index.
To build an index follow the steps:
For example, running
eclipse -nosplash -application org.eclipse.help.base.indexTool -vmargs -DindexOutput=d:/build/com.my.plugin -DindexLocale=en
will result in file doc_index.zip being saved in the nl/en
directory that will be created under d:/build/com.my.plugin. The
zip will contain index of contents of documents that are available to users
when they run the product in the en locale.
Packaging and Installation of the product's pre-built index
Pre-built indices, the
doc_index.zip files, need to be packaged as
a plug-in. You can choose to use a plug-in associated with the primary
feature, or choose to package the index for each language into separate fragments.
For example, if product's documentation is available in three languages, say
English, German and Simplified Chinese, a plug-in com.my.plugin can have the following structure:
com.my.plugin/
plugin.xml
nl/
de/
doc_index.zip
en/
doc_index.zip
zh/
CN/
doc_index.zip
other files of this plugin
The ID of the plug-in needs to be specified as a
productIndex preference
for org.eclipse.help.base plug-in. For plug-in in the above example, the
plugin_customization.ini
file needs to contain the entry
org.eclipse.help.base/productIndex=com.my.plugin
