Community
Participate
Working Groups
Allow documentation content to be installed on one (central) machine, and accessed by multiple Eclipse Workbench clients (on other machines). This requirement is based on the need for users to reduce the footprint of what's installed on their development machine; docs can get quite big. Also, documentation updates could be handled centrally, too. Would need a preference indicating the location of the central docs. Local doc plugins would be ignored (this situation to be covered in another feature request) and so could be not installed.
Note: links from local UA (and other) elements that would normally launch the local help system must now launch the remote help system instead.
*** Bug 122969 has been marked as a duplicate of this bug. ***
Also included in this enhancement: As a follow-up to enh 122967, allow a user to not only access a centralized remote help server directly from their workbench, but also to install help content (doc) plug-ins locally, and have those integrated into the same Help System view as the remote content. The scenario is this: developer works for big company who has centralized the product docs for their developers on a remote server (developers still access it via Help > Help Contents or links from context help or Welcome). Then the developer installs a new Eclipse-based tool (and docs) that the other users aren't using -- wants to see help, but his Eclipse is pointed at the remote help server.
Deferring to next release due to resource shortage. I will attach the current state of the work as an attachment to this bug. Some notes about the current state of things: The remote documents are provided by flowing the data through the local help server. The client always requests from the local server (which must be running even if all content is remote), and if the local server does not have the content it consults the remote server. If the remote server has the content, the local server downloads it, filters it, and sends it to the client. Thus, the client workbench does not even know that the content was remote. Another reason for always needing a local help server is that there may be local content, pushing the work of presenting the data and filtering to the client rather than putting a burden on the server, and for the links tab, bookmarks, and scope. These last 3 must be on a per-user basis, and there is currently no support for a single server to deliver these per user. This is why they are disabled in an infocenter. The remote help server is run as a normal infocenter; you do not need to do anything special to make it a remote help server. Table of contents information is retrieved by consulting the TocServlet of the local server rather than going directly through code. The TocServlet first looks locally, then consults the remote server's TocServlet for additional table of contents entries. The results are then merged by the local server and sent to the client. Supporting tocs contributed by a means other than plugin extensions required the addition of new API - the toc support is in org.eclipse.help and we cannot have this plugin make assumptions about what happens for remote content for our particular help implementation, so the notion of a new source of tocs, or a tocProvider was added here, and org.eclipse.help.base contributes a provider that gets tocs from the remote help server. This can be thought of as an extra level of indirection and we could even implement the plugin extension toc loader as one of these. To search, the workbench consults the SearchServlet of the local help server. The servlet then performs two searches in parallel - it searches the local content as would normally happen, and it consults the remote SearchServlet to do the same. Once both sets of results are in, the local SearchServlet sorts them by score and sends them to the client. Thus, again the client does not know whether a result is local or remote, this is handled transparently by the local server. Index is currently not yet implemented. One way to do this would be to add an IndexServlet and have the local help server find all the local and remote indices and merge them, then present to the user. The preference page was reworked, but is still not quite right. I favor the simple approach for this - first ask the user whether they have a remote help server. If yes, then enter the hostname and optionally the port. Currently there is a preference page for the local help server, which is used for troubleshooting. If we have to present both of these, it makes the preferences a bit complicated. We need to revisit the exact use cases for needing to configure the local help server - i.e. what can go wrong that we need to use these? Do we really need a preference page for this rare case, or can we use JVM args or some other less-UI-intrusive way? A few problems have arisen during the investigation of this feature: - Progress monitoring is difficult for remote content since we don't use RPC. We could implement this in the servlets by sending special progress data regularly, but I'd have to dig into this a little more. - Searching dynamic content on the remote server is complicated. We have to first get the "raw" remote results that are unfiltered, but with contributions resolved, then filter the results locally. Currently this is not even done in the local case - i.e. you will get false positives if you search for dynamic content that should only show up on, say, linux, but you're running in windows. Searching remotely also puts a potentially large burden on the infocenter, so I need to investigate whether it's possible to transfer some of this load to the client.
Created attachment 33218 [details] current state of work The zip contains a patch with all the changes, as well as the source for the affected plugins, since the patch will probably be stale when we revisit this.
Sending back to inbox as it was deferred for 3.2.
*** Bug 146766 has been marked as a duplicate of this bug. ***
*** Bug 41335 has been marked as a duplicate of this bug. ***
A question about requirements for Kari, etc. Would it be an acceptable restriction to not allow a book's content to be split up between the local and remote machine? That is, for any given book, its complete contents (all topics and subtopics) must either be all local or all remote, not mixed local & remote. I ask because this would affect the complexity of the new API for toc providers. If the requirement is not there then I would rather keep the API clean and simple.
>Would it be an acceptable >restriction to not allow a book's content to be split up between the local and >remote machine? Hmmm. No, that doesn't sound like an acceptable restriction to me. A "Book" (a top-level node, and all its children) can be built from many many contributions from many many plug-ins, owned my many many owners on different projects, and installed potentially at different times. And a book can be re-wired by another doc plug-in's TOC to no longer be on the bookshelf. This restriction would place incredible restrictions on the installer .. it would have to parse the nav tree before it knew what plug-ins had to be put in the same place. And what if something a user installed later, locally, wired in (with a "link") something that was already installed remotely ... the remote doc plug-in would have to be moved down to the local machine? That doesn't make sense. Unless I've completely misunderstood what you're saying. If so, sorry, and please re-ask.
I think you understood correctly, I just underestimated how intertwined things can get with large sets of documents. I won't add this restriction.
I'm declaring this one completed for M2. The functionality is now there and working. Any further work (performance, responsiveness, documentation) will be tracked in other bugs and this is now in maintenance mode. Since there are no docs yet, I'll explain how to set this up. There are two ways to configure this: 1. Pre-configured out of the box - In the plugin_customization.ini you can change these parameters (with defaults): org.eclipse.help.base/remoteHelpOn=false org.eclipse.help.base/remoteHelpHost= org.eclipse.help.base/remoteHelpPath=/help org.eclipse.help.base/remoteHelpUseDefaultPort=true org.eclipse.help.base/remoteHelpPort=80 If not on, then all others ignored. Also if default port is used, port number is ignored. So, for example, if you have an infocenter that you can access at http://myinfocenter.mydomain.com:8081/help/index.jsp, you would use these settings: org.eclipse.help.base/remoteHelpOn=true org.eclipse.help.base/remoteHelpHost=myinfocenter.mydomain.com org.eclipse.help.base/remoteHelpPath=/help org.eclipse.help.base/remoteHelpUseDefaultPort=false org.eclipse.help.base/remoteHelpPort=8081 2. Preference page under Help -> Content. You can specify the exact same info as the fields above. ---- On the server side, all you need to do is set up an infocenter as usual. Put whatever docs you want to access remotely on it. That's all you need to do. The infocenter has new servlets that offer web service-style XML content and the client knows how to talk to them. So the infocenter now serves a dual purpose, remote help and infocenter. Note that you cannot use an old infocenter here, it must be a 3.3 infocenter. Backward compatibility will be maintained so that you will be able to use, say, a 3.4 (or 4.0) workbench with a 3.3 infocenter. You just may not get any of the new features that are available in 3.4 or 4.0. As far as coverage, it will serve toc, keyword index, content, and context-sensitive help. I have tested NL to ensure that it fetches the content in the correct language from the infocenter, and an infocenter can serve many languages for remote help. Dynamic content should also work; filters, anchor contributions, and includes are processed on the client side and it will request included or contributed content from the remote server when needed. Toc nesting can also work across local/remote, so you can have a local book that wraps a remote toc that wraps yet another local toc. What I plan to do during M3 is see if we can apply this solution to the eclipse SDK, which would give us much more thorough testing, and we would benefit from the space savings. I am also working on improving the responsiveness of the UI if the remote infocenter or network connection is slow, i.e. show progress instead of being frozen.
