minor improvement for <chord> documentation

[lemzwerg]

While walking in the garden of abnormal MusicXML code, I found a (theoretical) example that follows the standard to the letter, but which is most certainly not what we want to see in reality. Please consider the following pseudo-XML code that constructs a two-note chord.

<note>       # at beat 1
<forward>    # one beat
<direction>  # at beat 2, for example 'sf'
<backward>   # one beat
<note>       # with a <chord> child

I thus suggest to improve the documention of <chord>. For example, this sentence

The <chord> element indicates that this note is an additional chord tone with the preceding note.

could be extended to

The <chord> element indicates that this note is an additional chord tone with the preceding note (without any <backup> or <forward> elements in between).

Alternatively, the documentation for <backup> and <forward> could mention that these elements are not allowed within a chord.

[infojunkie]

I don't think there's value in augmenting the documentation to handle hypothetical cases. It's like code, or human language: of course we can invent nonsensical phrases, but there's potentially an infinity of them. Creating rules to avoid hypothetical constructs will cause adverse effects: make the doc harder to read and reason about, detract attention from the real-world cases, and also run the risk of blocking potential uses that may be legitimate but that had not been considered when adding the rule.

The cases that are more interesting and worthy of documentation / schema modification are musical constructs that exist in the real world but cannot be represented in MusicXML. You and others have brought forward many of such cases and they are highly useful to help advance the spec.

Maybe we can consider hypothetical cases such as this one the equivalent of "unit tests" for the spec. As such, the best place to include them would be the semantic tests library that we're building. I would actually welcome your involvement in this initiative, seeing your interest in pathological cases.

[lemzwerg]

Well, I don't really agree with you – there are always apps that do the unthinkable. My example is <backup> – I really thought that people would follow the recommendation in the specification of always starting a new voice or staff. However, it's only described as 'generally used', and Dorico ignores it by happily emitting the following construct (in pseudo-XML).

<note>    # a quarter on beat one, voice 1
<backup>  # one beat
<harmony> # on beat one
<forward> # one beat
<note>    # on beat two, voice 1
...

I consider it bad that the specification is always 'behind', that is, people bend MusicXML in ways nobody is expecting, and we can only say "alas, it's too late to change that in the specification because apps are using it" in hindsight.

On the other hand, unit tests would be a good thing to test conformity. However, such tests are not a replacement for proper documentation to avoid unwanted interpretation IMHO.

[lemzwerg]

What I could imagine is to have a new section in the MusicXML specification between 'Attributes' and 'Examples' called 'Remarks'. In this new section there could be the 'fine print', holding more information that clarifies borderline situation like this one. Doing so wouldn't disturb the big picture but still give additional info.

[infojunkie]

Yes, I was thinking of something similar. Remarks / notes is a good way to approach gotchas, warnings, difficulties, etc., that don't belong to the schema documentation. It so happens that this is exactly what I'm currently working on for the site rewrite - markdown additions to the main documentation.

[infojunkie]

@lemzwerg continuing the discussion here until we reach some actionable conclusion.

However, it's only described as 'generally used', and Dorico ignores it by happily emitting the following construct (in pseudo-XML).

Can you show the source score and resulting MusicXML that Dorico emits? It might just be a bug on their side.

If the need is legitimate and inexpressible in MusicXML, then this is a concern to be addressed here. If the source can be represented in MusicXML today, and the Dorico export is wrong, then it's on their side.

we can only say "alas, it's too late to change that in the specification because apps are using it" in hindsight.

I'm not sure this scenario applies here. We started from a hypothetical case, and now you mention that Dorico produces what seems to be invalid MusicXML. There is nothing in the documentation that would be too late to revert.

However, such tests are not a replacement for proper documentation to avoid unwanted interpretation IMHO.

In my mind, it's the opposite. Prescriptive documentation (and laws) can only go so far to avoid unwanted behaviour, because human language is malleable and open to loophoiles. Tests, on the other hand, provide an unambiguous pass/fail judgment - that's why they are favoured in software. My thinking is that providing a battery of tests that demonstrate invalid MusicXML constructs, and that can be constantly augmented with new cases, will be valuable (and more efficient than prescriptive documentation) to software makers as they are developing their MusicXML import / export.

I hope that you can assist in this direction of building out validity tests, which I view as related to the wonderful MusicXML test suite in Lilypond that you've been maintaining.

[lemzwerg]

Can you show the source score and resulting MusicXML that Dorico emits? It might just be a bug on their side.

It can be found here; in case it matters it was produced with Dorico version 5.1.70.2200. To repeat: this MusicXML file is fully conforming! However, it uses the 'generally used' loophole in the specification, which doesn't inhibit the use of <backup> within the same voice.

If the need is legitimate and inexpressible in MusicXML, then this is a concern to be addressed here. If the source can be represented in MusicXML today, and the Dorico export is wrong, then it's on their side.

It's neither of that. Of course, the expected way to code the above example is

<harmony> # on beat one
<note>    # a quarter on beat one, voice 1
...

but nothing in the specification prevents what Dorico is doing.

BTW, my 'hyphothetical case' is also fully conforming with the current text of the specification.

My thinking is that providing a battery of tests that demonstrate invalid MusicXML constructs [...]

Who decides what is valid and what is invalid? IMHO this can't be done ad-hoc; instead, it must be documented somewhere.

I hope that you can assist in this direction of building out validity tests, which I view as related to the wonderful MusicXML test suite in Lilypond that you've been maintaining.

Will try. At least I seem to be good at finding loopholes 🙂