Amputator 1.2 for Movable Type and Blosxom

Short description

Amputator is a free plugin for Movable Type and Blosxom. It safely rewrites ampersand characters as an HTML entity reference: “&”.

Long description

If you want your HTML or XHTML to display smoothly across browsers and platforms, you need to use a little finesse with non-ASCII characters such as curly quotes, or “ä” or “™.” If you view source on this page, you’ll see I specified those last two characters by writing “ä” and “™.”

Sequences like “™” are called entity references, and their sole benefit is that they can be expressed in plain ASCII. HTML includes heaps of entity references to stand in for various accented and otherwise special characters not found in ASCII. Entity references all start with ampersands, and end with semicolons.

Unfortunately, HTML and XML reserve the ampersand exclusively for entity references. Any time you use an ampersand by itself, for example within the token delimiters of GET-style URLs like this one, the HTML parser will try to read it like the start of a nonexistent entity reference. Any decent browser will catch the error and recover, but it’s still a mistake, and your HTML won’t validate.

You can make your HTML clean again by replacing the ampersand with an entity reference for an ampersand. So instead of just “&”, you’d write “&”, and the browser will make the last-minute substitution.

Amputator steps in to relieve you of the crushing, trivial burden of replacing all those ampersands yourself. After installation into Movable Type or Blosxom, you can freely gab about Law & Order and Brown & Williamson, while your ampersands will be replaced by entity references on the fly, as you publish.

Of course, Amputator is smart enough to ignore ampersands attached to existing entities. Otherwise, writing “é” would come out “&eacute;”, and nobody likes that except the odd technical writer.

Movable Type Installation

Amputator requires Movable Type version 2.5 or later, and works fine with Movable Type 3.x.

Copy the Amputator.pl file into your Movable Type plugins directory. If you don’t have a plugins directory, create an empty directory named “plugins” in your MT server root, alongside all the MT CGIs, and put Amputator inside that new directory. In other words, your installation should look like this:

(MT home)/plugins/Amputator.pl

If you're using the MT "dynamic publishing" model, you'll want to install the PHP version of the Amputator plugin. Copy the "modifier.encode_ampersands.php" file from the "optional" folder of the Amputator distribution into MT's PHP plugins folder:

(MT home)/php/plugins/modifier.encode_ampersands.php

You can skip this step if you're not using dynamic publishing, but there's no harm installing it.
Now it’s time to edit your blog templates. Any tags that might contain a stray ampersand should be modified to call encode_ampersands. MTEntryBody is an obvious place to start:

<$MTEntryBody$>

becomes:

<$MTEntryBody encode_ampersands="1"$>

Easy! Ditto for <$MTEntryMore$>, or <$MTEntryTitle$>:

<$MTEntryMore encode_ampersands="1"$>
<$MTEntryTitle encode_ampersands="1"$>

You're done.

Blosxom Installation

Amputator requires Blosxom version 2.0 or later.

Rename the plugin from "Amputator.pl" to "Amputator". (Movable Type requires the dot-pl suffix for its plugins, but Blosxom forbids it.)
Copy the Amputator file into your Blosxom plugins directory. You're done. Amputator will cover the title and body of all entries.

Bugs

I know of only one case where Amputator improperly replaces an ampersand: if you're using a JavaScript snippet inside of a weblog entry, Amputator may convert an ampersand intended for the JavaScript interpreter instead of the browser, confusing the interpreter. If this problem affects you, please let me know at the address below so we can discuss a solution.

Aside from that, if you encounter a problem, please and tell me all about it.

Version History

1.2 Friday, August 26, 2005

Now compatible with Movable Type 3.2.
Blosxom already encodes ampersands when producing RSS, so Amputator leaves Blosxom's RSS output alone. I also abandoned the cleaner MT::Plugin namespace, because Blosxom couldn't handle it.
Amputator now officially supports MT's dynamic publishing model (thanks, Chad Everett).

1.1.1 Mon, Feb 21, 2005

No functional code changes, but Amputator now declares itself to MT 3 installations on the main menu page, and uses the sanctioned MT::Plugin::Amputator package instead of the Amputator package. Existing users should feel no pressure to upgrade unless they enjoy looking at the plugin census.

1.1 Tue, March 16, 2004

Updated for Blosxom support.

1.0: Thu, March 6, 2003

Initial release.

Documentation revised September 28, 2003.

Author

Nat Irons
http://bumppo.net

Additional Credits

John Gruber precipitated the release of this plugin by providing several good reasons why he was unwilling to make SmartyPants take care if it for me.

Max Barry suggested adding Blosxom support, after a previous ampersand-replacing plugin for Blosxom went AWOL.

Grettir Asmundarson and Chad Everett contributed code.