Merge pull request #21 from cellml/cellml-2-drafting

Update from upstream
cellml · Apr 6, 2020 · dc41839 · dc41839
2 parents bc2f10a + 064e788
commit dc41839
Show file tree

Hide file tree

Showing 75 changed files with 602 additions and 421 deletions.
diff --git a/src/conf.py b/src/conf.py
@@ -70,12 +70,10 @@
     'href_locator': ('https://www.w3.org/TR/2001/REC-xlink-20010627/#link-locators/%s', ''),
     'libcellml': ('https://libcellml.org/%s', ''),
     'libcellml_repo': ('https://github.com/cellml/libcellml.git%s', ''),
-    # TODO Update this when tutorials have a proper home.
-    'libcellml_tutorials': ('https://libcellml-tutorials.readthedocs.io/en/pr344_documentation/%s', ''),
     'libxml2': ('http://www.xmlsoft.org/%s', ''),
-    'mathml2help': ('https://www.w3.org/TR/MathML2/chapter4.html#id.4.2.1.3%s', ''),
+    'mathml2help': ('https://www.w3.org/TR/MathML2/chapter4.html%s', ''),
     'mathml2spec': ('http://www.w3.org/TR/2003/REC-MathML2-20031021/%s', ''),
-    'mathml2types': ('https://www.w3.org/TR/MathML2/chapter4.html#contm.typeattrib%s', ''),
+    'namespace_help': ('https://www.w3schools.com/xml/xml_namespaces.asp%s', ''),
     'opencor': ('https://opencor.ws/%s', ''),
     'pmr': ('https://models.physiomeproject.org/welcome/%s', ''),
     'python': ('https://www.python.org/%s', ''),
@@ -88,7 +86,6 @@
     'xml_1_1': ('http://www.w3.org/TR/xml11/%s', ''),
     'xml_infoset': ('http://www.w3.org/TR/2004/REC-xml-infoset-20040204/%s', ''),
     'xml_namespace_1_1': ('https://www.w3.org/TR/2006/REC-xml-names11-20060816/%s', ''),
-
 }
 
 # rst_epilog to define formatted, clickable code substitutions throughout.  It's included

diff --git a/src/reference/formal_and_informative/specA2.rst b/src/reference/formal_and_informative/specA2.rst
@@ -2,6 +2,22 @@
 
 .. include:: ../sectionA_definitions.inc
   :start-after: marker_cellml_information_sets_start
-  :end-before: marker_cellml_information_sets_end
+  :end-before: marker_cellml_information_sets_2
+
+.. include:: ../informative/informA2_2.rst
+
+.. include:: ../sectionA_definitions.inc
+  :start-after: marker_cellml_information_sets_2
+  :end-before: marker_cellml_information_sets_3
+
+.. include:: ../informative/informA2_3.rst
 
-.. include:: ../informative/informA2.rst
+.. include:: ../sectionA_definitions.inc
+  :start-after: marker_cellml_information_sets_3
+  :end-before: marker_cellml_information_sets_4
+
+.. include:: ../informative/informA2_4.rst
+
+.. include:: ../sectionA_definitions.inc
+  :start-after: marker_cellml_information_sets_4
+  :end-before: marker_cellml_information_sets_end
diff --git a/src/reference/formal_and_informative/specB01.rst b/src/reference/formal_and_informative/specB01.rst
@@ -18,4 +18,4 @@
 
 .. include:: ../informative/informB1_model3.rst
 
-.. include:: ../libcellml/libcellmlB1.rst
+.. todo ../libcellml/libcellmlB1.rst
diff --git a/src/reference/formal_and_informative/specB02.rst b/src/reference/formal_and_informative/specB02.rst
@@ -20,4 +20,4 @@
 
 .. include:: ../informative/informB2_import3.rst
 
-.. include:: ../libcellml/libcellmlB2.rst
+.. todo ../libcellml/libcellmlB2.rst
diff --git a/src/reference/formal_and_informative/specB03.rst b/src/reference/formal_and_informative/specB03.rst
@@ -12,4 +12,4 @@
   :start-after: marker_import_units_1
   :end-before: marker_import_units_end
 
-.. include:: ../libcellml/libcellmlB3.rst
+.. todo ../libcellml/libcellmlB3.rst
diff --git a/src/reference/formal_and_informative/specB04.rst b/src/reference/formal_and_informative/specB04.rst
@@ -7,4 +7,4 @@
 
 .. include:: ../informative/informB4_import_component1.rst
 
-.. include:: ../libcellml/libcellmlB4.rst
+.. todo ../libcellml/libcellmlB4.rst
diff --git a/src/reference/formal_and_informative/specB05.rst b/src/reference/formal_and_informative/specB05.rst
@@ -7,4 +7,4 @@
 
 .. include:: ../informative/informB5_units1.rst
 
-.. include:: ../libcellml/libcellmlB5.rst
+.. todo ../libcellml/libcellmlB5.rst
diff --git a/src/reference/formal_and_informative/specB06.rst b/src/reference/formal_and_informative/specB06.rst
@@ -13,4 +13,4 @@
 
 .. include:: ../informative/informB6_unit2.rst
 
-.. include:: ../libcellml/libcellmlB6.rst
+.. todo ../libcellml/libcellmlB6.rst
diff --git a/src/reference/formal_and_informative/specB07.rst b/src/reference/formal_and_informative/specB07.rst
@@ -19,4 +19,4 @@
 
 .. include:: ../informative/informB7_component3.rst
 
-.. include:: ../libcellml/libcellmlB7.rst
+.. todo ../libcellml/libcellmlB7.rst
diff --git a/src/reference/formal_and_informative/specB08.rst b/src/reference/formal_and_informative/specB08.rst
@@ -7,4 +7,4 @@
 
 .. include:: ../informative/informB8_variable1.rst
 
-.. include:: ../libcellml/libcellmlB8.rst
+.. todo ../libcellml/libcellmlB8.rst
diff --git a/src/reference/formal_and_informative/specB09.rst b/src/reference/formal_and_informative/specB09.rst
@@ -5,4 +5,4 @@
   :start-after: marker_reset_start
   :end-before: marker_reset_end
 
-.. include:: ../informative/informB9_reset1.rst
+.. todo .. include:: ../informative/informB9_reset1.rst
diff --git a/src/reference/formal_and_informative/specB12.rst b/src/reference/formal_and_informative/specB12.rst
@@ -29,8 +29,4 @@
   :start-after: marker_math_4
   :end-before: marker_math_end
 
-.. include:: ../libcellml/libcellmlB12_math.rst
-
-
-
-
+.. todo ../libcellml/libcellmlB12_math.rst
diff --git a/src/reference/formal_and_informative/specB15.rst b/src/reference/formal_and_informative/specB15.rst
@@ -25,8 +25,4 @@
 
 .. include:: ../informative/informB15_connection5.rst
 
-.. include:: ../libcellml/libcellmlB15_connection.rst
-
-
-
-
+.. todo ../libcellml/libcellmlB15_connection.rst
diff --git a/src/reference/formal_and_informative/specB16.rst b/src/reference/formal_and_informative/specB16.rst
@@ -13,5 +13,4 @@
 
 .. include:: ../informative/informB16_map_variables3.rst
 
-.. include:: ../libcellml/libcellmlB16_map_variables.rst
-
+.. todo ../libcellml/libcellmlB16_map_variables.rst
diff --git a/src/reference/formal_and_informative/specC01_interpretation_of_imports.rst b/src/reference/formal_and_informative/specC01_interpretation_of_imports.rst
@@ -4,4 +4,4 @@
   :start-after: marker_interpretation_of_imports_start
   :end-before: marker_interpretation_of_imports_end
 
-.. include:: ../informative/informC01_imports.rst
+.. todo ../informative/informC01_imports.rst
diff --git a/src/reference/formal_and_informative/specC02_units_reference.rst b/src/reference/formal_and_informative/specC02_units_reference.rst
@@ -8,4 +8,4 @@
   :start-after: marker_units_reference1
   :end-before: marker_units_reference_end
 
-.. include:: ../informative/informC02_units_reference.rst
+.. todo ../informative/informC02_units_reference.rst
diff --git a/src/reference/formal_and_informative/specC04_component_reference.rst b/src/reference/formal_and_informative/specC04_component_reference.rst
@@ -4,4 +4,4 @@
   :start-after: marker_component_reference_start
   :end-before: marker_component_reference_end
 
-.. include:: ../informative/informC04_component_reference.rst
+.. todo ../informative/informC04_component_reference.rst
diff --git a/src/reference/formal_and_informative/specC05_variable_reference.rst b/src/reference/formal_and_informative/specC05_variable_reference.rst
@@ -4,4 +4,4 @@
   :start-after: marker_variable_reference_start
   :end-before: marker_variable_reference_end
 
-.. include:: ../informative/informC05_variable_reference.rst
+.. todo ../informative/informC05_variable_reference.rst
diff --git a/src/reference/formal_and_informative/specC07_effect_of_units_on_variables.rst b/src/reference/formal_and_informative/specC07_effect_of_units_on_variables.rst
@@ -4,4 +4,4 @@
   :start-after: marker_effect_of_units_on_variables_start
   :end-before: marker_effect_of_units_on_variables_end
 
-.. include:: ../informative/informC07_effect_of_units_on_variables.rst
+.. todo ../informative/informC07_effect_of_units_on_variables.rst
diff --git a/src/reference/formal_and_informative/specC08_interpretation_of_mathematics.rst b/src/reference/formal_and_informative/specC08_interpretation_of_mathematics.rst
@@ -4,4 +4,4 @@
   :start-after: marker_interpretation_of_mathematics_start
   :end-before: marker_interpretation_of_mathematics_end
 
-.. include:: ../informative/informC08_interpretation_of_mathematics.rst
+.. todo ../informative/informC08_interpretation_of_mathematics.rst
diff --git a/src/reference/formal_and_informative/specC09_interpretation_of_encapsulation.rst b/src/reference/formal_and_informative/specC09_interpretation_of_encapsulation.rst
@@ -4,4 +4,4 @@
   :start-after: marker_interpretation_of_encapsulation_start
   :end-before: marker_interpretation_of_encapsulation_end
 
-.. include:: ../informative/informC09_interpretation_of_encapsulation.rst
+.. todo ../informative/informC09_interpretation_of_encapsulation.rst
diff --git a/src/reference/formal_and_informative/specC10_interpretation_of_map_variables.rst b/src/reference/formal_and_informative/specC10_interpretation_of_map_variables.rst
@@ -4,4 +4,4 @@
   :start-after: marker_interpretation_of_map_variables_start
   :end-before: marker_interpretation_of_map_variables_end
 
-.. include:: ../informative/informC10_interpretation_of_map_variables.rst
+.. todo ../informative/informC10_interpretation_of_map_variables.rst
diff --git a/src/reference/formal_and_informative/specC11_interpretation_of_variable_resets.rst b/src/reference/formal_and_informative/specC11_interpretation_of_variable_resets.rst
@@ -4,4 +4,4 @@
   :start-after: marker_interpretation_of_variable_resets_start
   :end-before: marker_interpretation_of_variable_resets_end
 
-.. include:: ../informative/informC11_interpretation_of_variable_resets.rst
+.. todo ../informative/informC11_interpretation_of_variable_resets.rst
diff --git a/src/reference/informative/informA1.rst b/src/reference/informative/informA1.rst
@@ -8,4 +8,43 @@
 
   .. container:: infospec
 
-    **TODO** Informal notes go here
+    .. container:: heading3
+
+      Namespaces
+
+    Namespaces are a way of making sure that names and definitions are interpreted within the right frame of reference.
+    In CellML, two namespaces are used.
+    These are the CellML namespace itself (which helps to define the :code:`units` elements as distinct from the XML default units system) and the MathML namespace used to interpret the :code:`math` elements.
+    For more information on namespaces in general, please refer to the :namespace_help:`W3 schools namespace page <>`, or for the MathML namespace please refer to the :mathml2help:`W3 MathML namespace <#inferf.namespace>` page.
+
+    .. container:: heading3
+
+      Unicode, Basic Latin, and European numerals
+
+    The Unicode project is an attempt to codify all of the symbols - alphabets, writings, even emojis - of all the languages of the world so that they can be interchangeable and interpreted by computers.
+    Since computers understand numbers rather than symbols, each character in each language is given a unique numerical code.
+    The codes themselves are arranged into blocks representing sets or alphabets of characters, and the Basic Latin alphabet is one of these.
+    It contains the upper and lowercase alphabet without decoration:
+
+      :code:`abcdefghijklmnopqrstuvwxyz` (symbols between :unicode:`0061` and :unicode:`007A`)
+      :code:`ABCDEFGHIJKLMNOPQRSTUVWXYZ` (symbols between :unicode:`0041` and :unicode:`005A`)
+
+    The European numerals are the Unicode set:
+
+      :code:`0123456789` (symbols between :unicode:`0030` and :unicode:`0039`)
+
+    In addition, CellML recognises four special characters:
+
+    - :code:`+` the plus sign (:unicode:`002B`),
+    - :code:`-` the minus sign (:unicode:`002D`),
+    - :code:`_` the underscore (:unicode:`005F`),
+    - :code:`.` the fullstop (:unicode:`002E`),
+
+    and the following whitespace characters:
+
+    - the space (:unicode:`0020`), 
+    - the tab (:unicode:`0009`), 
+    - the carriage return (:unicode:`000D`), and
+    - the line feed (:unicode:`000A`).  
+
+    Together these symbols define the only characters which can be interpreted into values for CellML element attributes and content. 
diff --git a/src/reference/informative/informA2.rst b/src/reference/informative/informA2.rst
diff --git a/src/reference/informative/informA2_2.rst b/src/reference/informative/informA2_2.rst
@@ -0,0 +1,72 @@
+.. _inform2_2:
+
+.. container:: toggle
+
+  .. container:: header
+
+    See more
+
+  .. container:: infospec
+
+    .. container:: heading3
+
+      Specific information items
+
+    There are different kinds of information stored in XML elements.
+    In the example below, the :code:`food_ideas` element has:
+
+    - :code:`title`, :code:`instructions`, :code:`ingredient` have *text* content (note that numbers like 1.0 are treated as text),
+    - :code:`ingredients` and :code:`food_ideas` have *element* contents, because they have child elements inside them,
+    - :code:`category` is an *attribute* of the :code:`recipe` element, and :code:`name` and :code:`units` are *attributes* of the :code:`ingredient` element, and
+    - the note within :code:`<!-- ... -->` comment tags is of an *unparsed* type and is ignored.
+
+    .. code-block:: xml
+
+      <food_ideas>
+        <recipe category="easy">
+          <title>Three ingredient scones</title>
+          <!-- These are so easy ... and if you're clever you'll save a little cream for whipping on the top! -->
+          <ingredients>
+            <ingredient name="cream" units="cup">1.0</ingredient>
+            <ingredient name="lemonade" units="cup">1</ingredient>
+            <ingredient name="selfraising_flour" units="cup">4</ingredient>
+          </ingredients>
+          <instructions>
+            Mix them all together using your hands.
+            You can use extra flour if you need to.
+            Bake at 220C for about 12 minutes or until golden.
+          </instructions>
+        </recipe>
+      </food_ideas>
+
+    Using CellML this could be written:
+
+    .. code-block:: xml
+
+      <model name="recipes">
+        <units name="cup">
+          <unit units="litre" prefix="milli" multiplier="250.0" />
+        </units>
+        <component name="Three_ingredient_scones">
+          <!-- Sigh ... if only it were possible for my computer to make me tea ... -->
+          <variable name="cream" cellml:units="cup" initial_value="1" />
+          <variable name="lemonade" cellml:units="cup" initial_value="1"  />
+          <variable name="selfraising_flour" cellml:units="cup" initial_value="5" />
+          <variable name="mixture" cellml:units="cup" />
+          <math>
+            <apply><eq/>
+              <ci>mixture</ci>
+              <apply><plus/>
+                <ci>cream</ci>
+                <ci>lemonade</ci>
+                <ci>selfraising_flour</ci>
+              </apply>
+            </apply>
+          </math>
+        </component>
+        <!-- BUT THIS IS NOT VALID! -->
+        <extra type="Danger_Will_Robinson">
+          Even though this looks like a valid XML text block, it's not allowed here.  Only those
+          elements which are explicitly specified as types of children are allowed!
+        </extra>
+      </model>
diff --git a/src/reference/informative/informA2_3.rst b/src/reference/informative/informA2_3.rst
@@ -0,0 +1,61 @@
+.. _inform2_3:
+
+.. container:: toggle
+
+  .. container:: header
+
+    See more
+
+  .. container:: infospec
+
+    .. container:: heading3
+
+      Semantic equivalence
+
+    The example below is identical to that in the previous "See more" block because:
+
+      - newlines, tabs, whitespace do not affect equivalence (except as part of text or attribute content),
+      - the order of element definition does not affect equivalence,
+      - the order of attribute definition does not affect equivalence, and
+      - comments do not affect equivalence.
+
+    .. code-block:: xml
+
+      <model name="recipes">
+        <component name="Three_ingredient_scones">
+          <!-- 
+             Comments are ignored ...
+             so here's a really long one about how much I now 
+             feel like yummy scones and jam and cream and tea ...
+          -->
+          
+          <!-- The order of child elements is ignored -->
+          <math>
+            <apply><eq/>
+              <ci>mixture</ci>
+              <apply><plus/>
+                <ci>cream</ci>
+                <ci>lemonade</ci>
+                <ci>selfraising_flour</ci>
+              </apply>
+            </apply>
+          </math>
+          
+          <!-- Whitespace (including tab, new line, and space) between attributes is ignored. -->
+          <variable 
+            name="selfraising_flour" 
+            cellml:units="cup" 
+          />
+           <variable         name="cream"           cellml:units="cup"          />
+
+          <!-- Whitespace (including tab, new line, and space) between elements is ignored. -->
+
+
+
+          <variable cellml:units="dimensionless"  name="mixture" /><variable name="lemonade" cellml:units="cup" />
+        </component>
+        <units name="cup">
+          <!-- The order of attributes within an element is ignored. -->
+          <unit multiplier="250.0" prefix="milli"  units="litre" />
+        </units>
+      </model>
diff --git a/src/reference/informative/informA2_4.rst b/src/reference/informative/informA2_4.rst
@@ -0,0 +1,15 @@
+.. _inform2_4:
+
+.. container:: toggle
+
+  .. container:: header
+
+    See more
+
+  .. container:: infospec
+
+    .. code-block:: none
+
+      <model name="myInvalidCellML" has other stuff in the element information item >
+        
+      </model>