Zovirl Industries

I updated permalink to work with metadate 0.0.3. This lets the absolute plugin look up permalinks outside the current directory.

Download permalink 0.0.2

Documentation is available here.

This plugin helps you use a consistent permanent link format by generating permanent links for you. It does this by exporting two variables, $permalink::story and $permalink::category, which contain the permanent link for the current story and category, respectively. It also provides a function permalink::get_link() which can be used by other plugins when they wish to get a permanent link for a file.

I also have some patches for blosxom.cgi and some other plugins that make them use permalink:

• blosxom: patch
• absolute plugin: patch
• breadcrumbs plugin: patch

Download permalink 0.0.1

Documentation is available here.

I updated metadate to parse metadates contained in stories. I had to do this because entries_cache wasn’t providing metadates for stories outside the current directory, but the permalink plugin needs those.

Download metadate 0.0.3 Be sure to rename it to “metadate”

Documentation is available here.

Well, the last version of fullcategory had a bug which broke permalinks. Yes, this plugin was supposed to fix a bug but instead contained a bug…haha. Thanks to Gary Gale for finding the problem. Anyway, here is the new version.

Download fullcategory 0.0.2

Documentation is available here.

By default, blosxom will return results for partial category name matches. For example, if “telephone” is a category, these would all return posts about telephones:

• http://example.com/telephone
• http://example.com/telepho
• http://example.com/tele

(If “television” was also a category, that last example would include posts from both the television & telephone categories)

This behavior gets in the way of Fletcher’s emptymessage plugin, so I wrote the fullcatgory plugin. Fullcategory changes Blosxom so only full category names will give results. This lets the emptymessage plugin do its thing. I’m pretty sure that with both emptymessage and fullcategory installed, I will be able to run an automatic link checker over my site and find dead (404) links, where before some links went to empty blosxom pages.

Download fullcategory 0.0.1

Documentation is available here.

A new version of metadate is available. This version changes the paths in the external metadate file. They used to be the full path of the file, now they are the path starting from $blosxom::datadir. This should make it easier to relocate the $blosxom::datadir (or have a blosxom installation on your desktop machine for testing)

Download metadate 0.0.2 Be sure to rename it to “metadate”

Documentation is available here.

This plugin lets you put metadates in an external file. This is especially useful when you want to specify metadates for files which can’t contain metadates themselves, such as directories, images, binary files, etc..

Download metadate 0.0.1 Be sure to rename it to “metadate”

Documentation is available here.

I came across one of the first tests of my new URI format today. I wanted to post an update to the timezone plugin, but I wanted to keep the previous version around. Hmmm…multiple stories on the same topic? That sounds like a job for a category. Sadly, the obvious category for this (/software/blosxom/plugins/timezone) was already taken by my previous version, which was sitting on these URIs:

• /2003/software/blosxom/plugins/timezone: the perl plugin
• /2003/software/blosxom/plugins/timezone_about: the blosxom article about the plugin
• /2003/software/blosxom/plugins/timezone_pod.html: documentation for the plugin

I’m not using the full date in my URI, so I only get to reuse a path once a year. Fortunately I got lucky because we just entered a new year. That means /2004/software/blosxom/plugins/timezone is available for me to use. Here are the new URIs I laid out:

• /2004/software/blosxom/plugins/timezone/: the category (main URI for the timezone plugin)
• /2004/software/blosxom/plugins/timezone/about_0_0_2: the blosxom article about version 0.0.2
• /2004/software/blosxom/plugins/timezone/about_0_0_3: the blosxom article about version 0.0.3
• /2004/software/blosxom/plugins/timezone/pod_0_0_2: the documentation for version 0.0.2
• /2004/software/blosxom/plugins/timezone/pod_0_0_3: the documentation for version 0.0.3
• /2004/software/blosxom/plugins/timezone/timezone_0_0_2: version 0.0.2 of the plugin
• /2004/software/blosxom/plugins/timezone/timezone_0_0_3: version 0.0.3 of the plugin

So, I moved the old files to the new locations, added the new files, and updated my metadates so they were all correct. I then updated my .htaccess to add 301 redirects for the old URIs:

...
Redirect permanent /2003/software/blosxom/plugins/timezone_about \
   http://zovirl.com/2004/software/blosxom/plugins/timezone/
RedirectMatch permanent /2003/software/blosxom/plugins/timezone_about\.(.*) \
   http://zovirl.com/2004/software/blosxom/plugins/timezone/index.$1
Redirect permanent /2003/software/blosxom/plugins/timezone \
   http://zovirl.com/2004/software/blosxom/plugins/timezone/timezone_0_0_2
Redirect permanent /2003/software/blosxom/plugins/timezone_pod.html \
   http://zovirl.com/2004/software/blosxom/plugins/timezone/pod_0_0_2.html
...

Finally I posted the new version. Overall it was a fairly simple task. I got lucky with the new year, in the future I’ll have to be more careful when I post stories I know will turn into categories in the future.

Update: Found one more gotcha: my internal links are generated using the absolute plugin. When I move files, old references to them need to be updated in my blosxom stories, otherwise absolute can’t find the files and doesn’t generate the right links.

Update 2: It really makes more sense to set the directories up like this:

http://zovirl.com/2004/software/blosxom/plugins/fullcategory/v0_0_1/about.blosxom
http://zovirl.com/2004/software/blosxom/plugins/fullcategory/v0_0_1/fullcategory
http://zovirl.com/2004/software/blosxom/plugins/fullcategory/v0_0_2/
...

Version 0.0.3 is now available. This version adds the ability to use the server’s default timezone and a new variable, $timezone::offset. This gives the offset from GMT (for example, for PST it will be -0800).

Download timezone 0.0.3. Be sure to rename it to “timezone”

Documentation is available here.

This is an update to Raffi Krikorian’s timezone plugin. In addition to the previous functionality (which allows Blosxom timestamps to use a different timezone than the server), the plugin now exports a variable, $timezone::name, so flavors can display the timezone next to times.

For example, this bit of flavor:

$mo_num/$da/$yr $hr:$min $timezone::name

might produce this output:
12/25/2003 11:19 PST

Download timezone 0.0.2. Be sure to rename it to “timezone”

Documentation is available here.

The Beginning

Out of the box, Blosxom comes with two URL styles for stories and one for categories. URLs for stories can be date-based (http://example.com/2003/12/26#duck.html) or category-based (http://example.com/photography/nature/duck.html). Categories get only category-based URLs (http://example.com/photography/nature/index.html).

After reading several articles on URL design, I decided I wanted something different than what Blosxom gave me. Especially influential were Jakob Nielsen’s URL as UI and Tim Berners-Lee’s Cool URIs don’t change. Tanya Rabourn has also posted a nice list of articles on URI design. After reading those articles, I decided I wanted to have URIs which I could keep forever, without breaking them.

The Plan

The URI format I decided to use is similar to Blosxom’s category-based format, except every URI is extensionless and begins with the creation date of that URI: http://example.com/2003/12/26/photography/nature/duck.

Advantages of this format:

• By starting each URI with a date, I should be able to reorganize my site without breaking links. Old URIs can be pointed to the new locations with 301 redirects
• There is no extension so I can change the default format of the document without changing the URI.
• The URI doesn’t expose any of the technology used to serve the site, so I can change the technology without breaking old links

Disadvantages of this format:

• Since a story will have a different date than the category it is in, URIs aren’t hackable. I don’t know of a way to solve this
• The dates make the URL rather long. This can be solved by including only the year: http://example.com/2003/photography/nature/duck.
• Some items are better without dates. http://example.com/2003/resume looks fine now but in 5 years that “2003″ will look bad. This can be solved by updating the URI every year and using 301 redirects to keep the old URIs working

The Implementation

While reading all the articles I saw a lot of material on how to design URIs and very little material on how to implement them. Getting Blosxom to use my new URI format ended up being more work than I expected. There were two main problems to solve: Blosxom had to generate the new URLs when it served content, and Blosxom had to recognize the new URLs when a client requested something.

I wrote the cooluri2 plugin to make Blosxom recognize the new URLs. The plugin is more complicated than I would like but it works.

Getting Blosxom to generate the new URLs took several plugins. The main one is permalink, which provides permalinks for stories and can be used by other plugins when they need a URL generated. Some files, like binary files and directories, can’t contain metadates and since the new scheme needs dates for everything, I wrote the metadate plugin. It lets metadates reside in an external file, so I can use metadates for all my categories. Finally, I patched the absolute plugin so I can easily reference other stories/files/categories.

Finally, when it comes time to reorganize my site I can do it freely. If I want to change a document’s URI (by moving it or changing the date on it) the old URI can be replaced with a 301 redirect to the new URI.

The Results

The new URI format requires several plugins but adds very little overhead when I’m just writing articles. The only extra thing I have to remember is to update my external metadate file when I add new directories or non-story files (if I forget then the modification time of the file is used, so nothing terrible happens, but I prefer to use metadates since last-modification times are fragile). By including only the year and not the full date in the URI there is very little cruft added. Overall I’m pleased with the results.

This plugin makes Blosxom recognize date-based, extensionless URIs (aka Cool URIs) for both stories and categories. If you are using the static_file plugin, Cool URIs will be recognized for static files also. The main motivation for this URI format is that links never have to break…ever. Goodbye 404 errors! You can read Tim Berners-Lee’s essay for more details on why Cool URIs are cool.

The idea for this plugin was based on the cooluri plugin written by Rob Hague, which makes Blosxom recognize extensionless URIs. Along with Blosxom’s built-in ability to recognize date-based URIs for stories, cooluri did almost what I wanted. It didn’t handle date-based URIs for categories however.

I wrote cooluri2 to do both. Now categories, stories, and static-files all can be referenced by cool URIs, like this:
http://example.com/2003/12/03/category
http://example.com/2003/12/14/category/story

Days and months can be left off if you prefer a shorter URI:
http://example.com/2003/12/category
http://example.com/2003/12/category/story
http://example.com/2003/category
http://example.com/2003/category/story

The date part of the URI is the creation date for that document. Note that stories may have different creation dates then the categories they are in, so you may end up with URIs like this:
http://example.com/2003/10/23/category
http://example.com/2003/12/14/category/story

If you use the cooluri2 plugin, you might want to read about how I converted my site to use Cool URIs.

Download cooluri2 0.0.1

Documentation is available here.

Occasionally a blosxom plugin needs a perl module that isn’t installed on the server, such as MIME::Types or File::Cat. For users who don’t have administrative access on their server, there has been no official place to install such modules. Additionally, users then needed to modify blosxom.cgi or the plugin to have it search the correct location.

This plugin attempts to help the situation by telling Perl to look for modules in $blosxom::plugin_dir/lib. This gives a standard place to install to (for example, File::Cat comes with one file, Cat.pm, which would go in $blosxom::plugin_dir/lib/File) and also means that users don’t have to modify anything to get perl to find the new module.

Note: uselib needs to be loaded before plugins requiring extra perl modules. You can do this by renaming it to something like 01uselib.

Download uselib 0.0.1

Update:Documentation is now available here.

So, I wanted to be able to post pictures. Seemed like a simple enough idea but I ran into a lot of problems. I tried 3 different plugins:

• autoimg
• binary
• static_file

autoimg replaces simple tags in the story with html img tags. It was the easiest of the 3 to use, but didn’t do a good job on the layout. On short stories, images would interfere with the next story. Also, autoimg wanted images to come out of my website’s directory, not the directory where I keep blosxom stories. While this might normally be a Good Thing (separation of content and presentation), in my case the pictures are the content.

binary intercepts URLs passed to blosxom and checks to see if the file exists. If it does, it gets served up. Otherwise, blosxom.cgi gets to deal with the URL normally. This lets me store my images in the blosxom story folder, right next to my text files. It had several bugs, however, and I gave up on it.

static_file is a rewrite of binary. It works much better for me. Combined with interpolate_conditional, it is very close to what I wanted.

Here is an example. In my story, I have this:

<a href="poppies.png">  <img src="poppies.thumb.png" alt=[poppies]"/> </a>

The .png images are sitting in the same directory as the .txt file for this story. interpolate_conditional generates the proper URLs, and static_file catches the requests and serves up the right images:

I would like an easier way to add images than entering raw html source, but for now I am happy. Oh, and in case you are wondering I modified interpolate_conditional so it would pass those $’s through when it sees two in a row. Here is the patch

Update: I also made a patch for static file to make the default MIME type configurable.

I want the timestamps on postings to use the PST/PDT timezone, but my server is set to to EST/EDT. I grabbed Raffi Krikorian’s timezone plugin but couldn’t get it to work. Turns out I had to rename it from “timezone.plugin” to “timezone”, after which it works perfectly. I still want the timezone appended on the timestamps (so it would say “posted at: 22:25 PST”, for example).

Update: I’ve updated the timezone plugin so it now exports the timezone for use by flavours.