data-parallel/vect-pragma.md

@@ -75,15 +75,37 @@ and so on.  (The variable `f` must have a proper function type.)
 
 ## The basic VECTORISE pragma for type constructors
 
+### Without right-hand side
+
+
+For a type constructor `T`, the pragma
+
+```wiki
+{-# VECTORISE type T #-}
+```
+
+
+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.
+
+
+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.)
+
+
+The type constructor `T` must be in scope, but it may be imported.  'PData' and 'PRepr' instances are automatically generated by the vectoriser.
+
+**TODO**
+
+- 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?
+
+### With right-hand side
+
 ```wiki
 {-# VECTORISE type T = ty #-}
 ```
 
 **TODO**
 
-- This isn' fully implemented yet.  (Implemented up to and including desugaring and being put into `ModGuts`, but not used in the vectoriser.)
-- We probably want two variants: one which just gives a tycon to vectorise and one also giving the vectorised tycon/type.  The first variant matches the default behaviour for locally defined data types, but enables to vectorise imported data types in subsequent modules.  (Eg, to vectorise data types from the Prelude without changing —or vectorising— the Prelude itself.)
-- Maybe don't have a rhs, but make this pragma mean that `T` should be vectorised as if the module containing `T` would have been vectorised.  (Post-hoc vectorisation of a data type.)
+- This isn't fully implemented yet.  (Implemented up to and including desugaring and being put into `ModGuts`, but not used in the vectoriser.)
 
 ## The VECTORISE SCALAR pragma for type constructors
 
@@ -98,6 +120,9 @@ 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.)
 
 
+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.
+
+
 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.)
 
 **TODO**