@DaveVenom, thanks for the detailed notes in the Quick reference thread (post 32). This reply covers Help. I’ll follow up with separate posts on Clarity, Test Gear and Dark.
Here’s the new design I propose for Help.
Help text will no longer be compiled into the plugin. It will be read from JSON files, one per module. Each file has the module’s description, then each parameter, input, output and indicator with its own text beside it, then any notes. The separate tables you found hard to follow are gone. Where one sentence covers a row of controls, the entry lists all their numbers, so it’s written once and you can see what it applies to. A plugin’s help is a folder of these files, one per module and named by module slug. The layout is the same wherever it lives: in your repository and installed plugin it’s your plugin’s help folder, and in the shipped database and a user’s folder it’s a folder named for the plugin.
For each control, Help will look in three places, in this order:
- The maker’s own file, shipped in a
helpfolder inside their plugin. The maker’s words win wherever they’ve written them, and they update with the maker’s releases. Makers never need anything from me: no pull request and no waiting for a Help release. - A user’s file in the Rack user folder. This is for modules whose makers haven’t written help, including closed-source ones. Someone who knows the module can fill it in, and library updates never touch it. A “Send this help” item on the main help pop-up opens a GitHub issue with the file ready to paste, and I’ll review it and fold it into the shipped database.
- The shipped database, which gives every module that can be analysed some help from day one.
I considered letting a user’s file override the maker’s, so that users could correct it. The problem is that a user’s file stays in place indefinitely. If a maker later fixes or expands their help, a stale user file would go on hiding the newer text, and nothing would show that it had gone out of date. Either order has some drawback, but the maker’s version is the one that follows the module’s changes, so it takes precedence wherever it exists. A correction to a maker’s help belongs with the maker.
A file can cover just part of a module, and the rest comes from the next source. Each pop-up says where its text came from, which also answers your earlier question about a bare-bones file against a fuller one.
For makers who’d rather not create that JSON by hand, help can be written in the source code. Directly after the line that configures a control, which is where its tooltip is defined, you add comment lines starting with //?. Those become that control’s help. //?module gives the module’s description, and //?note adds a note. A small Python script, using only the standard library, reads the source and writes the JSON files into your help folder. It turns control names into numbers from your enums, including ENUMS runs, and a configure call inside a loop covers the whole run. Anything it can’t place, it reports with the file and line instead of guessing. I’ve kept help separate from tooltips on purpose: a tooltip is best kept short, and help is where the detail goes.
So that a maker or a user doesn’t have to start from an empty file, the Help module’s right-click menu will have an export. It writes a starting file for every module in a chosen plugin, with every control, input, output and indicator listed, the current text beside each entry for reference, and blanks to fill in.
About speaking the whole help pop-up by default: I’d rather keep it as it is, where clicking a line speaks that one line. I’ll also keep speech as part of the help pop-up, available by clicking on the text you can see, rather than as a separate option. With my eyesight, I may read a short text myself and ask for it to be spoken when I prefer. And because text to speech sometimes garbles a word or a symbol, I may need to look at the text to understand a detail.
About choosing the key and click that opens help: I’ll add that. Option-click (Alt-click on Windows) stays the default, and the Help module’s right-click menu will let you pick another combination.
About the scroll bar appearing sometimes and not others: I’m looking into it, but I haven’t reproduced it yet. If you can tell me a module and a control where it happens, that would help me find it.
I’ve confirmed two of your bugs. Controls on a child panel, as in Envelope Factory, are missed because Help only looks at controls attached directly to the module’s panel. And on Windows, a new reading doesn’t stop the one before it. I’ll fix both.