UPPERCASE to indicate flexible names

.gitignore

@@ -13,4 +13,7 @@ nyaml/
 
 # Unknown
 /python/
-__github_creds__.txt
+__github_creds__.txt
+
+# used locally to validate nxdl.xsd and nxdlTypes.xsd
+XMLSchema.xsd

CHANGES.rst

@@ -21,6 +21,18 @@ Highlights of each release are described below.  For more details, see our wiki
 (https://github.com/nexusformat/definitions/wiki/Release-Notes)
 which provides links to the Release Notes (itemized list of changes) for any release.
 
+.. incoming change for next release
+
+  v2025.mm
+  ++++++++
+
+  for release sometime in *2025*
+
+  Maintenance
+  -----------
+
+  * Add nameType="partial" to NXDL schema.
+  * Use 'nameType' attribute in fields, groups, and attributes.
 
 v2024.02
 ++++++++

applications/NXcanSAS.nxdl.xml

@@ -278,7 +278,7 @@
         </doc>
       </attribute>
 
-      <field name="Q" type="NX_NUMBER" units="NX_PER_LENGTH">
+      <field name="Q" type="NX_NUMBER" units="NX_PER_LENGTH" nameType="specified">
         <!-- http://www.cansas.org/formats/canSAS2012/1.0/doc/basics.html#definition-of -->
         <doc>
           .. index:: NXcanSAS (applications); Q
@@ -425,7 +425,7 @@
           </doc>
         </attribute>
       </field>
-      <field name="I" type="NX_NUMBER">
+      <field name="I" type="NX_NUMBER" nameType="specified">
         <!-- http://www.cansas.org/formats/canSAS2012/1.0/doc/basics.html#definition-of-intensity -->
 		<doc>
           .. index:: NXcanSAS (applications); I
@@ -1187,7 +1187,7 @@
         ============================
       -->
 
-    <group name="TRANSMISSION_SPECTRUM" type="NXdata" minOccurs="0">
+    <group name="TRANSMISSION_SPECTRUM" type="NXdata" minOccurs="0" nameType="any">
       <doc>
         The *SAStransmission_spectrum* element
 

base_classes/NXdata.nxdl.xml

@@ -309,12 +309,7 @@
 
 		</doc>
 	</attribute>
-	<attribute name="AXISNAME_indices" type="NX_INT">
-		<!-- 
-			nxdl.xsd rules do not allow us to show this as a variable name 
-			- we'll use ALL CAPS (see #562)
-		-->
-		<!-- AXISNAME_indices documentation copied from datarules.rst -->
+	<attribute name="AXISNAME_indices" type="NX_INT" nameType="partial">
 		<doc>
 			The ``AXISNAME_indices`` attribute is a single integer or an array of integers that defines which :ref:`data &lt;/NXdata/DATA-field&gt;`
 			dimension(s) are spanned by the corresponding axis. The first dimension index is ``0`` (zero).
@@ -420,7 +415,7 @@
 			<doc>data label</doc>
 		</attribute>
 	</field>
-	<field name="FIELDNAME_errors" type="NX_NUMBER" nameType="any">
+	<field name="FIELDNAME_errors" type="NX_NUMBER" nameType="partial">
 		<doc>
 			"Errors" (meaning *uncertainties* or *standard deviations*)
 			associated with any field named ``FIELDNAME`` in this ``NXdata``
@@ -446,7 +441,7 @@
 	</field>
 
 	<!-- Data vs. plot coordinates -->
-	<field name="FIELDNAME_scaling_factor" type="NX_NUMBER">
+	<field name="FIELDNAME_scaling_factor" type="NX_NUMBER" nameType="partial">
 		<doc>
 			An optional scaling factor to apply to the values in any field named ``FIELDNAME``
 			in this ``NXdata`` group. This can be a :ref:`DATA &lt;/NXdata/DATA-field&gt;` field
@@ -468,7 +463,7 @@
 			When omitted, the scaling factor is assumed to be 1.
 		</doc>
 	</field>
-	<field name="FIELDNAME_offset" type="NX_NUMBER">
+	<field name="FIELDNAME_offset" type="NX_NUMBER" nameType="partial">
 		<doc>
 			An optional offset to apply to the values in FIELDNAME (usually the signal).
 

dev_tools/docs/nxdl.py

@@ -14,6 +14,7 @@
 from ..globals.urls import REPO_URL
 from ..utils.github import get_file_contributors_via_api
 from ..utils.nxdl_utils import get_inherited_nodes
+from ..utils.nxdl_utils import get_rst_formatted_name
 from ..utils.types import PathLike
 from .anchor_list import AnchorRegistry
 
@@ -564,13 +565,14 @@ def _print_doc_enum(self, indent, ns, node, required=False):
 
     def _print_attribute(self, ns, kind, node, optional, indent, parent_path):
         name = node.get("name")
+        formatted_name = get_rst_formatted_name(node)
         index_name = name
         self._print(
             f"{indent}" f"{self._hyperlink_target(parent_path, name, 'attribute')}"
         )
         self._print(f"{indent}.. index:: {index_name} ({kind} attribute)\n")
         self._print(
-            f"{indent}**@{name}**: {optional}{self._format_type(node)}{self._format_units(node)} {self.get_first_parent_ref(f'{parent_path}/{name}', 'attribute')}\n"
+            f"{indent}{formatted_name}: {optional}{self._format_type(node)}{self._format_units(node)} {self.get_first_parent_ref(f'{parent_path}/{name}', 'attribute')}\n"
         )
         self._print_doc_enum(indent, ns, node)
 
@@ -592,14 +594,15 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path):
         """
         for node in parent.xpath("nx:field", namespaces=ns):
             name = node.get("name")
+            formatted_name = get_rst_formatted_name(node)
             index_name = name
             dims = self._analyze_dimensions(ns, node)
 
             optional_text = self._get_required_or_optional_text(node)
             self._print(f"{indent}{self._hyperlink_target(parent_path, name, 'field')}")
             self._print(f"{indent}.. index:: {index_name} (field)\n")
             self._print(
-                f"{indent}**{name}**: "
+                f"{indent}{formatted_name}: "
                 f"{optional_text}"
                 f"{self._format_type(node)}"
                 f"{dims}"
@@ -624,6 +627,7 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path):
 
         for node in parent.xpath("nx:group", namespaces=ns):
             name = node.get("name", "")
+            formatted_name = get_rst_formatted_name(node)
             typ = node.get("type", "untyped (this is an error; please report)")
 
             optional_text = self._get_required_or_optional_text(node)
@@ -636,7 +640,7 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path):
             # TODO: https://github.com/nexusformat/definitions/issues/1057
             self._print(f"{indent}{hTarget}")
             self._print(
-                f"{indent}**{name}**: {optional_text}{typ} {self.get_first_parent_ref(f'{parent_path}/{name}', 'group')}\n"
+                f"{indent}{formatted_name}: {optional_text}{typ} {self.get_first_parent_ref(f'{parent_path}/{name}', 'group')}\n"
             )
 
             self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT)
@@ -664,9 +668,10 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path):
 
         for node in parent.xpath("nx:link", namespaces=ns):
             name = node.get("name")
+            formatted_name = get_rst_formatted_name(node)
             self._print(f"{indent}{self._hyperlink_target(parent_path, name, 'link')}")
             self._print(
-                f"{indent}**{name}**: "
+                f"{indent}{formatted_name}: "
                 ":ref:`link<Design-Links>` "
                 f"(suggested target: ``{node.get('target')}``)"
                 "\n"

dev_tools/utils/nxdl_utils.py

@@ -3,6 +3,7 @@
 """
 
 import os
+import re
 import textwrap
 from functools import lru_cache
 from glob import glob
@@ -839,3 +840,60 @@ def get_node_at_nxdl_path(
                 "Please check this entry in the template dictionary."
             )
     return elem
+
+
+def get_rst_formatted_name(node):
+    """Return the RST formatted name of the node (field, group, link or attribute).
+
+    The formatting is determined as follows:
+
+    - all characters are bold formatted
+    - substitutable characters are bold and italic formatted
+    - attributes start with a bold "@" character
+    """
+    name = node.get("name", "")
+    nameType = node.get("nameType", "")
+
+    node_type = get_local_name_from_xml(node)
+
+    if not name and node_type == "group":
+        # Derive the name from the type without the NX prefix
+        group_type = node.get("type", "")
+        name = group_type.lstrip("NX").upper()
+        if not nameType:
+            nameType = "any"
+
+    # Characters that are NOT substitutable
+    fixstart = "**"
+    fixstop = "**"
+
+    # Characters that are substitutable
+    varstart = ":bolditalic:`"
+    varstop = "`"
+
+    if nameType == "any":
+        # Formatting: bold and italicized
+        if node_type == "attribute":
+            return rf"{fixstart}@{fixstop}\ {varstart}{name}{varstop}"
+        else:
+            return f"{varstart}{name}{varstop}"
+
+    if nameType == "partial":
+        # Formatting: bold and capital letters italicized
+        substrings = _SPLIT_NAMETYPE_PARTIAL.findall(name)
+        formatted_parts = [
+            f"{varstart}{s}{varstop}" if s.isupper() else f"{fixstart}{s}{fixstop}"
+            for s in substrings
+        ]
+        if node_type == "attribute":
+            formatted_parts.insert(0, f"{fixstart}@{fixstop}")
+        return r"\ ".join(formatted_parts)
+
+    # Formatting: bold only
+    if node_type == "attribute":
+        return f"{fixstart}@{name}{fixstop}"
+    else:
+        return f"{fixstart}{name}{fixstop}"
+
+
+_SPLIT_NAMETYPE_PARTIAL = re.compile(r"[A-Z]+|[^A-Z]+")

manual/source/conf.py

@@ -48,7 +48,8 @@
     'sphinx.ext.githubpages',
     'sphinx.ext.todo',
     'sphinx_tabs.tabs',
-    'contrib_ext'
+    'contrib_ext',
+    'chios.bolditalic'
 ]
 
 # Show `.. todo` directives in the output
@@ -100,6 +101,13 @@ def setup(app):
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'NeXusManualdoc'
 
+html_contexthtml_context = {
+  'css_files': [
+    '_static/bespoke.css',  # custom CSS styling
+    '_static/bolditalic.css',  # bolditalic styling
+    ],
+  }
+
 # -- Options for Latex output -------------------------------------------------
 latex_elements = {
     'maxlistdepth':25, # some application definitions are deeply nested

manual/source/datarules.rst

@@ -67,8 +67,8 @@ described by the following :index:`rules <rules; naming>`:
    .. rubric:: Regular expression pattern for NXDL group and field names
 
    The NIAC recognises that the majority of the world uses characters
-   outside of the basic latin (a.k.a. US-ASCII, 7-bit ASCII) set
-   currently included in the allowed names. The restriction given here
+   outside of the basic latin (a.k.a. US-ASCII, 7-bit ASCII) [#7bit-ASCII]_
+   set currently included in the allowed names. The restriction given here
    reflects current technical issues and we expect to revisit the issue
    and relax such restrictions in future.
 

nxdl.xsd

@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 
+<!-- Here's a procedure to validate this XSD Schema file:
+https://stackoverflow.com/a/48980995/1046449 -->
+
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
 	targetNamespace="http://definition.nexusformat.org/nxdl/3.1"
 	xmlns:nx="http://definition.nexusformat.org/nxdl/3.1"
@@ -169,6 +172,34 @@
 		</xs:attribute>
 	</xs:attributeGroup>
 
+	<xs:attributeGroup name="nameTypeAttributeGroup">
+		<xs:attribute name="nameType" use="optional" default="specified">
+			<xs:annotation>
+				<xs:documentation>
+					This interprets the ``name`` attribute as:
+
+					* ``"specified"`` = Exactly this name.
+					  Note that if no ``name`` and ``nameType`` are provided 
+					  for a group, ``nameType="any"`` becomes the default.
+					* ``"any"`` = Any name not already used in group.
+					* ``"partial"`` = The capital letters are substitutable
+					  (empty string allowed) and the lower case letters
+					  (and other allowed symbols, such as ``_``) are not.
+
+					In each case, all names in a NeXus data file must
+					follow the naming :ref:`rules&lt;Design-Naming&gt;`.
+				</xs:documentation>
+			</xs:annotation>
+			<xs:simpleType>
+				<xs:restriction base="nx:NX_CHAR">
+					<xs:enumeration value="specified" />
+					<xs:enumeration value="any" />
+					<xs:enumeration value="partial" />
+				</xs:restriction>
+			</xs:simpleType>
+		</xs:attribute>
+	</xs:attributeGroup>
+
 	<xs:complexType name="definitionType">
 		<xs:annotation>
 			<xs:documentation>
@@ -486,6 +517,7 @@
 			</xs:annotation>
 		</xs:attribute>
 		<xs:attributeGroup ref="nx:deprecatedAttributeGroup"/>
+		<xs:attributeGroup ref="nx:nameTypeAttributeGroup"/>
 	</xs:complexType>
 
 	<xs:group name="groupGroup">
@@ -913,21 +945,7 @@
 						</xs:restriction>
 					</xs:simpleType>
 				</xs:attribute>
-				<xs:attribute name="nameType" use="optional" default="specified">
-					<xs:annotation>
-						<xs:documentation>
-							This interprets the name attribute as:
-							* ``specified`` = use as specified
-							* ``any`` = can be any name not already used in group
-						</xs:documentation>
-					</xs:annotation>
-					<xs:simpleType>
-						<xs:restriction base="nx:NX_CHAR">
-							<xs:enumeration value="specified" />
-							<xs:enumeration value="any" />
-						</xs:restriction>
-					</xs:simpleType>
-				</xs:attribute>
+				<xs:attributeGroup ref="nx:nameTypeAttributeGroup"/>
 			</xs:extension>
 		</xs:complexContent>
 	</xs:complexType>
@@ -1006,6 +1024,7 @@
 			</xs:annotation>
 		</xs:attribute>
 		<xs:attributeGroup ref="nx:deprecatedAttributeGroup"/>
+		<xs:attributeGroup ref="nx:nameTypeAttributeGroup"/>
 	</xs:complexType>
 
 	<xs:simpleType name="nonNegativeUnbounded">

requirements.txt

@@ -7,6 +7,7 @@ nyaml
 sphinx>=5
 sphinx-tabs
 sphinx-toolbox
+chios
 
 # Testing
 pytest