Add option to print only the first flat on each line

[davidweichiang]

This uses post_linebreak to figure out the first flat on each line, and records this information in the .gaux file so that \gre@alteration can print only the first flat. It needs two or three runs to converge.

Closes #157. (But not #1575.)

[davidweichiang]

Here's an example of the same score set at two different widths (and where GregoBase is currently wrong):

[rpspringuel]

Just one thing that I see right now (and it's not feature related), but it may just be my relative unfamiliarity with the desired feature.

Do you think that you could create a matching branch in the test repository and commit proposed tests showing the behavior you're trying to fix. Said tests could be based on the scores where things are currently incorrect, but if the problems are not glaringly obvious at a glance, some text explaining the problem should be added to the test.

I wouldn't commit the "corrected" expectations yet so that the image comparison failures can be used to highlight the changes and make sure they are what is desired.

[davidweichiang]

Done, though I'm not sure if the test is what you're looking for yet.

[rpspringuel]

Thinking about this, a modification to the gabc syntax may be necessitated by this idea: we might need to differentiate between a flat (or other alteration) that should always show and one that is allowed to disappear according to the ruleset chosen in the document.

Currently we have gx, gy, and g# which produce their respective alteration. I would assign these to the forced alteration set (in keeping with their current behavior, where all alterations are forced). gX and gY could be used for optional flats and naturals (ones subject to the ruleset), but what would the equivalent for the sharp be?

[davidweichiang]

I added the header option alteration-scope:line to indicate that all the flats in the score are "optional." But in the example, there is one flat that doesn't really need to be there, so I think it makes sense to always have the current "hard" flat available. In that case, I think the header option will no longer be needed.

I like gX and gY (though I am unsure if gY is really needed). I imagine that the "soft" sharp would be very rare, so maybe something like g#*?

[rpspringuel]

Looking back over #157 and #1575, I noticed that naturals (or sharps, I suppose) would also cancel the flat. @davidweichiang, have you taken that into account in this change? (I'm working on my own multi-line initial branch to try and get that finished and so don't have time to poke at this thoroughly myself).

The other points where alterations might get canceled are word-breaks and bar lines. We'll want to implement those possibilities eventually (and the combinations there-of that specify the Vatican and Dominican rulesets), but if we can just get naturals and line breaks for now, I think that's sufficient.

[davidweichiang]

The current logic is:

• Hard flats (x), sharps (#), and naturals (y) are always printed. So are the parenthesized (?) versions.
• A soft flat (X) is printed iff it is the first alteration (of any type) on the line or the previous alteration on the line is not x or X.
• Similarly for soft sharp (#*).
• A soft natural (Y) is printed iff the previous alteration on the line is not a natural (either y or Y).

So, for example, if the alterations on a line are YXXYYX, then they would be printed as

• Y: nothing
• X: flat
• X: nothing
• Y: natural
• Y: nothing
• X: flat

[davidweichiang]

I tried to explain the current logic in the documentation, and I hope it was clear enough. I think this is ready to go but am of course happy to make further changes if needed.

Here's a summary of the user-facing changes:

• Three new alterations, soft flat (X), natural (Y), and sharp (#*). Not a lot of thought was put into the choice of #*.
• A new command named \gresetalterationeffect. I don't know what the convention is about whether the name should include set. And maybe scope was a better choice than effect.
• Theoretically the argument is a comma-delimited list of keywords, but the only meaningful choices are
  • \gresetalterationeffect{note} (the default): print all soft flats and sharps, and no soft naturals
  • \gresetalterationeffect{line}: Dominican

[rpspringuel]

Do we use * for anything else? I don't recall off hand. If not then * could be the soft sharp all by itself.

[davidweichiang]

I don't see \* in the parser code, but that seems like a nice character to spend on something that will never(?) get used...

How about ##, which is sort of like a big #?

[rpspringuel]

I'm not to worried about "spending" characters. Adding new gabc syntax has become a very rare event at this point and we still have lots of unused characters.

[davidweichiang]

I'll change it to ## if it's okay with you. Has a clearer connection to # and is easy to type.

[davidweichiang]

Thanks! IMO the documentation is ready for review, but it will be very helpful to have a third pair of eyes on it.

[davidweichiang]

Actually, no, I'm not happy with the documentation. I'll work on it more and let you know when it's really ready.

[rpspringuel]

Don’t forget we have the doc_check.sh script to help with the documentation process. It won’t write documentation for you, but it’ll help you identify which macros still need to be documented.

_{Sent with GitHawk}

[davidweichiang]

@eschwab Hopefully that's better now!

[davidweichiang]

@rpspringuel and @eschwab I believe this is ready to go -- your remaining comments would be welcome!

[rpspringuel]

I don't see a CHANGELOG entry. Still examining other aspects of the PR.

[davidweichiang]

Done (not sure how much detail to go into, since it's complicated to explain)

[rpspringuel]

Test results all look good.

[davidweichiang]

What's the convention about \gresetalterationeffect vs. \grealterationeffect?

[davidweichiang]

I've tried to incorporate all the suggestions above. Thanks!

[rpspringuel]

\greset… is the appropriate naming convention for macros which change a setting. Our conventions have been adopted in a somewhat ad hoc manner and so some older setting macros don’t follow this one, but anything we add now should.

_{Sent with GitHawk}

[rpspringuel]

I think this is ready for merge once the conflicts are resolved (and that conflict is really inconsequential). @davidweichiang, can you merge in the latest version of develop and resolve the conflict created by the recent merge of #1610.

[davidweichiang]

Done! Thanks, hopefully this will be a big time-saver for some people.

[eschwab]

Let me just build and test it. If all good, I'll merge it in.