Blosxom: Upgrading to an RSS 2.0 Feed

Blosxom still pretty much just damn works, but it’s dying. A dead News link on a project site is never a good sign. It won’t be long before the STP will have to move to another weblog backend, but that’s for another day.

Today’s issue: Facebook keeps inexplicably dropping my RSS feed. Facebook is of course happy to pretend there isn’t an internet outside its walls, but I get a lot more feedback on my ideas through Facebook than in the blog comments. Whether it’s the cause of this problem or not, in keeping with its age, Blosxom serves feeds in the RSS 0.90 format, which would be a bit of a ColecoVision even if Blosxom had ever done it right.

I’ve modified my copy of the blosxom.cgi script to produce a modern RSS 2.0 feed that validates correctly. You can do the same. Here’s how:

1. Open blosxom.cgi in a text editor and scroll to the bottom.

2. Replace this rubbish:

rss content_type text/xml

rss head <?xml version=”1.0″?>\n<!– name=”generator”

content=”blosxom/$version” –>\n<!DOCTYPE rss PUBLIC “-//Netscape

Communications//DTD RSS 0.91//EN”

“http://my.netscape.com/publish/formats/rss-0.91.dtd”>\n\n<rss

version=”0.91″>\n  <channel>\n   

<title>$blog_title $path_info_da $path_info_mo

$path_info_yr</title>\n   

<link>$url</link>\n   

<description>$blog_description</description>\n   

<language>$blog_language</language>\n

rss story   <item>\n   

<title>$title</title>\n   

<link>$url/$yr/$mo_num/$da#$fn</link>\n   

<description>$body</description>\n  </item>\n

rss date \n

rss foot   </channel>\n</rss>

3. With this rubbish:

rss content_type text/xml

rss head <?xml version=”1.0″?>\n\n<rss

version=”2.0″>\n  <channel>\n   

<title>$blog_title $path_info_da $path_info_mo

$path_info_yr</title>\n   

<link>$url</link>\n   

<description>$blog_description</description>\n   

<language>$blog_language</language>\n

<generator>blosxom $version</generator>\n

<docs>http://blogs.law.harvard.edu/tech/rss</docs>\n

rss story   <item>\n   

<title>$title</title>\n   

<pubDate>$dw, $da $mo $yr $ti:00

GMT</pubDate>\n   

<link>$url/$yr/$mo_num/$da#$fn</link>\n   

<guid

isPermaLink=”true”>$url$path/$fn</guid>\n   

<description>$body</description>\n  </item>\n

rss date \n

rss foot   </channel>\n</rss>

That’s it.

Plugins

The following are the plugins in use on the Space Toast Pages, in the order in which they were installed. Note that plugins should be saved into Blosxom’s plugins folder with no file extension: do not add .cgi or .txt, for example, or they will not run.

Excludez

Available here. Prevents Blosxom from reading designated directories. Necessary to keep certain text files in the old pages directory from appearing as Space Toast Pages. Minimal setup, no headaches.

Blox

Available here. Automatically inserts paragraph tags and line breaks. Big time saver. Minimal setup. Has an optional “wiki-like” markup system, on by default, which was disabled after it mangled a Creative Commons license. Grinds JavaScript to a bloody pulp. (Would do well to disable itself inside comment tags.)

File

Available here. Allows the contents of text files to be inserted dynamically into templates and stories. Used to add the “Current Addiction” to the sidebar. Minimal setup, no headaches.

MoreEntries

Available here. Creates the “Next” and “Previous” links that appear at the bottom of the page when needed. Smart about when to add the links and when not to. Basic setup minimal, but changing the default wording and styling of the links requires digging through Perl code.

Meta

Available here. Required by the Entries_Cache_Meta plugin below. No setup, pain-free.

Entries_Cache_Meta

Available here. Allows a story to specify its posting date. Needed to backdate the old weekly issue Space Toast Pages and to keep Blosxom from treating edits as brand new postings. Poorly organized variable configuration slows setup.

WritebackPlus

Available here. Invites readers to post their comments about Space Toast Pages. (Hint: Dig through the >Run Fight Heal Magic line.) Complicated setup, but not out of line with total functionality. May need to be rethought if comment spam ever becomes a problem. Update: Was rethought when Comment Spam became a problem.

The problem of Comment Spam will receive its own posting shortly.

Cloaking Blosxom

The correct form of a URL is where/what, as a web address exists to organize content. By default, Blosxom serves pages from www.spacetoast.net/cgi-bin/blosxom.cgi, a machine-centric where/how address which breaks the above guideline. A method was needed to disguise the address of the cgi script.

Blosxom’s main site includes instructions for hiding the …cgi-bin/blosxom.cgi address on an Apache server by means of an .htaccess file — a local preferences file. Unfortunately, the instructions did not work for this site.

The first method given for cloaking Blosxom (bullet three, step two) redirected requests for any address in the STP directory to Blosxom, including images, media files and old pages. For this site, it would have been written thusly:

RewriteEngine on

RewriteRule ^STP/?(.*)$ /cgi-bin/blosxom.cgi/$1

The second given method (bullet three) invoked Blosxom only if a real file could not be found. It had problems with directories. Since STP/web/blosxom/ is a real directory, Blosxom did not attempt to create a page there, defaulting to either listing the files in the directory or producing a missing/forbidden error. Here is how it would have appeared:

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteRule ^STP/?(.*)$ blosxom.cgi/$1 [L,QSA]

Venerable Apache Server’s developers are a strange, thundering race who produce suitably impenetrable documentation, but after some levelling up the following was arrived at:

Options +Indexes

RewriteEngine on

RewriteCond %{REQUEST_FILENAME} !-f

RewriteRule ^STP(.*) http://www.spacetoast.net/cgi-bin/blosxom.cgi$1

Here is a breakdown. The first line overrides Laughing Squid’s default error when trying to browse a directory without an index file. The second turns the URL rewriting engine on. The third tells it when to work — in this case, when a file can not be found. (Notice that the missing directory line is now gone.) The fourth line tells Apache to remove “STP” and send the remainder of the address to the blosxom.cgi script.

This portion of the Blosxom installation took far more geekery than it should have. Strictly speaking though, it is optional.

Notes on Installing Blosxom

Blosxom’s official installation instructions are concise and straightforward. Installation required only a standard FTP client and a text editor. (I used JEdit with the FTP plugin installed.) The blosxom.cgi script ran as soon as it was installed; SpaceToast.net’s ISP, Laughing Squid, did not require it to be “blessed” first.

Configuration was straightforward. The settings are stored in the script itself. Many settings can be left at the defaults.

Fitting the Space Toast Pages’ existing layout into the Blosxom engine was equally straightforward. An old Space Toast Page was sliced into three “flavor” files, the head.html, story.html and foot.html files, with Blosxom markup tags added where dynamic content should be placed. (An additional date.html flavor file is required. On the Space Toast Pages it is an empty file, as date stamps are part of the story template.)

Blosxom stores posts as plain text files in the “data directory” and serves them as html files or rss feeds from the “blog directory.” The Space Toast Pages keep everything in SpaceToast.net/stp. Surprisingly, this doesn’t cause a problem. Any of the posts on the Space Toast Pages can be accessed as raw text files by simply substituting .txt for .html in the address bar. The text file is a real file sitting on SpaceToast.net; the html file is a fake created by Blosxom when it’s requested. An .htaccess file makes the ephemeral page look real — more on that in the next post on cgi cloaking.

Why Blosxom?

I’d been meaning to add blog software to my site for some time, and of all the content management systems I looked into, Blosxom seemed to best suite my prejudices:

  • Free and open source
  • Small and easy on the server
  • No annoying .php pages, as discussed in this rant
  • No database — nothing to yell at me if I make changes with FTP
  • Plugins to add missing features

With Blosxom now up and running, I can report that it delivers all of the above, at the cost of the following:

  • Missing, out of date and incomplete documentation
  • Missing, out of date and incomplete plugins

Blosxom is ancient in web terms, buoyed along by its simplicity of design. The original site is no longer updated, and while the current developers have mirrored the site to SourceForge, they appear to have done little to update it. Newer plugins can be found offsite, without documentation or generally even descriptions of what they do. Plugins listed on the conserved original site are often dead links; mirrors of the plugin code can usually be googled, but any documentation not included in the code itself is often gone. Blosxom has only basic functionality without plugins.

It is (apparently) possible for an artist with only a modest technical background to install, configure and use Blosxom. The core blosxom.cgi script is bulletproof, and the original installation instructions are quite good. Setup is minimal, and there are no dependancies. An understanding of Perl is not required.

Plugins can be another matter. Many of the plugin problems fall under a recurrent fallacy of open source: “It’s free, so I can be lazy.” Certain plugins expect the user to be a Perl hacker, which is counter to the philosophy behind the software. Others omit documentation, or are abandoned with features incomplete. Blosxom’s stop-and-go development over the years has not helped the problem. More on the plugins used on the Space Toast Pages will follow, after some notes on basic installation and the problem of “cloaking” the cgi-bin URLs.