gfx/js: per-preset F1 help URLs for ISF shaders and JS scripts#2094
gfx/js: per-preset F1 help URLs for ISF shaders and JS scripts#2094edumeneses wants to merge 1 commit into
Conversation
ISF (libisf): parse an optional "DOCUMENTATION" key from the ISF JSON header into descriptor::documentation, serialize it back, and set it as the process documentationLink in descriptorFromISFFile. Lets a shader preset point F1 at its own page instead of the generic ISF site. JS (score-plugin-js): add a ProcessFactory that overrides descriptor(const ProcessModel&) to scan the QML's first lines for a `// @documentation <url>` comment and use it as the documentationLink. With these, score-user-library presets can route F1 to their own score-docs pages. Verified compiling (libisf + gfx + js TUs); the rest of the tree has unrelated pre-existing build breakage in this checkout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| // comment so a preset can point F1 to its own help page. | ||
| inline QUrl documentationUrlFromScript(const QString& script) noexcept | ||
| { | ||
| static const QString tag = QStringLiteral("// @documentation"); |
There was a problem hiding this comment.
hmmm I'm not sure we want to add magic tags to JS... the fact that ISF is JSON inside a comment is already a constant source of headache. Maybe we could have a separate .json file with useful metadata instead ?
but generally I'm still dubious about the presets having their own documentation page, as the idea of presets is that people can bring their own and then suddenly it creates an imbalance where some presets have documentation and others don't, I think we should work on the design of the feature a bit more!
There was a problem hiding this comment.
Your argument is technically sound, but I feel users lose a lot without documentation for the extensive list of presets. I consider them score features, just as built-in PD abstractions count as "objects" for PD users (and some users never realize a lot of built-in PD objects are in fact abstractions).
What about another method to create help files or documentation for those user-created processes (templates)? We could have something similar to SuperCollider, where each template has its own help file, or an example/help system for scores (similar to PD and Max).
2 participants
ISF (libisf): parse an optional "DOCUMENTATION" key from the ISF JSON header into descriptor::documentation, serialize it back, and set it as the process documentationLink in descriptorFromISFFile. Lets a shader preset point F1 at its own page instead of the generic ISF site.
JS (score-plugin-js): add a ProcessFactory that overrides descriptor(const ProcessModel&) to scan the QML's first lines for a
// @documentation <url>comment and use it as the documentationLink.With these, score-user-library presets can route F1 to their own score-docs pages. Verified compiling (libisf + gfx + js TUs); the rest of the tree has unrelated pre-existing build breakage in this checkout.