DOC #1003 wording and indices

nexusformat · Mar 7, 2022 · 66d9168 · 66d9168
1 parent 44a1a5d
commit 66d9168
Show file tree

Hide file tree

Showing 5 changed files with 306 additions and 276 deletions.
diff --git a/base_classes/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml
@@ -64,12 +64,16 @@
 	</attribute>
 	<attribute name="signal">
 		<doc>
+			.. index:: find the default plottable data
 			.. index:: plotting
+			.. index:: signal attribute value
 
-			Declares which dataset is the default. 
-			The value is the name of the dataset to be plotted.
-			A field of this name *must* exist (either as dataset 
-			or as a link to a dataset).
+			Declares which NeXus field (HDF5 dataset) is the default. 
+			The value is the name of the NeXus field to be plotted.
+			A field of this name *must* exist (either as a NeXus field 
+			or as a link to a NeXus field).
+			The value must match the :ref:`regular expression pattern for NXDL
+			group and field names &lt;validItemName>`.
 
 			It is recommended (as of NIAC2014) to use this attribute
 			rather than adding a signal attribute to the dataset.
@@ -191,7 +195,7 @@
 		      mr: float[100]  --> the default independent data
 
 		  The field named in the ``signal`` attribute **must** exist, either
-		  directly as a dataset or defined through a link.
+		  directly as a NeXus field (HDF5 dataset) or defined through a link.
 
 		* The group ``axes`` attribute will name the
 		  *dimension scale* associated with the plottable data.
@@ -308,9 +312,9 @@
 
 			This pattern of using ``VARIABLE_errors`` can be used 
 			throughout a NeXus data file to associate uncertainties 
-			with a dataset named ``VARIABLE``.  This pattern also 
+			with a field named ``VARIABLE``.  This pattern also 
 			applies to other relationships such as ``VARIABLE_resolutions``
-			to connect additional data with a certain dataset. 
+			to connect additional data with a certain field. 
 		</doc>
 		<dimensions rank="1">
 			<doc>

diff --git a/base_classes/NXentry.nxdl.xml b/base_classes/NXentry.nxdl.xml
@@ -2,9 +2,9 @@
 <?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
 <!--
 # NeXus - Neutron and X-ray Common Data Format
-# 
+#
 # Copyright (C) 2008-2022 NeXus International Advisory Committee (NIAC)
-# 
+#
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
 # License as published by the Free Software Foundation; either
@@ -21,8 +21,8 @@
 #
 # For further information, see http://www.nexusformat.org
 -->
-<definition name="NXentry" 
-	type="group" 
+<definition name="NXentry"
+	type="group"
 	extends="NXobject"
 	category="base"
 	xmlns="http://definition.nexusformat.org/nxdl/3.1"
@@ -32,55 +32,61 @@
 
 	<attribute name="default">
 		<doc>
+			.. index:: find the default plottable data
 			.. index:: plotting
+			.. index:: default attribute value
 
 			Declares which :ref:`NXdata` group contains the data
 			to be shown by default.
 			It is needed to resolve ambiguity when more than
 			one :ref:`NXdata` group exists.
-			The value is the name of the default :ref:`NXdata` group.
+			The value is the name of the default :ref:`NXdata` group, which
+			must be the name of a child of the current group and that child must be a NeXus
+			group or a link to a NeXus group. The value must match the
+			:ref:`regular expression pattern for NXDL group and field names
+			&lt;validItemName>`.
 
 			For more information about how NeXus identifies the default
 			plottable data, see the
 			:ref:`Find Plottable Data, v3 &lt;Find-Plottable-Data-v3&gt;`
 			section.
 		</doc>
 	</attribute>
-	
+
 	<doc>
-		(**required**) :ref:`NXentry` describes the measurement. 
-		
+		(**required**) :ref:`NXentry` describes the measurement.
+
 		The top-level NeXus group which contains all the data and associated
-		information that comprise a single measurement. 
+		information that comprise a single measurement.
 		It is mandatory that there is at least one
 		group of this type in the NeXus file.	</doc>
-	
+
 	<group type="NXdata">
 		<doc>
 			The data group
-		
+
 			.. note:: Before the NIAC2016 meeting [#]_, at least one
 			   :ref:`NXdata` group was required in each :ref:`NXentry` group.
-			   At the NIAC2016 meeting, it was decided to make :ref:`NXdata` 
-			   an optional group in :ref:`NXentry` groups for data files that 
+			   At the NIAC2016 meeting, it was decided to make :ref:`NXdata`
+			   an optional group in :ref:`NXentry` groups for data files that
 			   do not use an application definition.
-			   It is recommended strongly that all NeXus data files provide 
-			   a NXdata group.  
-			   It is permissable to omit the NXdata group only when 
+			   It is recommended strongly that all NeXus data files provide
+			   a NXdata group.
+			   It is permissable to omit the NXdata group only when
 			   defining the default plot is not practical or possible
 			   from the available data.
-			   
-			   For example, neutron event data may not have anything that 
+
+			   For example, neutron event data may not have anything that
 			   makes a useful plot without extensive processing.
-			   
+
 			   Certain application definitions override this decision and
 			   require an :ref:`NXdata` group
 			   in the :ref:`NXentry` group.  The ``minOccurs=0`` attribute
-			   in the application definition will indicate the 
+			   in the application definition will indicate the
 			   :ref:`NXdata` group
 			   is optional, otherwise, it is required.
-	
-			   .. [#] NIAC2016: 
+
+			   .. [#] NIAC2016:
 			      https://www.nexusformat.org/NIAC2016.html,
 			      https://github.com/nexusformat/NIAC/issues/16
 
@@ -96,8 +102,8 @@
 	</field>
 	<field name="experiment_identifier">
 		<doc>
-			Unique identifier for the experiment, 
-			defined by the facility, 
+			Unique identifier for the experiment,
+			defined by the facility,
 			possibly linked to the proposals
 		</doc>
 	</field>
@@ -130,13 +136,13 @@
 	<field name="definition">
 		<doc>
 			(alternate use: see same field in :ref:`NXsubentry` for preferred)
-			
+
 			Official NeXus NXDL schema to which this entry conforms.
-			
+
 			This field is provided so that :ref:`NXentry` can be the overlay position
-			in a NeXus data file for an application definition and its 
+			in a NeXus data file for an application definition and its
 			set of groups, fields, and attributes.
-			
+
 			*It is advised* to use :ref:`NXsubentry`, instead, as the overlay position.
 		</doc>
 		<attribute name="version"><doc>NXDL version number</doc></attribute>
@@ -145,7 +151,7 @@
 	<field name="definition_local" deprecated="see same field in :ref:`NXsubentry` for preferred use">
 		<doc>
 			Local NXDL schema extended from the entry
-			specified in the ``definition`` field. 
+			specified in the ``definition`` field.
 			This contains any locally-defined,
 			additional fields in the entry.
 		</doc>
@@ -202,7 +208,7 @@
 		<attribute name="type">
 			<doc>The mime type should be an ``image/*``</doc>
 			<enumeration>
-				<!-- 
+				<!--
 					This is not perfect.
 					How do we set a default value for the type attribute?
 				 -->

diff --git a/base_classes/NXroot.nxdl.xml b/base_classes/NXroot.nxdl.xml
@@ -2,9 +2,9 @@
 <?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
 <!--
 # NeXus - Neutron and X-ray Common Data Format
-# 
+#
 # Copyright (C) 2008-2022 NeXus International Advisory Committee (NIAC)
-# 
+#
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
 # License as published by the Free Software Foundation; either
@@ -24,13 +24,13 @@
 <definition xmlns="http://definition.nexusformat.org/nxdl/3.1" category="base"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
-    name="NXroot" 
+    name="NXroot"
     type="group" extends="NXobject">
     <doc>Definition of the root NeXus group.</doc>
     <attribute name="NX_class">
         <doc>
-            The root of any NeXus data file is an ``NXroot`` class 
-            (no other choice is allowed for a valid NeXus data file).  
+            The root of any NeXus data file is an ``NXroot`` class
+            (no other choice is allowed for a valid NeXus data file).
             This attribute cements that definition.
         </doc>
         <enumeration>
@@ -49,7 +49,7 @@
     <attribute name="NeXus_version">
         <doc>
             Version of NeXus API used in writing the file.
-            
+
             Only used when the NAPI has written the file.
             Note that this is different from the version of the
             base class or application definition version number.
@@ -61,7 +61,7 @@
     <attribute name="HDF5_Version">
         <doc>
             Version of HDF5 library used in writing the file.
-            
+
             Note this attribute is spelled with uppercase "V",
             different than other version attributes.
         </doc>
@@ -83,14 +83,20 @@
     </group>
     <attribute name="default">
         <doc>
+            .. index:: find the default plottable data
             .. index:: plotting
-
-            Declares which :ref:`NXentry` group contains 
+            .. index:: default attribute value
+
+            Declares which :ref:`NXentry` group contains
             the data to be shown by default.
-            It is needed to resolve ambiguity when 
-            more than one :ref:`NXentry` group exists. 
-            The value is the name of the default :ref:`NXentry` group.
-
+            It is needed to resolve ambiguity when
+            more than one :ref:`NXentry` group exists.
+            The value is the name of the default :ref:`NXentry` group.  The
+            value must be the name of a child of the current group and that child must be a
+            NeXus group or a link to a NeXus group. The value must match the
+            :ref:`regular expression pattern for NXDL group and field names
+            &lt;validItemName>`.
+
             It is recommended (as of NIAC2014) to use this attribute
             to help define the path to the default dataset to be plotted.
             See https://www.nexusformat.org/2014_How_to_find_default_data.html

diff --git a/base_classes/NXsubentry.nxdl.xml b/base_classes/NXsubentry.nxdl.xml
@@ -32,13 +32,19 @@
 
 	<attribute name="default">
 		<doc>
+			.. index:: find the default plottable data
 			.. index:: plotting
+			.. index:: default attribute value
 
 			Declares which :ref:`NXdata` group contains the data
 			to be shown by default.
 			It is needed to resolve ambiguity when more than
 			one :ref:`NXdata` group exists.
-			The value is the name of the default :ref:`NXdata` group.
+			The value is the name of the default :ref:`NXdata` group, which
+			must be the name of a child of the current group and that child must
+			be a :ref:`NXdata` group or a link to a :ref:`NXdata` group. The
+			value must match the :ref:`regular expression pattern for NXDL group
+			and field names &lt;validItemName>`.
 
 			For more information about how NeXus identifies the default
 			plottable data, see the