diff options
Diffstat (limited to 'org.eclipse.help')
10 files changed, 361 insertions, 35 deletions
diff --git a/org.eclipse.help/schema/index.exsd b/org.eclipse.help/schema/index.exsd index 648014853..f2c06414c 100644 --- a/org.eclipse.help/schema/index.exsd +++ b/org.eclipse.help/schema/index.exsd @@ -2,15 +2,20 @@ <!-- Schema file written by PDE --> <schema targetNamespace="org.eclipse.help" xmlns="http://www.w3.org/2001/XMLSchema"> <annotation> - <appinfo> + <appInfo> <meta.schema plugin="org.eclipse.help" id="index" name="Keyword Index"/> - </appinfo> + </appInfo> <documentation> For registering a keyword index for contributed help content. </documentation> </annotation> <element name="extension"> + <annotation> + <appInfo> + <meta.element /> + </appInfo> + </annotation> <complexType> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="index"/> @@ -35,9 +40,9 @@ <documentation> </documentation> - <appinfo> + <appInfo> <meta.attribute translatable="true"/> - </appinfo> + </appInfo> </annotation> </attribute> </complexType> @@ -56,15 +61,27 @@ the name of the index file which contains the list of keywords and related topics of the help content. <p> <i><b>Configuration Markup for index file:</b></i> +</p> <p> <tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT index (entry)* ></tt><br> -<br> -<tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT entry (entry | topic)* ></tt><br> +</p> +<p> +<tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT entry (entry | topic |see)* ></tt><br> <tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST entry keyword CDATA #REQUIRED ></tt><br> -<br> +</p> +<p> <tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT topic EMPTY ></tt><br> <tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST topic href CDATA #REQUIRED ></tt><br> <tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST topic title CDATA #IMPLIED ></tt><br> +</p> +<p> +<tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT see (subpath)* ></tt><br> +<tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST see keyword CDATA #REQUIRED ></tt><br> +</p> +<p> +<tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT subpath EMPTY ></tt><br> +<tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST subpath keyword CDATA #IMPLIED ></tt><br> +</p> <p><b>The index element</b> <p>The index element represents an instance of index. Index consists of entries, each of them corresponds to a particular keyword. All contributed indexes are merged to one master index which the Help System provides to the user. When index is built, entries are appended in alphabetical order. <p><b>The entry element</b> @@ -77,10 +94,12 @@ topics are associated with the single keyword. If the attribute is not specified, the title comes from the label attribute if present otherwise from a TOC which owns the link. If the link does not belong to any TOC, the title or label attribute must be specified, or else the title becomes undefined. +<p><b>The see element</b> +The see element represents a synonym to an entry in the index. Clicking on a see link will cause the index to navigate to the index entry for which this is a synonym. The keyword attribute represents the top level element for the synonym. The <b>subpath</b> elements are used only if the synonym is not at the top level of the index and represent additional components of the synonym path. </documentation> - <appinfo> + <appInfo> <meta.attribute kind="resource"/> - </appinfo> + </appInfo> </annotation> </attribute> </complexType> @@ -98,27 +117,27 @@ becomes undefined. <documentation> the implementation class for the index provider. This class must implement the <samp>org.eclipse.help.AbstractIndexProvider</samp> interface. </documentation> - <appinfo> + <appInfo> <meta.attribute kind="java" basedOn="org.eclipse.help.AbstractIndexProvider"/> - </appinfo> + </appInfo> </annotation> </attribute> </complexType> </element> <annotation> - <appinfo> + <appInfo> <meta.section type="since"/> - </appinfo> + </appInfo> <documentation> 3.2 </documentation> </annotation> <annotation> - <appinfo> + <appInfo> <meta.section type="examples"/> - </appinfo> + </appInfo> <documentation> The following is an example of using the index extension point. @@ -172,28 +191,27 @@ becomes undefined. </annotation> <annotation> - <appinfo> + <appInfo> <meta.section type="apiInfo"/> - </appinfo> + </appInfo> <documentation> An implementation of <samp>org.eclipse.help.AbstractIndexProvider</samp> must be supplied if a <samp>indexProvider</samp> is used. </documentation> </annotation> - <annotation> - <appinfo> + <appInfo> <meta.section type="implementation"/> - </appinfo> + </appInfo> <documentation> The default implementation of the help system UI supplied with the Eclipse platform fully supports the <samp>index</samp> extension point. </documentation> </annotation> <annotation> - <appinfo> + <appInfo> <meta.section type="copyright"/> - </appinfo> + </appInfo> <documentation> Copyright (c) 2006 Intel Corporation and others.<br> All rights reserved. This program and the accompanying materials are made diff --git a/org.eclipse.help/src/org/eclipse/help/IIndexEntry2.java b/org.eclipse.help/src/org/eclipse/help/IIndexEntry2.java new file mode 100644 index 000000000..73e2af46b --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/IIndexEntry2.java @@ -0,0 +1,27 @@ +/******************************************************************************* + * Copyright (c) 2009 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; + +/** + * IIndexEntry2 is an index entry which may have see eleemnts as children + * + * @since 3.5 + */ +public interface IIndexEntry2 extends IIndexEntry { + + /** + * Obtains see references for this entry + * + * @return array of ITopic + */ + public IIndexSee[] getSees(); + +} diff --git a/org.eclipse.help/src/org/eclipse/help/IIndexSee.java b/org.eclipse.help/src/org/eclipse/help/IIndexSee.java new file mode 100644 index 000000000..3234291ac --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/IIndexSee.java @@ -0,0 +1,36 @@ +/******************************************************************************* + * Copyright (c) 2009 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; + +/** + * An entry that represents a see also node in the index. A see + * also node must always reference another node. + * + * @since 3.5 + */ +public interface IIndexSee extends IUAElement { + + public String getKeyword(); + + /** + * Determines whether the text to be displayed is "see" or "see also" + * @return true if this is a "see also", false if this is a "see" + */ + public boolean isSeeAlso(); + + /** + * + * @return an array of length zero if this see element references an element + * at the top level of the index, otherwise a list of entries which represent keywords + * at the second and lower levels of the index tree. + */ + public IIndexSubpath[] getSubpathElements(); +} diff --git a/org.eclipse.help/src/org/eclipse/help/IIndexSubpath.java b/org.eclipse.help/src/org/eclipse/help/IIndexSubpath.java new file mode 100644 index 000000000..3aa64d316 --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/IIndexSubpath.java @@ -0,0 +1,25 @@ +/******************************************************************************* + * Copyright (c) 2009 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; + +/** + * A directive indicating the content at the given path should be included in + * this document, and replace this node. + * + * @since 3.5 + */ +public interface IIndexSubpath extends IUAElement { + + /** + * @return A segment of the keyword path of a seeAlso element + */ + public String getKeyword(); +} diff --git a/org.eclipse.help/src/org/eclipse/help/internal/UAElementFactory.java b/org.eclipse.help/src/org/eclipse/help/internal/UAElementFactory.java index fad34379f..b72b86569 100644 --- a/org.eclipse.help/src/org/eclipse/help/internal/UAElementFactory.java +++ b/org.eclipse.help/src/org/eclipse/help/internal/UAElementFactory.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2007 IBM Corporation and others. + * Copyright (c) 2007, 2009 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 @@ -22,6 +22,8 @@ import org.eclipse.help.IContext; import org.eclipse.help.IInclude; import org.eclipse.help.IIndex; import org.eclipse.help.IIndexEntry; +import org.eclipse.help.IIndexSee; +import org.eclipse.help.IIndexSubpath; import org.eclipse.help.ILink; import org.eclipse.help.IToc; import org.eclipse.help.ITopic; @@ -30,6 +32,8 @@ import org.eclipse.help.internal.context.Context; import org.eclipse.help.internal.extension.ContentExtension; import org.eclipse.help.internal.index.Index; import org.eclipse.help.internal.index.IndexEntry; +import org.eclipse.help.internal.index.IndexSee; +import org.eclipse.help.internal.index.IndexSubpath; import org.eclipse.help.internal.toc.Link; import org.eclipse.help.internal.toc.Toc; import org.w3c.dom.Element; @@ -47,6 +51,8 @@ public class UAElementFactory { { IAnchor.class, Anchor.class }, { IInclude.class, Include.class }, { ILink.class, Link.class }, + { IIndexSee.class, IndexSee.class }, + { IIndexSubpath.class, IndexSubpath.class }, { IToc.class, Toc.class }, { ICommandLink.class, CommandLink.class }, { IIndex.class, Index.class }, @@ -66,6 +72,8 @@ public class UAElementFactory { classByElementName.put(Context.NAME, Context.class); classByElementName.put(CommandLink.NAME, CommandLink.class); classByElementName.put(Link.NAME, Link.class); + classByElementName.put(IndexSee.NAME, IndexSee.class); + classByElementName.put(IndexSubpath.NAME, IndexSubpath.class); classByElementName.put(ContentExtension.NAME_CONTRIBUTION, ContentExtension.class); classByElementName.put(ContentExtension.NAME_CONTRIBUTION_LEGACY, ContentExtension.class); classByElementName.put(ContentExtension.NAME_REPLACEMENT, ContentExtension.class); diff --git a/org.eclipse.help/src/org/eclipse/help/internal/index/Index.java b/org.eclipse.help/src/org/eclipse/help/internal/index/Index.java index 9142e3b2d..75f9f69ed 100644 --- a/org.eclipse.help/src/org/eclipse/help/internal/index/Index.java +++ b/org.eclipse.help/src/org/eclipse/help/internal/index/Index.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2005, 2007 Intel Corporation and others. + * Copyright (c) 2005, 2009 Intel 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 @@ -8,9 +8,12 @@ * Contributors: * Intel Corporation - initial API and implementation * IBM Corporation - 122967 [Help] Remote help system + * IBM Corporation - add support for see / see also *******************************************************************************/ package org.eclipse.help.internal.index; +import java.util.Iterator; + import org.eclipse.help.IIndex; import org.eclipse.help.IIndexEntry; import org.eclipse.help.internal.UAElement; @@ -36,4 +39,21 @@ public class Index extends UAElement implements IIndex { public IIndexEntry[] getEntries() { return (IIndexEntry[])getChildren(IIndexEntry.class); } + + /** + * @param see A see element + * @return true if the keyword of the see matches an entry in the index + */ + public boolean containsSeeTarget(IndexSee see) { + if (children == null) getChildren(); + String keyword = see.getKeyword(); + for (Iterator iter = children.iterator(); iter.hasNext();) { + Object next = iter.next(); + if (next instanceof IndexEntry && keyword.equals(((IndexEntry)next).getKeyword())) { + return true; + } + } + return false; + } + } diff --git a/org.eclipse.help/src/org/eclipse/help/internal/index/IndexAssembler.java b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexAssembler.java index 638470bf7..b461219eb 100644 --- a/org.eclipse.help/src/org/eclipse/help/internal/index/IndexAssembler.java +++ b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexAssembler.java @@ -19,6 +19,8 @@ import java.util.List; import java.util.Map; import java.util.Set; +import org.eclipse.help.IIndex; +import org.eclipse.help.IIndexEntry; import org.eclipse.help.ITopic; import org.eclipse.help.IUAElement; import org.eclipse.help.internal.HelpPlugin; @@ -51,7 +53,7 @@ public class IndexAssembler { this.locale = locale; process(contributions); Index index = merge(contributions); - sort(index); + sortAndPrune(index); return index; } @@ -73,12 +75,14 @@ public class IndexAssembler { * Merges the children of nodes a and b, and stores them into a. If the two * contain the same keyword, only one is kept but its children are merged, * recursively. If multiple topics exist with the same href, only the - * first one found is kept. + * first one found is kept. If multiple see elements are found with the same target + * only one is retained */ private void mergeChildren(UAElement a, UAElement b) { // create data structures for fast lookup Map entriesByKeyword = new HashMap(); Set topicHrefs = new HashSet(); + Set seeTargets = new HashSet(); IUAElement[] childrenA = a.getChildren(); for (int i=0;i<childrenA.length;++i) { UAElement childA = (UAElement)childrenA[i]; @@ -87,6 +91,8 @@ public class IndexAssembler { } else if (childA instanceof Topic) { topicHrefs.add(childA.getAttribute(Topic.ATTRIBUTE_HREF)); + } else if (childA instanceof IndexSee) { + seeTargets.add(((IndexSee)childA)); } } @@ -113,6 +119,12 @@ public class IndexAssembler { a.appendChild(childB); topicHrefs.add(href); } + } else if (childB instanceof IndexSee) { + if (!seeTargets.contains(((IndexSee) childB))) { + // add see only if it doesn't exist yet + a.appendChild(childB); + seeTargets.add(childB); + } } } } @@ -136,18 +148,19 @@ public class IndexAssembler { /* * Sort the given node's descendants recursively. */ - private void sort(UAElement element) { + private void sortAndPrune(UAElement element) { if (comparator == null) { comparator = new IndexComparator(); } - sort(element, comparator); + sortAndPrune(element, comparator); } /* * Sort the given node's descendants recursively using the given - * Comparator. + * Comparator. Prune out any empty entry elements. Return true if this node was + * not pruned */ - private void sort(UAElement element, Comparator comparator) { + private boolean sortAndPrune(UAElement element, Comparator comparator) { // sort children IUAElement[] children = element.getChildren(); if (children.length > 1) { @@ -160,9 +173,30 @@ public class IndexAssembler { } } // sort children's children + boolean hasChildren = false; for (int i=0;i<children.length;++i) { - sort((UAElement)children[i], comparator); + hasChildren = hasChildren | sortAndPrune((UAElement)children[i], comparator); + } + if (element instanceof IIndexEntry && !hasChildren) { + element.getParentElement().removeChild(element); + return false; } + if (element instanceof IndexSee && !isValidSeeReference((IndexSee) element)) { + element.getParentElement().removeChild(element); + return false; + } + return true; + } + + boolean isValidSeeReference(IndexSee see) { + UAElement ancestor = see.getParentElement(); + while (!(ancestor instanceof Index)) { + if (ancestor == null) { + return true; + } + ancestor = ancestor.getParentElement(); + } + return ((Index)ancestor).containsSeeTarget(see); } /* @@ -201,7 +235,9 @@ public class IndexAssembler { int c1 = getCategory((UAElement)o1); int c2 = getCategory((UAElement)o2); if (c1 == c2) { - + if (o1 instanceof IndexSee) { + return ((IndexSee)o1).compareTo(o2); + } // same type of object; compare alphabetically String s1 = getLabel((UAElement)o1); String s2 = getLabel((UAElement)o2); @@ -239,9 +275,11 @@ public class IndexAssembler { return 1; } return 4; + } else if (element instanceof IndexSee) { + return 5; } else { - return 5; + return 6; } } diff --git a/org.eclipse.help/src/org/eclipse/help/internal/index/IndexEntry.java b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexEntry.java index 22d121a84..14377714f 100644 --- a/org.eclipse.help/src/org/eclipse/help/internal/index/IndexEntry.java +++ b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexEntry.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2005, 2007 Intel Corporation and others. + * Copyright (c) 2005, 2009 Intel 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 @@ -8,15 +8,18 @@ * Contributors: * Intel Corporation - initial API and implementation * IBM Corporation - 122967 [Help] Remote help system + * IBM Corporation - Added support for see references *******************************************************************************/ package org.eclipse.help.internal.index; import org.eclipse.help.IIndexEntry; +import org.eclipse.help.IIndexEntry2; +import org.eclipse.help.IIndexSee; import org.eclipse.help.ITopic; import org.eclipse.help.internal.UAElement; import org.w3c.dom.Element; -public class IndexEntry extends UAElement implements IIndexEntry { +public class IndexEntry extends UAElement implements IIndexEntry2 { public static final String NAME = "entry"; //$NON-NLS-1$ public static final String ATTRIBUTE_KEYWORD = "keyword"; //$NON-NLS-1$ @@ -46,4 +49,8 @@ public class IndexEntry extends UAElement implements IIndexEntry { public void setKeyword(String keyword) { setAttribute(ATTRIBUTE_KEYWORD, keyword); } + + public IIndexSee[] getSees() { + return (IIndexSee[])getChildren(IIndexSee.class); + } } diff --git a/org.eclipse.help/src/org/eclipse/help/internal/index/IndexSee.java b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexSee.java new file mode 100644 index 000000000..b5108052b --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexSee.java @@ -0,0 +1,107 @@ +/******************************************************************************* + * Copyright (c) 2009 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.index; + +import java.util.Arrays; + +import org.eclipse.help.IIndexSee; +import org.eclipse.help.IIndexSubpath; +import org.eclipse.help.internal.UAElement; +import org.w3c.dom.Element; + +import com.ibm.icu.text.Collator; + +public class IndexSee extends UAElement implements IIndexSee, Comparable { + + public static final String NAME = "see"; //$NON-NLS-1$ + public static final String ATTRIBUTE_KEYWORD = "keyword"; //$NON-NLS-1$ + + public IndexSee(Element src) { + super(src); + } + + public IndexSee(IIndexSee src) { + super(NAME, src); + setKeyword(src.getKeyword()); + appendChildren(src.getChildren()); + } + + public String getKeyword() { + return getAttribute(ATTRIBUTE_KEYWORD); + } + + private String[] getPath() { + IIndexSubpath[] subpaths = getSubpathElements(); + String[] result = new String[1 + subpaths.length]; + result[0] = getKeyword(); + for (int i = 0; i < subpaths.length; i++) { + result[i + 1] = subpaths[i].getKeyword(); + } + return result; + } + + public void setKeyword(String keyword) { + setAttribute(ATTRIBUTE_KEYWORD, keyword); + } + + private int getCategory(String keyword) { + if (keyword != null && keyword.length() > 0) { + char c = keyword.charAt(0); + if (Character.isDigit(c)) { + return 2; + } + else if (Character.isLetter(c)) { + return 3; + } + return 1; + } + return 4; + } + + public int compareTo(Object arg0) { + Collator collator = Collator.getInstance(); + if (arg0 instanceof IndexSee) { + String[] path = getPath(); + String[] targetPath = ((IndexSee)arg0).getPath(); + for (int i = 0; i < path.length; i++) { + if (i >= targetPath.length) { + return 1; + } + if (getCategory(path[i]) != getCategory(targetPath[i])) { + return getCategory(path[i]) - getCategory(targetPath[i]); + } + int result = collator.compare(path[i], targetPath[i]); + if (result != 0) { + return result; + } + } + return path.length - targetPath.length; + } + return 0; + } + + public boolean equals(Object obj) { + return obj instanceof IndexSee && compareTo(obj) == 0; + } + + public int hashCode() { + return Arrays.hashCode(getPath()); + } + + public boolean isSeeAlso() { + return !this.equals(getParentElement().getChildren()[0]); + } + + public IIndexSubpath[] getSubpathElements() { + return (IIndexSubpath[])getChildren(IIndexSubpath.class); + } +} diff --git a/org.eclipse.help/src/org/eclipse/help/internal/index/IndexSubpath.java b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexSubpath.java new file mode 100644 index 000000000..47f1b0507 --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/internal/index/IndexSubpath.java @@ -0,0 +1,40 @@ +/******************************************************************************* + * Copyright (c) 2009 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.index; + +import org.eclipse.help.IIndexSubpath; +import org.eclipse.help.internal.UAElement; +import org.w3c.dom.Element; + +public class IndexSubpath extends UAElement implements IIndexSubpath { + + public static final String NAME = "subpath"; //$NON-NLS-1$ + public static final String ATTRIBUTE_KEYWORD = "keyword"; //$NON-NLS-1$ + + public IndexSubpath(IIndexSubpath src) { + super(NAME, src); + setKeyword(src.getKeyword()); + appendChildren(src.getChildren()); + } + + public IndexSubpath(Element src) { + super(src); + } + + public String getKeyword() { + return getAttribute(ATTRIBUTE_KEYWORD); + } + + public void setKeyword(String keyword) { + setAttribute(ATTRIBUTE_KEYWORD, keyword); + } + +} |