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]

We try to avoid unprefixed macros in order to prevent name conflicts with other packages (regardless of how unlikely we think they are). Our prefix system is:

• \gre@: Internal macros that users should never interact with in their documents
• \Gre: Macros written to the gtex file by the executable. Advanced users might interact with these to do special things in their document
• \gre: user facing macros. We expect users to make use of these macros regularly.

With that in mind, \alterationchar and \alterationhole should probably be named \gre@alterationchar and \gre@alterationhole.

[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.

[eschwab]

I have been loosely following this PR, when it is ready I would like to review the documentation for ease of comprehension.

As for ## or #* I concur that ## is a better symbol.

There is also ♯ U+266F the actual sharp, but that would easily be confused with #.

[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!

[rpspringuel]

Please use typographical quotes around behind.

[rpspringuel]

Same comment about quotes.

[rpspringuel]

And a third time.

[davidweichiang]

This was a copy-paste from the existing documentation for \GreFlat and friends. I've changed them throughout the whole manual.