Merge pull request #1489 from nexusformat/1435-complex-units-like-eV-…

…per-mm

complex units, such as eV/mm

manual/source/nxdl-types.rst

@@ -41,7 +41,29 @@ Unit categories in NXDL specifications
 describe the expected type of units for a NeXus field. They should describe
 valid units consistent with the :ref:`NeXus units <Design-Units>` section.
 The values for unit categories are restricted (by
-an enumeration) to the following table.
+an enumeration) to the table below.
+
+.. admonition:: When no unit category applies...
+
+    If a unit is not provided by the list of NeXus unit categories, instead
+    of providing a category, a field element can include an example of the
+    units directly.
+
+    The example does not constrain the scale of the units. For example, if
+    the unit is ``eV/mm``, the user could specify in a data file ``eV/cm``,
+    or any other unit that is convertible to the example given.
+
+    .. rubric:: Example
+    .. code-block:: xml
+
+        <field name="monochromator_dispersion" units="eV/mm">
+
+    It is recommended that users and application developers check if their units
+    and their unit examples adhere to the UDUNITS standard.  [#]_
+
+    Conformance is not validated at this time.
+
+    .. [#] https://www.unidata.ucar.edu/software/udunits/
 
 ..  Generated from ../nxdlTypes.xsd via a custom Python tool
     ../../utils/units2rst.py ../../nxdlTypes.xsd > units.table

nxdl.xsd

@@ -692,9 +692,25 @@ https://stackoverflow.com/a/48980995/1046449 -->
 					<xs:annotation>
 						<xs:documentation>
 							String describing the engineering units.
-							The string should be appropriate for the value
-							and should conform to the NeXus rules for units.
+							The string should be appropriate for the value.
+
+							* If a unit is not provided by the list of NeXus 
+							  unit categories, instead of providing a category, 
+							  a field element can include an example of the 
+							  units directly.
+
+							* The example does not constrain the scale of the 
+							  units. For example, if the unit is ``eV/mm``, the
+							  user could specify in a data file ``eV/cm``, or any 
+							  other unit that is convertible to the example given.
+
+							It is recommended that users and application developers 
+							check if their units and their unit examples adhere to 
+							the UDUNITS standard.  [#]_
+
 							Conformance is not validated at this time.
+
+							.. [#] https://www.unidata.ucar.edu/software/udunits/
 						</xs:documentation>
 					</xs:annotation>
 				</xs:attribute>

nxdlTypes.xsd

@@ -44,6 +44,7 @@
 
 				They should describe valid units consistent with
 				the manual section on NeXus units (based on UDUNITS).
+
 				Units are not validated by NeXus.
 			</xs:documentation>
 		</xs:annotation>
@@ -81,6 +82,7 @@
 			nxdl:NX_VOLUME
 			nxdl:NX_WAVELENGTH
 			nxdl:NX_WAVENUMBER
+			xs:string
 			" />
 	</xs:simpleType>