Add minimum plugin version to the metadata parser

[Nick-Mazuk]

Scripts can have the finaleplugin.MinJWLuaVersion metadata field set in their plugindef. #121 Brought this to my attention, and this field should be displayed on the website where users download scripts under "More details" (or "Hide details" when the details are shown, as in the screenshot). This means this field must be parsed as part of the metadata json for the scripts.

I'll fix this.

[rpatters1]

The full list of fields like this is:

finaleplugin.MinJWLuaVersion
finaleplugin.MaxJWLuaVersion

Both JW Lua and RGP Lua respond to these as you would expect. The difference is that JW Lua will put them in the menu but refuse to run them (with an error message). RGP Lua does not even load them.

finaleplugin.MinFinaleVersion
finaleplugin.MaxFinaleVersion

Both JW Lua and RGP Lua respond to these as you would expect, but these refer to the Finale "year". JW Lua treats any version after Finale 2014 as having version 9999 (if I recall correctly: I haven't tested it recently). Finale 2014.5 and earlier use the year number. RGP Lua adds 10000 to the 64-bit version number. So Finale 25 would be 10025, etc. The idea is that if you have a MinVersionNumber of Finale 26, you would use 10026 as the MinVersionNumber, and that should prevent it from loading on JW Lua at all.

finaleplugin.MinFinaleVersionRaw
finaleplugin.MaxFinaleVersionRaw

These are only recognized by RGP Lua, and they refer to the 32-bit raw Finale version, which makes more sense as a hex number than a decimal number. The JW Lua docs describe it.

I'm not sure if it makes sense to capture all of these in the docs, but MinJWLuaVersion certainly does.

[Nick-Mazuk]

Thanks for all the details!

I think it does make sense to parse them all for the docs because if someone specifies it, there's probably a reason. We can then choose which ones to display later, though I'll probably just go ahead and display them all so we don't get as many random messages about "why isn't this working?".

[rpatters1]

I have realized that a lot of the metadata fields that Jari recommended were not actually used by JW Lua. It appears that Jari had an idea of eventually creating a repository much like this one, and many of the metadata fields were with an eye towards implementing it. RGP Lua reads the obvious ones and a few of the others, but besides the obvious ones it doesn't do anything with that data. I think we can decide what metadata we'd like to see be in the plugindef function. Both JW and RGP Lua ignore fields they don't know about. That might include expanding the list of categories to whatever we want them to be. (I find Jari's list to be somewhat limited and outdated.)

And while we are on the topic of documentation, I realized we have no way to add a description of each script and how to use it. (We have that for library functions but not the scripts themselves, unless I missed it.) As part of the RGP Lua 0.59 release I will be submitting some changes to a few of the scripts to respond to the shift and/or opt/alt key and change behaviors (when running under RGP Lua 0.59). It would be nice to be able to document this.

Also, as an aside, I finally have the needed new properties in FCArticulation to finish autopostion_rolled_chords.lua, which I will be submitting as well (with MinJWLuaVersion set) as soon as I release 0.59. And it will have a behavior change based on modifier keys, basically the same as my plugin of similar name.

[Nick-Mazuk]

I realized we have no way to add a description of each script and how to use it

JW Lua specifies a field in the plugindef called finaleplugin.Notes. This accepts any multi-line string and isn't parsed by anything right now except the workflow that parses this metadata for the docs website. So we can add usage instructions to this field and they will appear on the site.

If you were to press "Show details" to expand the script description, this Notes metadata will appear right above "Author" in this image.

No script in the repo currently uses this field. If you want an example of how to use it, this is the test case for the deploy script:

https://github.com/finale-lua/jw-lua-scripts/blob/3fc1c7d6d31654483e39e97e9ba8177146b6b98e/.github/actions/get-metadata/tests/06-notes.lua#L1-L8

Which is parsed into this JSON:

https://github.com/finale-lua/jw-lua-scripts/blob/3fc1c7d6d31654483e39e97e9ba8177146b6b98e/.github/actions/get-metadata/tests/06-notes.json#L1-L21

[rpatters1]

Perfect. I suggest we encourage developers to use this field for specifying how to use the script and what the use cases might be.

…

On Sat, Jan 15, 2022 at 9:48 PM Nick Mazuk ***@***.***> wrote: I realized we have no way to add a description of each script and how to use it JW Lua specifies a field in the plugindef called finaleplugin.Notes. This accepts any multi-line string and isn't parsed by anything right now *except* the workflow that parses this metadata for the docs website. So we can add usage instructions to this field and they will appear on the site. If you were to press "Show details" to expand the script description, this Notes metadata will appear right above "Author" in this image. [image: Screen Shot 2022-01-15 at 7 44 29 PM] <https://user-images.githubusercontent.com/5659171/149646404-712a18b2-2712-478b-9040-1e11e0e40132.png> No script in the repo currently uses this field. If you want an example of how to use it, this is the test case for the deploy script: https://github.com/finale-lua/jw-lua-scripts/blob/3fc1c7d6d31654483e39e97e9ba8177146b6b98e/.github/actions/get-metadata/tests/06-notes.lua#L1-L8 Which is parsed into this JSON: https://github.com/finale-lua/jw-lua-scripts/blob/3fc1c7d6d31654483e39e97e9ba8177146b6b98e/.github/actions/get-metadata/tests/06-notes.json#L1-L21 — Reply to this email directly, view it on GitHub <#122 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACYB6X3KUMBFKU5HFNUG6NTUWI5XPANCNFSM5LGGHAJQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you commented.Message ID: ***@***.***>

[rpatters1]

I've started adding finaleplugin.Notes to some of the scripts. Is that supposed to show up in the Show Details for on the website? On Sun, Jan 16, 2022 at 7:35 AM Robert Patterson < ***@***.***> wrote:

…

Perfect. I suggest we encourage developers to use this field for specifying how to use the script and what the use cases might be. On Sat, Jan 15, 2022 at 9:48 PM Nick Mazuk ***@***.***> wrote: > I realized we have no way to add a description of each script and how to > use it > > JW Lua specifies a field in the plugindef called finaleplugin.Notes. > This accepts any multi-line string and isn't parsed by anything right now > *except* the workflow that parses this metadata for the docs website. So > we can add usage instructions to this field and they will appear on the > site. > > If you were to press "Show details" to expand the script description, > this Notes metadata will appear right above "Author" in this image. > > [image: Screen Shot 2022-01-15 at 7 44 29 PM] > <https://user-images.githubusercontent.com/5659171/149646404-712a18b2-2712-478b-9040-1e11e0e40132.png> > > No script in the repo currently uses this field. If you want an example > of how to use it, this is the test case for the deploy script: > > > https://github.com/finale-lua/jw-lua-scripts/blob/3fc1c7d6d31654483e39e97e9ba8177146b6b98e/.github/actions/get-metadata/tests/06-notes.lua#L1-L8 > > Which is parsed into this JSON: > > > https://github.com/finale-lua/jw-lua-scripts/blob/3fc1c7d6d31654483e39e97e9ba8177146b6b98e/.github/actions/get-metadata/tests/06-notes.json#L1-L21 > > — > Reply to this email directly, view it on GitHub > <#122 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/ACYB6X3KUMBFKU5HFNUG6NTUWI5XPANCNFSM5LGGHAJQ> > . > Triage notifications on the go with GitHub Mobile for iOS > <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> > or Android > <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. > > You are receiving this because you commented.Message ID: > ***@***.***> >

[Nick-Mazuk]

Yes, it is supposed to show up. Looked at this and it turns out because the repo named change, the automatic deployments broke. Will work on fixing this later today if I have time.

Also unrelated, I got a feature request for RGP Lua via email to allow custom images in dialogs.

[jwink75]

Oh wow, custom images in dialogs would be amazing! I imagine it would be a lot to wrap my head around, but that would be amazing. Potentially even more amazing would be the ability to use different fonts in the dialogs, would that be possible at all? I was envisioning something like a little dashboard that could pop up for inputting all the fun, wacky shapes in the SMuFL fonts like the random curves or the varying width sine shapes, but without the ability to use those characters there’s no really elegant way of doing that.

…

-Jake

On Jan 19, 2022, at 9:56 AM, Nick Mazuk ***@***.***> wrote: Yes, it is supposed to show up. Looked at this and it turns out because the repo named change, the automatic deployments broke. Will work on fixing this later today if I have time. Also unrelated, I got a feature request for RGP Lua via email to allow custom images in dialogs. — Reply to this email directly, view it on GitHub <#122 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMCBUQ36GSZSTACZYWOQ3PTUW33L3ANCNFSM5LGGHAJQ>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you are subscribed to this thread.

[rpatters1]

Those kinds of UI-based changes (with the possible exception of changing the font on the mac side) would introduce considerable complexity. I have been restricting myself to expanding on the existing framework as much as possible.

Personally, adding bells and whistles to the UI is not a priority for me. For example, the modeless support I added was already there in the PDK Framework and just needed to be hooked up to Lua, with some minor tweaks to get rid of global variables. It also had a knock-on effect of enabling the forthcoming Lua state retention feature, so it was worth the effort irrespective of UI.

When it comes to scripting I tend to agree with Elon Musk (to a degree) that all input is error. By that I mean that I would rather expend effort to eliminate a UI than to create a fancier one. (I am currently busy making all my script dialog boxes optional.) Custom graphics and even changing fonts on the Windows side will require significant effort and/or incur significant risk. Maybe Jan Angermüller will take it on, because I know he would like to have custom graphics. But taking that as an example, normally you store custom graphics in resources, but lua scripts don't have resources. So now you have to invent a way to manage them that's cross-platform. It certainly can be done, but not by me (at least so far as I can predict).

BTW: I wonder if you could create a dialog in a C/C++ library and call it from a script. RGP Lua supports loading them. The most reliable way would be to compile in the same version of Lua that I'm using (which is generic Lua 5.2 with one bug fix that enables C/C++ library loading). One of the things that is on my list is to break out that Lua version into a separate repository, since it is completely independent of MakeMusic's proprietary code. That would greatly facilitate the creation of RGP Lua-specific libraries.