165168 [Help] Better control of how help content is arranged and ordered

11 files changed, 538 insertions, 29 deletions

diff --git a/org.eclipse.help/schema/helpData.exsd b/org.eclipse.help/schema/helpData.exsd
new file mode 100644
index 000000000..c3a3f44c5
--- /dev/null
+++ b/org.eclipse.help/schema/helpData.exsd
@@ -0,0 +1,195 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- Schema file written by PDE -->
+<schema targetNamespace="Help data XML format">
+<annotation>
+      <appInfo>
+         <meta.schema plugin="Help data XML format" id="" name="Help data XML format"/>
+      </appInfo>
+      <documentation>
+         The help data XML file is used by products to control the order of books in the help table of contents, as well whether or not books or keyword index sets should be displayed at all. The file must be referenced in the product&apos;s &lt;code&gt;plugin_customization.ini&lt;/code&gt; file using the &lt;code&gt;org.eclipse.help/HELP_DATA&lt;/code&gt; property.
+      </documentation>
+   </annotation>
+
+   <element name="extensions">
+      <annotation>
+         <documentation>
+            The extension data for Help.
+         </documentation>
+      </annotation>
+      <complexType>
+         <sequence>
+            <element ref="tocOrder" minOccurs="0" maxOccurs="1"/>
+            <element ref="hidden" minOccurs="0" maxOccurs="1"/>
+         </sequence>
+      </complexType>
+   </element>
+
+   <element name="tocOrder">
+      <annotation>
+         <documentation>
+            Specifies the order in which top-level table of contents entries (also called &quot;books&quot;) or categories of books should appear in Help. If one of the items listed is not available, it is ignored. If there are items available that are not listed and not hidden, they will be displayed after the ones listed here.
+         </documentation>
+      </annotation>
+      <complexType>
+         <choice minOccurs="0" maxOccurs="unbounded">
+            <element ref="toc"/>
+            <element ref="category"/>
+         </choice>
+      </complexType>
+   </element>
+
+   <element name="toc">
+      <annotation>
+         <documentation>
+            A reference to a top-level table of contents (TOC) entry, also called a &quot;book&quot;.
+         </documentation>
+      </annotation>
+      <complexType>
+         <attribute name="id" type="string" use="required">
+            <annotation>
+               <documentation>
+                  The unique identifier for this book. For XML file TOC contributions, this is a path to the file in the form &quot;&lt;code&gt;/&amp;lt;plugin_id&amp;gt;/&amp;lt;path&amp;gt;/&amp;lt;file&amp;gt;&lt;/code&gt;&quot; (e.g., &quot;&lt;code&gt;/org.eclipse.platform.doc.user/toc.xml&lt;/code&gt;&quot;). In general, this is the ID of the &lt;code&gt;TocContribution&lt;/code&gt; supplied by its originating &lt;code&gt;AbstractTocProvider&lt;/code&gt;.
+               </documentation>
+            </annotation>
+         </attribute>
+      </complexType>
+   </element>
+
+   <element name="category">
+      <annotation>
+         <documentation>
+            A reference to a category of top-level table of contents (TOC) entries (books). Categories are implicitly created when a table of contents contribution declares itself to be of that category, for example, by specifying a &lt;code&gt;category&lt;/code&gt; attribute for the &lt;code&gt;toc&lt;/code&gt; element in the &lt;code&gt;org.eclipse.help.toc&lt;/code&gt; extension point.
+         </documentation>
+      </annotation>
+      <complexType>
+         <attribute name="id" type="string" use="required">
+            <annotation>
+               <documentation>
+                  The unique id of the category.
+               </documentation>
+            </annotation>
+         </attribute>
+      </complexType>
+   </element>
+
+   <element name="hidden">
+      <annotation>
+         <documentation>
+            Contains a set of help items that should be hidden from the user.
+         </documentation>
+      </annotation>
+      <complexType>
+         <choice minOccurs="0" maxOccurs="unbounded">
+            <element ref="toc"/>
+            <element ref="category"/>
+            <element ref="index"/>
+         </choice>
+      </complexType>
+   </element>
+
+   <element name="index">
+      <annotation>
+         <documentation>
+            A reference to a contribution of help index keywords.
+         </documentation>
+      </annotation>
+      <complexType>
+         <attribute name="id" type="string" use="required">
+            <annotation>
+               <documentation>
+                  The unique identifier for this contribution of keywords. For XML file index contributions, this is a path to the file in the form &quot;&lt;code&gt;/&amp;lt;plugin_id&amp;gt;/&amp;lt;path&amp;gt;/&amp;lt;file&amp;gt;&lt;/code&gt;&quot; (e.g., &quot;&lt;code&gt;/org.eclipse.platform.doc.user/index.xml&lt;/code&gt;&quot;). In general, this is the ID of the &lt;code&gt;IndexContribution&lt;/code&gt; supplied by its originating &lt;code&gt;AbstractIndexProvider&lt;/code&gt;.
+               </documentation>
+            </annotation>
+         </attribute>
+      </complexType>
+   </element>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="since"/>
+      </appInfo>
+      <documentation>
+         3.3
+      </documentation>
+   </annotation>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="examples"/>
+      </appInfo>
+      <documentation>
+         &lt;p&gt;
+The following example shows how to arrange the following books in the order shown:
+&lt;/p&gt;
+
+&lt;ul&gt;
+&lt;li&gt;Book #1: &quot;Introduction to XYZ&quot; (category: &quot;&lt;code&gt;user.intro&lt;/code&gt;&quot;) in &lt;code&gt;/com.xyz.doc.user/introToc.xml&lt;/code&gt;&lt;/li&gt;
+&lt;li&gt;Book #2: &quot;Using XYZ&quot; (category: &quot;&lt;code&gt;user.content&lt;/code&gt;&quot;) in &lt;code&gt;/com.xyz.doc.user/usingToc.xml&lt;/code&gt;&lt;/li&gt;
+&lt;li&gt;Book #3: &quot;Troubleshooting&quot; (category: &quot;&lt;code&gt;user.reference&lt;/code&gt;&quot;) in &lt;code&gt;/com.xyz.doc.user/refToc.xml&lt;/code&gt;&lt;/li&gt;
+&lt;/ul&gt;
+
+&lt;p&gt;
+As well as hide the following books/categories and related keyword indexes:
+&lt;/p&gt;
+
+&lt;ul&gt;
+&lt;li&gt;Book #4: &quot;Platform ABC&quot; (category: &lt;code&gt;none&lt;/code&gt;) in &lt;code&gt;/org.abc.doc.isv/toc.xml&lt;/code&gt;&lt;/li&gt;
+&lt;li&gt;Book #5: &quot;DEF Toolkit&quot; (category: &quot;&lt;code&gt;isv.reference&lt;/code&gt;&quot;) in &lt;code&gt;/com.def.doc.isv/toc.xml&lt;/code&gt;&lt;/li&gt;
+&lt;li&gt;Book #6: &quot;GHI Support&quot; (category: &quot;&lt;code&gt;isv.reference&lt;/code&gt;&quot;) in &lt;code&gt;/com.ghi.doc.isv/toc.xml&lt;/code&gt;&lt;/li&gt;
+&lt;/ul&gt;
+
+&lt;p&gt;
+The markup would be the following:
+&lt;/p&gt;
+
+&lt;p&gt;
+&lt;pre&gt;
+&lt;extensions&gt;
+   &lt;tocOrder&gt;
+      &lt;toc id=&quot;/com.xyz.doc.user/introToc.xml&quot;/&gt;
+      &lt;category id=&quot;user.content&quot;/&gt;
+      &lt;toc id=&quot;/com.xyz.doc.user/refToc.xml&quot;/&gt;
+   &lt;/tocOrder&gt;
+   &lt;hidden&gt;
+      &lt;toc id=&quot;/org.abc.doc.isv/toc.xml&quot;/&gt;
+      &lt;category id=&quot;isv.reference&quot;/&gt;
+      &lt;index id=&quot;/org.abc.doc.isv/index.xml&quot;/&gt;
+      &lt;index id=&quot;/com.def.doc.isv/index.xml&quot;/&gt;
+   &lt;/hidden&gt;
+&lt;/extensions&gt;
+&lt;/pre&gt;
+&lt;/p&gt;
+      </documentation>
+   </annotation>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="apiInfo"/>
+      </appInfo>
+      <documentation>
+         
+      </documentation>
+   </annotation>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="implementation"/>
+      </appInfo>
+      <documentation>
+         This API is supported by any help implementation that is based on &lt;code&gt;org.eclipse.help&lt;/code&gt;, including the default help implementation provided by Eclipse.
+      </documentation>
+   </annotation>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="copyright"/>
+      </appInfo>
+      <documentation>
+         Copyright (c) 2006 IBM Corporation and others.&lt;br&gt;
+All rights reserved. This program and the accompanying materials are made 
+available under the terms of the Eclipse Public License v1.0 which accompanies 
+this distribution, and is available at &lt;a href=&quot;http://www.eclipse.org/legal/epl-v10.html&quot;&gt;http://www.eclipse.org/legal/epl-v10.html&lt;/a&gt;
+      </documentation>
+   </annotation>
+
+</schema>
diff --git a/org.eclipse.help/src/org/eclipse/help/internal/HelpData.java b/org.eclipse.help/src/org/eclipse/help/internal/HelpData.java
new file mode 100644
index 000000000..ff4dbc6ef
--- /dev/null
+++ b/org.eclipse.help/src/org/eclipse/help/internal/HelpData.java
@@ -0,0 +1,187 @@
+/*******************************************************************************
+ * Copyright (c) 2006 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.help.internal;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.StringReader;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import javax.xml.parsers.SAXParser;
+import javax.xml.parsers.SAXParserFactory;
+
+import org.eclipse.core.runtime.Platform;
+import org.eclipse.core.runtime.Preferences;
+import org.xml.sax.Attributes;
+import org.xml.sax.InputSource;
+import org.xml.sax.SAXException;
+import org.xml.sax.helpers.DefaultHandler;
+
+/*
+ * Interface to the help data file contents defined in plugin_customization.ini under
+ * key org.eclipse.help/HELP_DATA.
+ */
+public class HelpData {
+
+	private static final String ELEMENT_TOC_ORDER = "tocOrder"; //$NON-NLS-1$
+	private static final String ELEMENT_HIDDEN = "hidden"; //$NON-NLS-1$
+	private static final String ELEMENT_TOC = "toc"; //$NON-NLS-1$
+	private static final String ELEMENT_CATEGORY = "category"; //$NON-NLS-1$
+	private static final String ELEMENT_INDEX = "index"; //$NON-NLS-1$
+	private static final String ATTRIBUTE_ID = "id"; //$NON-NLS-1$
+	
+	private static HelpData instance;
+	
+	private List tocOrder;
+	private Set hiddenTocs;
+	private Set hiddenIndexes;
+	
+	/*
+	 * Returns the singleton instance.
+	 */
+	public static synchronized HelpData getInstance() {
+		if (instance == null) {
+			instance = new HelpData();
+		}
+		return instance;
+	}
+	
+	/*
+	 * Returns whether the currently running product has any help data defined.
+	 */
+	public boolean exists() {
+		Preferences prefs = HelpPlugin.getDefault().getPluginPreferences();
+		return prefs.getString(HelpPlugin.HELP_DATA_KEY).length() != 0;
+	}
+	
+	/*
+	 * Returns a list of strings which are the IDs of the tocs/categories listed
+	 * in tocOrder.
+	 */
+	public synchronized List getTocOrder() {
+		if (tocOrder == null) {
+			loadHelpData();
+		}
+		return tocOrder;
+	}
+
+	/*
+	 * Returns a set of strings which are the IDs of the tocs/categories listed
+	 * in the hidden section.
+	 */
+	public synchronized Set getHiddenTocs() {
+		if (hiddenTocs == null) {
+			loadHelpData();
+		}
+		return hiddenTocs;
+	}
+
+	/*
+	 * Returns a set of strings which are the IDs of the indexes listed
+	 * in the hidden section.
+	 */
+	public synchronized Set getHiddenIndexes() {
+		if (hiddenIndexes == null) {
+			loadHelpData();
+		}
+		return hiddenIndexes;
+	}
+
+	/*
+	 * Allow unit tests to override for providing test data.
+	 */
+	public InputStream getHelpDataFile(String filePath) throws IOException {
+		return Platform.getProduct().getDefiningBundle().getEntry(filePath).openStream();
+	}
+
+	/*
+	 * Loads and parses the file and populates the data structures.
+	 */
+	private void loadHelpData() {
+		tocOrder = new ArrayList();
+		hiddenTocs = new HashSet();
+		hiddenIndexes = new HashSet();
+		Preferences prefs = HelpPlugin.getDefault().getPluginPreferences();
+		String filePath = prefs.getString(HelpPlugin.HELP_DATA_KEY);
+		try {
+			SAXParser parser = SAXParserFactory.newInstance().newSAXParser();
+			InputStream in = getHelpDataFile(filePath);
+			parser.parse(in, new Handler());
+		}
+		catch (Throwable t) {
+			String msg = "Error loading help data file \"" + filePath + "\""; //$NON-NLS-1$ //$NON-NLS-2$
+			HelpPlugin.logError(msg, t);
+		}
+	}
+
+	/*
+	 * SAX Handler for parsing the help data file.
+	 */
+	private class Handler extends DefaultHandler {
+		
+		private boolean inTocOrder;
+		private boolean inHidden;
+		
+		/* (non-Javadoc)
+		 * @see org.xml.sax.helpers.DefaultHandler#startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)
+		 */
+		public void startElement(String uri, String localName, String name, Attributes attributes) throws SAXException {
+			if (ELEMENT_TOC_ORDER.equals(name)) {
+				inTocOrder = true;
+			}
+			else if (ELEMENT_HIDDEN.equals(name)) {
+				inHidden = true;
+			}
+			else if (ELEMENT_TOC.equals(name) || ELEMENT_CATEGORY.equals(name)) {
+				String id = attributes.getValue(ATTRIBUTE_ID);
+				if (id != null) {
+					if (inTocOrder) {
+						tocOrder.add(id);
+					}
+					else if (inHidden) {
+						hiddenTocs.add(id);
+					}
+				}
+			}
+			else if (ELEMENT_INDEX.equals(name) && inHidden) {
+				String id = attributes.getValue(ATTRIBUTE_ID);
+				if (id != null) {
+					hiddenIndexes.add(id);
+				}
+			}
+		}
+		
+		/* (non-Javadoc)
+		 * @see org.xml.sax.helpers.DefaultHandler#endElement(java.lang.String, java.lang.String, java.lang.String)
+		 */
+		public void endElement(String uri, String localName, String name) throws SAXException {
+			if (ELEMENT_TOC_ORDER.equals(name)) {
+				inTocOrder = false;
+			}
+			else if (ELEMENT_HIDDEN.equals(name)) {
+				inHidden = false;
+			}
+		}
+		
+		/*
+		 * Note: throws clause does not declare IOException due to a bug in
+		 * sun jdk: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6327149
+		 * 
+		 * @see org.xml.sax.helpers.DefaultHandler#resolveEntity(java.lang.String, java.lang.String)
+		 */
+		public InputSource resolveEntity(String publicId, String systemId) throws SAXException {
+			return new InputSource(new StringReader("")); //$NON-NLS-1$
+		}
+	}
+}
diff --git a/org.eclipse.help/src/org/eclipse/help/internal/HelpPlugin.java b/org.eclipse.help/src/org/eclipse/help/internal/HelpPlugin.java
index 4b6595b7b..7206df3ae 100644
--- a/org.eclipse.help/src/org/eclipse/help/internal/HelpPlugin.java
+++ b/org.eclipse.help/src/org/eclipse/help/internal/HelpPlugin.java
@@ -27,6 +27,7 @@ import org.osgi.framework.BundleContext;
 public class HelpPlugin extends Plugin {
 
 	public final static String PLUGIN_ID = "org.eclipse.help"; //$NON-NLS-1$
+	public final static String HELP_DATA_KEY = "HELP_DATA"; //$NON-NLS-1$
 	public final static String BASE_TOCS_KEY = "baseTOCS"; //$NON-NLS-1$
 	public final static String IGNORED_TOCS_KEY = "ignoredTOCS"; //$NON-NLS-1$
 	public final static String IGNORED_INDEXES_KEY = "ignoredIndexes"; //$NON-NLS-1$
diff --git a/org.eclipse.help/src/org/eclipse/help/internal/index/IndexManager.java b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexManager.java
index ac713ec7d..d7e9d3448 100644
--- a/org.eclipse.help/src/org/eclipse/help/internal/index/IndexManager.java
+++ b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexManager.java
@@ -9,6 +9,7 @@
  *     Intel Corporation - initial API and implementation
  *     IBM Corporation - 122967 [Help] Remote help system
  *                       163558 Dynamic content support for all UA
+ *                       165168 [Help] Better control of how help content is arranged and ordered
  *******************************************************************************/
 package org.eclipse.help.internal.index;
 
@@ -30,6 +31,7 @@ import org.eclipse.core.runtime.Preferences;
 import org.eclipse.help.AbstractIndexProvider;
 import org.eclipse.help.IIndex;
 import org.eclipse.help.IndexContribution;
+import org.eclipse.help.internal.HelpData;
 import org.eclipse.help.internal.HelpPlugin;
 
 public class IndexManager {
@@ -161,15 +163,21 @@ public class IndexManager {
 	}
 
 	private Set getIgnoredIndexContributions() {
-		HashSet ignored = new HashSet();
-		Preferences pref = HelpPlugin.getDefault().getPluginPreferences();
-		String preferredIndexes = pref.getString(HelpPlugin.IGNORED_INDEXES_KEY);
-		if (preferredIndexes.length() > 0) {
-			StringTokenizer suggestdOrderedInfosets = new StringTokenizer(preferredIndexes, " ;,"); //$NON-NLS-1$
-			while (suggestdOrderedInfosets.hasMoreTokens()) {
-				ignored.add(suggestdOrderedInfosets.nextToken());
+		HelpData helpData = HelpData.getInstance();
+		if (helpData.exists()) {
+			return helpData.getHiddenIndexes();
+		}
+		else {
+			HashSet ignored = new HashSet();
+			Preferences pref = HelpPlugin.getDefault().getPluginPreferences();
+			String preferredIndexes = pref.getString(HelpPlugin.IGNORED_INDEXES_KEY);
+			if (preferredIndexes.length() > 0) {
+				StringTokenizer suggestdOrderedInfosets = new StringTokenizer(preferredIndexes, " ;,"); //$NON-NLS-1$
+				while (suggestdOrderedInfosets.hasMoreTokens()) {
+					ignored.add(suggestdOrderedInfosets.nextToken());
+				}
 			}
+			return ignored;
 		}
-		return ignored;
 	}
 }
diff --git a/org.eclipse.help/src/org/eclipse/help/internal/toc/TocManager.java b/org.eclipse.help/src/org/eclipse/help/internal/toc/TocManager.java
index 7a00f73e9..2adebeb72 100644
--- a/org.eclipse.help/src/org/eclipse/help/internal/toc/TocManager.java
+++ b/org.eclipse.help/src/org/eclipse/help/internal/toc/TocManager.java
@@ -27,6 +27,7 @@ import org.eclipse.core.runtime.Platform;
 import org.eclipse.core.runtime.Preferences;
 import org.eclipse.help.AbstractTocProvider;
 import org.eclipse.help.TocContribution;
+import org.eclipse.help.internal.HelpData;
 import org.eclipse.help.internal.HelpPlugin;
 import org.eclipse.help.internal.util.ProductPreferences;
 
@@ -189,16 +190,22 @@ public class TocManager {
 	}
 	
 	private Set getIgnoredTocContributions() {
-		HashSet ignored = new HashSet();
-		Preferences pref = HelpPlugin.getDefault().getPluginPreferences();
-		String preferredTocs = pref.getString(HelpPlugin.IGNORED_TOCS_KEY);
-		if (preferredTocs.length() > 0) {
-			StringTokenizer suggestdOrderedInfosets = new StringTokenizer(preferredTocs, " ;,"); //$NON-NLS-1$
-			while (suggestdOrderedInfosets.hasMoreTokens()) {
-				ignored.add(suggestdOrderedInfosets.nextToken());
+		HelpData helpData = HelpData.getInstance();
+		if (helpData.exists()) {
+			return helpData.getHiddenTocs();
+		}
+		else {
+			HashSet ignored = new HashSet();
+			Preferences pref = HelpPlugin.getDefault().getPluginPreferences();
+			String preferredTocs = pref.getString(HelpPlugin.IGNORED_TOCS_KEY);
+			if (preferredTocs.length() > 0) {
+				StringTokenizer suggestdOrderedInfosets = new StringTokenizer(preferredTocs, " ;,"); //$NON-NLS-1$
+				while (suggestdOrderedInfosets.hasMoreTokens()) {
+					ignored.add(suggestdOrderedInfosets.nextToken());
+				}
 			}
+			return ignored;
 		}
-		return ignored;
 	}
 
 	/*
@@ -235,9 +242,16 @@ public class TocManager {
 		// first categorize the TOCs
 		List itemsToOrder = new ArrayList();
 		Map categorized = categorizeTocs(Arrays.asList(unorderedTocs), itemsToOrder);
-			
+		
 		// order them
-		List orderedItems = ProductPreferences.getOrderedList(HelpPlugin.getDefault(), HelpPlugin.BASE_TOCS_KEY, itemsToOrder);
+		List orderedItems;
+		HelpData helpData = HelpData.getInstance();
+		if (helpData.exists()) {
+			orderedItems =  ProductPreferences.getOrderedList(itemsToOrder, helpData.getTocOrder());
+		}
+		else {
+			orderedItems = ProductPreferences.getOrderedList(HelpPlugin.getDefault(), HelpPlugin.BASE_TOCS_KEY, itemsToOrder);
+		}
 			
 		// replace with actual TocContribution or category
 		orderedItems = substituteValues(orderedItems, categorized);
diff --git a/org.eclipse.help/src/org/eclipse/help/internal/util/ProductPreferences.java b/org.eclipse.help/src/org/eclipse/help/internal/util/ProductPreferences.java
index eaa70df6e..ff53c353e 100644
--- a/org.eclipse.help/src/org/eclipse/help/internal/util/ProductPreferences.java
+++ b/org.eclipse.help/src/org/eclipse/help/internal/util/ProductPreferences.java
@@ -146,6 +146,10 @@ public class ProductPreferences {
 		return getOrderedList(items, primary, secondary);
 	}
 
+	public static List getOrderedList(List items, List order) {
+		return getOrderedList(items, order, null);
+	}
+
 	/**
 	 * Returns the given items in an order that best satisfies the given orderings.
 	 * The primary ordering is consulted first, then the secondary.
@@ -174,17 +178,19 @@ public class ProductPreferences {
 		
 		// if there are any remaining items, order them
 		if (!itemsRemaining.isEmpty()) {
-			List secondaryOrderingsRemaining = new ArrayList(Arrays.asList(secondary));
-			List bestMatch;
-			while ((bestMatch = findBestMatch(itemsRemaining, secondaryOrderingsRemaining)) != null) {
-				// satisfy this ordering
-				Iterator iter = bestMatch.iterator();
-				while (iter.hasNext()) {
-					String item = (String)iter.next();
-					if (itemsRemaining.contains(item)) {
-						orderedList.add(item);
-						itemsRemaining.remove(item);
-						secondaryOrderingsRemaining.remove(bestMatch);
+			if (secondary != null && secondary.length > 0) {
+				List secondaryOrderingsRemaining = new ArrayList(Arrays.asList(secondary));
+				List bestMatch;
+				while ((bestMatch = findBestMatch(itemsRemaining, secondaryOrderingsRemaining)) != null) {
+					// satisfy this ordering
+					Iterator iter = bestMatch.iterator();
+					while (iter.hasNext()) {
+						String item = (String)iter.next();
+						if (itemsRemaining.contains(item)) {
+							orderedList.add(item);
+							itemsRemaining.remove(item);
+							secondaryOrderingsRemaining.remove(bestMatch);
+						}
 					}
 				}
 			}
diff --git a/org.eclipse.ua.tests/data/help/preferences/helpData1.xml b/org.eclipse.ua.tests/data/help/preferences/helpData1.xml
new file mode 100644
index 000000000..c51e67644
--- /dev/null
+++ b/org.eclipse.ua.tests/data/help/preferences/helpData1.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<extensions>
+	<tocOrder>
+		<toc id="toc1"/>
+		<category id="category1"/>
+		<toc id="toc2"/>
+		<toc id="toc3"/>
+	</tocOrder>
+	<hidden>
+		<index id="index1"/>
+		<category id="category2"/>
+		<index id="index2"/>
+		<toc id="toc4"/>
+	</hidden>
+</extensions>
\ No newline at end of file
diff --git a/org.eclipse.ua.tests/data/help/preferences/helpData2.xml b/org.eclipse.ua.tests/data/help/preferences/helpData2.xml
new file mode 100644
index 000000000..f660b6f3f
--- /dev/null
+++ b/org.eclipse.ua.tests/data/help/preferences/helpData2.xml
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<extensions>
+</extensions>
\ No newline at end of file
diff --git a/org.eclipse.ua.tests/data/help/preferences/helpData3.xml b/org.eclipse.ua.tests/data/help/preferences/helpData3.xml
new file mode 100644
index 000000000..2fdd8d75e
--- /dev/null
+++ b/org.eclipse.ua.tests/data/help/preferences/helpData3.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<extensions>
+	<tocOrder>
+	</tocOrder>
+	<hidden>
+	</hidden>
+</extensions>
\ No newline at end of file
diff --git a/org.eclipse.ua.tests/help/org/eclipse/ua/tests/help/preferences/AllPreferencesTests.java b/org.eclipse.ua.tests/help/org/eclipse/ua/tests/help/preferences/AllPreferencesTests.java
index f9d7d3252..fab3a51e7 100644
--- a/org.eclipse.ua.tests/help/org/eclipse/ua/tests/help/preferences/AllPreferencesTests.java
+++ b/org.eclipse.ua.tests/help/org/eclipse/ua/tests/help/preferences/AllPreferencesTests.java
@@ -30,5 +30,6 @@ public class AllPreferencesTests extends TestSuite {
 	 */
 	public AllPreferencesTests() {
 		addTest(ProductPreferencesTest.suite());
+		addTest(HelpDataTest.suite());
 	}
 }
diff --git a/org.eclipse.ua.tests/help/org/eclipse/ua/tests/help/preferences/HelpDataTest.java b/org.eclipse.ua.tests/help/org/eclipse/ua/tests/help/preferences/HelpDataTest.java
new file mode 100644
index 000000000..e5370f03f
--- /dev/null
+++ b/org.eclipse.ua.tests/help/org/eclipse/ua/tests/help/preferences/HelpDataTest.java
@@ -0,0 +1,72 @@
+/*******************************************************************************
+ * Copyright (c) 2006 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.ua.tests.help.preferences;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import junit.framework.Assert;
+import junit.framework.Test;
+import junit.framework.TestCase;
+import junit.framework.TestSuite;
+
+import org.eclipse.help.internal.HelpData;
+import org.eclipse.ua.tests.plugin.UserAssistanceTestPlugin;
+
+/*
+ * Tests the help data ordering of tocs and hiding tocs, indexes, etc.
+ */
+public class HelpDataTest extends TestCase {
+
+	private static final String[][][] TEST_DATA = new String[][][] {
+		{ { "data/help/preferences/helpData1.xml" }, { "toc1", "category1", "toc2", "toc3" }, { "toc4", "category2" }, { "index1", "index2" } },
+		{ { "data/help/preferences/helpData2.xml" }, { }, { }, { } },
+		{ { "data/help/preferences/helpData3.xml" }, { }, { }, { } },
+	};
+	
+	/*
+	 * Returns an instance of this Test.
+	 */
+	public static Test suite() {
+		return new TestSuite(HelpDataTest.class);
+	}
+
+	public void testHelpData() {
+		for (int i=0;i<TEST_DATA.length;++i) {
+			String[][] entry = (String[][])TEST_DATA[i];
+			String file = entry[0][0];
+			List expectedTocOrder = Arrays.asList(entry[1]); 
+			Set expectedHiddenTocs = new HashSet(Arrays.asList(entry[2])); 
+			Set expectedHiddenIndexes = new HashSet(Arrays.asList(entry[3])); 
+			HelpDataTester data = new HelpDataTester(file);
+			Assert.assertEquals("Did not get the expected toc order from help data file " + file, expectedTocOrder, data.getTocOrder());
+			Assert.assertEquals("Did not get the expected hidden tocs from help data file " + file, expectedHiddenTocs, data.getHiddenTocs());
+			Assert.assertEquals("Did not get the expected hidden indexes from help data file " + file, expectedHiddenIndexes, data.getHiddenIndexes());
+		}
+	}
+
+	private class HelpDataTester extends HelpData {
+		
+		private String path;
+		
+		public HelpDataTester(String path) {
+			this.path = path;
+		}
+		
+		public InputStream getHelpDataFile(String filePath) throws IOException {
+			return UserAssistanceTestPlugin.getDefault().getBundle().getEntry(path).openStream();
+		}
+	}
+}