XBELicious Installation and User's Guide

1 Introduction

XBELicious is a set of scripts to help you store your del.icio.us bookmarks in XBEL format and to mold those bookmarks into a hierarchy of folders based partly upon the tags that you have given to those bookmarks. If you are a del.icio.us user and want to also have a copy of your set of bookmarks stored in XBEL format (such as for use in Konqueror), or if you want to organize a local cache of your bookmarks in XML format for any other reason (such as for backup), then XBELicious may be useful for you.

2 Requirements

The XBELicious conversion script requires at least Python 2.4 and at least 4Suite 1.0b3. XBELicious uses 4Suite for XML processing. XBELicious also has a control script written in bash and needs an SSL-enabled version of the wget utility to retrieve the del.icio.us bookmarks using their Web API. Of the above, everything but 4Suite is likely to be installed on most modern UNIX-like distributions.

3 Installation

You can download any of the available releases from XBEL's SourceForge download page, and you can obtain the latest sources for hacking or use at the Subversion URL https://svn.sourceforge.net/svnroot/xbel/XBELicious/ . You can then extract the source archive with a command like the following:

$ tar -xzf {archive filename}

You can run XBELicious directly from the extracted directory, or you can copy all of the files from the source/ directory within the extracted directory to somewhere on your $PATH to be able to run it without a directory prefix.

4 Use

XBELicious downloads your del.icio.us bookmarks and funnels them into an XBEL document. XBELicious can use a preexisting XBEL document as a template for the new one; we'll cover that a bit later. As XBELicious will retrieve your bookmarks from del.icio.us over the Internet, it needs to know your username and password. XBELicious looks in the environment variables DEL_USER and DEL_PASSWD for your username and password, respectively. You can set these variables in the del2xbel.sh script itself by removing the # character from the beginning of the two lines with these variables and changing their values, by writing a small wrapper script that sets these variables and then calls del2xbel.sh, or by setting these variables from the command line, for example using the following commands (in bash):

$ export DEL_USER=your_del.icio.us_username
$ export DEL_PASSWD=your_del.icio.us_password

In the XBEL output from XBELicious, the titles of most folders correspond to tags; some folders are marked as being special, and are not considered to represent tags by XBELicious. Without a template, XBELicious creates an XBEL folder in the output for each tag in your del.icio.us collection, and for each such folder it stores every bookmark tagged with the corresponding tag in that folder. To generate such a "flat" XBEL file (recommended as a starting point), use the following command:

$ del2xbel.sh {del.icio.us XML filename} > {output XBEL filename}

If you have created a template XBEL file, then you can use it with XBELicious to have XBELicious fill in that template's directory structure with bookmarks that match the tags that correspond to that directory structure. This is covered in more detail in “Templates”. To reference a template in this way, use the following command:

$ del2xbel.sh {del.icio.us XML filename} \
              {xbel template filename} > {output XBEL filename}

The first parameter to these commands is always the filename for the downloaded del.icio.us bookmarks; if (and only if) there is no file at that name then it will be created by downloading the bookmarks. These examples assume that the del2xbel.sh script is in your $PATH; if you are calling the script by providing an explicit path, then replace the script name with the full path to the script in the examples. The del2xbel.sh script outputs the resulting XBEL file to standard output, so these examples use shell redirection to place that output into a file.

5 Templates

Your del.icio.us bookmarks are organized using a set of tags. In contrast, XBEL organizes bookmarks hierarchically using folders. How can we manage tagged bookmarks in the hierarchical XBEL format? If you provide XBELicious with an XBEL template, then XBELicious uses a simple rule to organize these bookmarks. If a bookmark has tags that match the name of the current folder and each of the current folder's ancestor folders, and if the bookmark is not placed in any subfolders of the current folder, then XBELicious will "file" the bookmark in the current folder.

For example, if your XBEL template has a hierarchy of folders like "Computers → linux → news" and you have a bookmark tagged with all three of these tags, then it will be placed under the "news" folder because it has tags corresponding to each level in this hierarchy. Note, however, that this bookmark will not be placed in either of the two higher directories, because it fits best in the news category. A bookmark tagged with "Computers" and "news" would only be placed under "Computers" because it doesn't have the "linux" tag, and a bookmark tagged with "linux" and "news" would not be stored in any of these three folders. You can find a complete (although small) example of a set of bookmarks and one possible XBEL template in the test directory within the source distribution.

One way to use XBELicious, then, is in two (or more) passes. In the first pass, you output an XBEL file with the flat list of all your tags. Using this file, you organize the folders (representing tags) into a hierarchy that matches how you think about the relationships among your tags. Then you can run XBELicious again, using this newly organized XBEL file as the template, and XBELicious will "fill it in" with the bookmarks that fit into your hierarchy. Any bookmarks that have any tags which did not fit into the hierarchy will be placed into flat tag folders based on the "extra" tags, as before. Obviously, there are many possible ways to organize your tags; you will want to experiment and find an organization that makes sense to you. If you use KDE and Konqueror, then you may want to use the Bookmark Editor to organize the folders in your XBEL template. The Bookmark Editor can be accessed using Bookmarks Edit Bookmarks from within Konqueror.