203553: Apply patch plus additional docs improvements on behalf on Beth Tibbitts. Remove unused usageDescription attribute.

core/org.eclipse.cdt.core/schema/templates.exsd

@@ -6,14 +6,14 @@
          <meta.schema plugin="org.eclipse.cdt.core" id="templates" name="Template Extension point"/>
       </appInfo>
       <documentation>
-         This templates extension point facilitates the users to contribute their Template XMLs to the Template Engine plugin.
+         This templates extension point facilitates the users to contribute their Template XMLs to the Template Engine plug-in.
       </documentation>
    </annotation>
 
    <element name="extension">
       <annotation>
          <documentation>
-            Extension point added to Template Engine plugin.  Any plugin, which intends to contribute XML templates to Temaplate Engine has to extend this extension point, and add template element.
+            Extension point added to Template Engine plugin.  Any plugin, which intends to contribute XML templates to Template Engine has to extend this extension point, and add template element.
          </documentation>
       </annotation>
       <complexType>
@@ -57,30 +57,41 @@
          <sequence>
             <element ref="toolChain" minOccurs="0" maxOccurs="unbounded"/>
          </sequence>
+         <attribute name="id" type="string" use="required">
+            <annotation>
+               <documentation>
+                  A unique identifier for this template contribution. This does not need to be the same as the id of the template (as defined in template.xml) it is contributing. This allows contributing the same template.xml more than once (for example for multiple project types, or with alternate page sequences).
+               </documentation>
+            </annotation>
+         </attribute>
          <attribute name="location" type="string" use="required">
             <annotation>
                <documentation>
-                  The location of the template(relative within the extender plugin).
+                  The path of template.xml (relative to the base of the containing plug-in). For example &quot;templates/TemplateOne/template.xml&quot;. This attribute is mandatory. 
-This is a must enter, attribute.
                </documentation>
                <appInfo>
                   <meta.attribute kind="resource"/>
                </appInfo>
             </annotation>
          </attribute>
-         <attribute name="filterPattern" type="string">
+         <attribute name="projectType" type="string" use="required">
             <annotation>
                <documentation>
-                  Any filterPatter associated with this Template to be used by TemplateEngine.
+                  This id refers to the cdt project type that the template will be associated with. Project types are contributed to the org.eclipse.cdt.managedbuilder.core.buildDefinitions extension-point. See the CDT Build System documentation in the developer guide for built-in project type ids.
-This is an optional attribute.
                </documentation>
             </annotation>
          </attribute>
-         <attribute name="usageDescription" type="string">
+         <attribute name="isCategory" type="boolean">
             <annotation>
                <documentation>
-                  A notation describing how this template is used. Usually used to filter the list of templates on offer depending on other wizard attributes.
+                  If true this template contribution should appear as a folder. Defaults to false.
-This is an optional attribute.
+               </documentation>
+            </annotation>
+         </attribute>
+         <attribute name="filterPattern" type="string">
+            <annotation>
+               <documentation>
+                  filterPattern is a java.util.regex.Pattern format string which is used to match against build configuration ids. This is an optional attribute, if absent will all configurations will match.
                </documentation>
             </annotation>
          </attribute>
@@ -94,27 +105,6 @@ This is an optional attribute.
                </appInfo>
             </annotation>
          </attribute>
-         <attribute name="isCategory" type="boolean">
-            <annotation>
-               <documentation>
-                  
-               </documentation>
-            </annotation>
-         </attribute>
-         <attribute name="projectType" type="string" use="required">
-            <annotation>
-               <documentation>
-                  
-               </documentation>
-            </annotation>
-         </attribute>
-         <attribute name="id" type="string">
-            <annotation>
-               <documentation>
-                  
-               </documentation>
-            </annotation>
-         </attribute>
       </complexType>
    </element>
 
@@ -147,17 +137,13 @@ This is an optional attribute.
          The following is an example of the extension point usage:
 &lt;p&gt;
 &lt;pre&gt;
-   &lt;extension
+   &lt;extension point=&quot;org.eclipse.cdt.core.templates&quot;&gt;
-         id=&quot;simpleEXETemplateExample&quot;
+      &lt;template
-         name=&quot;Simple EXE Template Example&quot;
+         id=&quot;org.foobar.templates.MyExampleTemplate&quot;
-         point=&quot;org.eclipse.cdt.templateengine.templates&quot;&gt;
+         location=&quot;templates/MyExampleTemplate/template.xml&quot;
-      &lt;template 
+         projectType=&quot;org.eclipse.cdt.build.core.buildArtefactType.exe&quot;
-            filterPattern=&quot;.*&quot;
+         filterPattern=&quot;.*&quot;&gt;
-            usageDescription=&quot;Simple EXE&quot;
+      &lt;/template&gt;
-            location=&quot;templates/org/eclipse/cdt/templates/projecttemplates/Simple EXE/template.xml&quot;
-            projectType=&quot;org.eclipse.cdt.build.projectType.exe&quot;
-            wizardId=&quot;org.eclipse.cdt.templates.ui.NewManagedProjectWizard&quot;&gt;
-      &lt;/template&gt; 
    &lt;/extension&gt;
 &lt;/pre&gt;            
 

core/org.eclipse.cdt.core/templateengine/org/eclipse/cdt/core/templateengine/TemplateEngine.java

@@ -111,7 +111,7 @@ public class TemplateEngine {
 	}
 
 	/**
-	 * This method will be called by Contianer UIs (Wizard, PropertyPage,
+	 * This method will be called by Container UIs (Wizard, PropertyPage,
 	 * PreferencePage). Create a Template instance, update the ValueStore, with
 	 * SharedDefaults. This method calls the getTemplate(URL), after getting URL
 	 * for the given String TemplateDescriptor.
@@ -209,7 +209,6 @@ public class TemplateEngine {
 		String pluginId = null;
 		String projectType = null;
 		String filterPattern = null;
-		String usage = null;
 		boolean isCategory = false;
 		String extraPagesProvider = null;
 
@@ -217,14 +216,13 @@ public class TemplateEngine {
 		for(int i=0; i<extensions.length; i++) {
 			IExtension extension = extensions[i];
 			IConfigurationElement[] configElements = extension.getConfigurationElements();
-			pluginId = extension.getNamespaceIdentifier(); // Plugin-id of the extending plugin.
+			pluginId = extension.getNamespaceIdentifier(); // Plug-in id of the extending plug-in.
 			for(int j=0; j<configElements.length; j++) {
 				IConfigurationElement config = configElements[j];
 				templateId = config.getAttribute(TemplateEngineHelper.ID);
 				location = config.getAttribute(TemplateEngineHelper.LOCATION);
 				projectType = config.getAttribute(TemplateEngineHelper.PROJECT_TYPE);
 				filterPattern = config.getAttribute(TemplateEngineHelper.FILTER_PATTERN);
-				usage = config.getAttribute(TemplateEngineHelper.USAGE_DESCRIPTION);
 				isCategory = Boolean.valueOf(config.getAttribute(TemplateEngineHelper.IS_CATEGORY)).booleanValue();
 				extraPagesProvider = config.getAttribute(TemplateEngineHelper.EXTRA_PAGES_PROVIDER);
 				
@@ -236,7 +234,7 @@ public class TemplateEngine {
 				
 				TemplateInfo templateInfo = new TemplateInfo(templateId, projectType, filterPattern, location, 
 														pluginId, toolChainIdSet,
-														usage, extraPagesProvider, isCategory);
+														extraPagesProvider, isCategory);
 				if (!templateInfoMap.containsKey(projectType)) {
 					templateInfoMap.put(projectType, new ArrayList/*<TemplateInfo>*/());
 				}
@@ -280,12 +278,12 @@ public class TemplateEngine {
 	}
 	
 	/**
-	 * Gets an array of template info objects matching the criteria passed as params.
+	 * Gets an array of template info objects matching the criteria passed as parameters.
 	 * @param projectType may not be null
 	 * @param toolChain may be null to indicate no tool-chain
 	 * @param usageFilter a usage string which is matched against the filter from the template, may be null
 	 * to indicate no usage filtering
-	 * @return an array of template infos (never null)
+	 * @return an array of TemplateInfo objects (never null)
 	 */
 	public TemplateInfo[] getTemplateInfos(String projectType, String toolChain, String usageFilter) {
 		List/*<TemplateInfo>*/ templateInfoList = (List/*<TemplateInfo*/) templateInfoMap.get(projectType.trim());
@@ -364,7 +362,7 @@ public class TemplateEngine {
 	/**
 	 * Returns the Children of the Element.
 	 * @param element
-	 * @return List of the child elelments
+	 * @return List of the child elements
      * 
      * @since 4.0
 	 */
@@ -374,7 +372,7 @@ public class TemplateEngine {
 		for (int i = 0, l = children.getLength(); i < l; i++) {
 			Node child = children.item(i);
 			if (child.getNodeType() == Node.ELEMENT_NODE) {
-				list.add((Element) child);
+				list.add(child);
 			}
 		}
 		return list;
@@ -395,7 +393,7 @@ public class TemplateEngine {
 		for (int i = 0, l = children.getLength(); i < l; i++) {
 			Node child = children.item(i);
 			if (child.getNodeType() == Node.ELEMENT_NODE && child.getNodeName().equals(tag)) {
-				list.add((Element) child);
+				list.add(child);
 			}
 		}
 		return list;

core/org.eclipse.cdt.core/templateengine/org/eclipse/cdt/core/templateengine/TemplateInfo.java

@@ -21,7 +21,6 @@ import java.util.Set;
 public class TemplateInfo {
 	private String projectTypeId;
 	private String filterPattern;
-	private String usageDescription;
 	private String templatePath;
 	private String pluginId;
 	private Set toolChainIdSet;
@@ -32,7 +31,7 @@ public class TemplateInfo {
 	private List configs;
 	
 	public TemplateInfo(String templateId, String projectTypeId, String filterPattern, String templatePath, 
-			String pluginId, Set toolChainIdSet, String usageDescription, 
+			String pluginId, Set toolChainIdSet, 
 			String pagesProvider, boolean isCategory) {
 		this.templateId = templateId;
 		this.filterPattern = filterPattern;
@@ -40,7 +39,6 @@ public class TemplateInfo {
 		this.pluginId = pluginId;
 		this.projectTypeId = projectTypeId;
 		this.toolChainIdSet = toolChainIdSet;
-		this.usageDescription = usageDescription != null ? usageDescription : ""; //$NON-NLS-1$
 		this.pagesProvider = pagesProvider;
 		this.isCategory = isCategory;
 		this.configs = null;
@@ -77,13 +75,6 @@ public class TemplateInfo {
 	public String getFilterPattern() {
 		return filterPattern;
 	}
-
-	/**
-	 * @return   the usageDescription
-	 */
-	public String getUsageDescription() {
-		return usageDescription;
-	}
 	
 	public String getExtraPagesProvider() {
 		return pagesProvider;

doc/org.eclipse.cdt.doc.isv/guide/projectTemplateEngine/Howtoregistertemplates.html

@@ -29,7 +29,7 @@ How&nbsp;to&nbsp;register&nbsp;a&nbsp;template&nbsp;with&nbsp;Eclipse</p>
 
 </div><div class="Head1">
 
-<h1>How to register a template with Eclipse</h1>
+<h1>How to register a project template with CDT</h1>
 </div><div class="Bodytext">
 <p>
 Once the project template is ready, you need to register it with Eclipse
@@ -40,7 +40,7 @@ group all the resources required for this application in a folder
 "HelloWorld". 
 </p>
 <p>
-To register a project template with Eclipse follow the steps given below:
+To register a project template with CDT follow the steps given below:
 </p>
 <ol>
 <li>
@@ -50,9 +50,9 @@ the source folders.
 </p>
 <li>
 <p>
-Create a folder and copy the project template along with all the
+Create a new folder to contain the template project's content e.g. "MyExampleProject/templates/MyExampleTemplate".
-resources required to create the project. For example, all the hearder files,
+Copy the project template.xml along with all the resources required to create the project. For example, all the
-source files, resource files etc. 
+header files, source files, resource files etc. 
 </p>
 <li>
 <p>
@@ -65,7 +65,9 @@ editor, refer to <i>PDE
 <li>
 <p>
 Click <code>Add</code> to select
-<code class="filename">org.eclipse.cdt.templateengine</code> plug-in from the list.
+<code class="filename">org.eclipse.cdt.core</code> and
+<code class="filename">org.eclipse.cdt.ui</code>
+plug-ins from the list.
 </p>
 <li>
 <p>
@@ -79,29 +81,31 @@ Click <code>Add</code> to create an extension to the extension-point.
 <li>
 <p>
 Select the extension-point with ID
-<code class="filename">org.eclipse.cdt.templateengine.templates</code> from the list of
+<code class="filename">org.eclipse.cdt.core.templates</code> from the list of
-extensions-points.
+extension-points.
 </p>
 <li>
 <p>
 Right-click on the newly added extension, and select
 <code class="ProgramOutput">New</code> &gt;  
 <code class="ProgramOutput">template</code> from the context menu.
+The first one has already been added for you, <code class="ProgramOutput">"(template)"</code>.
 </p>
 <li>
 <p>
-Choose the new template added in step 6 from the <code class="ProgramOutput">All
+Select the new template added in the previous step from the <code class="ProgramOutput">All
-Extensions</code> list.
+Extensions</code> list.  Its name is initially <code class="ProgramOutput">"(template)"</code>.
 </p>
 <li>
 <p>
-Specify the <code class="ProgramOutput">wizardId</code> attribute of the template as
+Specify the <code class="ProgramOutput">id</code> attribute of this template contribution, for example
-"<em>org.eclipse.cdt.project.ui.NewProjectWizard</em>". This
+"<em>com.foobar.templates.contrib.MyTemplate1</em>". This attribute is mandatory. The id need not be
-attribute is mandatory.
+the same as the template id (from template.xml). This allows contributing the same template.xml multiple
+times. It will replace <code class="ProgramOutput">"(template)"</code> in the list.
 </p>
 <li>
 <p>
-Specify the location of the template relative to the plug-in created
+Specify the location of the template XML file, relative to the plug-in created
 in step 1. This attribute is mandatory.
 </p>
 <li>
@@ -127,31 +131,15 @@ API document for
 </p>
 <li>
 <p>
-Select an appropriate project type from the
+Specify the project type you wish the template to be associated with. The project type id can be
-<code class="ProgramOutput">projectType</code> drop-down list. This is an optional attribute. 
+found by looking at the project types contributed to the  buildDefinitions extension point. See the CDT Build System documentation in the developer guide for built-in project type ids.
-</p>
+<code class="ProgramOutput">projectType</code> drop-down list. This is an mandatory attribute.
-<li>
-<p>
-Specify the <code class="ProgramOutput">usageDescription</code>, which is a notation
-describing how this template is used. Usually used to filter the list of
-templates on offer depending on other wizard attributes. This is an optional
-attribute. For more information, refer to Java API document for
-<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">java.util.regex.Pattern</a>.
-</p>
-<p>
-The New Project wizard will list only those templates, which are
-relevant for the build Configurations choosen for the project. For a example, if the developer
-choose to create a <code class="ProgramOutput">C++ Application for Symbian OS</code>, the wizard
-will list all the templates with the relevant
-<code class="ProgramOutput">usageDescription</code>. Otherwise, for a standard <code class="ProgramOutput">CDT
-C++ Project</code> the wizard will list all the templates, irrespective of
-whether the <code class="ProgramOutput">usageDescription</code> is specified or not. 
 </p>
 <li>
 <p>
 Specify the <code class="ProgramOutput">pagesAfterTemplateSelectionProvider</code>,
 which is a fully qualified name of the class that implements
-<code class="filename">org.eclipse.cdt.templateengine.IPagesAfterTemplateSelectionProvider</code>
+<code class="filename">org.eclipse.cdt.ui.templateengine.IPagesAfterTemplateSelectionProvider</code>
 interface. This is an optional attribute. 
 </p>
 </li>