Fixed: Expand duration group prose

[ahankinson]

Expands the rules for repeated rhythmic sequences. Nothing has changed except a clarification on how they should be interpreted.

Figuring out where they could and couldn't be used took a bit of time; I think I got it, but may have missed something.

I renamed them "Duration Groups" because they are initiated by a grouping of duration values.

[github-actions]

PR Preview Action v1.4.7
🚀 Deployed preview to https://rism-digital.github.io/pae-code-spec/pr-preview/pr-127/
on branch gh-pages at 2024-06-03 11:40 UTC

[lpugin]

I don't understand this sentence.

[ahankinson]

It just means that the durations cycle... 484ABCDEFGAB would result in the three repetitions of the 484 figure.

[lpugin]

I am confused with the use of MUST here. My understanding is that it is about how things must be coded, not how what is written must match the code, so the MUST is confusing in this paragraph.

[lpugin]

It is like if you say "a note following a 4 MUST be a quarter note"

[ahankinson]

It could a) stop (i.e., not repeat the durations) or b) go backwards (weird, I know, but it could) or c) be interruptible by adding a specific duration (which is why the requirement to cancel it is necessary) or d) apply to only otherwise grouped notes (e.g., only beams would take the duration group).

It's better to be pedantic than to be vague, IMO. There's no room for interpretation when is says it MUST repeat from the first.

BTW, we do say that a note following a 4 MUST be a quarter note... https://plaine-and-easie.info/v2/index.html#durations

[lpugin]

BTW, we do say that a note following a 4 MUST be a quarter note...

Can you point me to the line? Sorry, I cannot find it.

[lpugin]

Suggested change

	A duration group MUST remain in effect until another duration value is declared. A new duration value
	A duration group remains in effect until another duration value is declared. A new duration value

[ahankinson]

Why did you remove this requirement? Without it, there is no requirement that a duration value interrupts the repetition of the group.

[lpugin]

Same as above. I find this confusing.

[ahankinson]

Could you suggest some other wording that keeps the normative requirement that a duration group remains in effect until cancelled?

[lpugin]

Something like `"A duration group indicates that the note names following it have a duration as given in the group and in that order. When the number of notes reaches the number of durations given in the group, the durations applies again from the beginning of the group. Any duration given in the notes following the duration group cancels it."

[ahankinson]

I think we still need the MUST in there to indicate the requirement.

[lpugin]

The second sentence is not very clear. Chords have a single value anyway, haven't they?

[ahankinson]

That's never explicitly stated.

[lpugin]

I was thinking about this

[BaMikusi]

This is just to express my full support for @lpugin's view that the MUST's are quite confusing.
But perhaps an alternative could be to say "will remain" and "will have"?

[ahankinson]

"will" is a statement of fact, not a statement of requirement. "I will go to the store to find milk" is different from "I must go to the store to find milk." It can be made a requirement with the imperative "shall" as in "you shall go to the store and find milk".

I've been using MUST because it imposes a very easy system of understanding what things are required (MUST / MUST NOT), recommendations (SHOULD / SHOULD NOT), and optional (MAY). Otherwise there is a danger that internally the requirements are not phrased in a consistent way and the actual requirements are lost in the "language."

The number of RFC keywords in use can be expanded if you think it would make for better prose, but (at least for me) the words are used to help me keep track of what the actual valid / invalid requirements are, and limiting them helps me to keep a consistent tense, tone, and terminology.

See RFC 2119 for a definition of what each of the terms mean: https://datatracker.ietf.org/doc/html/rfc2119

(Otherwise we end up with the current state of affairs where no one actually knows what "valid" PAE is other than "does it render OK, it must be fine.")

[lpugin]

Sure, I get that, and I am perfectly fine where we have it. It is only that here you use it the other way around. Namely to say that the notes MUST be in accordance with the code.

You do not say that notes after a G-2 clef MUST be in G-2 clef until a clef change is given. Or we say "The clef code MUST be three characters long", but then "The character x indicates sharp keys and b flat keys.", and not "The note with a character x in front MUST be a sharped note".

[BaMikusi]

To approach the point from another angle, if human users will not understand your language (and if Laurent and I both stop short here, there would surely be others), it won't really matter how consistent your text appears to be from a structural point of view.

[ahankinson]

OK; could you help me rewrite it in another way that makes it clear that there are actually some requirements for a duration group? I understand not liking the way it's phrased, but I also need a way of ensuring that someone coming to this that wants to implement support for PAE also knows what their tool MUST or MUST NOT do.

[lpugin]

I'll use this as a model https://plaine-and-easie.info/v2/#repeat-group

[ahankinson]

All users of this spec are human users. It's actually being written specifically FOR human users, who have an annoying tendency to get "creative" with their interpretations when no creativity is desired. If we don't want to end up "cleaning up" the incipits every decade or so because of creative interpretations of the rules, then this is the best chance we have to do so. And the best way I know how to do that is to create a very clear indication of, specifically, what IS and what IS NOT allowed. Not everyone needs to know this, but the people (us, and the "us" in the future) who create the tools that put the red squiggles under the things that are wrong do need to know, and they'll need this document to tell them what everyone else is supposed to be doing too.

If you mean the actual cataloguers looking for guidelines on how to apply these rules, then we have #50 "Create encoding guidelines" which we will write once we settle on the rules. However, #50 also needs to point to something as the authority for what is and isn't allowed.

[BaMikusi]

@ahankinson You seem to have taken my comment as a general criticism for the entire specifications text -- which it was not meant to be. I merely said as much that, if we leave these two passage like this, readers will be confused -- whereby either Laurent's "remain" or my "will remain" would deliver essentially the same message without confusion. I did not say (and did not want to imply) that you should start rewriting the text entirely without modal verbs.

[ahankinson]

Sorry -- it was simply the emphasized "for humans" that triggered me. I know it's not a particularly natural way of writing, and for those who don't deal with specifications it can even be a bit alien, but it's my core intention that it is clearly written for humans first and foremost. (The inverse implication being that I'm simply writing for a mechanical audience...)

[BaMikusi]

Alles klar -- and then apologies for that human from my side.
After all, we are all humans, and if a human writes 20+ emails a day, plus 30+ Slack messages, surely some points will not be made elaborately enough.