Community
Participate
Working Groups
In "plugin_customization.ini" the order of the TOC top-level books (primary TOCs) can be specified statically: the IDs of the primary TOCs (or categories) of the books to order have to be listed. But this works only if these IDs are known at the time the application is built. In cases in which these IDs are not known in advance because the TOC contributions are released after the application has been released, it is not possible to specify a TOC order. Example: The documentation of a product exists in different versions that should be shown in parallel (a higher version should not hide lower versions). The latest version should be at the top, e.g. "My Product 4.2.0" should be listed before "My Product 1.2.3". Because the application has been shipped without knowing about upcoming documentation it was not possible to specify the order in "plugin_customization.ini".
Created attachment 208235 [details] Proposed patch (in Git patch format) Proposal: extension point "org.eclipse.help/tocOrderVoter" The static order of the top-level books can be changed by one or more "tocOrderVoter"s which must implement "java.util.Comparator". The book that polls more votes in contrast to another book is sorted before the other book or if it polls fewer votes then it is sorted behind the other book. The voting system (in contrast to "org.eclipse.help.base.searchProcessor" which can change the order of the search results) yields a deterministic TOC order independent of the sequence of votes cast by several voters.
Gerrit patch set: https://git.eclipse.org/r/21868
Dani, John, I'm not as familiar with this area. I don't mind the idea of modifying the TOC but if we already have a nother help extension point, org.eclipse.help.searchProcessor, that works on the processor approach (gets to modify the search results) I'm wondering if we should use that pattern even though as Holger mentioned it's probably not as deterministic for multiple processors (as the run order is arbitrary) PW
(In reply to Holger Voormann from comment #0) > In "plugin_customization.ini" the order of the TOC top-level books (primary > TOCs) can be specified statically: the IDs of the primary TOCs (or > categories) of the books to order have to be listed. But this works only if > these IDs are known at the time the application is built. You could put placeholders into the HELP_DATA file. Adding an extension point that allows an arbitrary plug-in to potentially destroy the intended/shipped order of a product is dangerous and not something I'd like to add. Maybe instead of an extension point we could allow to provide one single comparator directly with the product. However, so far product/branding plug-ins don't have code. Not sure whether there's a hard constraint that prevents us from doing this.
(In reply to Dani Megert from comment #4) In HELP_DATA a category can be used as placeholder. What is missing is a dynamic comparator to sort all TOCs of a category within this category. Maybe, the "org.eclipse.help.toc" extension point could be extended by a "categoryOrder" element with a "category" and a "class" attribute. What do you think?
(In reply to Holger Voormann from comment #5) > (In reply to Dani Megert from comment #4) > In HELP_DATA a category can be used as placeholder. What is missing is a > dynamic comparator to sort all TOCs of a category within this category. > Maybe, the "org.eclipse.help.toc" extension point could be extended by a > "categoryOrder" element with a "category" and a "class" attribute. What do > you think? I've you're not into sorting the top-level elements, then you could implement this via tocProvider. The provider would read your dynamically contributed toc entries and sort them.
