Any thoughts?

Yeah KRunner lack discoverability.

I would suggest to add those keys to the Krunner kcm in a column.

And add a deploying suggestion box below the input to list them or in the one that appears when you click on the down arrow below/above the search history.

I have updated the description with the mockup and a bit of explanation on the backend.

Firstly: I think this is quite an important thing to solve. IMO most users would be interested in knowing at least the general purpose features of KRunner (like calculation, unit conversion, time zones, window switching) but will only learn about them if they are observant enough and find them by chance.

In the case of KRunner we are not even getting the basics of providing help right: There is no help button. There is no way to learn about KRunner usage without searching online. Even when opening the help center there is only one page for KRunner ( help:/plasma-desktop/krunner.html ) as part of the plasma-desktop help and that page doesn't explain how to use the coolest KRunner features.

But there is a help page that is actually useful: https://userbase.kde.org/Plasma/Krunner
So I think step one is to add a button to KRunner that will display this help. The easy fix would be to just have an "Online Help" button but the KDE preferred way (?) is probably a handbook page somewhere.

That webpage also has an interesting sentence:

Clicking on the '?' icon opens a scrollable list that explains the syntax of all the available runners. This is a good way to discover new functionality!

It seems like the feature you are proposing here already existed in some form back then? Does the code for it still exist? It would be very interesting to find out why this was removed and how it displayed the information. I found a 10 year old picture of the question mark in question:

In any case the idea in the task description is definitely a step in the right direction. I am a bit worried about the discoverability of this discoverability feature though. ^^

• The button to open the example has no text and no descriptive icon
• To get there one has to click "Configure KRunner..." which isn't where one would expect such a feature

In any case I brainstormed a bit about what would be the ideal solution and this is the best idea I had so far:

I hope these mockups get the main points across. I didn't stress about details when making them and copy-pasted parts of the article from https://userbase.kde.org/Plasma/Krunner which is pretty exhaustive and helpful like I said. The queries and the description from Plasma::RunnerSyntax could also appear in this new right part of the KCM and even appear instead of an article if those queries and descriptions are descriptive enough (or maybe have a "Syntax" button at the top-right?).

First of all thanks a lot, those are some awesome ideas!

But there is a help page that is actually useful: https://userbase.kde.org/Plasma/Krunner

That one is completely outdated, unfortunately :/

I found a 10 year old picture of the question mark in question:

This is it looks when you click it:

Does the code for it still exist? It would be very interesting to find out why this was removed and how it displayed the information.

It could exist somewhere, but I doubt that it will be very useful. I know for sure that the syntaxes were also used. They have been around for ages.
To the why it was removed: Most likely the missing multiline support in Krunner5, this renders the concept on how they were displayed useless.

Also when discussing this some time ago with @ngraham we came to the conclusion that some kind of inline help might be useful, but should not be the priority. This is because KRunner is very limited in the text it can display and also in extra functionality, like the launch button mentioned. Also it would be really overwhelming to get so much information at once. And the plugin selector is a really good overview of all the plugins that are available.

The button to open the example has no text and no descriptive icon

That was a proof if concept screenshot, when creating a MR in the framework. We can choose any icon and text we want ;-)

To get there one has to click "Configure KRunner..." which isn't where one would expect such a feature

That is a good point. It was done differently in KDE4 where each you could click a configure icon for each runner match.

And these mockups are a great idea!

The queries and the description from Plasma::RunnerSyntax could also appear in this new right part of the KCM and even appear instead of an article if those queries and descriptions are descriptive enough (or maybe have a "Syntax" button at the top-right?).

Hmm, the way you described it we would have two sources of data: The Runner syntaxes and the article(could be a docbook).
The syntaxes are for the biggest part already available, even though they might need a bit of an update. But there are currently no docbooks/other documentation formats for runners, which could make it very hard to make it look consistent (like if you have an example with a lot of screenshots etc and then just two lines of explaining text for the next plugin).

Also the docbooks would be static, meaning that they could not adapt to the config like trigger words that are essential for the syntaxes. And functionality like the launch button, could not be implemented. And such a button is IMO super useful, because it allows you to type out a query with just one click.

But I think the way you aligned the usage information to the right of the plugin selector is really nice. Especially because we are now using systemsettings instead of kcmshell we have a far bigger window by default, which we could make good use of with your proposal. Then we could use the design of the mockup on how to display the syntaxes.

But there is a help page that is actually useful: https://userbase.kde.org/Plasma/Krunner

That one is completely outdated, unfortunately :/

Well, it is the best we have. ^^ I still think it does a great job explaining the concept of KRunner and plugins to new users. Anyways –

I normally try to imagine what would be the ideal solution first and then see what is practical. So if you want we can ignore the article for now and just put the runner syntaxes where the article is in my mockup and we would already have an alright solution overall I think.

This is it looks when you click it:

This has the obvious issues of displaying a ton of information with no way to filter it. Also this only supports one syntax, and in the case of the calculator runner there are two of three syntaxes missing.

To the why it was removed: Most likely the missing multiline support in Krunner5, this renders the concept on how they were displayed useless.

Yea, having no support for multiline descriptions seems like a dealbreaker. Let's maybe scratch that idea.

Also when discussing this some time ago with @ngraham we came to the conclusion that some kind of inline help might be useful, but should not be the priority.

I was also thinking in that direction at first but couldn't come up with anything useful that wasn't also annoying. If you came up with a specific idea that would be interesting.

That was a proof if concept screenshot, when creating a MR in the framework. We can choose any icon and text we want ;-)

Sorry for my presumptuous assumption. :P

To get there one has to click "Configure KRunner..." which isn't where one would expect such a feature

That is a good point. It was done differently in KDE4 where each you could click a configure icon for each runner match.

Maybe something like "Open Menu Page..." could work for the existing button once the syntax information is integrated.

Hmm, the way you described it we would have two sources of data: The Runner syntaxes and the article(could be a docbook).
The syntaxes are for the biggest part already available, even though they might need a bit of an update.

It definitely sounds like the syntax information should be prominently displayed there if no other usage information is available.

But there are currently no docbooks/other documentation formats for runners, which could make it very hard to make it look consistent (like if you have an example with a lot of screenshots etc and then just two lines of explaining text for the next plugin).

I don't think it would be that bad to have one page with only a few lines and one with many. Naturally some plugins will have a lot more features than others and a very different amount of use cases.

Also the docbooks would be static, meaning that they could not adapt to the config like trigger words that are essential for the syntaxes. And functionality like the launch button, could not be implemented. And such a button is IMO super useful, because it allows you to type out a query with just one click.

Considering that you are implementing KRunner store functionality, would it be feasible for Plugins to ship their own .qml file to provide a (possibly interactive) article? Otherwise their only way to communicate their usage would be their store page and the syntaxes. Specifically looking at the calculator example in my mockup an article seems to be vastly superior and sometimes even necessary to explain the usage. I am not sure a syntax can be enough here.
... Hmm, now that I think more about it maybe it would be okay enough if plugins would have a QString or QTextDocument introduction() method that would be displayed above the syntaxes. That would be somewhat limited compared to QML but it would allow for some kind of article on plugin usage.
Disclaimer: I have no idea of the KRunner code.

Considering that you are implementing KRunner store functionality, would it be feasible for Plugins to ship their own .qml file to provide a (possibly interactive) article?

Actually not sure how this is technically possible. Also the KRunner syntaxes are currently not accessible from QML.

Specifically looking at the calculator example in my mockup an article seems to be vastly superior and sometimes even necessary to explain the usage. I am not sure a syntax can be enough here.

Please note that the syntaxes where not very powerful in the previous KDE versions, so there was also not the possibility to add extensive documentation. And considering that it only had internal usage in KF5 so far there was pretty much no effort put into making the description more extensive.

But we could add new properties to the sxntax: In the mocup you can see the icon on the left of each block, that could be added. Also we could add a documentation property. This should be optional and can contain more detailed documentation, maybe in HTML/Markdown format. This way we would not replace the usage information, but rather embrace it.

QString or QTextDocument introduction() method that would be displayed above the syntaxes

The runners already have a description property, which we could use for a brief introduction. The idea mentioned above would be similar to yours, except it would be per syntax. This way we would be more flexible on how the text is structured.

Disclaimer: I have no idea of the KRunner code.

No issue, you have great design ideas :)

Danke für die Blumen :]

Please note that the syntaxes where not very powerful in the previous KDE versions, so there was also not the possibility to add extensive documentation. And considering that it only had internal usage in KF5 so far there was pretty much no effort put into making the description more extensive.

Oh okay. Makes sense.

Also we could add a documentation property.

If I understand you correctly the text would/could then have the following structure:

Runner Name
runner description

[repeat for each syntax] {
   syntax documentation (new optional documentation property - can contain rich text)
   icon
   example queries
   syntax description
   launch button
}

I assume the order of the syntaxes is fixed. This will then even allow to write a rich text introduction and transitions between syntaxes etc. I think that's fine then.

In T13073#238756, @felixernst wrote:

If I understand you correctly the text would/could then have the following structure:

Runner Name
runner description

[repeat for each syntax] {
   syntax documentation (new optional documentation property - can contain rich text)
   icon
   example queries
   syntax description
   launch button
}

Yeah! It is important to note that the launch button launches the example queries and we can have multiple of them. And regarding the information that is contained in each syntax you are absolutely right. (But I guess you didn't wanted to express the layout here). Also the icon would also be a new property (just to clarify).

I assume the order of the syntaxes is fixed. This will then even allow to write a rich text introduction and transitions between syntaxes etc. I think that's fine then.

Yep, the runner can set the order of the syntaxes.

Sounds good 👍

Just a little addition: If the documentation property exists we could use it instead of the description. This way we wouldn't have to worry about making sure they are in perfectly match with the other one. And then the descriptions still have a purpose, because inline help is still a TODO(while not the priority and there are other issues that have to be sorted out first).

The documentation would explain all the features and useful information of the runner and the description would just be a quick reminder on how to use(in the sense of trigger) this runner.

BTW found this https://community.kde.org/KRunner/Problems page on the community wiki. And the usage help was an issue 5 years ago ;-)

At this point I would also like other developers with KRunner knowledge to give some feedback if the idea with some kind of documentation property is worth doing or if it a bit over the top.

In T13073#238696, @felixernst wrote:

In any case I brainstormed a bit about what would be the ideal solution and this is the best idea I had so far:

I really, really like this idea.

Just a little addition: If the documentation property exists we could use it instead of the description. This way we wouldn't have to worry about making sure they are in perfectly match with the other one. And then the descriptions still have a purpose, because inline help is still a TODO(while not the priority and there are other issues that have to be sorted out first).

That's a good idea! The documentation property can pull in the description property anyway so we'd have more flexibility in the text structure without losing functionality.

You also asked me on Matrix to make/edit another mockup that includes a query in the text. Normally my idea would be to have examples like the one in the calculator text in the mockup be queries with a "Try it" button next to it that would copy the query into the users actual KRunner. But I am not sure this would work because you said they have some internal usage. So I don't quite understand the constraints of how syntaxes and queries need to be structured or if we are free to change them for this documentation without regard to other code paths.

I found https://techbase.kde.org/Development/Tutorials/Plasma4/AbstractRunner#Publishing_Recognized_Syntax and there it says

the variable query text entered by the user […] will be replaced in the user interface with something more meaningful when shown as documentation.

Does this mean we can have any input in a query? i.e. could the "Date and Time" runner have a query with the command "time japan" and then a "Try it" button next to it that copies it to KRunner so the the actual current time in Japan would pop up right there? If you have some documentation or code I could read I would also take that as an explanation although I am quite busy with Akademy this week. :P

While you're massively overhauling the KCM's user interface, it would be a good opportunity to port the whole thing to QML, too. ;)

In T13073#238828, @ngraham wrote:

While you're massively overhauling the KCM's user interface, it would be a good opportunity to port the whole thing to QML, too. ;)

The plugin selector is not available for QML and is also in need of an overhaul https://phabricator.kde.org/T12265

But I am not sure this would work because you said they have some internal usage.

The example queries are used in the single runner mode. We don't have to worry about that at all, because we only read all the values.

So I don't quite understand the constraints of how syntaxes and queries need to be structured or if we are free to change them for this documentation without regard to other code paths.

We can change the description as we want and add other properties as much as we like :)

the variable query text entered by the user […] will be replaced in the user interface with something more meaningful when shown as documentation.

IMO this is explained really complicated, lets make it easy and give you an example:

Lets say we have the kdevelop runner which launches KDevelop with the selected session. Then an example query could look like this
kdevelop :q:
This is the "internal" format, replaced in the user interface with something more meaningful would mean that :q: gets replaced with a string which describes what the user should enter there, in this case this is the session name.
So the result we would display at the end in KRunner could be
kdevelop <session name>

We could also chnge the "<>" character for sth. else if that would look better in the UI.

Does this mean we can have any input in a query? i.e. could the "Date and Time" runner have a query with the command "time japan" and then a "Try it" button next to it that copies it to KRunner so the the actual current time in Japan would pop up right there?

That is actually sth. which is done really weird: The example queries are more like templates for a query. To take your "Date and Time" runner example the example query would be time <country> and in the description we would do some further explanation.

If you have some documentation or code I could read I would also take that as an explanation

https://invent.kde.org/network/ktp-contact-runner/-/blob/master/src/contactrunner.cpp#L81

Okay, thanks. I think I understand all the properties now.

Does this mean we can have any input in a query? i.e. could the "Date and Time" runner have a query with the command "time japan" and then a "Try it" button next to it that copies it to KRunner so the the actual current time in Japan would pop up right there?

That is actually sth. which is done really weird: The example queries are more like templates for a query. To take your "Date and Time" runner example the example query would be time <country> and in the description we would do some further explanation.

Allowing people to launch such a thing doesn't seem all that helpful to me. That's like: "Hey, let me write the 4 letter keyword for you. Now you write the search term. Teamwork!" I think it makes sense to have a launch button but only for full runnable examples. So additionally to the new Syntax properties "documentation" and "icon" I would suggest to have "runnableExamples". The text would then be structured like this:

RunnerSyntax::documentation() (if that is not available RunnerSyntax::description)
|Space|    RunnerSyntax::exampleQueriesWithTermDescription()
| for |    Examples:
| Icon|    RunnerSyntax::runnableExamples()    "Run this example"-button(s)

Using the "Telepathy Contact Runner" and its current code for two syntaxes as an example this would lead to this:

This could be enriched by the new properties to achieve this kind of documentation:

That is a good example, thanks a lot!

And maybe it makes sense to detach these syntaxes from the internal usage (currently only used single runner mode).

I am going to make a phabricator task for this :)

Adding this in the KCM is blocked by the QML port which is blocked by some frameworks stuff. https://invent.kde.org/plasma/plasma-workspace/-/merge_requests/1102 is a draft for adding a runner which provides help information. Feel free to try it out & comment on my suggestions.