doc: add a note on isl_dim_type

Signed-off-by: Sven Verdoolaege <skimo@kotnet.org>

diff --git a/doc/user.pod b/doc/user.pod
index afd0f2c..3ef99a0 100644 (file)
--- a/doc/user.pod
+++ b/doc/user.pod
@@ -565,8 +565,23 @@ corresponding C<isl_id> is alive.
 
 =head2 Spaces
 
-Whenever a new set or relation is created from scratch,
+Whenever a new set, relation or similiar object is created from scratch,
 the space in which it lives needs to be specified using an C<isl_space>.
+Each space involves zero or more parameters and zero, one or two
+tuples of set or input/output dimensions.  The parameters and dimensions
+are identified by an C<isl_dim_type> and a position.
+The type C<isl_dim_param> refers to parameters,
+the type C<isl_dim_set> refers to set dimensions (for spaces
+with a single tuple of dimensions) and the types C<isl_dim_in>
+and C<isl_dim_out> refer to input and output dimensions
+(for spaces with two tuples of dimensions).
+Local spaces (see L</"Local Spaces">) also contain dimensions
+of type C<isl_dim_div>.
+Note that parameters are only identified by their position within
+a given object.  Across different objects, parameters are (usually)
+identified by their names or identifiers.  Only unnamed parameters
+are identified by their positions across objects.  The use of unnamed
+parameters is discouraged.
 
        #include <isl/space.h>
        __isl_give isl_space *isl_space_alloc(isl_ctx *ctx,