improve description of the value of the default attribute

[prjemian]

• FIX @default is a step by step process instead of a direct jump (should be better documented) #1003
• REF Is 'default' attribute value an absolute reference or a relative one? #1063
• REF Base Class and Application Definition development questions NIAC#107

[prjemian]

Is there any other documentation to be revised?

[woutdenolf]

LGTM. I added some comments related to keeping the docs HDF5 agnostic.

I also see you often make the distinction between a field and a link to field (e.g. either as a NeXus field or as a link to a NeXus field). I guess this is done all over the documentation but imo this is an HDF5 feature which has nothing to do with the NeXus standard. But anyway, that should be discussed elsewhere.

[mkoennecke]

I am in favor of woutdenolfs more general wording.

[prjemian]

@benajamin notes that this legacy text is out of date:

definitions/base_classes/NXdata.nxdl.xml

Lines 181 to 184 in 66d9168

	* 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.

Look at this code (in base_classes/NXdata.nxdl.xml) for some suggestion:

   <attribute name="auxiliary_signals">
                   ``signal`` attribute).  Each auxiliary signal needs to be of

definitions/base_classes/NXdata.nxdl.xml

Lines 52 to 64 in 5798a56

	<attribute name="auxiliary_signals">
	<doc>
	.. index:: plotting
	Array of strings holding the names of additional signals to
	be plotted with the default signal (specified by the
	``signal`` attribute). Each auxiliary signal needs to be of
	the same shape as the default signal.
	.. NIAC2018:
	https://www.nexusformat.org/NIAC2018Minutes.html
	</doc>
	</attribute>

[prjemian]

Also, NXentry no longer requires a NXdata group.

[benajamin]

@woutdenolf

I also see you often make the distinction between a field and a link to field (e.g. either as a NeXus field or as a link to a NeXus field). I guess this is done all over the documentation but imo this is an HDF5 feature which has nothing to do with the NeXus standard. But anyway, that should be discussed elsewhere.

I agree in staying general, but I don't know if it is fair to say that only HDF5 has links.

[prjemian]

@benajamin @woutdenolf This is ready for review again.

[woutdenolf]

Apart from some technical fixes, it seems all good now. Thanks for the hard work!

A small additional comment: I noticed you used the phrase

The value of the default attribute :ref:names <validItemName> an
existing child of this group

The link to validItemName is not really needed imo but I guess it doesn't hurt either.

[benajamin]

LGTM

[prjemian]

Thanks for the reviews!