CMSIS_5/CMSIS/DoxyGen/Pack/src/examples_schema.txt

/**************************************************************************************************/
/** 
\page pdsc_examples_pg  /package/examples element

The element \ref element_example describes fully defined examples contained in the PACK.
An example lists the files that belong to an example. The example itself and each individual file may
refer to a \ref element_condition "condition" that must resolve to true; if it is false the example or file will be ignored.
The board element is used to reference to one or more board descriptions using the board vendor and name an example is targeted for.
Each example can specify attributes listing related components using Class (Cclass=), Group (Cgroup=), Subgroup (Csub) and a Version (Cversion=)

\b Example
\code
  <examples>
    <example name="Blinky" folder="Boards/MCBSTM32F200/Blinky" doc="Abstract.txt" version="1.0">
      <description>This is a basic example demonstrating the development flow and letting the LED on the board blink</description>
      <board vendor="STMicroelectronics" name="32F429IDISCOVERY"/>
      <project>
        <environment name="uv"  load="ARM/Blinky.uvproj"/>
        <environment name="iar" load="IAR/Blinky.ewarm" />
      </project>
      <attributes>
        <component Cclass="CMSIS" Cgroup="Core"/>
        <component Cclass="Device" Cgroup="Startup"/>
        <keyword>Blinky</keyword>
        <keyword>Getting Started</keyword>
      </attributes>
    </example>
  </examples>  

\endcode

<p>&nbsp;</p>		
<hr>

\section element_examples /package/examples

Grouping element for examples. No more than one such group can exist in a PACK.

<table class="cmtable" summary="Element: Example">
  <tr>
    <th>Parent</th>
    <th colspan="3">Chain</th>
  </tr>
  <tr>
    <td>\ref pdsc_package_pg "package"</td>
    <td colspan="3">\ref pdsc_package_pg "/package"</td>
  </tr>	
  <tr>
    <th>Child&nbsp;Elements</th>
    <th>Description</th>
    <th>Type</th>
    <th>Occurrence</th>
  </tr>
  <tr>
    <td>\ref element_example "example"</td>
    <td>Description of fully specified project</td>
    <td>ExampleType</td>
    <td>1..* </td>
  </tr>
 </table>

<p>&nbsp;</p>		
<hr>

\section element_example /package/examples/example

An example section is used to provide the required information for accessing an example project contained in a PACK. All examples contained in the installed packs can be 
listed including a brief description. A selected example will get copied into a user selected destination folder. Based on the user selected environment the respective project 
file will be loaded. The ID of an example is the combination of the PACK vendor, the board information and the example name and version. Examples with the same ID are
treated as a single example.

<table class="cmtable" summary="Element: Example">
  <tr>
    <th>Parent</th>
    <th colspan="3">Chain</th>
  </tr>
  <tr>
    <td>\ref element_examples "examples"</td>
    <td colspan="3">\ref element_examples</td>
  </tr>	
  <tr>
    <th>Attributes</th>
    <th>Description</th>
    <th>Type</th>
    <th>Use</th>
  </tr>
  <tr>
    <td>name</td>
    <td>Name of the example</td>
    <td>xs:string</td>
    <td>required</td>
  </tr>
  <tr>
    <td>folder</td>
    <td>Relative path to the example base folder within the package. If selected, then the directory including all sub-folders and files will be copied,
 	unless the archive attribute gets set.</td>
    <td>xs:string</td>
    <td>required</td>
  </tr>
  <tr>
    <td>archive</td>
    <td>Filename and extension of the archive file containing all files and sub-folders of the example. The archive is located in the path specified by the 
	attribute \b <em>folder</em>. If selected, then the whole archive will be extracted.</td>
    <td>xs:string</td>
    <td>optional</td>
  </tr>
  <tr>
    <td>doc</td>
	<td>Document that describes the example.</td>
	<td>xs:string</td>
	<td>required</td>
  </tr>
  <tr>
    <td>version</td>
    <td>Example version number.  The version format is described in \ref VersionType "Version Type".</td>
	</td>
    <td>VersionType</td>
    <td>optional</td>
  </tr>
  <tr>
    <th>Child&nbsp;Elements</th>
    <th>Description</th>
    <th>Type</th>
    <th>Occurrence</th>
  </tr>
  <tr>
    <td>description</td>
    <td>Briefly documents the purpose and scope of the example. The test can be displayed in an example selector.</td>
    <td>xs:string</td>
    <td>1</td>
  </tr>
  <tr>
    <td>\ref element_example_board "board"</td>
    <td>Complex type providing a reference to a board description using board name and vendor.</td>.
    <td>BoardReferenceType</td>
    <td>1</td>
  </tr>
  <tr>
    <td>\ref element_example_project "project"</td>
	<td>Complex type describing the project files for different environments</td>
	<td>ExampleProjectType</td>
	<td>1..* </td>
  </tr>
  <tr>
    <td>\ref element_example_attributes "attributes"</td>
	<td>Group element for project attributes, which list required components, define example categories, and set keywords to filter and search for examples.</td>
	<td>ExampleAttributesType</td>
	<td>1</td>
  </tr>
</table>

<p>&nbsp;</p>		
<hr>

\section element_example_board /package/examples/example/board
This element specifies the board that can be used with the example project. 

\b Example:
\code
  <board name="MV1000A" vendor="MyVendor"/>
\endcode

<p>&nbsp;</p>		

<table class="cmtable" summary="Element: Example Board">
  <tr>
    <th>Parent</th>
    <th colspan="3">Chain</th>
  </tr>
  <tr>
    <td>\ref element_example "example"</td>
    <td colspan="3">\ref element_example</td>
  </tr>	
  <tr>
    <th>Attributes</th>
    <th>Description</th>
    <th>Type</th>
    <th>Use</th>
  </tr>
  <tr>
    <td>vendor</td>
    <td>Vendor name of the board.</td>
    <td>xs:string</td>
    <td>required</td>
  </tr>
  <tr>
    <td>name</td>
    <td>Commercial name of the board.</td>
    <td>xs:string</td>
    <td>required</td>
  </tr>
  <tr>
    <td>Dvendor</td>
	<td>Vendor name of the device used on the board.  Use predefined values as listed in the table \ref DeviceVendorEnum "Device Vendor". </td>
	<td>DeviceVendorEnum</td>
	<td>optional</td>
  </tr>
  <tr>
    <td>Dfamily</td>
	<td>Name of the target device family used on the board. This attribute is optional if either DsubFamily or Dname is already specified.  \n <b>\token{Deprecated since version 1.1}</b></td>
	<td>xs:string</td>
	<td>optional</td>
  </tr>
  <tr>
    <td>DsubFamily</td>
	<td>Name of the target device sub-family used on the board. This attribute is optional if either Dfamily or Dname is already specified.  \n <b>\token{Deprecated since version 1.1}</b></td>
	<td>xs:string</td>
	<td>optional</td>
  </tr>
  <tr>
    <td>Dname</td>
	<td>Name of the target device used on the board. This attribute is optional if either Dfamily or DsubFamily is already specified.  \n <b>\token{Deprecated since version 1.1}</b>.</td>
	<td>xs:string</td>
	<td>optional</td>
  </tr>
</table>

\note
Values for <b>\token{deprecated attributes}</b> are read from the board description element \ref element_board_mountedDevice.

<p>&nbsp;</p>
<hr>

\section element_example_project /package/examples/project
A project element is a sequence of \em environment elements that describe the name of the environment and the project file to be loaded.

<b>Example:</b>
\code
<project>
  <environment ... />
  <environment ... />
</project>
\endcode

<p>&nbsp;</p>

<table class="cmtable" summary="Element: Example Project">
  <tr>
    <th>Parent</th>
	<th colspan=3>Chain</th>
  </tr>
  <tr>
    <td>\ref element_example "example"</td>
	<td colspan=3>\ref element_example</td>
  </tr>
  <tr>
    <th>Element</th>
    <th>Description</th>
    <th>Type</th>
    <th>Occurrence</th>
  </tr>
  <tr>
    <td>\ref element_example_project_env "environment"</td>
	<td>Specifies the environment and project file with extension.</td>
	<td>xs:complexType</td>
	<td>1..*</td>
  </tr>
</table>

<p>&nbsp;</p>
<hr>

\section  element_example_project_env /package/examples/project/environment
The environment element describes the name of the environment and the project file to be loaded.

<b>Example:</b>
\code
<project>
  <environment name="uv" load="ARM/Blinky.uvproj"/>
  <environment name="iar" load="IAR/Blinky.ewarm" />
</project>
\endcode

<p>&nbsp;</p>
  
<table class="cmtable" summary="Element: Example Project">
  <tr>
    <th>Parent</th>
	<th colspan=3>Chain</th>
  </tr>
  <tr>
    <td>\ref element_example_project "project"</td>
	<td colspan=3>\ref element_example_project</td>
  </tr>
  <tr>
    <th>Attributes</th>
    <th>Description</th>
    <th>Type</th>
    <th>Use</th>
  </tr>
  <tr>
    <td>name</td>
    <td>Name of the required tool-chain (for example: \token{uv}, \token{iar}, etc.)</td>
    <td>xs:string</td>
    <td>required</td>
  </tr>
  <tr>
    <td>load</td>
    <td>Specifies the project file with extension. A path relative to \em folder attribute of the element \ref element_example can be appended.</td>
    <td>xs:string</td>
    <td>required</td>
  </tr>
</table>

<p>&nbsp;</p>
<hr>

\section element_example_attributes /package/examples/example/attributes

<b>Example:</b>
\code
<example>
  <attributes>
    <category>Example Project</category>
    <category>For a specific board</category>
	...
    <component Cclass="CMSIS" Cgroup="Core"/>
    <component Cclass="Device" Cgroup="Startup"/>
	...
	<keyword>Blinky</keyword>
	<keyword>Getting Started</keyword>
  </attributes>
</example>
\endcode

<p>&nbsp;</p>

<table class="cmtable" summary="Element: Example Attributes">
  <tr>
    <th>Parent</th>
	<th colspan=3>Chain</th>
  </tr>
  <tr>
    <td>\ref element_example "example"</td>
	<td colspan=3>\ref element_example</td>
  </tr>
  <tr>
    <th>Child&nbsp;Elements</th>
    <th>Description</th>
    <th>Type</th>
    <th>Occurrence</th>
  </tr>
  <tr>
    <td>category</td>
    <td>Free form string defining an example category. A category can be used to filter examples in an example browser.</td>
    <td>xs:string</td>
    <td>0..*</td>
  </tr>
  <tr>
    <td>\ref element_example_attribute_component "component"</td>
    <td>Group for defining the components used in the example.</td>
    <td>ComponentCategoryType</td>
    <td>0..*</td>
  </tr>
  <tr>
    <td>keyword</td>
    <td>Free form string defining a keyword that relates to the example. A keyword can be used to search for examples.</td>
    <td>xs:string</td>
    <td>0..*</td>
  </tr>
</table>

<p>&nbsp;</p>
<hr>

\section element_example_attribute_component /package/examples/example/attributes/component
The component element specifies the Cclass to which the example belongs. 
This can be used to list all related components within an example.

<b>Example:</b>
\code
<attributes>
  ...
  <component Cclass="CMSIS" Cgroup="Core"/>
  <component Cclass="Device" Cgroup="Startup"/>
  ...
</attributes>
\endcode

<p>&nbsp;</p>

<table class="cmtable" summary="Element: Attribute Component">
  <tr>
    <th>Parent</th>
	<th colspan=3>Chain</th>
  </tr>
  <tr>
    <td>\ref element_example_attributes "attribute"</td>
	<td colspan=3>\ref element_example_attributes</td>
  </tr>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Use</th>
  </tr>
  <tr>
    <td>Cclass</td>
    <td>Free form string defining an example class. Predefined values can be used as listed in the table \ref CclassType "Component Classes".</td>
    <td>CclassType</td>
    <td>required</td>
  </tr>
  <tr>
    <td>Cgroup</td>
    <td>Free form string defining an example group. Predefined values can be used as listed in the table \ref CgroupType "Component Groups".</td>
    <td>CgroupType</td>
    <td>optional</td>
  </tr>
  <tr>
    <td>Csub</td>
    <td>Free form string defining an example subgroup. The type is described in \ref CsubType "Component Subgroups".</td>
    <td>CsubType</td>
    <td>optional</td>
  </tr>
  <tr>
    <td>Cversion</td>
    <td>Free form string defining an example version.  The version format is described in \ref VersionType "Version Type".</td>
    <td>VersionType</td>
    <td>optional</td>
  </tr>
  <tr>
    <td>Cvendor</td>
    <td>Free form string defining the vendor of the example.</td>
    <td>xs:string</td>
    <td>optional</td>
  </tr>
</table>
<p>&nbsp;</p>

*/