Mallard was designed from the beginning to make it easy for plugins to add pages into application help documents. This works really well in a lot of cases, but sometimes you want to mention extra functionality even when the plugin isn’t installed. And sometimes, extra functionality is provided by plugins to backend frameworks. A GStreamer plugin isn’t going to install Banshee help files, and a Telepathy plugin isn’t going to install Empathy help files.
So we have pages in the Empathy help that talk about using IRC. To use IRC in Empathy, you have to have telepathy-idle installed, and it turns out that some distros don’t install it by default. If the help just blindly assumes it’s installed, it just leaves the user confused. So we addressed this by adding a note like this:
This is somewhat helpful. The user at least knows why all those IRC options aren’t showing up. If he’s savvy, he’ll open his package manager and be chatting in no time. If not, he at least has something to Google for. But why not make it easier?
Click the link and you get this:
This is not a mockup. This is yelp-3-0. And it rocks.
Nice work! Can’t wait to see this in action. Already thinking of how Banshee can use this for MP3 and other codecs.
This does rock. Awesome work, Shaun!
What happens if the package is already installed?
You rock man! This is pure awesomeness!
But the big question is when yelp-webkit will be merged in yelp-3-0?
It’s so logical that I wonder why it hasn’t been done before 🙂 Good point !!!
Packagekit should supply metadata i think, so that this help page could say “IRC support for Empathy” instead of “telepathy-idle”.
Woah! That sure rocks!
This looks brilliant… a couple of questions:
How is this marked up? How are differences in package names across distributions accounted for? Is there documentation for this available (quick glance at the current Mallard docs didn’t turn anything up)?
Seriously rock!
How do you determine the package name? It will probably be different in different distros. I guess you have a configure option for the documentation build system?
Very seriously rocks!
Wow, so many comments. I’ll try to answer a few questions.
Alexander, if the package is already installed, you’ll get a dialog that says as much when you click the link. It’s possible we could do notes like these that query PK and only display if necessary. But I want to be careful about the amount of time it takes to show a page.
Dmitrijs, there is no need to merge the webkit branch into yelp-3-0. The yelp-3-0 branch already uses WebKit. 🙂
Jonas, right now, it’s indicated with a URL-like thing that looks like “install:telepathy-idle”, on an href attribute. I want to move it to the xref attribute (Mallard allows that), leaving href as a fallback URL to show in case the user isn’t running PK. Differences in package names across distros could be handled by conditional processing if we get it in. See http://projectmallard.org/pipermail/mallard-list_projectmallard.org/2010-March/000002.html for a proposal on that.
Also, for GStreamer codecs, PK has a method to just install by the capability they provide, without worrying about package names. This system should probably be extended to support stuff like that.
This rocks! This is going to be the first time I will actually and in good conscience recommend users to look at Help documents. Thank you for working on this!
Why do you ask the user twice if they want to install the package? They’ve already decided to install it by clicking on the first link.
Ryan, that’s the way PackageKit works. When the link is clicked, Yelp just sends PackageKit a message telling it to install a package. PackageKit prompts for confirmation, searches, and handles privelage escalation. I’m not sure if there’s a way I can get around the initial confirmation dialog. Something to look into though.
shaunm:
You shouldn’t need conditionals at all. I think all the packaging systems understand the equivalent of rpm’s “virtual provides.” The install:whatever
will look for any package which provides whatever.
What is really going to be helpful is for there to be a way to help distributors compile a complete listing of what those whatevers for all the yelp controlled documentation are so the virtual provides in the packaging can be placed correct in the packaging.
So take the empathy example… when people are prepping empathy for packaging there needs to be a clean way to get a complete listing of all the packagekit interactions that the empathy documentation embeds which we can then shove into a distribution specific built time checker to ensure all the provides are already covered in packaging.. and flag the ones that don’t so they can be fixed by adding the corresponding virtual provide in other packages.
Instead of conditionals what needs to happen is a consensus discussion on what that namespace should look like. For codecs there’s the common mimetype namespace already which is a no-brainer. But what you are talking about is more abstract and there needs to be an effort to come to consensus instead of conditionalized code which just adds complexity.
-jef
Jef, certainly the more we can make the lookups distro-neutral, the better. Yelp isn’t talking directly to your pakage manager. It’s using PackageKit. So what sorts of capabilities we have depends on what PackageKit provides.
PackageKit does contain various special-purpose methods for things. There’s InstallGStreamerResources for installing codecs and InstallFontconfigResources for installing fonts for languages. In Empathy’s case, maybe PackageKit should have InstallTelepathyResource. As we start to use install links in our help, we can work with the PackageKit developers on this stuff.
Note, however, that conditional processing is useful in general, and not just for install links. So that’s something we’re going to do anyway. And even working with the PackageKit developers, there may still be times when conditional processing is the only short-term solution.
Next step: links that allow to go directly to a configuration panel or to launch an action. If I lookup how to change my login photo, then no need to navigate the configuration menu/panels, just open the right panel for me.