--- /Users/yaya/NXtransformations.nxdl.xml	2016-10-05 14:34:15.000000000 -0400
+++ base_classes/NXtransformations.nxdl.xml	2016-10-05 10:51:17.000000000 -0400
@@ -24,7 +24,7 @@
 <definition xmlns="http://definition.nexusformat.org/nxdl/3.1" 
 	category="contributed"
 	name="NXtransformations" 
-	version="1.0"
+	version="1.1"
 	type="group" 
 	extends="NXobject"
 	ignoreExtraGroups="true"
@@ -33,19 +33,38 @@
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
 	>
+				<!--	
+						nxdl.xsd rules do not allow us to show this as a variable name
+						- we'll use AXISNAME in ALL CAPS for consistency with the
+						use in NXDATA.  We'll use AXISUNITS for the units appropriate
+						to the type of axis.
+				-->
 
 	<doc>
-		Collection of translations and rotations to describe a geometry
+		Collection of axis-based translations and rotations to describe a geometry.
+		May also contain general axes that do not move.
 		
-		A sequence of transformations lists the
+		A nested sequence of transformations lists the
 		offset and rotation steps needed to describe the position and orientation
 		of any movable or fixed device.
 
-		This class will usually contain all axes of a sample stage or goniometer.
+		There will be one or more transformations (axes)  defined by one or more fields
+		for each transformation.  The all-caps name AXISNAME designates the
+		particular axis generating a transformation (e.g. a rotation axis or a translation
+		axis or a general axis).   The all-caps name AXISUNITS designates the
+		units appropriate to the transformation_type value, i.e. ``NX_LENGTH`` for
+		``translation``, ``NX_ANGLE`` for ``rotation``, and ``NX_UNITLESS`` for
+		``general``.
+
+		This class will usually contain all axes of a sample stage or goniometer or
+		a detector.  The NeXus default McSTAS coordinate frame is assumed, but additional
+		useful coordinate axes may be defined as general axes.
 
 		The entry point (``depends_on``) will be outside of this class and point to a
 		field in here. Following the chain may also require following ``depends_on`` 
-		links to transformations outside, for example to a common base table.
+		links to transformations outside, for example to a common base table.  If
+		a relative path is given, it is relative to the group enclosing the ``depends_on``
+		specification.
 		
 		..
 			Given an entry point :math:`\vec{p_i}`, the point :math:`\vec{p_{i+1}}` 
@@ -67,41 +86,83 @@
 		This entire explanation is not clear.
 		-->
 
-	<field name="TRANSFORMATION" nameType="any" type="NX_NUMBER" maxOccurs="unbounded">
+	<field name="AXISNAME" nameType="any" units="AXISUNITS" type="NX_NUMBER" maxOccurs="unbounded">
 		<doc>
 			Units need to be appropriate for translation or rotation
 			
-			The name of this field is not defined.  The user is free to use any name
-			that does not cause confusion.  When using more than one TRANSFORMATION field,
+			The name of this field is not forced.  The user is free to use any name
+			that does not cause confusion.  When using more than one AXISNAME field,
 			make sure that each field name is unique in the same group, as required
 			by HDF5.
 		</doc>
 		<attribute name="transformation_type">
+			<doc>
+				The transformation_type may be ``translation``, in which case the
+				values are linear displacements along the axis, ``rotation``,
+				in which case the values are angular rotations around the axis,
+				or ``general`` for an axis that simply helps to define a coordinate
+				frame and does not have any displacement values.
+			</doc>
 			<enumeration>
 				<item value="translation" />
 				<item value="rotation" />
+				<item value="general" />
 			</enumeration>
 		</attribute>
-		<attribute name="vector" type="NX_NUMBER">
+		<attribute name="vector" units="NX_DIMENSIONLESS" type="NX_NUMBER">
 			<doc>
-				Three values that define the axis for this transformation
+				Three values that define the axis for this transformation.
+				The axis should be normalized to unit length, making it
+				dimensionless.  For ``rotation`` axes, the direction should be
+				chosen for a right-handed rotation with increasing angle.
+				For ``translation`` axes the direction should be chosen for
+				increasing displacement.
 			</doc>
+			<dimensions rank="1" value="3" />
 		</attribute>
 		<attribute name="offset" type="NX_NUMBER">
 			<doc>
 				A fixed offset applied before the transformation (three vector components).
 			</doc>
+			<dimensions rank="1" value="3" />
 		</attribute>
 		<attribute name="offset_units" type="NX_CHAR">
 			<doc>
-				Units of the offset.
+				Units of the offset.  Values should be consistent with NX_LENGTH.
 			</doc>
 		</attribute>
 		<attribute name="depends_on" type="NX_CHAR">
 			<doc>
-				Points to the name of the next element in the geometry chain.
+				Points to the path to a field defining the axis on which this
+				depends or the string ".".
 			</doc>
 		</attribute>
 	</field>
-</definition>
+	<field name="AXISNAME_end" units="AXISUNITS" nameType="any" type="NX_NUMBER" minOccurs="0">
+		<doc>
+			AXISNAME_end is a placeholder for a name constructed from the actual
+			name of an axis to which ``_end`` has been appended.
+
+			The values in this field are the end points of the motions that start
+			at the corresponding positions given in the AXISNAME field.
+		</doc>
+	</field>
+	<field name="AXISNAME_range" units="AXISUNITS"  nameType="any" type="NX_NUMBER" minOccurs="0">
+		<doc>
+			AXISNAME_range is a placeholder for a name constructed from the actual
+			name of an axis to which ``_range`` has been appended.
+
+			The values in this optional field are differences between the values
+			in the field AXISNAME_end and the field AXISNAME.
+		</doc>
+	</field>
+	<field name="AXISNAME_average_range" units="AXISUNITS"  nameType="any" type="NX_NUMBER" minOccurs="0">
+		<doc>
+			AXISNAME_average_range is a placeholder for a name constructed from the actual
+			name of an axis to which ``_average_range`` has been appended.
 
+			The value of this optional field is the average of the differences between the
+			values in the field AXISNAME_end and the field AXISNAME.			
+		</doc>
+	</field>
+</definition>
