Skip to content

gfx/js: per-preset F1 help URLs for ISF shaders and JS scripts #2094

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
edumeneses wants to merge 1 commit into
base: master
Choose a base branch
from
+47 −1
Open

gfx/js: per-preset F1 help URLs for ISF shaders and JS scripts #2094

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions src/plugins/score-plugin-gfx/3rdparty/libisf/src/isf.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1132,6 +1132,10 @@ static const ossia::string_map<root_fun>& root_parse{[] {
if(v.get_type() == sajson::TYPE_STRING)
d.credits = v.as_string();
}});
p.insert({"DOCUMENTATION", [](descriptor& d, const sajson::value& v) {
if(v.get_type() == sajson::TYPE_STRING)
d.documentation = v.as_string();
}});
p.insert({"CATEGORIES", [](descriptor& d, const sajson::value& v) {
if(v.get_type() == sajson::TYPE_ARRAY)
{
Expand Down Expand Up @@ -2914,6 +2918,12 @@ std::string parser::write_isf() const
oss << " \"CREDIT\": \"" << escape_json(m_desc.credits) << "\",\n";
}

// Add documentation URL if present
if(!m_desc.documentation.empty())
{
oss << " \"DOCUMENTATION\": \"" << escape_json(m_desc.documentation) << "\",\n";
}

// Add categories if present
if(!m_desc.categories.empty())
{
Expand Down
1 change: 1 addition & 0 deletions src/plugins/score-plugin-gfx/3rdparty/libisf/src/isf.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,7 @@ struct descriptor
} mode{ISF};
std::string description;
std::string credits;
std::string documentation;
std::vector<std::string> categories;
std::vector<input> inputs;
std::vector<output_declaration> outputs; // Parsed from OUTPUTS array; empty = single color output
Expand Down
2 changes: 2 additions & 0 deletions src/plugins/score-plugin-gfx/Gfx/ISFProcess.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ struct ISFHelpers
base.author = QString::fromStdString(desc.credits);
if(!desc.description.empty())
base.description = QString::fromStdString(desc.description);
if(!desc.documentation.empty())
base.documentationLink = QUrl(QString::fromStdString(desc.documentation));
for(auto& cat : desc.categories)
base.tags.push_back(QString::fromStdString(cat));
}
Expand Down
35 changes: 34 additions & 1 deletion src/plugins/score-plugin-js/JS/JSProcessFactory.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,40 @@ struct LanguageSpec
static constexpr const char* language = "JS";
};

using ProcessFactory = Process::ProcessFactory_T<JS::ProcessModel>;
// Scan the first lines of a QML script for a `// @documentation <url>`
// 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");

@jcelerier jcelerier Jul 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

@edumeneses edumeneses Jul 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

int line = 0;
for(const QString& raw : script.split('\n'))
{
if(++line > 20)
break;
const QString trimmed = raw.trimmed();
if(trimmed.startsWith(tag))
{
const QString url = trimmed.mid(tag.size()).trimmed();
if(!url.isEmpty())
return QUrl(url);
}
}
return {};
}

class ProcessFactory final : public Process::ProcessFactory_T<JS::ProcessModel>
{
public:
using Process::ProcessFactory_T<JS::ProcessModel>::descriptor;
Process::Descriptor descriptor(const Process::ProcessModel& m) const noexcept override
{
auto desc = Metadata<Process::Descriptor_k, JS::ProcessModel>::get();
const auto& js = safe_cast<const JS::ProcessModel&>(m);
if(auto url = documentationUrlFromScript(js.executionScript()); !url.isEmpty())
desc.documentationLink = url;
return desc;
}
};
struct LayerFactory : Process::EffectLayerFactory_Base
{
using Model_T = JS::ProcessModel;
Expand Down
Loading