i207 Reorder and rewrite chapter 3

src/reference/formal_and_informative/specC09_interpretation_of_encapsulation.rst → src/reference/formal_and_informative/specC_components.rst

@@ -1,4 +1,13 @@
-.. _specC09:
+
+.. ** PREVIOUSLY THIS WAS THE COMPONENT_REFERENCE SECTION **
+
+.. include:: ../sectionC_interpretation.inc
+  :start-after: marker_component_reference_start
+  :end-before: marker_component_reference_end
+
+.. include:: ../informative/informC04_component_reference.rst
+
+.. ** PREVIOUSLY THIS WAS THE INTERPRETATION OF ENCAPSULATIONS **
 
 .. include:: ../sectionC_interpretation.inc
   :start-after: marker_interpretation_of_encapsulation_start

src/reference/formal_and_informative/specC01_interpretation_of_imports.rst → src/reference/formal_and_informative/specC_imports.rst

@@ -1,4 +1,3 @@
-.. _specC01:
 
 .. include:: ../sectionC_interpretation.inc
   :start-after: marker_interpretation_of_imports_start

src/reference/formal_and_informative/specC_maths.rst

@@ -0,0 +1,12 @@
+
+.. include:: ../sectionC_interpretation.inc
+  :start-after: marker_interpretation_of_mathematics_start
+  :end-before: marker_interpretation_of_mathematics_end
+
+.. todo ../informative/informC08_interpretation_of_mathematics.rst
+
+.. include:: ../sectionC_interpretation.inc
+  :start-after: marker_interpretation_of_initial_values_start
+  :end-before: marker_interpretation_of_initial_values_end
+
+.. include:: ../informative/informC06_interpretation_of_initial_values.rst

src/reference/formal_and_informative/specC_models.rst

@@ -0,0 +1,6 @@
+
+.. include:: ../sectionC_interpretation.inc
+  :start-after: marker_interpretation_of_models_start
+  :end-before: marker_interpretation_of_models_end
+
+.. todo ../informative/informC_model.rst

src/reference/formal_and_informative/specC11_interpretation_of_variable_resets.rst → src/reference/formal_and_informative/specC_resets.rst

@@ -1,4 +1,3 @@
-.. _specC11:
 
 .. include:: ../sectionC_interpretation.inc
   :start-after: marker_interpretation_of_variable_resets_start

src/reference/formal_and_informative/specC03_interpretation_of_units.rst → src/reference/formal_and_informative/specC_units.rst

@@ -1,4 +1,3 @@
-.. _specC03:
 
 .. include:: ../sectionC_interpretation.inc
   :start-after: marker_interpretation_of_units_start
@@ -22,4 +21,14 @@
   :start-after: marker_interpretation_of_units_3
   :end-before: marker_interpretation_of_units_end
 
-.. include:: ../libcellml/libcellmlC03_interpretation_of_units.rst
+.. ** THIS IS WHERE THE UNITS_REFERENCE SECTION STARTS **
+
+.. include:: ../sectionC_interpretation.inc
+  :start-after: marker_units_reference_start
+  :end-before: marker_units_reference1
+
+.. include:: ../informative/informC02_units_reference.rst
+
+.. include:: ../sectionC_interpretation.inc
+  :start-after: marker_units_reference1
+  :end-before: marker_units_reference_end

src/reference/formal_and_informative/specC10_interpretation_of_map_variables.rst → src/reference/formal_and_informative/specC_variables.rst

@@ -1,4 +1,13 @@
-.. _specC10:
+
+.. ** PREVIOUSLY THIS WAS VARIABLE REFERENCES **
+
+.. include:: ../sectionC_interpretation.inc
+  :start-after: marker_variable_reference_start
+  :end-before: marker_variable_reference_end
+
+.. include:: ../informative/informC05_variable_reference.rst
+
+.. ** PREVIOUSLY THIS WAS INTERPRETATION OF MAP_VARIABLES **
 
 .. include:: ../sectionC_interpretation.inc
   :start-after: marker_interpretation_of_map_variables_start

src/reference/index_sectionC.rst

@@ -6,6 +6,12 @@ Interpretation
 
 .. toctree::
     :maxdepth: 1
-    :glob:
 
-    formal_and_informative/specC*
+    formal_and_informative/specC_models.rst
+    formal_and_informative/specC_units.rst
+    formal_and_informative/specC_components.rst
+    formal_and_informative/specC_variables.rst
+    formal_and_informative/specC_imports.rst
+    formal_and_informative/specC_maths.rst
+    formal_and_informative/specC_resets.rst
+

src/reference/sectionC_interpretation.inc

@@ -1,12 +1,40 @@
 .. _sectionC:
 
+
+.. marker_interpretation_of_models_start
+
+Interpretation of ``model`` elements
+------------------------------------
+
+.. container:: preamble
+
+  A *model* is a conceptual entity defining a system of equations.
+
+  A model is defined by a :code:`model` element.
+
+  A model has a name, determined by the :code:`name` attribute of its :code:`model` element.
+
+  A model contains zero or more units [LINK **TODO**].
+
+  A model contains zero or more components [LINK **TODO**].
+
+
+**TODO** Stuff about models should go here!
+
+.. marker_interpretation_of_models_end
+
+
 .. marker_interpretation_of_imports_start
 
 .. _specC_interpretation_of_imports:
 
 Interpretation of ``import`` elements
 -------------------------------------
 
+.. container:: preamble
+
+  **TODO** Preamble for imports goes here
+
 #. Each :code:`import` element present in a :ref:`CellML infoset<specA_cellml_infoset>` (the importing infoset) SHALL define a new and distinct instance of the CellML infoset which is referenced by the :code:`href` attribute (the imported infoset).
    This imported infoset instance SHALL provide the context in which the child of an import element (a :code:`units` or :code:`component` element) is defined and interpreted.
 
@@ -132,6 +160,18 @@ The term "units reference" refers to the value of a :code:`units_ref` attribute
 Interpretation of ``units`` elements
 ------------------------------------
 
+.. container:: preamble
+
+  A *units definition* is a conceptual entity representing physical units.
+
+  A units definition is defined by a :code:`units` element or an :code:`import units` element, or is one of the built-in units listed in the :ref:`Built-in Units table<table_built_in_units>`.
+
+  A units definition has a *name*, determined by the :code:`name` attribute of its :code:`units` element or :code:`import units` element, or by the "Name" column in the :ref:`Built-in Units table<table_built_in_units>`.
+
+  A units definition has a *unit reduction*, determined by the rules in section XYZ **TODO**.
+
+
+
 1. The :code:`units` element SHALL be interpreted as the product of its
    :code:`unit` element children, according to the following rules:
 
@@ -289,6 +329,11 @@ Effect of ``units`` on a ``variable``
 Interpretation of ``math`` elements
 -----------------------------------
 
+.. container:: preamble
+
+  **TODO** Preamble for maths and initial values goes here
+
+
 #. The following :code:`component` elements SHALL, for the purposes of this specification, be "pertinent component elements":
 
    #. All :code:`component` elements in the top-level :ref:`CellML infoset<specA_cellml_infoset>` for the :ref:`CellML model<specA_cellml_model>`;
@@ -306,11 +351,23 @@ Interpretation of ``math`` elements
 
 .. _specC_interpretation_of_encapsulation:
 
-
 Interpretation of ``encapsulation`` elements
 --------------------------------------------
 
-1. For the purposes of this specification, there SHALL be a "conceptual encapsulation digraph" in which there is EXACTLY one node for every component in the :ref:`CellML model<specA_cellml_model>`.
+.. container:: preamble
+
+  A *component* is a conceptual entity representing a group of variables.
+
+  A component is defined by a :code:`component` element or an :code:`import component` element.
+
+  A component has a *name*, determined by the :code:`name` attribute of its :code:`component` element or :code:`import component` element.
+
+  A component contains zero or more variables [LINK **TODO**].
+
+  A component contains zero or more encapsulated components, as defined in section ABC **TODO**.
+
+
+#. For the purposes of this specification, there SHALL be a "conceptual encapsulation digraph" in which there is EXACTLY one node for every component in the :ref:`CellML model<specA_cellml_model>`.
    Therefore the encapsulation digraph will not contain any loops.
 
 2. Where a :code:`component_ref` element appears as a child of another :code:`component_ref` element, there SHALL be an arc in the encapsulation digraph, and that arc SHALL be from the node corresponding to the component referenced by the parent :code:`component_ref` element, and to the node corresponding to the component referenced by the child :code:`component_ref` element.
@@ -339,7 +396,27 @@ Interpretation of ``encapsulation`` elements
 Interpretation of ``map_variables`` elements
 --------------------------------------------
 
-1.  For the purposes of this specification, the variable equivalence (conceptual) network SHALL be an undirected graph with one node for every :code:`variable` element in the :ref:`CellML model<specA_cellml_model>`.
+.. container:: preamble
+
+  A *variable* is a conceptual entity representing a mathematical variable.
+
+  A variable is defined by a :code:`variable` element.
+
+  A variable has a *name*, determined by the :code:`name` attribute of its :code:`variable` element.
+
+  A variable has *units*, determined by the :code:`units` attribute of its :code:`variable` element.
+  The value of the :code:`units` attribute of a :code:`variable` element must equal the name of a predefined unit, or a unit defined within the model.
+
+  A variable has an *initial value*, determined by the :code:`initial_value` attribute of its :code:`variable`.
+
+  A variable has an *interface*, determined by the :code:`interface` attribute of its :code:`variable` element.
+
+  A variable can be part of an *equivalent variable network*, as defined in section PQR **TODO**.
+
+  A variable can be used in equations, see section KLM **TODO**.
+
+
+#.  For the purposes of this specification, the variable equivalence (conceptual) network SHALL be an undirected graph with one node for every :code:`variable` element in the :ref:`CellML model<specA_cellml_model>`.
     The arcs of this graph SHALL be equivalences defined in the CellML model.
 
 .. marker_interpretation_of_map_variables_1
@@ -407,10 +484,14 @@ Interpretation of ``map_variables`` elements
 
 .. _specC_interpretation_of_variable_resets:
 
-
 Interpretation of ``reset`` elements
 ------------------------------------
 
+.. container:: preamble
+
+  **TODO** Preamble for resets goes here
+
+
 #. Each :code:`reset` element describes a change to be applied to the variable referenced by the :code:`variable` attribute when specified conditions are met during the simulation of the model.
 
 #. All :code:`reset` elements SHALL be considered sequentially for the connected variable set (see :ref:`Interpretation of map_variables<specC_interpretation_of_map_variables>`) to which the referenced variable belongs.

src/static/css/cellml.css

@@ -83,6 +83,20 @@ li {
     content: " -";
 }
 
+.preamble {
+    background: #ececec;
+    color: saddlebrown;
+    padding: 10px;
+
+    margin-top: 0;
+    margin-bottom: 15px;
+    margin-left: 0;
+    margin-right: 0;
+
+    line-height: 24px;
+    font-family: "Lato", "proxima-nova", "Helvetica Neue", "Arial", sans-serif;
+}
+
 .infospec {
     /* border-top: 1px solid #b9c6dd; */
     background: #e1eaf0;