diff --git a/manual/source/defs_intro.rst b/manual/source/defs_intro.rst index 1c05edef1..b42ecb972 100644 --- a/manual/source/defs_intro.rst +++ b/manual/source/defs_intro.rst @@ -6,11 +6,23 @@ Introduction to NeXus definitions .. .. image:: img/NeXus.png -While the design principles of NeXus are explained in the :ref:`UserManual`, this Reference Documentation specifies all allowed :ref:`base classes ` and all standardized :ref:`application definitions `. Furthermore, it also contains :ref:`contributed definitions ` of new bases classes or application definitions that are currently under review. +While the design principles of NeXus are explained in the +:ref:`UserManual`, this Reference Documentation specifies +all allowed :ref:`base classes ` +and all standardized :ref:`application definitions `. +Furthermore, it also contains +:ref:`contributed definitions ` +of new bases classes or application definitions that +are currently under review. -Base class definitions and application definitions have basically the same structure, but different semantics: Base class definitions define the *complete* set of -terms that *might* be used in an instance of that class. Application definitions -define the *minimum* set of terms that *must* be used in an instance of that class. +Base class definitions and application definitions have basically +the same structure, but different semantics: + +* Base class definitions define the *complete* set of + terms that *might* be used in an instance of that class. + +* Application definitions + define the *minimum* set of terms that *must* be used in an instance of that class. Base classes and application definitions are specified using a domain-specific XML scheme, the :ref:`NXDL`. @@ -168,3 +180,49 @@ attribute [#minOccurs]_ 1 for NXDL *application definitions* and *contributed definitions*, ``minOccurs=1`` is the default. In all cases, the ``minOccurs`` attribute in the NXDL file will override the default for that element (group, field, attribute, or link). + +.. index:: !choice + +Choice +====== + +The ``choice`` element allows one to create a group with a defined name +that is one specific NXDL base class from a defined list of possibilities + +In some cases when creating an application definition, more than one +choice of base class might be used to define a particular subgroup. +For this particular situation, the ``choice`` was added to the NeXus +NXDL Schema. + +In this example fragment of an NXDL application definition, +the ``pixel_shape`` could be represented by *either* +``NXoff_geometry`` or ``NXcylindrical_geometry``. + + +.. code-block:: xml + :linenos: + + + + + Shape description of each pixel. Use only if all pixels in the detector + are of uniform shape. + + + + + Shape description of each pixel. Use only if all pixels in the detector + are of uniform shape and require being described by cylinders. + + + + + +The ``@name`` attribute of the ``choice`` element specifies the name that +will appear in the HDF5 data file using one of the groups listed within the choice. +Thus, it is not necessary to specify the name in each group. (At some point, +the NXDL Schema may be modified to enforce this rule.) + +A ``choice`` element may be used wherever a ``group`` element +is used. It **must** have at least two groups listed (otherwise, it would +not be useful). diff --git a/manual/source/introduction.rst b/manual/source/introduction.rst index 8817a1eb8..0e13c475b 100644 --- a/manual/source/introduction.rst +++ b/manual/source/introduction.rst @@ -195,7 +195,10 @@ Important Classes ----------------- Here are some of the important classes found in nearly all NeXus files. A -complete list can be found in the :ref:`Design` chapter. +complete list can be found in the :ref:`Design-NeXusClasses` chapter. +A complete list of *all* NeXus classes may be found in +the :ref:`all.class.definitions` chapter. + .. note:: ``NXentry`` is the only class required in a valid NeXus data file. diff --git a/nxdl.xsd b/nxdl.xsd index 5b0942a95..5f515f3fc 100644 --- a/nxdl.xsd +++ b/nxdl.xsd @@ -367,6 +367,41 @@ + + + + A ``choice`` element is used when a named group might take one + of several possible NeXus base classes. Logically, it must + have at least two group children. + + + + + + + NeXus base class that could be used here. + The group will take the ``@name`` attribute + defined by the parent ``choice`` element + so do not specify the ``@name`` attribute of + the group here. + + + + + + + + + The name to be applied to the selected child group. + None of the child groups should define a + ``@name`` attribute. + + + + + + + @@ -474,6 +509,14 @@ + + + + Use a ``choice`` if a named group could be either + of a defined list of base classes. + + + diff --git a/utils/nxdl_desc2rst.py b/utils/nxdl_desc2rst.py index a3e3837c8..a98a6f362 100755 --- a/utils/nxdl_desc2rst.py +++ b/utils/nxdl_desc2rst.py @@ -84,6 +84,15 @@ :ref:`NXDL.data.type.fieldType` ''', + 'choice': ''' +A ``choice`` element is used when a named group might take one +of several possible NeXus base classes. Logically, it must +have at least two group children. + +For more details, see: +:ref:`NXDL.data.type.choiceType` + ''', + 'group': ''' A ``group`` element can *only* be a child of a ``definition`` or ``group`` element. @@ -323,7 +332,7 @@ def applyTemplates(ns, parent, path, indentLevel, handler=generalHandler): for node in parent.xpath(path, namespaces=ns): name = node.get('name') or node.get('ref') or node.get('value') if name is not None: - if name in ('nx:groupGroup'): + if name in ('nx:groupGroup',): print(">"*45, name) if name in db: raise "Duplicate name found: " + name @@ -438,6 +447,7 @@ def main(tree, ns): "/xs:schema/xs:complexType[@name='docType']", "/xs:schema/xs:complexType[@name='enumerationType']", "/xs:schema/xs:complexType[@name='fieldType']", + "/xs:schema/xs:complexType[@name='choiceType']", "/xs:schema/xs:complexType[@name='groupType']", "/xs:schema/xs:complexType[@name='linkType']", "/xs:schema/xs:complexType[@name='symbolsType']",