Upgrade examples - add explanation to XML

examples/DDCAD/compact/IR_assy_all_colour.xml

@@ -9,6 +9,7 @@
      # For the list of contributors see $DD4hepINSTALL/doc/CREDITS.
      #
      #==========================================================================
+
 -->
 
   <includes>
@@ -18,10 +19,23 @@
   <detectors>
     <detector id="1" name="Shape_STL" type="DD4hep_TestShape_Creator">
       <check>
-        <shape type="CAD_MultiVolume" ref="${DD4hepExamplesINSTALL}/examples/DDCAD/models/STL/IR_assy_all_colour.stl" unit="cm">
-	  <volume id="0" name="s1" vis="Shape3_vis">
-          </volume>
- 
+	<!-- If you supply materials and visualisation attributes to the shape:
+	     1) The material attribute in the <shape/> element will be applied 
+	        to all sub-volumes without an explicit material attribute in the 
+   	        <volume/> element.
+	     2) dto. the material cchild in the <shape/> element.
+	     3) The material attribute in the <volume/> element applies 
+	        ONLY to the volume specified. This allows to specify a separate 
+                material for each sub-volume in multi-volume CADs.
+             4) The vis attribute in the  <volume/> element applies 
+	        ONLY to the volume specified. The name identifies a dd4hep vis object.
+        -->
+        <shape type="CAD_MultiVolume"
+	       ref="${DD4hepExamplesINSTALL}/examples/DDCAD/models/STL/IR_assy_all_colour.stl"
+	       unit="cm"
+	       material="Iron">
+	  <!-- alternative:  <material name="Iron"/>  -->
+	  <volume id="0" name="s1" vis="Shape3_vis" material="Gold"/>
         </shape>
       </check>
 

examples/DDCAD/compact/MultiShape_MS3D_jeep.xml

@@ -18,8 +18,27 @@
   <detectors>
     <detector id="1" name="Shape_OBJ" type="DD4hep_TestShape_Creator">
       <check>
-        <shape type="CAD_MultiVolume" ref="${DD4hepExamplesINSTALL}/examples/DDCAD/models/MS3D/jeep1.ms3d" unit="cm">
+ 	<!-- The <envelope/> element defines an envelope volume for the 
+	     contained subvolumes defined by the <volume/> elements.
+	     The element informationm id fed to a plugin of type 
+	     "DD4hep_StdVolume".
+	     See <DD4hep>/DDCore/src/XML/Utilities.cpp for 
+	     details about possible arguments.
 
+             If you supply materials and visualisation attributes to the shape:
+	     1) The material attribute in the <shape/> element will be applied 
+	        to all sub-volumes without an explicit material attribute in the 
+   	        <volume/> element.
+	     2) dto. the material cchild in the <shape/> element.
+	     3) The material attribute in the <volume/> element applies 
+	        ONLY to the volume specified. This allows to specify a separate 
+                material for each sub-volume in multi-volume CADs.
+             4) The vis attribute in the  <volume/> element applies 
+	        ONLY to the volume specified. The name identifies a dd4hep vis object.
+        -->
+	<shape type="CAD_MultiVolume"
+	       ref="${DD4hepExamplesINSTALL}/examples/DDCAD/models/MS3D/jeep1.ms3d"
+	       unit="cm">
           <!--      Envelope definition
                     This is optional: By default the child volumes are placed in an assembly.
           -->