ProvidePluginDocs

How to make your plug-in's documentation available to users from within Protege

In Protege versions 2.1 and higher, we added the ability for plug-in authors to provide "About Box" and documentation information for users via Protege's Help menu. We highly recommend (but do not require) plug-in authors to take advantage of this functionality. Instructions for doing so are provided throughout this article.

To follow is a screen shot of the "About Plugins" dialog, launched by clicking the Help -> About Plugins... menu item. The list of plug-ins in the "Installed Plugins" pane are those plug-ins that specify About Box information. The "about" information is provided by plug-in authors in the form of an HTML file.

Note that "about" information is displayed within a frame in Protege, but if you provide any clickable links on this page, they will launch in the user's default browser.

If a plug-in author specifies documentation information for a plug-in, the name of the plug-in will appear when users click the Help -> Plugins menu item. When a user clicks on a particular plug-in name in the menu, documentation for the plug-in will launch in the user's default browser. As with "about" information, documentation must be provided in HTML format. If your documentation is not written in HTML, a possible option is to provide a simple HTML page, which has additional instructions for accessing your plug-in's documentation.

Plug-in authors must specify the location of About Box and documentation HTML files in the plugin.properties file. The plugin.properties file is a is a text file in which plug-in authors can:

• declare dependencies on other plug-ins
• specify "About Box" information
• specify the location of documentation

This file resides in the root directory for your plug-in. This Wiki article only describes the syntax for specifying the location of About Box and documentation information. If you also need to declare a plug-in as dependent on other plug-ins, please see the Wiki article entitled "Instructions for declaring dependencies between Protege plug-ins".

Below is an example of the proper syntax for specifying the location of a plug-in's documentation. This snippet was taken from the DataMaster Tab's plugin.properties file.

plugin.component.count=1
plugin.component.name.0=DataMaster Tab
plugin.component.about.0=about-datamaster.html
plugin.component.doc.0=about-datamaster.html
...

These few lines indicate that both About Box and documentation are provided in the root directory for the DataMaster plug-in. To take a closer look at this example, open the <protege-install-dir>/plugins/edu.stanford.smi.protegex.datamaster directory (if you happen to have Protege installed).

Here is another snippet from the plugin.properties file for the PAL Tabs plug-in:

plugin.component.count=1
plugin.component.name.0=PAL Tabs
plugin.component.about.0=about_pal_tabs.html
plugin.component.doc.0=http://protege.stanford.edu/plugins/paltabs/pal-documentation/index.htm

A final example demonstrates the syntax for the situation where multiple plug-ins reside in the same directory. This is the plugin.properties file for the Standard Extensions plug-in. Note that this plug-in only provides documentation information, but not "about" information.

plugin.component.count=2
plugin.component.name.0=Graph Widget
plugin.component.doc.0=http://protege.stanford.edu/doc/tutorial/graph_widget
plugin.component.name.1=Table Widget
plugin.component.doc.1=http://protege.stanford.edu/doc/tutorial/tables

Many existing Protege plug-ins have provided About Box and documentation information. To see examples of these simple HTML files, browse to your Protege installation and examine the contents of the plugins subdirectory. These sorts of HTML files should not be difficult to create or maintain, which is why (as mentioned above) we encourage plug-in authors to provide them. It can be a much better experience for an end user of your plug-in if he/she is able to launch help documentation directly from Protege's user interface.

See Also: Instructions for declaring dependencies between Protege plug-ins