The SHOE Knowledge Annotator

Introduction

The Knowledge Annotator is a Java program that allows users to mark-up web pages with SHOE knowledge without having to worry about the HTML-like codes. The Annotator is available as an applet or a stand-alone Java application. The button below allows you to start the applet version so that you can get the look and feel of the program. See below for information on obtaining the application version. We suggest that you read the short tutorial below before you start the Annotator.

Knowledge Annotator Applet

A note on the Knowledge Annotator Applet:

• The Annotator is still under development. As such, it is subject to change at any time. If you find any bugs or have suggestions for improvement, send e-mail to Jeff Heflin.

Help! The applet doesn't run correctly on my machine!

Downloading the Knowledge Annotator

Version 0.93 of the Knowledge Annotator, made available November 9, 2000 is available in both ZIP and Gzipped tar formats. Choose which version you wish to download by clicking on one of the items below:

• Download ZIP version (KA.zip)
• Download Gzipped tar version (KA.tar.gz)

You can also download the Knowledge Annotator source code, see the Downloads page for details.

Applet Tutorial

Press the button above. After a short wait, the Knowledge Annotator window will appear. This window has three panels: Instances, Use Ontologies and Claims. Initially these three panels are empty.

Opening a URL

First, you must open a Web page that has been SHOE annotated. To do this, select File-Open URL from the menu bar. A dialog box will appear that requests you to specify a URL. Many of the PLUS group sites have SHOE markup. We suggest that you look at http://www.cs.umd.edu/projects/plus/SHOE/ or http://www.cs.umd.edu/users/heflin/ (a list of some other SHOE pages is here). After you type in a URL of your choice, press the OK button. At least one item will appear in the instance list.

Working with Instances

To view the information associated with an instance, click on it. Assuming the instance has been fully annotated, you should see entries in the Use Ontology and Claims lists. The three buttons below the Instances list are used to modify instances for the current document.

To create a new instance, press the Add button, or select Add from the Instance menu. A dialog box will appear. You must enter the instance's key in the "Key:" field. Usually, this key is a valid URL. The "Delegate-To:" field is an advanced feature and can be left blank. Read the SHOE Specification for details on this field. The "Name:" field allows to optionally assign a name to the instance. If you press the "Using Title" button, the field will be filled by the title of the page (taken from the >TITLE> tag). Press OK if you are satisfied with your entries, or press Cancel to abort.

To edit an instance, select it and then press the Edit button. A dialog that looks like the one from Create will appear, but this time some of the fields will already be filled in. Change them as desired, and then press OK.

To delete an instance, select it and then press the Delete button. The instance will be removed from the list and the document. Likewise, any claims made by that instance will be removed. This procedure cannot be undone (without reloading the file), so use it carefully.

Working with Use Ontologies

Use Ontologies specify the frame of reference for an instance. An instance must use at least one ontology, and can use more if necessary. Without a Use Ontology, an instance has no pool of valid categories and relations from which to base claims on. Unless an instance has been selected, all of the buttons associated with Use Ontologies will be disabled. The Add, Edit, and Delete buttons work like those for Instances. To Edit or Delete a Use Ontology, it must be selected before you press the button. The Use Ontologies window has two lists and four fields. The first list called "Known Ontologies" displays all ontologies that have been seen in this session. This is useful if you are annotating many documents that are in the same domain. Selecting an ontology from this list will automatically fill in the "Id:", "Version:", and "URL:" fields. Note, that if you have just started the Annotator and are working with a brand new document, this list will be empty. The second list is titled "Elements:". When you select an ontology from the first list, this list displays all of the elements of that ontology. This list is only intended to be an aid in determining if an ontology contains elements that might be useful to you; selecting an item from the list has no effect. The "Id:" is the name of an ontology, "Version:" is the version number, "Prefix:" is a short sequence of characters that is placed before a category or relation to indicate that it is defined in this ontology and "URL:" is the location where the ontology can be found. Of these fields, only the URL is optional, but until there becomes a standard database of common SHOE ontologies, we highly recommend that you always specify it.

Working with Claims

A claim is statement made by an instance. Instances can make claims about themselves or other instances. There are two types of claims: Categories and Relations. Instances can be assigned categories to say that they have something in common with other instances of the same category. Relations are used to describe properties of instances or to state that they are related to other instances. Each relations has two or more arguments, where each argument is a property or another instance.

In the Claims window, all of the claims are organized by the subject of the claim. Technically, the subject is either the instance of a category or the first argument of a relation. Subjects will be flushed left in the list and will be display as name (key = "key-value"). Each claim will be indented beneath its subject and consists of a phrase followed by one or more arguments. Categories start with the phrase "is-a", while relations start with the phrase that best describes them.

Claims have the same set of buttons as the other two lists, and these buttons have the same functionality. The Add and Edit buttons bring up the Claim Window. This window contains a "Use Ontologies" list, an "Elements" list, a "Filter" selector, a "Type" selector, three text fields, and the OK, Cancel and New buttons. The "Type:" field is used to select whether you will add a Category or a Relation. In Add mode, selecting this will change the look of the window. However, it is disabled in Edit mode. To identify which ontology your new claim will be based on, use either the "Use Ontologies" list or the "Prefix" field. If you select from the list, the appropriate prefix will be filled in for you. Next, choose a category or relation from the "Elements:" list. This list will display all of a given type that appear in the selected ontology. When an item is selected, the "Name:" field will be automatically filled in with this value. The next step depends on whether you are adding a category or a relation. If you are adding a category, then you can use the "For:" field to enter the instance which is being categorized. If left blank, this is assumed to be the containing instance. If you are adding a relation, you will have to enter the arguments. The required type of each argument is displayed to its left. If you want any argument to refer to the instance making the claims, then simply type ME. If this is the only claim you are adding, press OK to save your changes and close the winodw. If you wish to add another claim, press New to save your changes but leave the window open. Press Cancel to close the window without saving.

You can save yourself some work by selecting an item in the Claim List before pressing Add. If you select a relation, that relation will be the default, and the first argument will default to the subject. Additionally, the "Elements:" list will be filtered to show only relations in which the subject can play a role (based on the category of the subject). If a category was selected from the Claim List, then the subject will be the default value in the "For:" field of the window.

Views

The View menu allows you to look at different views of your document. To see how SHOE changes the HTML for a Web page, select "View-Source HTML" from the menu. This will display the HTML for the page, including any SHOE tags. If you change or add SHOE to a document, use this option to see the new or changed SHOE tags. You can also use this option to copy the HTML and paste it into a new file. To go back to the screen which allows you to edit things, select "View-Claim Phrases" from the menu. A slight variation of this is the "View-Claim Predicates" in which claims are displayed in a function-like notation, instead of as short English phrases. The "Summary" view displays a compact summary of the SHOE Knowledge in the document in a single pane. You can copy this text into a file for printing or other reference.

If You Have Problems Running the Applet...

Many common problems with the Knowledge Annotator are discussed in the FAQ. This applet should run on any broswer with a correct implementation of Java 1.0. Unfortunately, most browsers have their own unique bugs in their implementations. If you seem to be having browser specific problems, here are some things to try...

• If you have the appletviewer program avaiable from Sun (as part of the JDK), type appletviewer http://www.cs.umd.edu/projects/plus/SHOE/KnowledgeAnnotator.html at the command prompt.
• Try upgrading to the latest version of your browser
• Try using a different browser (see our table below)
• Download the annotator and run it as an application.

The table below lists the applet's compatability with various browsers and platforms that we have tested it on. If you have tried it in a different environment, please let us know how it works.

Knowledge Annotator Applet Compatability with Common Browsers

OS	Browser	Results
Windows 95, NT	Netscape 3.0+	No problems detected
Windows 95, NT	IE Explorer 4.0	No problems detected
Mac OS	IE Explorer 4.0	Scrollbars do not work
Mac OS	Netscape 4.0+	Slow performance, bizarre flickering
Mac OS	Netscape 3.0	Applet won't run
SunOS	Netscape 4.0+	No problems detected
SunOS	Netscape 3.0	Unstable

Using the Annotator Offline

Often, it is convenient to work with the Annotator when one does not have a connection to the Internet. However, the Annotator uses the Net to retrieve the ontologies that it uses to help format and validate your SHOE pages. Fortunately, you can make local copies of all relevant ontologies. To let the Annotator know where these files are, you need to create an ASCII text file called ontproxy.dat. We recommend that you use a text editor to create this file, but you can use a word processor if you save the results as ASCII text. The format of the file is as follows: each line consists of 3 tab-delimited fields, where the fields are ontology-id, ontology-version, and preferredURL (this is the new URL where the system should look for the ontology). You can use the file protocol to specify files stored locally (e.g., file:/onts/cs.html) or the HTTP protocol to specify a mirror site (e.g., http://ont.mirror.org/cs.html).

In UNIX, if your ontologies are stored locally in a directory called onts, the ontproxy.dat file might look like this:

base-ontology   1.0     file:/onts/base.html
cs-dept-ontology        1.0     file:/onts/cs.html

If instead you are using a MS Windows operating system, see the example below. Don't forget to specify the drive letter in file URLs, pay close attention to the three slashes before the drive letter, and notice that forward slashes are used as separators (instead of the usual backslash in Windows):

base-ontology   1.0     file:///c:/onts/base.html
cs-dept-ontology        1.0     file:///c:/onts/cs.html

After you have created the ontproxy.dat file, place it in the same directory that you issue the "java Annotator.KA_App" or "jre Annotator.KA_App" commands from.