Little Known Things about the Eclipse Infocenter: Debugging Information (5/5)

This is the last of the five well-hidden features of the Infocenter. The Eclipse Infocenter is the Eclipse help system launched as a web application which can of course also be remotely debugged like any other Java application. But in situations when you cannot easily access the server on which the Infocenter is running you can still get hold of a list of active plug-ins and some help-specific configuration information. Furthermore, you can display any file of an active plug-in. This debugging information, which is similar to the Configuration Details in the About Dialog of your Eclipse IDE, can be accessed not by following a link or by clicking a button but by opening specific URLs.

For a table of active plug-ins just open the page about.html. You can sort the rows by clicking on a column header. This list can be used to get the source code of the plug-ins, which is required for a remote debugging session. Or you can check if there are any known security vulnerabilities (e. g. cross-site scripting vulnerability) that need to be fixed by updating the Infocenter. You should use Eclipse 3.8 or newer just to be on the safe side. Two weeks ago I found three pretty old Infocenters with security issues which are certainly not the only ones. I informed the operators but nothing has happened so far. For this reason I even waited until today with publishing this post.

To get help-specific preferences you have to open about.html?show=preferences. But this page shows only the basic help configuration. To get a file such as plugin.xml, toc.xml or META-INF/MANIFEST.MF of a specific plug-in you have to open rtopic/plug.in.id/path/to/file, for example:

• rtopic/org.eclipse.linuxtools.gprof.docs/plugin.xml
• rtopic/org.eclipse.core.runtime/META-INF/MANIFEST.MF
• rtopic/org.eclipse.platform/splash.bmp

This was the final episode of the series on five little known things about the Eclipse Infocenter. I hope that you liked it. How many of the well-hidden features did you already know?

1. Basic and Bot Mode
2. Deep Linking
3. Search Links
4. Language Switching
5. Debugging Information

Advertisement

Little Known Things about the Eclipse Infocenter: Language Switching (4/5)

The Eclipse Infocenter is the Eclipse help system launched as a web application. Three of five well-hidden features about the Infocenter have already been presented: Basic and Bot Mode, Deep Linking and Search Links. Here comes little known thing number four: Language Switching.

The Infocenter is multilingual. The Eclipse Babel project provides languages packs for the user interface. When the content is available in different languages it depends on your web browser settings which language will be chosen. The language setting of your web browser can be overruled by appending ?lang=… to the URL. Eclipse Luna Help is in English only, but for example the Infocenter for IBM Rational Team Concert for System z 2.0 is available in French (lang=fr), Spanish (lang=es), Japanese (lang=ja), Korean (lang=ko) and many other languages. It is also possible but rarely used to distinguish between American English (lang=en_US) and British English (lang=en_GB). In IBM’s Infocenter for Content Analytics Version 2.2 you can even switch the user interface language to Arabic (lang=ar) with right-to-left layout:

By the way, to confuse your colleagues you can switch the layout of their non-Arabic Eclipse IDE including help to right-to-left with the runtime option -dir rtl. 😉

Sometimes it make sense to provide only parts of the help content in different languages. For instance, often the user manual is available in several languages, whereas the API documentation is available in English only. But also if the content is not multilingual the chosen (user interface) language affects searching. This is caused by the language-dependent stemming: searching in English for plan without quotes will find topics that contain planning or plans, the same query in Korean does not find these English topics. Infocenter administrators can limit the list of supported user interface languages via the runtime option -locales.

Stay tuned for the last little known thing about the Eclipse Infocenter on my list: Debugging Information!

Little Known Things about the Eclipse Infocenter: Search Links (3/5)

The Eclipse Infocenter is the Eclipse help system launched as a web application. Two of five well-hidden features about the Infocenter have already been presented here. After Basic and Bot Mode and Deep Linking here comes little known thing number three: Search Links.

Search links are queries which can be used for sharing or creating a search input field in or outside the Infocenter. You can search all content, a single book or a single chapter. To search all content you have to append /index.jsp?tab=search&searchWord=… to the base Infocenter address like in  this example of searching for eclipse runtime options within the Eclipse Luna online help. The following HTML snippet creates a search field for Luna help:

    <form action="http://help.eclipse.org/luna/index.jsp"
          method="get" accept-charset="utf-8">
        <input type="hidden" name="tab" value="search">
        <input name="searchWord">
        <input type="submit" value="Search">
    </form>

In order to search within a book you have to use the toc parameter in addition to the tab and searchWord parameters as well as quickSearch=true and
quickSearchType=QuickSearchToc: /index.jsp?tab=search&quickSearch=true&quickSearchType=QuickSearchToc&toc=…&searchWord=… To get the value for the toc parameter, open /basic/searchView.jsp?searchWord=-&scopedSearch=true, select one book, click the Go button and get the value from the scope parameter of the new URL.

A chapter can be specified by the path parameter: /index.jsp?tab=search&quickSearch=true&quickSearchType=QuickSearchToc&toc=…&path=…&searchWord=… The value of tab is a tuple of subchapter indexes starting with 0 separated by underscores. For example path=0_2 refers to the third subchapter of the first top-level chapter of the book specified by the toc parameter.

In addition to the parameters described above you can use the optional parameters maxHits and showSearchCategories. The maxHits parameter specifies the maximal number of results to return and its value ranges between 1 and 500. The user settings Group by Categories can be overridden by showSearchCategories=true or by showSearchCategories=false.

If you do not pass the Turing Test because you are not human you may be interested in the more machine-readable search results in XML. The XML document is available at /search?phrase=… and includes also the scoring. The parameter phrase is equal to the searchWord parameter described above. The maximal number of results is limited to 1,000 (maxHits is not supported). The XML search results can be easily used in scripts. For example, this little Ant script finds common misspellings by querying for each item of Wikipedia’s list of common misspellings. It finds 131 typos in the current Luna help with only a very low false positive rate.

The next little known things about the Eclipse Infocenter on my list are Language Switching and Debugging Information. Stay tuned!

Little Known Things about the Eclipse Infocenter: Deep Linking (2/5)

The Eclipse Infocenter is the Eclipse help system launched as a stand-alone web application. Five well-hidden features about the Infocenter will be presented one after the other here. Basic and Bot Mode have already been presented and here comes the second little known thing: deep linking.

The Infocenter does not yet support deep linking: When you browse inside the Infocenter the URL does not change. If you want to bookmark a topic you will have to copy the topic link via right-click menu from the table of contents, paste the link into the address bar and bookmark this URL.

VMware has already implemented deep linking without contributing it back to Eclipse. This is not the only adaption VMware made. Unfortunately, one of these additional adaptions does not work with Internet Explorer 8 (in contrast to Firefox, Google Chrome and Internet Explorer 11), so that the table of contents does not show up. There are no such problems with the plain Eclipse Infocenter. This is why contributing back makes sense. 😉

However, deep linking has not yet been implemented in the plain Eclipse Infocenter and you have to copy manually the link from the table of contents. This link is redirected to the version with HTML frames. If you want to see the topic framelessly without the table of contents, search field, etc. you will have to append ?noframes=true to the link. Alternatively, in the URL you could replace /topic/ with /nftopic/ or – if you want to have the navigation breadcrumb at the top – with /ntopic/.

With the resultof parameter you can highlight text. The topic is automatically scrolled to the first hit. This can be used to link to a specific section inside a topic. For example, if you want to link to the “Dark theme” inside the “What’s New in Luna” topic you will have to append ?resultof=”Dark theme” to the link. The phrase to be highlighted has to be enclosed in parentheses. Two or more phrases have to be concatenated without delimiters as you can see in the following example:

To combine both frames and highlighting is a little bit tricky. First you have to open the topic link which redirects you to index.jsp?topic=…; then you have to append ?resultof=… to the redirected URL. The ?topic=…?resultof=… instead of ?topic=…&resultof=… is probably a work-a-round for an error waiting to be fixed. 😉

The next little known things about the Eclipse Infocenter on my list are Search Links, Language Switching and Debugging Information. Stay tuned!

Little Known Things about the Eclipse Infocenter: Basic and Bot Mode (1/5)

The Eclipse help system can also be launched as a stand-alone web application, the so-called Infocenter. The Eclipse Infocenter is widely used by several companies and organizations, with and without adaptions. Although many of you will be familiar with help.eclipse.org or one of these websites, hardly anyone will know all of the five well-hidden features of the Infocenter that might be useful to you. They will be presented individually here. And here comes number one: the basic and the bot mode.

When you visit the Infocenter with a very, very, very old web browser such as the Internet Explorer 5.5 or Netscape Navigator 4.8 the website looks different than with any web browser that was released in the last twelve years. This so-called basic mode (in contrast to the advanced mode for current browsers) exists mainly because these old browsers do not support JavaScript callbacks. For instance, if you click on a book in the table of contents, the table of contents HTML frame will be replaced by a new HTML page in which the whole subtree of the clicked book is expanded. This is realized simply by HTML links. In the normal advanced mode the chapters of the next level are asynchronously loaded via JavaScript without leaving the page.

The basic mode can also be useful with a current browser. For example, if you need the whole table of contents of a book then it can be easily extracted (and copied) from /basic/tocView.jsp. This saves you manually expanding every individual chapter.

In the Infocenter, the browser detection to switch between basic and advanced mode is done via the User-Agent HTTP header field. The User-Agent field is also used to present the website without HTML frames to web crawlers in a third mode, the bot mode. For the Google Search Bot the Luna Help with its 17,875 topics looks like this:

The next little known things about the Eclipse Infocenter on my list are Deep Linking, Search Links, Language Switching and Debugging Information. Stay tuned!

Eclipse Infocenters in the Wild

Apart from help.eclipse.org for Luna and previous simultaneous releases Eclipse offers its Infocenter for Orion:

In the wild the Infocenter is used for instance by Tasktop without modification except an additional header…

… or by Freescale and by bada Developers:

I like the red style of Wolfram. Even the icons have been adapted:

ARM has made functional changes to the Infocenter. With the menu to the left of the search box you can select where to search, e. g. within the title only or in the whole document. Interestingly, some icons have been removed: there is no Print/Search Topic (and its Subtopics) icon and no Link with Contents icon in the Contents toolbar; no Group by Categories and no number of matches in Search Results.

Sybase also made some search modifications. The drop-down menu right of the search field makes it easier to switch between search scopes that have been created. The flashlight symbol of the search icon to search a topic (and its subtopics) has been replaced with a magnifying glass.

The Infocenter of VMware is hardly recognizable as such. The tabs are shown at the top instead of at the bottom. Maybe because today common web browsers do not have a status line and show the target of a link while hovering it in the left bottom corner which hides bottom tabs.

IBM, the company which has done most of the development work for Eclipse’s Infocenter, added a Collaboration tab to show hot topics and – if logged in – the user’s own comments. There is also a frame below the topic frame for topic-specific comments.

IBM has begun to replace this and other Infocenter instances with its new Knowledge Center. I guess but I don’t know that it is still based on Eclipse Infocenter. It does not use HTML framesets but an iframe for the topic. The search field is wider and the search scope follows automatically the selected book which covers a product.

Most of the modifications described above are about searching. Please drop a comment if you have come across an Infocenter with other modifications. If you like a modification then report it to Eclipse, or even better, implement it and contribute it to Eclipse and watch them reintroduce it into the wild.

Like to pimp your help, eh?

Assuming you have help content and it comprises more than a couple of sentences, your users will explore it by searching the whole content or by following hyperlink by hyperlink, digging deeper level by level into the table of contents. In Eclipse Help it is also possible to search only part of the content by defining a scope or by selecting a topic and searching its subtopics. But this is rarely used because it is cumbersome. Also the wildcards ‘*’, ‘?’ and the boolean operators NOT and OR are rarely used. Just like with Google or DuckDuckGo people tend to search for keywords only.

Autocomplete, instant search and more

To make searching easier I developed for Advantest a small JavaScript which Advantest made Open Source. It is used to pimp the Advantest SOC help cover page by a search field with autocomplete, instant search (= search results are shown as you type), book selector drop-down menu and input assistance for complex queries.

Try it!

The Advantest SOC help is for customers only, but you can see the JavaScript eh.js (uncompressed, compressed) in action at the Eclipse Luna Help demo page which I have created. Because in JavaScript cross-domain callbacks (which are required for the instant search) are forbidden, this sample page misuses a proxy which makes it slower than when integrated into your help. To see the content of a topic by hovering a search result you have to allow insecure content: click the shield icon in the address bar:

Get inspired

eh.js can also be used for searching a particular part such as a book or a chapter: Place the mouse over a TOC item link to display a search field for this topic and its subtopics only. Eclipse Luna Help contains 66 books and probably you do not want to get your search results flooded by hits in all of them. Or maybe you will use eh.js as a starting point to develop a complete new user interface for the good old Eclipse Help. What should it look like?

Helpful API or Speedy Lucene 2.9

(Based on an illustration from 1936)

Since 3.3 (June 2007) Eclipse has contained Apache Lucene 1.9.1, which was released in March 2006 as the search framework for the help system. Unfortunately, org.eclipse.help.base makes it impossible to update to Lucene 2.x or 3.x without breaking the API by reexporting Lucene packages and by exposing Lucene classes in an extension point. Nevertheless, in Eclipse 3.7 M3 Lucene 1.9.1 has been replaced by 2.9.1. What are the benefits? Was it worth to break the API? What do you have to know when you deliver help content?

Cheating with Prebuilt Indexes

On my two year old laptop with Eclipse Classic 3.6.1 it takes about 4 seconds to get the search results of the very first query. The major part of these 4 seconds contains the merging of the prebuilt indexes that are contained in the 5 documentation plug-ins (plugins/*.doc.*.jar) into one and storing it in the configuration area for later queries. Without these prebuilt indexes I would have to wait more than 30 seconds for the first search results. Even though this happens only once per installation, a 30-second wait is too long and this is the reason why Eclipse provides the feature of shipping help content with a prebuilt index.

While merging prebuilt indexes the progress bar shows 0%

Faster Indexing

To my surprise, in Eclipse 3.7 M3 with Lucene 2.9.1 the first query takes about 7 instead of 4 seconds. Is Eclipse Help with Lucene 2.9.1 slower than with Lucene 1.9.1? No, it isn’t. Because the version of Lucene which with the index is created must match the runtime version and because Eclipse 3.7 M3 is – probably by mistake – still shipped with Lucene 1.9.1 indexes, the prebuilt indexes are ignored. So it takes only about 7 instead of 30 seconds to create the index from scratch. Due to the Apache Lucene improvements creating an index is now more than 3 times faster than with the 5 years old Lucene 1.9.1. Without the prebuilt indexes the Eclipse Classic download size would be 2.6 MB smaller but the first query would take about 7 seconds (with Eclipse 3.6 and Lucene 1.9.1 more than 30 seconds) instead of 3 or 4 seconds with prebuilt indexes.

Testing the Limits

I also tested this with three huge help plug-ins: about 470 MB total size, more than 15,000 HTML files, and prebuilt indexes with a total size of about 20 MB. In Eclipse 3.6 (with Lucene 1.9.1) it takes about 10 seconds with and about 4.5 minutes without prebuilt indexes in contrast to Eclipse 3.7 M3 (Lucene 2.9.1) with only about less than 2 minutes without and about 8 seconds with prebuilt indexes.

Help Content for Eclipse 3.6 and 3.7

As plug-in developer you may want to support different versions of Eclipse. Especially if you have a huge help plug-in you should ship the content with both, Lucene 1.9.1 and 2.9.1, indexes. In contrast to the documentation it seems to be possible to register more than one index. Eclipse ignores indexes which were prebuilt with a different than the runtime version of Lucene. Of course, a plug-in that contains multiple indexes is always lager than a plug-in with only one or without an index but waiting too long for the search results will bother users and make some users stop using the help.

My 2.9 cents

Now, that the underlying search framework is so extremely fast, I think it would make sense not to merge the prebuilt search indexes into one anymore but to use the prebuilt indexes directly and merge the search result of all prebuilt indexes instead.

Why not increase the major version number of the org.eclipse.help.base bundle instead of sticking to 3.x only because the version number of the Eclipse distribution is 3.x which is a marketing and not a OSGi version number? Now it is possible to install bundles that require the Eclipse help bundle 3.x and that may fail at runtime. I would prefer the installation of such bundles being rejected. I think the OSGi versioning is helpful and we should not cheat it. In my view, developing a large framework like Eclipse in small steps with some (e.g. 2 or 3 years) backwards compatibility is still one of the biggest challenges in software development that has not yet been met.