Updated interaction section

doc/interaction.rst

@@ -24,7 +24,7 @@ Modelverse Kernel (MvK)
 
 The Modelverse Kernel (MvK) is the execution core of the Modelverse, and connects to the Modelverse State to fetch the instructions to execute.
 All its execution information is stored in the MvS as well, and therefore it has to (theoretically) query the MvS for each and every instruction.
-It merely consists of a set of model transformation rules which take the current state of the MvS, and do a set of modifications on it.
+It merely consists of a set of model transformation rules which take the current state of the MvS, and does a transformation on it, similar to model transformations.
 Only developers will ever have to directly interface with the Modelverse Kernel.
 
 Modelverse Interface (MvI)
@@ -32,52 +32,60 @@ Modelverse Interface (MvI)
 
 The Modelverse Interface (MvI) is the actual interface used by most users of the Modelverse.
 It provides any type of interface, whether it be graphical, textual, or any other interface.
-While this is the component that users interact with, there should be no (meta-)modelling knowledge whatsoever in this part, as it is only responsible for providing a user-friendly interface to the Modelverse.
+While this is the component users interact with, there should be no (meta-)modelling knowledge whatsoever in this part, as it is only responsible for providing a user-friendly interface to the Modelverse operations.
+All meta-modelling related operations, such as model transformations, conformance checking, process enactment, and so on, are directly supported in the Modelverse and are available to the MvI through the use of the provided interface.
 This component can make use of the provided wrapper, which does the binding with the Modelverse.
 
 Necessary scripts
 -----------------
 
-The Modelverse consists of a set of scripts.
-For most users, there are only three relevant scripts, none of them taking parameters:
+The Modelverse consists of a set of scripts, stored in the *scripts* folder.
+For most users, there are only two relevant scripts, none of them taking mandatory parameters:
 
 1. *run_tests.py*, which runs all tests.
-2. *run_local_modelverse.py*, which starts up a local Modelverse server, combining the MvS and MvK.
-3. *prompt.py*, which connects to the local Modelverse and provides a minimal raw interface.
+2. *run_local_modelverse.py*, which starts up the Modelverse server, combining the MvS and MvK at the same machine. An optional argument can be passed to run the Modelverse on a specific port (default: 8001).
+
+While other scripts are present, they are mostly variations of the existing scripts or are only useful for Modelverse development purposes.
 
 Wrapper
 -------
 
-Most often, however, the Modelverse is not used using the raw interface.
-Therefore, additionally we provide a simple Python-based wrapper for the Modelverse, which can be included in arbitrary scripts.
+Most often, the Modelverse is not used using the raw interface it provides by default.
+Therefore, we additionally provide a simple Python-based wrapper for the Modelverse, which can be included in arbitrary scripts.
 As the Modelverse can run as a service, wrappers can be created in any language that supports XML/HTTPRequests.
-By default, a Python wrapper is provided, which is discussed in this documentation.
-This Python wrapper was used by a variety of MvI implementations supported today.
-Tools can include all Modelverse operations merely by including the *modelverse.py* file from the *wrappers* folder.
+By default, a Python and SCCDXML wrapper are provided, of which the Python interface is discussed in this documentation.
+The SCCDXML wrapper forms the basis for the Python wrapper and is similar in use.
+These wrappers are used by a variety of MvI implementations supported today, and indeed themselves encompass an MvI if they are used directly by the user (e.g., in batch processing of models).
+Tools can include all Modelverse operations merely by including the *modelverse.py* file from the *wrappers* folder (or including the SCCDXML model in *wrappers/classes/modelverse.xml*).
 It is this interface that is used throughout this documentation, although other interfaces are highly similar.
-Note that the Python interface is a synchronous, and therefore blocking, interface.
+Note that the Python interface is a synchronous (i.e., blocking) interface, and therefore not recommended for use in Graphical User Interfaces (GUI).
+The SCCDXML wrapper is asynchronous and perfectly suited for use in GUIs.
 
 The wrapper provides all necessary (meta-)modelling operations that can be used by the MvI.
 As the Modelverse is independent of its (visual/textual) user interface, we only discuss the Modelverse wrapper in this documentation.
-The wrapper functions are explained through the use of examples, in a tutorial-like fashion.
-A full overview of all wrapper functions is also provided at the end of the documentation.
+For an example use of the wrappers, we refer to the tests of the Modelverse (using all functionality of the wrapper) and the `Modelverse prototype GUI<https://msdl.uantwerpen.be/git/yentl/modelverse_GUI.git>`_.
+The wrapper functions are explained further in this documentation through the use of examples, in a tutorial-like fashion.
+A full overview of all Python wrapper functions is provided at the end of the documentation.
+
+Note that the Modelverse makes use of exceptions to signal unexpected behaviour.
+These are not covered in this tutorial, as their meaning is obvious from their name.
+All Modelverse exceptions inherit from the *ModelverseException*, which can be used as a catch-all.
 
 Initializing the Modelverse
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Before we start, we must connect to the Modelverse.
-This can be done by executing the operation *init*::
+This can be done throught the *init* function::
 
     >>> init("http://modelverse.uantwerpen.be")
 
 This assumes that there is a Modelverse running at the specified address.
-It is also possible to work fully locally.
-For that, you must start up a Modelverse at your own system by invoking the command::
+It is also possible to omit this optional argument, in which case a connection is made to localhost at port 8001 (i.e., the default when running locally).
+For that, you must first start up a Modelverse at your own system by invoking the command::
 
     python scripts/run_local_modelverse.py
 
 Afterwards, connect to the local Modelverse through the usual *init* operation.
-For a local Modelverse, the init can be left empty.
 This call might block for some time if the Modelverse server is still starting up::
 
     >>> init()
@@ -85,8 +93,7 @@ This call might block for some time if the Modelverse server is still starting u
 Logging in
 ^^^^^^^^^^
 
-Now that we are connected to the Modelverse, we need to log in.
-Without logging in, the Modelverse has no clue which operations are permitted, and which models are readable, or even writable.
+Now that we are connected to the Modelverse, we need to log in before any operations can be invoked.
 To log in, use the *login* operation::
 
     >>> login("yentl", "secret password")
@@ -96,3 +103,4 @@ When the username does not exist yet, it is created upon invocation.
 The provided password can be used in subsequent invocations of the Modelverse to login as this user again.
 
 If this command finished successfully, the Modelverse is ready to be used.
+The used operations will differ depending on the type of user you are.