Give new structure to the Modelverse documentation, split in types of users

doc/bootstrap.rst

@@ -0,0 +1,20 @@
+Bootstrap
+=========
+
+Explain what the bootstrapping actually does
+
+Initial Code
+------------
+
+Explain the initial files and possibly link to them as well
+
+Initial Models
+--------------
+
+Explain the initial models and how they link together
+Explain the bootstrap compiler for models
+
+Altering the Bootstrap File
+---------------------------
+
+Explain how to alter bootstrap files and what needs to be done to change it

doc/concrete_syntax.rst

@@ -0,0 +1,25 @@
+Concrete Syntax
+===============
+
+Explain concrete syntax and why we want to have it
++ refer to paper
+
+Defining Concrete Syntax
+------------------------
+
+Explain how we define concrete syntax in the Modelverse
+
+MM_Rendered
+^^^^^^^^^^^
+
+Explain how MM_Rendered looks like and what it can be used for
+
+Modelverse Client
+-----------------
+
+Explain the simple client, and why it can be minimal
+
+Modelverse Perceptualization
+----------------------------
+
+Explain perceptualization and how it communicates with the Modelverse

doc/conformance.rst

@@ -0,0 +1,19 @@
+Conformance
+===========
+
+Explain the conformance relation in the context of the Modelverse
+
+Multi-Conformance
+-----------------
+
+Explain the notion of multi-conformance and why it is useful
+
+Metamodel Finding
+-----------------
+
+Explain why we can do metamodel finding, and why we would like it
+
+Conformance Bottom
+------------------
+
+Explain the use of conformance bottom, and how it contributes in combination with metamodel finding, or finding a binding

doc/developer.rst

@@ -0,0 +1,15 @@
+Using the Modelverse as a Developer
+===========================================
+
+.. toctree::
+   :maxdepth: 2
+
+   Scripts <scripts>
+   Wrappers <wrappers>
+   Model representation <model>
+   Modelverse components <components>
+   Communication models <communication_models>
+   Primitives <primitives>
+   Bootstrap <bootstrap>
+   Internals <internal>
+   Interfaces <interface>

doc/index.rst

@@ -13,20 +13,8 @@ Contents:
     
    Installation <installation>
    Basic interaction <interaction>
-   Modelling <modelling>
-   Metamodelling <metamodelling>
-   Transformations <transformations>
-   Operations <operations>
-   Services <services>
-   Concrete Syntax <concrete_syntax>
+   Types of user <users>
+   Modeller <modeller>
+   Language Engineer <language_engineer>
+   Developer <developer>
    Common problems and solutions <problems>
-   Modelling Language <modellanguage>
-   Action Language <actionlanguage>
-   Wrappers <wrappers>
-   Model representation <model>
-   Permission system <permissions>
-   Modelverse components <components>
-   Communication models <communication_models>
-   Primitives <primitives>
-   Internals <internal>
-   Interfaces <interface>

doc/language_engineer.rst

@@ -0,0 +1,13 @@
+Using the Modelverse as a Language Engineer
+===========================================
+
+.. toctree::
+   :maxdepth: 2
+
+   Metamodelling <metamodelling>
+   Model Langugage <languageengineer_modellanguage>
+   Transformations <transformations>
+   Operations <operations>
+   Services <services>
+   Concrete Syntax <concrete_syntax>
+   Conformance <conformance>

doc/modeller.rst

@@ -0,0 +1,10 @@
+Using the Modelverse as a Modeller
+==================================
+
+.. toctree::
+   :maxdepth: 2
+
+   Modelling <modelling>
+   Permission system <permissions>
+   Action Langugage <actionlanguage>
+   Model Langugage <modeller_modellanguage>

doc/modeller_modellanguage.rst

@@ -0,0 +1,209 @@
+Modelling Language
+==================
+
+Apart from the action language, the Modelverse also has a modelling language.
+With this language, models (*i.e.*, data) can be defined in addition to the algorithms.
+
+This language is still work in progress, but should be decent enough to construct simple metamodels and instantiate them.
+All models have the extension \*.mvc, indicating that they are models and should be compiled as such.
+
+If you want to create models interactively, such as with another tool, it is strongly recommended to use the interactive interface to do this, as the modelling language is completely static.
+
+Language description
+--------------------
+
+The modelling language defines data structures, which will be formed as models in the Modelverse.
+
+Several constructs are supported.
+
+Include
+^^^^^^^
+
+When combined with action language, for example with code fragments, the action language might require some includes of header files.
+To do this, the includes can be placed at the top of the hierarchy.
+The structure is as follows::
+
+        include "primitives.alh"
+
+Model
+^^^^^
+
+Every model is defined by first specifying the type of model to instantiate, followed by the name of the model to create.
+The name of the model can then later on be referenced in other models (as type, or for exporting).
+Within the model, all names of the type model can be used as types again.
+This is only used internally for bootstrapping purposes, so feel free to write whatever you want here.
+
+The structure is as follows::
+
+        SimpleClassDiagrams PetriNets{
+                ...
+        }
+
+All further operations happen inside such a definition.
+
+Instance
+^^^^^^^^
+
+A model consists of some instances.
+These instances are instances of types specified by the model that is the metaclass of the current model.
+
+The structure is as follows::
+
+        SimpleClassDiagrams PetriNets {
+                Class Place {
+                        ...
+                }
+        }
+
+Attribute
+^^^^^^^^^
+
+Each model instance can contain attributes.
+There are two kinds of attributes: defining attributes, or value attributes.
+
+For defining attributes, the structure is as follows::
+
+    Class A{
+        my_parameter : ParameterType
+    }
+
+This defines a parameter called *my_parameter* which is typed by *ParameterType*.
+*ParameterType* must always be a type defined in the type that is being instantiated.
+Even if this is a primitive, such as *Integer*, the metamodel must define what it calls an *Integer*.
+While this might seem bothersome, this clearly defines the notion of what a type means, without having to resort to the implementation.
+
+Value attributes are similar, but have a different syntax, and contain an actual value.
+Their structure is as follows::
+
+    A a{
+        my_parameter = 1
+    }
+
+They assign a value to a previously defined attribute.
+In this case, it is important that the value conforms to the type specified in the defining attribute.
+
+Merge with Action Language
+--------------------------
+
+It is of course possible to incorporate action language inside of a model.
+A typical use case for this is the definition of constraints or actions.
+Action language is surrounded by dollar signs ($), which causes the parser to redirect the text between dollar signs to the action language parser.
+All includes necessary for the compilation of the action code, must be provided at the top of the document.
+
+Examples
+--------
+
+Some simple examples of models are provided below.
+This code only makes the specified models available in code; to do something with these models, an algorithms has to read out the model and operate on it.
+
+Petri Net metamodel
+^^^^^^^^^^^^^^^^^^^
+
+A simple Petri Net metamodel can be created, based on the SimpleClassDiagrams metamodel.
+This looks like this::
+
+    import models/SimpleClassDiagrams as SCD
+
+    SCD PetriNets{
+        SimpleAttribute Natural {}
+        Class Place{
+            tokens : Natural
+        }
+        Class Transition{}
+        Association P2T (Place, Transition) {
+            weight : Natural
+        }
+        Association T2P (Transition, Place) {
+            weight : Natural
+        }
+    }
+
+    export PetriNets to models/PetriNets
+
+Note that in this metamodel, there is no constraint placed on the value of a Natural: it can literaly be anything.
+That is why usually, you want to place constraints on the value.
+In this case, the value needs to be an integer, and it must be larger than or equal to zero.
+Such constraints are written in the action language, surrounded by dollar signs::
+
+    import models/SimpleClassDiagrams as SCD
+    include "primitives.alh"
+
+    SCD PetriNets{
+        SimpleAttribute Natural {
+            $
+                if (bool_not(is_physical_int(self))):
+                    return "Natural has no integer value at " + name!
+                elif (integer_lt(self, 0)):
+                    return "Natural does not have a positive or zero value at " + name!
+                else:
+                    return "OK"!
+             $
+        }
+        Class Place{
+            tokens : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+        Class Transition{}
+        Association P2T (Place, Transition) {
+            weight : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+        Association T2P (Transition, Place) {
+            weight : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+    }
+
+Petri Net instance
+^^^^^^^^^^^^^^^^^^
+
+The previous metamodel can then be instantiated::
+
+    import models/PetriNets as PetriNets
+
+    PetriNets my_petrinet {
+        Place p1 {
+            tokens = 1
+        }
+        Place p2 {
+            tokens = 3
+        }
+        Transition t1 {}
+        P2T (p1, t1) {
+            weight = 1
+        }
+        T2P (t1, p2) {
+            weight = 2
+        }
+    }
+
+    export my_petrinet to models/my_petrinet
+
+Use in interactive interface
+----------------------------
+
+The interactive interface, such as the *prompt.py* script, can also invoke the model compiler.
+In this case, however, the import, export, and model type and model name parameters are ignored as they have to be defined and checked in the bigger context of the MvC.
+
+Internal use only
+-----------------
+
+Some constructs only make sense in the context of the bootstrap generation.
+These constructs can still be used at all times, but are meaningless.
+
+Import
+^^^^^^
+
+An import pulls in a model and makes it accessible using a simpler identifier.
+The structure is as follows::
+
+    import path/in/modelverse as my_model
+
+After this import, the model that was previously exported to *path/in/modelverse* becomes available as *my_model*.
+

doc/operations.rst

@@ -0,0 +1,24 @@
+Operations
+==========
+
+Describe the different types of operations
+
+Model Transformations
+---------------------
+
+Link back to previous section
+
+Manual Operations
+-----------------
+
+Explain manual operations: do the merge and split automatically
+
+Action Language
+---------------
+
+Explain how to do things programmatically
+
+Process Model
+-------------
+
+Explain how process model can combine different operations and manage data flow as well as control flow

doc/problems.rst

@@ -1,3 +1,16 @@
 Common problems and solutions
 =============================
 
+List set of common problems and their solution
+
+TODO: body_id is None
+---------------------
+
+Missing definition after declaration
+
+TODO: None has no length
+------------------------
+
+Operations done on a failed object, such as a dictionary read on a non-existing element
+
+TODO: find more

doc/users.rst

@@ -0,0 +1,24 @@
+Types of users
+==============
+
+Identify three types of users
+The next one implies all previous ones due to required knowledge
+
+Add figure showing the hierarchy maybe?
+
+Modeller
+--------
+
+Explain the job of the modeller
+
+Language Engineer
+-----------------
+
+Explain the job of the language engineer
+Explain why this includes all knowledge of the modeller as well, though in a different domain
+
+Developer
+---------
+
+Explain the job of the developer
+Explain why this includes all knowledge of the modeller and language engineer as well, though in a different domain