added documentation

3 files changed, 67 insertions, 27 deletions

diff --git a/examples/org.eclipse.compare.examples/doc-html/ui_structurecreator_ex.html b/examples/org.eclipse.compare.examples/doc-html/ui_structurecreator_ex.html
index 61ed4bdc0..303c9a339 100644
--- a/examples/org.eclipse.compare.examples/doc-html/ui_structurecreator_ex.html
+++ b/examples/org.eclipse.compare.examples/doc-html/ui_structurecreator_ex.html
@@ -8,35 +8,75 @@
 
 <h2>Compare Example - Structural Compare for Key/Value Pairs</h2>
 
+<h3>Introduction</h3>
+
+This example demonstrates how to support structural compare for
+files consisting of key/value pairs. It shows how to implement and register a
+custom structure creator that parses key/value pairs into a tree structure
+that is used as the input to the structural compare framework provided by the
+Compare plugin. In addition, it registers a standard text viewer for the individual
+key/value pairs.
+
 <p>
-The Structural Compare Example demonstrates how to register an custom structure creator
-for a file exe
-for 
 
-The Java Editor example demonstrates the standard features available for custom text editors.
-It also shows howÊto register an editor for a file extension (in this case .jav) and how to
-define a custom Document provider for use by that editor.
-This example is only for demonstration purposes. Java editing support is provided by theÊEclipse Java Tooling. 
+This example is only for demonstration purposes. Structural compare support
+for Java property files (another key/value format) is provided by the Eclipse Java Tooling. 
 
+<h3> Running the example</h3>
 
-The File Viewer example shows how a simple application can be implemented using SWT.
-This application provides the ability to navigate files and folders and manipulate them via Drag and Drop.
-It includes the use of alternate threads for long actions and demonstrates the use of the Tree,
-Table, Toolbar and Program.
-</p>
+<ol>
+	<li>Create a project (not necessarily a Java project)</li>
+	
+	<li>Create a key/value pair file f1.kv</li>
+	
+	<li>Open <strong>Window</strong> &gt; <strong>Preferences</strong> &gt; <strong>Workbench</strong> &gt; <strong>File Association</strong>
+	and associate the default text editor with the file extension "kv"</li>
+	
+	<li>Open f1.kv with the editor and enter this contents
+	<pre>
+lastname=Doe
+firstname=John
+city=Chicago
+state=IL
+</pre></li>
+	
+	<li>Make a copy of this file and rename it f2.kv</li>
+	
+	<li>Open f2.kv and change the firstname "John" to "Mary"</li>
+
+	<li>Add another key/value pair "country=US" to f2.kv</li>
+	
+	<li>Select both files f1.kv and f2.kv</li>
+	
+	<li>From the context menu select <strong>Compare With<strong> &gt; <strong>Each Other</strong></li>
+	
+	<li>A new compare editor opens that shows the structural differences of both files in its
+	top pane. Selecting one of the properties "firstname" or "country" feeds the text of the
+	corresponding key/value pair into the standard text compare viewer in the bottom pane.
+	</li>
+	
+</ol>
+
+<h3>Code organization of the example</h3>
+The example code is organized in a single package <tt>org.eclipse.compare.examples.structurecreator</tt>:
+
+<ul>
+	<li><tt>KeyValuePairStructureCreator</tt><br>
+	is the structure creator that parses the contents of a stream into a tree of
+	<tt>IStructureComparator</tt>s.
+	</li>
+	
+	<li><tt>TextMergeViewerCreator</tt><br>
+	is a factory for TextMergeViewers. It is registered for the type "kvtxt" which is the
+	type of an individual key/value pair.
+	</li>
+	
+	<li><tt>Util</tt><br>
+	provides utility methods for NLS support and for reading an InputStream as a String.
+	</li>
+	
+</ul>
 
-<h3>Running the example</h3>
-<p>
-Follow the <a href="swt_manual_setup.html">Manual Setup</a> 
-instructions to install and run the example from your workspace.
-</p>
-<p>
-The "Main" class is <code>org.eclipse.swt.examples.fileviewer.FileViewer</code>.
-</p>
-<p>
-This example can also be run using the <a href="swt_launcher_ex.html">Example Launcher</a>.
-Select the File Viewer item from the Standalone category and click Run.
-</p>
 
 <p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corporation and others 2000, 2003. All Rights Reserved." BORDER=0 height=14 width=324></a></p>
 </body>
diff --git a/examples/org.eclipse.compare.examples/plugin.xml b/examples/org.eclipse.compare.examples/plugin.xml
index 970875eda..c6f1ef661 100644
--- a/examples/org.eclipse.compare.examples/plugin.xml
+++ b/examples/org.eclipse.compare.examples/plugin.xml
@@ -28,7 +28,7 @@
 <extension
 	point="org.eclipse.compare.contentMergeViewers">
 	<viewer
-		extensions="kv"
+		extensions="kvtxt"
 		class="org.eclipse.compare.examples.structurecreator.TextMergeViewerCreator">
 	</viewer>
 </extension>
diff --git a/examples/org.eclipse.compare.examples/src/org/eclipse/compare/examples/structurecreator/KeyValuePairStructureCreator.java b/examples/org.eclipse.compare.examples/src/org/eclipse/compare/examples/structurecreator/KeyValuePairStructureCreator.java
index 657b5d28b..8d1b2188b 100644
--- a/examples/org.eclipse.compare.examples/src/org/eclipse/compare/examples/structurecreator/KeyValuePairStructureCreator.java
+++ b/examples/org.eclipse.compare.examples/src/org/eclipse/compare/examples/structurecreator/KeyValuePairStructureCreator.java
@@ -56,11 +56,11 @@ public class KeyValuePairStructureCreator implements IStructureCreator {
 		}
 
 		/**
-		 * Every key/value pair is of type "txt" so that the builtin TextMergeViewer is used automatically.
+		 * Every key/value pair is of type "kvtxt". We register a TextMergeViewer for it. 
 		 * @see ITypedElement#getType
 		 */
 		public String getType() {
-			return "txt"; //$NON-NLS-1$
+			return "kvtxt"; //$NON-NLS-1$
 		}
 		
 		/**