use consistent terms when names are flexible

[prjemian]

In some NXDL files, the name for a group, field, or attribute is flexible (the exact name given by the NXDL specification is not required) and is set at the time the HDF file is written. Across the suite of NXDL files, different terms are used to mark a name as flexible. In some cases, there is no indication that a name may be substituted. In others, upper case is used, In some other cases, such as for groups that have not been given explicit names, a default is shown in parentheses. A few, select examples should describe the variations:

NXDL	type	name given
NXdata	field	data
NXdata	field	variable
NXdata	attribute	AXISNAME_indices
NXentry	group	(data)
NXscan	group	(instrument)
NXtransformations	field	AXISNAME
NXtransformations	field	AXISNAME_end

The documentation publishing process applies the parentheses for groups where the name is not specified in the NXDL file. Such as (from NXentry):

<group type="NXsample" />

is documented as

(sample): (optional) NXsample

It is proposed to choose either UPPER_CASE or (parentheses) to denote when a name is flexible and to apply this decision across all NXDL files. The proposed should not change the meaning of any definition, but just use consistent nomenclature.

[prjemian]

Note that the procedures that publish the manual use the parenthesis style ((suggestion)). Perhaps we standardize that.

[prjemian]

In nxdl.xsd, there is an attribute to an NXDL field element that addresses this point: nameType="any"

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

[prjemian]

If we enclose the flexible part of the name within parentheses, this will require a change to the XML Schema and the regular expression.

Suggest that we use all capital letters (in addition to the nameType="any" attribute) to indicate in the documentation when a name is flexible. "All caps" looks simpler.

[prjemian]

Pulling this out of the NXDL 3.3 milestone since a draft may take some review before acceptance. Will work that up in a branch.

[zjttoefs]

Discussed at the Telco today. Just UPPERCASE wasn't deemed obvious enough. The parentheses were not strongly favoured either, though.
Suggestion was to use the uppercase to instruct the user directly like
AXISNAMEPLACEHOLDER and AXISNAMEPLACEHOLDER_indices. Use of underscores as in AXISNAME_PLACEHOLDER was discouraged because AXISNAME_PLACEHOLDER_indices looks confusing.
Alternatives could be CHANGETHISAXISNAME or the like.

[prjemian]

Might not make the next milestone (NXDLD 2018.3 planned) but will leave on the list for now.

[zjttoefs]

Also relevant for CHANGETHISAXISNAME_set for demand values as in #599

[prjemian]

The table given above will change to:

NXDL	type	name given
NXdata	field	DATA
NXdata	field	VARIABLE
NXdata	attribute	AXISNAME_indices
NXentry	group	DATA
NXscan	group	INSTRUMENT
NXtransformations	field	AXISNAME
NXtransformations	field	AXISNAME_end