clarify species type extension

[s9105947]

This PR clarifies the species type extension, adds a full definition using ABNF.
Technically it introduces breaking changes -- for details, please see below.

Issues: #256 #257 #258 #259 #260 #261

Description

• Species Type: Full Grammar of some Ideas #256 Full ABNF grammar
  • I added a full definition using ABNF in every section.
  • In the future the rule for elements might have to be updated.
  • Examples are still the main way readability is ensured -- the grammar is intended as an auxiliary tool if the textual description is not sufficient.
• "single species" vs. "multiple species" #257 single species and multiple species
  • There is a clearer distinction made between a single and a list of particle species.
  • Breaking: other: is not allowed in lists, as to allow it the semicolon ; would have to be forbidden from its content.
  • Separator placement is clarified: Double list separator forbidden (item1;;item2), trailing separator optional.
  • Clarified that a list with one particle species and a single particle species must be treated equally -- as they can't (necessarily) be distinguished/used the same syntax.
  • We discussed encoding (relative) quantities included in lists. This is not included.
• Species Type: Character Set after "other:" #258 charset after other:
  • Clarified that only printing ascii characters (0x21-0x7e), as well as space are allowed.
  • Breaking: Control characters are now forbidden. Note that newline (ascii 0xa) and horizontal tab (ascii 0x9) are thereby forbidden too.
  • Added note discouraging use of other: (without suffix) as well as trailing spaces -- even though they are allowed.
• Species Type: Clarification on Atom Syntax #259 clarify atom syntax
  • Clarified that elements must be case sensitive.
• Species Type: Suggestion for Ion Syntax #260 ion syntax
  • Proposition of ion syntax has been dropped.
  • Clarified that ions are not supported by the base standard.
  • Added note discussing when charge state SHOULD NOT and when it MAY be encoded by an implementation.
• Species Type: Clarifications on Molecule Syntax #261 molecule syntax
  • Proposition for molecule syntax has been dropped.
  • Clarified by rewriting paragraph.

In its entirety, this aims to clarify the current version of the standard.
Except for the treatment of other:, all unambiguous parts have been left untouched.

Valid examples:

electron
He
#2H
electron;H
electron;H;
Si;
other:
other:myitem
other:this looks like a list;but is actually a single particle species
other: note that this text can be very long
other: there is no \n escaping

Invalid examples:

species	invalid because
other:·	non-ascii char ·
electron;;H	empty list item/double semicolon ;;
Uux	not part of the periodic table
H2O	molecules not supported

Affected Components

• EXT-SpeciesType

Logic Changes

• other: forbidden in lists
• unprecise description for molecules removed, such implementations would be non-conformant now

Writer Changes

• Forbid non-printing ascii in speciesTypes
• ensure lists do not contain other:
• ensure that particle species lists with one item are equivalent to single particle species

Existing writers are compatible, as long as they

• do not use non-printing ascii chars for speciesType

Reader Changes

Lists with one item must be considered single particle species.

As molecules and ions have been explicitly forbidden, reader implementations are encouraged to specify their additionally accepted syntax explicitly.
(Which they should do anyways).

• openPMD-validator: https://github.com/openPMD/openPMD-validator/
  • not implemented
  • PR #38 is broken anyways (checking against undocumented charset, no syntax checking)

(I did not encounter any other mentions of speciesType in the related tools.)

Data Converter

Not implemented, hence no changes necessary.

[s9105947]

Following discussion in #262 I replaced RFC 2119 terms (MUST, SHOULD NOT...) with bold text, but using lowercase.
I can remove the emphasis, though I'm a little reversed towards that -- I used the subtle differences between must (not) and should (not) deliberately, and kinda fear that being lost. Though diverting the style from the remaining standard must be avoided.

[ax3l]

Thank you already!

I marked a few typos and will do a thorough review soon!

[DavidSagan]

Thanks for the work done by everyone!

[s9105947]

If I read the openPMD validator correctly (do I?), currently only non-empty strings consisting of a-zA-Z0-9:;- are accepted as SpeciesType. Though this is not documented in the current standard, should we put it into the current version?

My main idea of using printing ASCII chars was to allow the broadest, "non-harmful" charset to not break compatability. But I guess that the openPMD validator is also somewhat authoritative, so presumably nothing would be broken by demanding a-zA-Z0-9;:-?

[ax3l]

I think that makes sense, if one uses the speices type extension then one should actually specify a SpeciesType.
(We have special keywords like None for some attributes, but I am not sure it makes sense here.)