RFC: Script group names

[Nick-Mazuk]

The issue

This is in response to #257.

#257 adds a new script to help configure the hairpin_creator.lua script. The configuration script is named "Hairpin creator configuration", which makes sense. However, on the website the original script is named "Hairpin create crescendo".

https://www.finalelua.com/scripts?search=Hairpin%20create%20crescendo

This has a few issues:

1. Someone who reads "Hairpin create crescendo" might not realize it creates other hairpins
2. Someone looking at the website might not realize the two scripts are related

I suggest we figure out a better way of naming scripts with multiple menu items.

How names are currently determined

Names are currently determined from the return value in the plugindef:

function plugindef()
    return "Hairpin create crescendo", "Hairpin create crescendo", "Create crescendo spanning the selected region"
end

This script's name will be shown as "Hairpin create crescendo" since that string is the first value in the return statement. This made sense when we didn't have additional menu options since the first value in the return statement would be what's displayed in the Finale menu. However, this doesn't make sense for scripts taking advantage of the recently added finaleplugin.AdditionalMenuOptions option.

function plugindef()
    finaleplugin.AdditionalMenuOptions = [[
        Hairpin create diminuendo
        Hairpin create swell
        Hairpin create unswell
    ]]
    finaleplugin.AdditionalDescriptions = [[
        Create diminuendo spanning the selected region
        Create a swell (messa di voce) spanning the selected region
        Create an unswell (inverse messa di voce) spanning the selected region
    ]]
    finaleplugin.AdditionalPrefixes = [[
        hairpin_type = finale.SMARTSHAPE_DIMINUENDO
        hairpin_type = -1 -- "swell"
        hairpin_type = -2 -- "unswell"
    ]]
    return "Hairpin create crescendo", "Hairpin create crescendo", "Create crescendo spanning the selected region"
end

Now, the name "Hairpin create crescendo" doesn't accurately represent what this script file accomplishes.

Proposal

For scripts with multiple menu items, we allow a new item in the plugin def for the script group name.

function plugindef()
    finaleplugin.ScriptGroupName = "Hairpin creator"
    return "Hairpin create crescendo", "Hairpin create crescendo", "Create crescendo spanning the selected region"
end

To prevent abuse, the new finaleplugin.ScriptGroupName field will be ignored if there aren't any additional menu options. However, when there are additional menu options, the script group name will be displayed on the website instead of the first value in the return statement.

No changes will be needed to RGP Lua, only to the metadata generator. I hope to tackle this and a few other metadata generator backlog items within the next week or two. Though opening this up for comments and suggestions in the meantime.

cc @cv-on-hub @rpatters1

[rpatters1]

This sounds reasonable to me. Note that all the other finaleplugin properties use Pascal case, so I think this one should be as well.

[Nick-Mazuk]

Note that all the other finaleplugin properties use Pascal case, so I think this one should be as well.

Yes, thanks for pointing that out. I've updated the original post to reflect that (and will use PascalCase when I actually implement this).

[cv-on-hub]

This is an excellent proposal. The "wrong name" has bothered me since the first time I used AdditionalMenuOptions.

[Nick-Mazuk]

Sounds like there's consensus that I should move forward on this.

If either of you want to create PRs adding the new finaleplugin.ScriptGroupName to existing scripts, feel free. That way when I update the metadata parsing and website those script names will automatically be updated.

[Nick-Mazuk]

I'm working on this right now.

As I was rereading #169, I noticed we also had the discussion of how to show the additional descriptions.

With the current finaleplugin.ScriptGroupName proposal, the description of the first script would still be shown on the website (i.e., "Create crescendo spanning the selected region" in the above example). As I'm implementing this right now, I'll also add a finaleplugin.ScriptGroupDescription field that will act just like the ScriptGroupName field but for descriptions.