feat: implement issue 335 to add environments section below package (#337)

Co-authored-by: Joachim Krech <[email protected]>

Author: OCHSTM

doxygen/pack.dxy

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Open-CMSIS-Pack"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "Version 1.7.43"
+PROJECT_NUMBER         = "Version 1.7.44"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

doxygen/src/General.txt

@@ -78,6 +78,12 @@ The following sections provide more information:
     <th>Version</th>
     <th>Description</th>
   </tr>
+  <tr>
+    <td>1.7.44</td>
+    <td>
+      - added optional 'environments' section below package element to hold environment-specific information pertaining to the package as a whole
+    </td>
+  </tr>
   <tr>
     <td>1.7.43</td>
     <td>

doxygen/src/components_schema.txt

@@ -1218,9 +1218,9 @@ The possible values are not imposed by this specification.
 
 \section element_component_environments /package/.../environments
 
-The group <b>environments</b> can appear in \ref element_component "component" element. This group is the frame for defining individual \ref element_component_environment "environment".
+The group <b>environments</b> can appear in \ref element_component "component" element and in \ref element_package "package" element. This group is the frame for defining individual \ref element_component_environment "environment".
 
-\b Example:
+\b Example #1:
 \code
 <package>
   ...
@@ -1235,6 +1235,21 @@ The group <b>environments</b> can appear in \ref element_component "component" e
 </package>
 \endcode
 
+\b Example #2: describing "tool-x" and "tool-y" custom information applicable to the whole pack:
+\code
+<package>
+  <environments>
+    <environment name="tool-x">
+      ...
+    </environment>
+    <environment name="tool-y">
+      ...
+    </environment>
+  </environments>
+  ...
+</package>
+\endcode
+
 <p>&nbsp;</p>
 
 <table class="cmtable" summary="Element: Environments">
@@ -1250,6 +1265,10 @@ The group <b>environments</b> can appear in \ref element_component "component" e
     <td>\ref element_component "component"</td>
     <td colspan="3">\ref element_component "/package/components/bundle/component"</td>
   </tr>
+  <tr>
+    <td>\ref element_package "package"</td>
+    <td colspan="3">\ref element_package "/package"</td>
+  </tr>
   <tr>
     <th>Child&nbsp;Elements</th>
     <th>Description</th>

doxygen/src/pdsc_format.txt

@@ -63,6 +63,7 @@ The \ref packFormat is structured using grouping elements and contains the follo
  - \subpage element_package_description "<description>": brief description of the software pack with optional link to Markdown overview documentation.
  - \subpage element_ECCN "<ECCN>": section listing Export Control Classification Numbers (ECCN) for EU and US.
  - \subpage element_keywords "<keywords>": lists keywords to search for packages. Can be used for search engines.
+ - \ref element_component_environments "environments": Grouping element for environments information. Each inner \ref element_component_environment "environment" element may be used to provide tool-specific information pertaining to the package as a whole.
  - \subpage element_repository "<repository>": specifies the URL and repository type of a public repository where the pack originates from.
  - \subpage element_dominate "<dominate>": the pack contains one or more device, API, or component that overrules other packs with identical items.
  - \subpage element_releases "<releases>": lists release versions with descriptions.
@@ -99,7 +100,7 @@ This example of a *.pdsc File explains the sections, particularly how dependenci
 The basic package information captures the package vendor, the package name, a brief description of the package, and the schema version.
 Additional elements support the logistics of handling packages. The url specifies the origin of the description. It may be left empty if
 the pack will not be uploaded onto a web server. A license file might point to license agreements. A list of keywords
-assists searching for packages.
+assists searching for packages. An optional environments element can be used to list environment-specific information.
 
 \b Example:
 \code
@@ -127,6 +128,15 @@ assists searching for packages.
     <keyword>STM32F2xx</keyword>
   </keywords>
 
+  <environments>
+    <environment name="tool-x">                                               <!-- tool-x specific information for the whole package -->
+      ...
+    </environment>
+    <environment name="tool-y">                                               <!-- tool-y specific information for the whole package -->
+      ...
+    </environment>
+  </environments>
+
   <taxonomy>                                                                  <!-- class and group descriptions -->
     <description Cclass="Board Support">
       Generic Interfaces and Templates for Evaluation and Development Boards
@@ -307,6 +317,12 @@ assists searching for packages.
     <td>group</td>
     <td>0..1 </td>
   </tr>
+  <tr>
+    <td>\ref element_component_environments "environments"</td>
+    <td>Grouping element for environments information. Each inner \ref element_component_environment "environment" element may be used to provide tool-specific information pertaining to the package as a whole.</td>
+    <td>group</td>
+    <td>0..1</td>
+  </tr>
   <tr>
     <td>\ref element_generators "generators"</td>
     <td>Specifies generator tools that have been used to create components.</td>

schema/PACK.xsd

@@ -18,13 +18,15 @@
   limitations under the License.
 
 
-  $Date:        12. Nov 2024
-  $Revision:    1.7.43
+  $Date:        14. Nov 2024
+  $Revision:    1.7.44
   $Project: Schema File for Package Description File Format Specification
 
   Package file name convention <vendor>.<name>.<version>.pack
-  SchemaVersion=1.7.43
+  SchemaVersion=1.7.44
 
+  14. Nov 2024: v1.7.44
+   - added optional 'environments' section below package element to hold environment-specific information pertaining to the package as a whole
   12. Nov 2024: v1.7.43
    - added optional 'ECCN' section for EU and US export control classification numbers
   10. Oct 2024: v1.7.42
@@ -133,7 +135,6 @@
    - added 'Star' to DcoreEnum
   1. December 2020: v1.7.2
    - added 'XC' to CompilerEnumType to enable use of Microchip XC32 compiler
-
   13. November 2020: v1.7.1
   - undo removing deprecated attributes as they are still used in latest pdsc file versions:
     DeviceVendorEnum: Lapis Semiconductor, DeviceVendorEnum: Pname, BoardReferenceType: Dvendor, Dname
@@ -241,7 +242,7 @@
 
 -->
 
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="qualified" version="1.7.43">
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="qualified" version="1.7.44">
 
   <!-- NonNegativeInteger specifies the format in which numbers are represented in hexadecimal or decimal format -->
   <xs:simpleType name="NonNegativeInteger">
@@ -2296,6 +2297,15 @@
         <xs:element name="changelogs" type="ChangelogsType" minOccurs="0" />
         <!-- keyword for Search Engine Indexing (e.g. Google) -->
         <xs:element name="keywords" type="KeywordsType" minOccurs="0" />
+        <!-- extension point to add information pertaining to the package as a whole -->
+        <!-- list of environments (elements containing information that is specific for a development tool) -->
+        <xs:element name="environments" minOccurs="0" >
+          <xs:complexType>
+            <xs:sequence>
+              <xs:element name="environment" type="EnvironmentType" minOccurs="1" maxOccurs="unbounded" />
+            </xs:sequence>
+          </xs:complexType>
+        </xs:element>
         <!-- generators are tools and utilities that are used to generate software components -->
         <xs:element name="generators" type="GeneratorsType" minOccurs="0" />
         <!-- definition of devices including references to device support files contained in package -->