Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Plug-in Developer Guide
Previous Page Home Next Page

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:

  • build a product, including all documentation plug-ins,
  • create an index for a desired locale by running this command:
    eclipse -nosplash -application org.eclipse.help.base.indexTool -vmargs -DindexOutput=outputDirectory -DindexLocale=locale
    
    from the directory containing the product.  The following arguments need to be set :
    outputDirectory - specifies path of the directory where the index is to be saved
    locale - specifies locale for which the index will be built

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

 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire