search

rism-digital / pae-code-spec

Issue tracker and website for the Plaine and Easie specification
https://plaine-and-easie.info/
0 stars 0 forks source link

Fixed: Expand duration group prose #127

Open ahankinson opened 1 month ago

ahankinson commented 1 month ago

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[bot] commented 1 month ago

PR Preview Action v1.4.7 :---: :rocket: 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

BaMikusi commented 1 month ago

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 commented 1 month ago

"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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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

ahankinson commented 1 month ago

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 commented 1 month ago

@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 commented 1 month ago

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 commented 1 month ago

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.