Some updates to the modelling operations documentation

doc/modelling.rst

@@ -2,13 +2,13 @@ Modelling
 =========
 
 Modelling is the core activity in the Modelverse.
-A model is based on a meta-model, or a language, which, for the sake of this tutorial, assume to exist.
+A model is based on a meta-model, or a language, which, for the sake of this tutorial, we assume exists already.
 Throughout this tutorial, we will focus on how to instantiate a simple Petri Net model.
 We assume that our language has a notion of *Place*, *Transition*, *P2T* arc, and *T2P* arc.
 The *Place* has a *name* and *tokens*, the *Transition* has a *name*.
-Both the *P2T* and *T2P*"arcs have a *weight*.
+Both the *P2T* and *T2P* arcs have a *weight*.
 This information is stored in the metamodel, which we will define later on.
-For now, assume that the metamodel is stored in the Modelverse using the name *PetriNets*.
+For now, assume that the metamodel is stored in the Modelverse as *formalisms/PetriNets*.
 
 Model Management
 ----------------
@@ -24,6 +24,7 @@ Creating a new instance of PetriNets is simple, and can be done using the *model
 
 The first parameter of the operation indicates the name that we would like to give to our newly created model.
 This name is available to all users, and is therefore a unique identifier.
+Note that this operation creates a new model, and therefore the target location should be writable, as otherwise a *PermissionDenied* exception is raised.
 The second parameter is the metamodel that we want to use to conform to.
 The value needs to be a name that is available in the Modelverse, and readable to the current user.
 
@@ -37,11 +38,14 @@ To get a list of currently available models, users can query the Modelverse with
 
 This list contains the various entries in the specified location.
 Note that this operation does not specify anything about the permissions of the supplied entries.
-Entries that end with a forward slash (/) are folders, and can subsequently be listed::
+Entries that end with a forward slash (/) are folders, and can subsequently be listed (with or without trailing forward slash)::
 
     >>> model_list("formalisms")
     ["Bottom", "SimpleClassDiagrams", "Tracability", ...]
 
+    >>> model_list("formalisms/")
+    ["Bottom", "SimpleClassDiagrams", "Tracability", ...]
+
     >>> model_list("users/admin")
     []
 
@@ -55,6 +59,7 @@ Update
 
 Models can be updated in the sense that they can be moved.
 This is the operation *model_move*, which takes a model and moves it to the specified location.
+When invoked on a folder, the complete folder, including all subfolders, is moved to the new location.
 There is no output to this operation::
 
     >>> model_move("models/my_pn", "models/my_new_pn")
@@ -70,10 +75,13 @@ Model deletion is permanent and cannot be reverted::
 Modifying a model
 -----------------
 
-Apart from operations at the model management level, where models are considered as atomic, several operations are provided to operate on the model contents.
-We categorize them by their effects on the Modelverse: create, read, or delete.
-Updates are not allowed, and must be expanded in individual delete and create operation.
-Create and delete operations are only allowed when the user has write permission to the model, which users have by default on their own models.
+Apart from operations at the model management level, where models are considered as atomic, several operations are provided to operate on the model contents directly.
+We again categorize them by their effects on the Modelverse: create, read, or delete.
+Updates are not allowed, and must thus be expanded in individual delete and create operation.
+Create and delete operations are only allowed when the user has write permission to the model, which users have by default on models they created themselves.
+
+As will become clear, all these operations take the model in which they operate as first argument.
+Subsequent operations on the same model are optimized, offering a noticeable performance improvement.
 
 Create
 ^^^^^^
@@ -96,13 +104,20 @@ Create
         >>> instantiate("models/my_pn", "P2T", edge=("p1", "t1"))
         p2t1
 
+   Optionally, users can suggest an ID themselves, through the *ID* parameter.
+   Note that there is no guarantee that this will actually be the returned ID (e.g., if the ID is already in use)::
+
+        >>> instantiate("models/my_pn", "Place", ID="p123")
+        p123
+        >>> instantiate("models/my_pn", "Place", ID="p1")
+        p1_2
+
 2. *attr_assign* assigns attributes of a specific model element.
    For example, it specifies the name and number of tokens of our PetriNet place::
    
-        >>> instantiate("models/my_pn", "Place")
-        p1
-        >>> attr_assign("models/my_pn", "p1", "name", "place 1")
-        >>> attr_assign("models/my_pn", "p1", "tokens", 2)
+        >>> p1 = instantiate("models/my_pn", "Place")
+        >>> attr_assign("models/my_pn", p1, "name", "place 1")
+        >>> attr_assign("models/my_pn", p1, "tokens", 2)
 
    The value of the attribute can be any simple primitive: string, integer, float, or boolean.
    When the attribute already exists, its value is overwritten.