Open Devhelp books installed in unusual locations

If you are a GNOME developer, there are high chances you encountered this problem - you install your beta versions to a seperate prefix (something like /opt/my-beta instead of the regular /usr), and then when you come to browse their documentation in Devhelp, it fails to find them. Some will be tempted to sudo, and then symlink the documentation to /usr/share/gtk-doc. Personally, I'm not a fan of sudo-ing and messing around...

Today I had enough of this, and decided I'm going to solve this. A quick search in the Devhelp source code found the code that searches for books. The book_manager_add_books_in_data_dir () function searches SOME_PREFIX/gtk-doc/html for Devhelp books, and it's called from dh_book_manager_populate () with the directories returned by g_get_user_data_dir () and by g_get_system_data_dirs ().

Thanks to some help from Mikachu (from #gimp irc), which matched the much longer description on the freedesktop basedir-specs, I found out that appending a directory to the environment variable $XDG_DATA_DIRS is enough to make Devhelp search for documentation there.

Sweet! That was much easier than I thought it would be :D

So to summarize, this is what you do:

1. Compile your program, while setting the installation prefix to some prefix $PREFIX
2. Build and install it (make and make install)
3. Find your installed gtk-doc documentation. Usually it is located on $PREFIX/share/gtk-doc/html/YOUR_PROGRAM. Make sure that directory contains a file with the suffix of .devhelp.
4. Set the $XDG_DATA_DIRS environment variables, and prepend (don't append!) that directory (usually $PREFIX/share) to that variable. In bash syntax, you should type
   export XDG_DATA_DIRS=$PREFIX/share/:$XDG_DATA_DIRS

Why prepend and not append? Well, apparently Devhelp doesn't seem to like having two books with the same title, so it takes the first one it finds... Since it follows the directories in that environment variables by their order, it means that we should add our directory to the begining of the search path.

Note that this method has 2 cons:

1. You can't view previous versions of the documentation, since as I said Devhelp takes only the first version it finds
2. You must launch Devhelp with the above environment variable set. So either lunch it from your build console, or create a script to modify the variable and then lunch Devhelp. Note that IDEs that launch Devhelp (like anjuta, and gedit with plugins) must have the variable set for themselves (by launching them with the variable set already).

So, it's not perfect. But way better that symlinking stuff into the /usr/share/gtk-doc directory. This also shows why open source is so good - "If you don't like it, fix it!". Or as I prefer to say "If you don't like it, hack it" :D