Yelp For Help

by Paul Arnote (parnote)

After all of these years using Linux (about 13 years, give or take), I discovered something new that I never knew existed. I was performing updates on my compact notebook computer that I carry with me to work, and I noticed a weird little program called "Yelp" scheduled for updates. It piqued my curiosity, and I was quite surprised by what I found out about it.

Yelp is definitely in the PCLinuxOS repository, and may even already be installed on your computer. It was on mine, but I had no idea it was even there, much less what function it performed. It doesn't even appear anywhere in my Xfce applications menu, either, which is probably one thing that kept it hidden from me for so long. I've since rectified that issue, and put a launcher for it on my Xfce panel.

As you can see, Yelp lists all the "help" documents on your computer that conform to the freedesktop.org help system specification (only available in *.xml format). This means all help documents in the Mallard, DocBook, man, info, GSL (GNU Scientific Library), and HTML document formats can be viewed in Yelp. In a way, this reminds me of the Windows Help system, both the old RTF-based Winhelp (*.hlp files) and the newer HTML-based help system, built around HTML documents (*.chm files... the "c" stands for "compiled").

Yelp is a part of the GNOME desktop environment, but can easily be installed on other desktops. I am a diehard Xfce desktop fan, and Yelp runs great on Xfce. Since I haven't been a KDE user in quite a while, I don't know if this next bit is still accurate or not. Konqueror used to be able to serve as a "help" viewer in much the same way that Yelp does. You could view man, DocBook, Mallard, info, GSL and HTML documents directly in Konqueror, and their appearance in Konqueror looked almost exactly like it appears in Yelp. But even on KDE, Yelp may be a lighter-weight alternative to using Konqueror, even if it involves installing it separately on your system.

Simply click on the help topic you desire, and you will be sped off to that help file's contents. In the above image, I've delved a few levels deep into the "Character Map" manual.

Use the arrows in the upper left corner of the Yelp window to go back and forth between viewed topics of the help file/manual. On the upper right corner of the Yelp window, you can "star" (bookmark) a frequently visited/referenced topic, or even search for words/phrases/terms you want help with.

The "hamburger" menu at the far right upper corner allows you to open help topics in a new window, search through the help topics, print the help topics, change the font size that the help topics are presented in, or return to the "main" help page by selecting "All Help" from the menu.

Remember I mentioned the freedesktop.org help system specification earlier, which was spelled out only in a XML file? Trying to read it opened in your browser is -- to say the least -- challenging. Page and paragraph breaks don't occur where they should, and there is no character formatting available (image above). It's not what they call "human readable." The cure is simple: download the XML file to your hard drive. Then, go to a command line and type yelp, followed by the XML file of the help system specification (with a qualified path if you're not already in the directory where the XML file is stored), and the XML file for the help system specifications becomes very human-readable (image below).

Add In The Tools

Here's something very few people around here (if even any) know about me. Way, way back in my 16-bit "Windows days," I was deeply immersed in the RTF-based Windows Help community. I was fascinated by how it worked, its possibilities for uses other than "help" for programs, and how to extend its capabilities far beyond its original purpose. Ralph Walden, the lead developer for Windows help for Microsoft, was like a god-like figure to me.

To that end, I was the author of a shareware Windows help authoring system, called MiniHelp Plus 3.5. It allowed the user to use a basic text editor, such as Notepad, to create a specially scripted file that would create the requisite RTF files, as well as the other files needed by the help compiler. I was also the author of a dynamic linked library (DLL) that extended 16-bit Windows help files ability many times over what it would do natively. That DLL was called Arsenal, and allowed Windows help to display 256 color graphics (natively, it only displayed 16 color graphics), embed and playback audio and video files, read and write data from/to INI files, and lots of other handy little routines.

I would have continued developing for winhlp32 and onward to HTML-based Windows help, except that I kind of got left in the dust when things moved from 16-bit to 32-bit. I could barely afford my 16-bit C/C++ compiler when I got it. I saved and scraped together the money to buy it, and couldn't afford to upgrade to a 32-bit development environment. As a result, the rest of the world moved on with 32-bit programming, and I was unable to continue developing my 16-bit programs (there are others) into 32-bit programs.

So, that fire to create hypertext documents never really burned out for me. Embers of that fire still smolder today. Even though the rest of the world moved on to 32-bit help, I continued to create 16-bit help/hypertext for a while longer. I pretty much quit when things moved on to HTML based help systems. Fortunately, Yelp gives users several ways to create hypertext documents. You can use HTML, XML, DocBook, Mallard, and other file types to create the files that Yelp is able to read.

Also in the PCLinuxOS repository is a set of special tools, called yelp-tools. These tools are not installed by default, but can easily be installed via Synaptic. They allow you to properly create the "helpful" hypertext documents that Yelp can read. Getting into all the different tools and file types that can be used to create help/hypertext documents is quite a bit beyond the scope of this article, as well as my ability to talk intelligently about them. Still, you can explore them on your own, as I will most likely do at some point. You can find more information about getting started with DocBook here. Mallard also has some getting-started tutorials here. And, of course, you can find HTML information just about everywhere and anywhere. One thing I've already noticed is that both DocBook and Mallard are both XML based, so if you already know some XML, you'll be ahead of the game.