DOC #879 reference from NeXus classes page

manual/source/classes/index.rst

@@ -10,84 +10,103 @@ Definitions of NeXus classes. These are split into base_classes (low level objec
 application definitions (groupings of objects for a particular technique) and 
 contributed_definitions (proposed definitions from the community)
 
-:ref:`base classes <base.class.definitions>`
- NeXus base class definitions define the set of terms that
- *might* be used in an instance of that class.
- Consider the base classes as a set of *components*
- that are used to construct a data file.
-
- Base class definitions are permissive rather than restrictive.
- While the terms defined aim to cover most possible use cases,
- and to codify the spelling and meaning of such terms,
- the class specifications cannot list all acceptable groups and fields.
- To be able to progress the NeXus standard, additional data
- (groups, fields, attributes) are acceptable in NeXus HDF5 data files.
-
- Users are encouraged to find the best *defined* location in which 
- to place their information. It is understood there is not a 
- predefined place for all possible data.
-
- Validation procedures should treat such additional items 
- (not covered by a base class specification) as notes or warnings
- rather than errors. 
-
-:ref:`application definitions <application.definitions>`
- NeXus application definitions define the *minimum*
- set of terms that
- *must* be used in an instance of that class.
- Application definitions also may define terms that
- are optional in the NeXus data file.
-
- As in base classes (see above), additional terms that are
- not described by the application definition may be added to
- data files that incorporate or adhere to application definitions. 
-
- .. index:: link
-
- Use NeXus links liberally in data files to reduce duplication of data.
- In application definitions involving raw data,
- write the raw data in the :ref:`NXinstrument` tree and then link to it
- from the location(s) defined in the relevant application definition.
- See figure :ref:`NeXus Multi Method Hierarchy <table.NXsubentry>`
- for an example.
-
- .. index:: subentry; NXsubentry, use of, multi-modal data
-
- To write a data file with an application definition, start with either
- a :ref:`NXentry` (or :ref:`NXsubentry`) group [#]_ and write the name of the
- application definition in the ``definition`` field. Then write data into 
- this group according to the specifications of the application definition.
-
- .. [#] For data files involving just an application definition, use
- the :ref:`NXentry` group. Such as this structure::
- 
- entry:NXentry
+The complete :index:`!vocabulary`` of terms (names of groups, fields, attributes, and
+links) used in NeXus NXDL files is available for download. See this table for
+the different formats available:
+
+========================================= ============================================
+download file description
+========================================= ============================================
+:download:`/_static/nxdl_vocabulary.html` Human-readable HTML list of anchors, by vocabulary term, with links to the manual.
+:download:`/_static/nxdl_vocabulary.json` vocabulary list by key in [JSON](https://www.w3schools.com/whatis/whatis_json.asp) format
+:download:`/_static/nxdl_vocabulary.txt` list of all anchors, sorted alphabetically
+:download:`/_static/nxdl_vocabulary.yml` vocabulary list by key in [YAML](https://yaml.org/) format
+========================================= ============================================
+
+Base classes
+------------------
+
+NeXus :ref:`base class <base.class.definitions>` definitions define the set of terms that
+*might* be used in an instance of that class.
+Consider the base classes as a set of *components*
+that are used to construct a data file.
+
+Base class definitions are permissive rather than restrictive.
+While the terms defined aim to cover most possible use cases,
+and to codify the spelling and meaning of such terms,
+the class specifications cannot list all acceptable groups and fields.
+To be able to progress the NeXus standard, additional data
+(groups, fields, attributes) are acceptable in NeXus HDF5 data files.
+
+Users are encouraged to find the best *defined* location in which 
+to place their information. It is understood there is not a 
+predefined place for all possible data.
+
+Validation procedures should treat such additional items 
+(not covered by a base class specification) as notes or warnings
+rather than errors. 
+
+Application Definitions
+------------------------
+
+NeXus :ref:`application definitions <application.definitions>` define the *minimum*
+set of terms that
+*must* be used in an instance of that class.
+Application definitions also may define terms that
+are optional in the NeXus data file.
+
+As in base classes (see above), additional terms that are
+not described by the application definition may be added to
+data files that incorporate or adhere to application definitions. 
+
+.. index:: link
+
+Use NeXus links liberally in data files to reduce duplication of data.
+In application definitions involving raw data,
+write the raw data in the :ref:`NXinstrument` tree and then link to it
+from the location(s) defined in the relevant application definition.
+See figure :ref:`NeXus Multi Method Hierarchy <table.NXsubentry>`
+for an example.
+
+.. index:: subentry; NXsubentry, use of, multi-modal data
+
+To write a data file with an application definition, start with either
+a :ref:`NXentry` (or :ref:`NXsubentry`) group [#]_ and write the name of the
+application definition in the ``definition`` field. Then write data into 
+this group according to the specifications of the application definition.
+
+.. [#] For data files involving just an application definition, use
+ the :ref:`NXentry` group. Such as this structure::
+ 
+ entry:NXentry
+ definition="NXsas"
+ 
+ For files that describe multi-modal
+ data and require use of two or more application definitions
+ (such as :ref:`NXsas` *and* :ref:`NXcanSAS`), you must place each
+ application definition in a :ref:`NXsubentry` of the :ref:`NXentry` group.
+ Such as this structure::
+ 
+ entry:NXentry
+ raw:NXsubentry
  definition="NXsas"
- 
- For files that describe multi-modal
- data and require use of two or more application definitions
- (such as :ref:`NXsas` *and* :ref:`NXcanSAS`), you must place each
- application definition in a :ref:`NXsubentry` of the :ref:`NXentry` group.
- Such as this structure::
- 
- entry:NXentry
- raw:NXsubentry
- definition="NXsas"
- reduced:NXsubentry
- definition="NXcanSAS"
- fluo:NXsubentry
- definition="NXfluo"
- 
- If you anticipate your data file will eventually require an additional
- application definition, you should start with each application definition
- in a :ref:`NXsubentry` group.
-
-:ref:`contributed definitions <contributed.definitions>`
- NXDL files in the NeXus contributed definitions include propositions from
- the community for NeXus base classes or application definitions, as well
- as other NXDL files for long-term archival by NeXus. Consider the contributed
- definitions as either in *incubation* or a special
- case not for general use.
+ reduced:NXsubentry
+ definition="NXcanSAS"
+ fluo:NXsubentry
+ definition="NXfluo"
+ 
+ If you anticipate your data file will eventually require an additional
+ application definition, you should start with each application definition
+ in a :ref:`NXsubentry` group.
+
+Contributed Definitions
+------------------------
+
+NXDL files in the NeXus :ref:`contributed definitions <contributed.definitions>` include propositions from
+the community for NeXus base classes or application definitions, as well
+as other NXDL files for long-term archival by NeXus. Consider the contributed
+definitions as either in *incubation* or a special
+case not for general use.
 
 .. toctree::
  :hidden: