make the "axes" section more readable

base_classes/NXdata.nxdl.xml

@@ -73,21 +73,25 @@
 		.. index:: axes (attribute)
 		.. index:: coordinates
 
-		The :ref:`AXISNAME </NXdata/AXISNAME-field>` fields contain the coordinates associated to the :ref:`data </NXdata/DATA-field>` values.
-		The names of the fields to be used as coordinates are provided by the :ref:`axes </NXdata@axes-attribute>` attribute.
-		One :ref:`AXISNAME </NXdata/AXISNAME-field>` field provides the coordinates along one or more :ref:`data </NXdata/DATA-field>` dimensions.
-		The rank of an :ref:`AXISNAME </NXdata/AXISNAME-field>` must be equal to the number of dimensions it spans.
-
-		The :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes define the :ref:`data </NXdata/DATA-field>` dimension(s) spanned
-		by the corresponding :ref:`AXISNAME </NXdata/AXISNAME-field>` fields. When the :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attribute
-		is missing for an :ref:`AXISNAME </NXdata/AXISNAME-field>` field, it defaults to the index or indices of the :ref:`AXISNAME </NXdata/AXISNAME-field>`
-		name in the list of axis names provided by the :ref:`axes </NXdata@axes-attribute>` attribute. For this reason the string "." can be used in the
-		:ref:`axes </NXdata@axes-attribute>` list as a placeholder in order for other axis names to have the desired index.
-
-		It is not recommended to omit the :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes as ambiguity in assigning axes
-		to data dimensions can arise. In addition it is strongly discouraged to define the :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attribute
-		for some :ref:`AXISNAME </NXdata/AXISNAME-field>` fields but not for others. A reader application can easily deal with this but it complicates human interpretation.
-
+		The :ref:`AXISNAME </NXdata/AXISNAME-field>` fields contain the axis coordinates associated with the data values. The names of all :ref:`AXISNAME </NXdata/AXISNAME-field>`
+		fields are listed in the :ref:`axes </NXdata@axes-attribute>` attribute.
+
+		`Rank`
+
+		:ref:`AXISNAME </NXdata/AXISNAME-field>` fields are typically one-dimensional arrays, which annotate one of the dimensions. However, the fields can also have a rank greater than 1,
+		in which case the rank of each :ref:`AXISNAME </NXdata/AXISNAME-field>` must be equal to the number of data dimensions it spans.
+
+		`Dimensions`
+
+		The data dimensions annotated by an :ref:`AXISNAME </NXdata/AXISNAME-field>` field are defined by the :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attribute.
+		When this attribute is missing, the position(s) of the :ref:`AXISNAME </NXdata/AXISNAME-field>` string in the :ref:`axes </NXdata@axes-attribute>` attribute are used.
+
+		When all :ref:`AXISNAME </NXdata/AXISNAME-field>` fields are one-dimensional, and none of the data dimensions have more than one axis, the
+		:ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes are often omitted. If one of the data dimensions has no :ref:`AXISNAME </NXdata/AXISNAME-field>` field,
+		the string “.” can be used in the corresponding index of the axes list.
+
+		When providing :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes it is recommended to do it for all axes.
+
 		**Uncertainties:**
 
 		Standard deviations on data values as well as coordinates can be provided by :ref:`FIELDNAME_errors </NXdata/FIELDNAME_errors-field>` fields