improve description of the value of the default attribute

base_classes/NXdata.nxdl.xml

@@ -41,9 +41,9 @@
  -->
 
  <symbols>
- <doc>These symbols will be used below to coordinate datasets with the same shape.</doc>
- <symbol name="dataRank"><doc>rank of the ``data`` field</doc></symbol>
- <symbol name="n"><doc>length of the ``variable`` field</doc></symbol>
+ <doc>These symbols will be used below to coordinate fields with the same shape.</doc>
+ <symbol name="dataRank"><doc>rank of the ``DATA`` field</doc></symbol>
+ <symbol name="n"><doc>length of the ``VARIABLE`` field</doc></symbol>
  <symbol name="nx"><doc>length of the ``x`` field</doc></symbol>
  <symbol name="ny"><doc>length of the ``y`` field</doc></symbol>
  <symbol name="nz"><doc>length of the ``z`` field</doc></symbol>
@@ -64,15 +64,17 @@
  </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 is the default. 
+ The value is the name of the NeXus field to be plotted.
+ (The value :ref:`names &lt;validItemName>` an existing child
+ of this group. The child group must itself be a NeXus group.)
 
  It is recommended (as of NIAC2014) to use this attribute
- rather than adding a signal attribute to the dataset.
+ rather than adding a signal attribute to the field.
  See https://www.nexusformat.org/2014_How_to_find_default_data.html
  for a summary of the discussion.
  </doc>
@@ -124,7 +126,7 @@
 
  Integer array that defines the indices of the *signal* field 
  (that field will be a multidimensional array)
- which need to be used in the *AXISNAME* dataset in 
+ which need to be used in the *AXISNAME* field in 
  order to reference the corresponding axis value.
 
  The first index of an array is ``0`` (zero).
@@ -162,10 +164,11 @@
 
  .. index:: plotting
 
- It is mandatory  that there is at least one :ref:`NXdata` group 
- in each :ref:`NXentry` group. 
- Note that the ``variable`` and ``data`` 
+ It is strongly recommended that there is at least one :ref:`NXdata`
+ group in each :ref:`NXentry` group.
+ Note that the fields named ``VARIABLE`` and ``DATA`` 
  can be defined with different names. 
+ (Upper case is used to indicate that the actual name is left to the user.)
  The ``signal`` and ``axes`` attributes of the 
  ``data`` group define which items 
  are plottable data and which are *dimension scales*, respectively.
@@ -174,12 +177,14 @@
  to provide a default plot for the data of this :ref:`NXentry`. The actual data
  might be stored in another group and (hard) linked to the :ref:`NXdata` group.
 
- * Each :ref:`NXdata` group will define only one data set
- containing plottable data, dimension scales, and 
- possibly associated standard deviations.
- Other data sets may be present in the group.
+ * Each :ref:`NXdata` group will define one field as the default
+ plottable data. The value of the ``signal`` attribute names this field.
+ Additional fields may be used to describe the dimension scales and 
+ uncertainities.
+ The ``auxiliary_signals`` attribute is a list of the other fields
+ to be plotted with the ``signal`` data.
  * The plottable data may be of arbitrary rank up to a maximum
- of ``NX_MAXRANK=32``.
+ of ``NX_MAXRANK=32`` (for compatibility with backend file formats).
  * The plottable data will be named as the value of 
  the group ``signal`` attribute, such as::
 
@@ -191,7 +196,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 or defined through a link.
 
  * The group ``axes`` attribute will name the
  *dimension scale* associated with the plottable data.
@@ -308,14 +313,14 @@
 
  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>
  A dimension scale must have a rank of 1 and has length ``n``, 
- same as ``variable``.
+ same as ``VARIABLE``.
  </doc>
  <dim index="1" value="n"/>
  </dimensions>

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,59 @@
 
  <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
+ It is used to resolve ambiguity when
  one :ref:`NXdata` group exists.
- The value is the name of the default :ref:`NXdata` group.
+ The value :ref:`names &lt;validItemName>` a child group. If that group
+ itself has a ``default`` attribute, continue this chain until an
+ :ref:`NXdata` group is reached.
 
  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 +100,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 +134,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 +149,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 +206,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?
  -->

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,18 @@
  </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 used to resolve ambiguity when
+ more than one :ref:`NXentry` group exists.
+ The value :ref:`names &lt;validItemName>` the default :ref:`NXentry` group. The
+ value must be the name of a child of the current group. The child must be a
+ NeXus group or a link to a NeXus group.
+
  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

base_classes/NXsubentry.nxdl.xml

@@ -32,13 +32,17 @@
 
  <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
+ It is used to resolve ambiguity when
  one :ref:`NXdata` group exists.
- The value is the name of the default :ref:`NXdata` group.
+ The value :ref:`names &lt;validItemName>` the default :ref:`NXentry` group. The
+ value must be the name of a child of the current group. The child must be a
+ NeXus group or a link to a NeXus group.
 
  For more information about how NeXus identifies the default
  plottable data, see the
@@ -81,9 +85,9 @@
  </field>
  <field name="experiment_identifier">
  <doc>
- Unique identifier for the experiment, defined by
- the facility, possibly linked to the proposals
- </doc>
+ Unique identifier for the experiment, defined by
+ the facility, possibly linked to the proposals
+ </doc>
  </field>
  <field name="experiment_description">
  <doc>Brief summary of the experiment, including key objectives.</doc>