Merge pull request #1188 from nexusformat/1004-NXxpcs-clarification

NXxpcs: clarify use of entry_identifier, entry_identifier_uuid, and scan_number

contributed_definitions/NXxpcs.nxdl.xml

@@ -57,15 +57,32 @@
 
     <field name="entry_identifier">
       <doc>
-        Unique identifier for the experiment.
+        **Locally** unique identifier for the experiment (a.k.a. run or scan).
+
+        * For bluesky users, this is the run's `"scan_id"`.
+        * For SPEC users, this is the scan number (``SCAN_N``).
       </doc>
     </field>
     <field name="entry_identifier_uuid" minOccurs="0" maxOccurs="1">
       <doc>
         (optional) UUID identifier for this entry.
+
+        See the `UUID standard &lt;https://www.rfc-editor.org/rfc/rfc4122.html&gt;`__ (or
+        `wikipedia &lt;https://en.wikipedia.org/wiki/Universally_unique_identifier&gt;`__)
+        for more information.
+
+        * For `bluesky &lt;https://blueskyproject.io/&gt;`__ users, this is the
+          run's `"uid"` and is expected for that application.
+        * Typically, `SPEC &lt;https://certif.com/content/spec/&gt;`__ users will
+          not use this field without further engineering.
       </doc>
     </field>
-    <field name="scan_number" type="NX_INT">
+    <field name="scan_number" type="NX_INT"
+      deprecated="Use the ``entry_identifier`` field.">
+      <!--
+        Use of "deprecated" is to advise the XPCS authors of this change.
+        The `scan_number` field will be removed by 2022-12-31.
+      -->
       <doc>
         Scan number (must be an integer).