Examples, Tutorials, and How-to’s; Oh my!
The Web is a wonderful place to find software documentation; how-to’s, tutorials, and user’s manuals. The problem is like most resources on the Web, you need to sift through a lot of stuff to find what you’re looking for – or what actually works.
I’m working on a project right now where I need to develop a GUI for a Linux application. In the past I would have used Java Swing but it’s been so long since I’ve done this kind of work that it’s like starting from scratch. So, I decided to learn a GUI programming library and development tool that I could use from C/C++ as well as a scripting language or Java. I decided on GTK+ and Glade after doing some research. GTK+ is the GIMP Tool Kit used to develop the GUI for GIMP, the GNU Image Manipulation Program. It’s kind of like Photoshop without the price tag. GTK+ has a C API but a library, libgtkmm, provides C++ wrappers for GTK+. Glade is a graphical GUI development tool. It allows you to build up a GUI by dragging and dropping the graphical objects you need to build up you GUI. Finally, a library, libglademm, hooks up the output from Glade to libgtkmm.
The next step was to find some documentation, tutorials, and examples on the Web. I found some easy “Hello World” examples that didn’t really help much. I also found some very complete documentation but the author was really intent on me learning autoconfig, automake, and libtool. Now I’m sure learning these tools would be good for me in the long run but right now I’m on a deadline. Researching these tools I found a bunch of outdated examples that wouldn’t work on my up-to-date Linux environment. I finally found a quick how-to that was complex enough to be useful but didn’t require me to learn a bunch of other tools: A simple libglademm application. The example application is a simple calculator. It demonstrates the basics of building a GUI using Glade and then writing the C++ code behind it that makes it work.
I ran into some other outdated how-to’s this weekend. I was helping a friend set up Embedded Linux on an ARM evaluation board. The manufacturer actually provided a very complete build of GNU tools for their processor and Linux 2.6 build source for their development board. The problem was that there were too many how-to’s on the site – mostly outdated. Some of the older ones were just plain wrong or referred to links on their web site that no longer exist. The most up-to-date and correct documentation was buried in their file downloads and you had to hunt around to find everything. Once we found the right downloads and documentation, the build went smoothly with the exception of one minor glitch.
By the way, this is not to say that commercial software is better. Commercial software is often worse with even harder to find documentation and even more outdated material. Often you need to buy a book to make up for the lack of documentation that comes with the product.
So here’s my message to all of you great people who provide open source software: please delete your obsolete documentation, and to paraphrase Einstein; “Keep it a simple as possible but no simpler.”
Finally, I have to say, that I think Glade, Gtk+, libglademm, and gtkmm are great!







