## Contributing XHTML help documents

Why use XHTML?

The help system provides the ability to produce dynamic help content by annotating your XHTML markup with special tags to filter, include, and extend documents. These features are not available when using HTML.

How to contribute XHTML

XHTML help documents are contributed in much the same way as HTML, except there are a few important differences that must be there in order to support dynamic content and searching. These required modifications are listed below:

- You must bind the XHTML search participant to your doc plugin.

  The eclipse help implementation uses Lucene to index its documents to speed up searching. In order to index a document, Lucene must be able to read the format. Eclipse already provides a search participant for indexing XHTML documents, so you simply need to tell the help system to use it for your documents. Add the following extension to your plug-in manifest:

         <extension
               point="org.eclipse.help.base.luceneSearchParticipants">
            <binding participantId="org.eclipse.help.base.xhtml"/>
         </extension>

- If using dyamic content, you must bind the XHTML dynamic content producer to your doc plugin.

  If you want to produce dynamic content using the XML annotations, you need to tell the help system that it should process your documents. This is done by binding the XHTML dynamic content producer to your plugin.

         <extension
               point="org.eclipse.help.contentProducer">
            <binding producerId="org.eclipse.help.dynamic"/>
         </extension>

XHTML include format

If you wish to use includes in your XHTML, the format of the `path` attribute is as follow: (explained below)

       <plugin_id>/<path_to_xhtml_file>/<filename_xhtml>/<element_id>

Where the fields are:

- plugin_id: The id of the plug-in containing the content to include (e.g. `org.eclipse.help`)
- path_to_xhtml_file: The plug-in relative path to the file (e.g. `/my_folder/my_sub_folder/`)
- filename_xhtml: The name of the XHTML file, including extension (e.g. `my_file.xhtml`)
- element_id: The unique identifier for the element you wish to include. This is set by adding an `id` attribute to that element (e.g. `my.element.id`)

For example, if you wish to include the paragraph (`<p>` element) with the id `my_copyright` from the file `/copyrights/copyright.xhtml` in plugin `my.product.plugin`, you would specify the following:

       my.product.plugin/copyrights/copyright.xhtml/my_copyright