Bugzilla – Full Text Bug Listing
| Summary: | [Doc] Platform userdocs still use deprecated "luceneSearchParticipants" extension point | ||
|---|---|---|---|
| Product: | [Eclipse Project] Platform | Reporter: | Martin Oberhuber <mober.at+eclipse> |
| Component: | User Assistance | Assignee: | Chris Goldthorpe <cgold> |
| Status: | RESOLVED FIXED | QA Contact: | |
| Severity: | major | ||
| Priority: | P3 | CC: | cgold |
| Version: | 3.7 | ||
| Target Milestone: | 3.7 M6 | ||
| Hardware: | All | ||
| OS: | All | ||
| Whiteboard: | |||
Actually I found that in plugin.xml for the userdocs, even a warning is shown because the "xhtml" ID is no longer declared for the participant binding. In other words, the extension is dysfunctional.
This raises a couple questions:
1. Who is responsible for maintaining the Platform userdocs?
- Warnings should be taken seriously.
- Or, the project is configured to report an ERROR in this case
instead of a warning.
2. Is it acceptable in terms of backward compatibility to remove the XHTML
LuceneSearchParticipant? I could imagine that for adopter products, the
effect of doing so may be drastic: since any XHTML documents would no
longer be indexed or found in the help, unless they upgrade all their
help plugins.
It looks like the old "xhtml" LuceneSearchParticipant should continue
to live, but in a "backward compatibility" plugin e.g.
org.eclipse.help.base.compatibility
And, a respective note must likely be added to the "Migration" docs for
adopters, to (a) recommend using the new search participant, and (b) tell
them that the compatibility plugin can be removed when no clients need
it any more.
I'm marking the defect as critical due to the finding in (2).
One end-user visible effect of this defect is: Search docs for the term "External Programs". It returns a "potential hit" in the document org.eclipse.platform.doc.user/tasks/tasks-51.xhtml . I assume that this is classified as a "potential hit" only because this is an XHTML document and the official XHTML support is not available to platform.doc.user due to this defect. Maybe the newer Lucene version supports XHTML automatically out of the box, then no longer having the old "xhtml" lucene search participant available would be a less critical issue --> Severity back to "major" again. To validate these assumptions, searching for "External Programs" in the Helios docs returns the same hit as a normal hit (and not potential): http://help.eclipse.org/helios/topic/org.eclipse.platform.doc.user/tasks/tasks-51.xhtml There are a couple of things going on here.
The <binding> element below is no longer required since Eclipse 3.4. It used to be that xhtml documents would only be indexed correctly if a binding with participantId of org.eclipse.help.base.xhtml was in plugin.xml but now the help system checks the doctype of help topics to determine whether to use an html parser or an xhtml parser.
<extension
point="org.eclipse.help.base.luceneSearchParticipants">
<binding participantId="org.eclipse.help.base.xhtml"/>
</extension>
This extension can safely be removed from plugin.xml and I will remove it.
The potential hit is for a different reason. The help system allows xhtml files to include preprocessing directives so that the content can vary depending for example on the operating system or presence of other bundles. /org.eclipse.platform.doc.user/tasks/tasks-51.xhtml contains a preprocessing filter causing a paragraph to only show on windows systems.
<p filter="ws=win32"><img border="0" src="../images/win_only.png" alt="Windows only" />
Editors that support OLE document mode can also run in the editor area of the Workbench.
</p>
If an xhtml file contains preprocessing directives any hit shows as a potential hit because at the time the index is built ( at least in the case of a prebuilt index ) it is not known how the file will be preprocessed. The algorithm for determining whether to call a hit a potential hit is not sophisticated, if there is any preprocessing in an xhtml file any search hit in that file will be labeled a potential hit.
I have removed the extension from org.eclipse.platform.doc.user/plugin.xml. |
Build ID: I20110126-0800 (3.7m5 candidate) In org.eclipse.platform.doc.user/plugin.xml there is: <extension point="org.eclipse.help.base.luceneSearchParticipants"> <binding participantId="org.eclipse.help.base.xhtml"/> </extension> But as per the ISV docs shipped with the same build, this extension point is deprecated and the new "org.eclipse.help.base.searchParticipant" extension point should be used instead. We should be "eating our own dog food" and use the new extension point, both as an example for adopters and as a test to make sure the new system works as expected.