data-parallel/vect-pragma.md

@@ -94,7 +94,7 @@ For a type constructor `T`, the pragma
 ```
 
 
-indicates that the type `T` should be vectorised and embeds no parallel arrays.  This is similar to where the vectoriser automatically decides to vectorise a type, but but no special vectorised representation needs to be generated as the type embeds no arrays.
+indicates that the type `T` should be vectorised and embeds no parallel arrays.  This is the same as where the vectoriser automatically decides to vectorise a type, but no special vectorised representation needs to be generated as the type embeds no arrays.  The purpose of this pragma is to enable the vectorisation of imported types from modules that where not compiled with vectorisation enabled.
 
 
 The data type constructor `T` that together with its constructors `Cn` may be used in vectorised code, where `T` and the `Cn` represent themselves in vectorised code. An example is the treatment of 'Bool'.  'Bool' together with 'False' and 'True' may appear in vectorised code and they remain unchanged by vectorisation.  (There is no need for a special representation as the values cannot embed any arrays.)
@@ -102,7 +102,9 @@ The data type constructor `T` that together with its constructors `Cn` may be us
 
 The type constructor `T` must be in scope, but it may be imported.  'PData' and 'PRepr' instances are automatically generated by the vectoriser.
 
-**TODO**
+**ALTERNATIVE:** This pragma simply means to treat an imported tycon as if it was defined in this module (and is automatically vectorised as usual).  This is what I just implemented.
+
+**OPEN QUESTION:**
 
 - Do we need to be able to specify that an imported type embedding arrays should be vectorised including the generation of a specialised right-hand side?
 
@@ -126,7 +128,7 @@ For a type constructor `T`, the pragma
 ```
 
 
-indicates that the type is scalar; i.e., it has no embedded arrays.  Note that the type cannot be parameterised (as we could not rule out that any of the type parameters at a usage site is an array type.)
+indicates that the type is scalar; i.e., it has no embedded arrays and its constructors can \*only\* be used in scalar code.  Note that the type cannot be parameterised (as we would not be able to rule out that a type parameter is instantiated with an array type at a usage site.)
 
 
 Due to this pragma declaration, `T` that may be used in vectorised code, where `T` represents itself.  However, the representation of `T` is opaque in vectorised code. An example is the treatment of `Int`.  `Int`s can be used in vectorised code and remain unchanged by vectorisation.  However, the representation of `Int` by the `I#` data constructor wrapping an `Int#` is not exposed in vectorised code.  Instead, computations involving the representation need to be confined to scalar code.
@@ -134,6 +136,9 @@ Due to this pragma declaration, `T` that may be used in vectorised code, where `
 
 The type constructor `T` must be in scope, but it may be imported.  The `PData` and `PRepr` instances for `T` need to be manually defined.  (For types that the vectoriser automatically determines that they don't need a vectorised version, instances for `PData` and `PRepr` are still generated automatically.)
 
+
+NB: The crucial difference between `{-# VECTORISE type T1 #-}` and `{-# VECTORISE SCALAR type T2 #-}` is that the \*representation\* (i.e., the constructors) of the latter can only be used in scalar code. However, the representation of both `T1` and `T2` does not get vectorised — so, both types are suitable for code that does not get vectorised due to vectorisation avoidance.
+
 **TODO**
 
 - For type constructors identified with this pragma, can we generate an `instance` of the `Scalar` type class automatically (instead of relying on it being in the library)?