james mckay dot net

It turns out that the WordPress Syntax Highlighter plugin that I mentioned a couple of weeks ago has some rather nasty artifacts. One in particular is that when you try to display HTML — or any code containing HTML — WordPress tries to “fix” this by adding extra tags that you may not want to make it valid XHTML, and it b0rks your nice tidily formatted source code in the process. Another problem was that it converted emoticons to images — a big no-no when you’re writing source code.

Yeah, maybe I should have been using the rich text editor, but that caused other problems. Rich text editors generally wreak havoc with source code, so it’s best to turn them off when you’re doing anything of that nature.

This was the reason why I stuck with Code Auto Escape for so long. Entering source code is awkward, to be sure, but nevertheless the plugin is pretty robust and does a good job. I did try a few proper syntax highlighter plugins way back, but I didn’t find any of them all that satisfactory. However, Code Auto Escape is a plugin that Just Works™.

It also turns out that Alex Gorbatchev’s Syntax Highlighter JavaScript code allows you to set various options for your code blocks, such as hiding the toolbar or the line numbers, or starting numbering at a number other than 1. The WordPress Syntax Highlighter plugin does not expose these options.

Sooo… why not combine the two approaches?

Over the Bank Holiday I’ve spent a few hours writing a new plugin that does precisely that. I took Code Auto Escape as the baseline, and added a whole bunch of extra code to plug in the syntax highlighter scripts.

Interested? Get Coder 1.0 alpha 1 here.

Comments (1) »

Posted at 13:41 in WordPress plugins

I’ve been thinking a bit recently that many other programmers’ blogs do a much better job of handling code snippets than mine does. Since time immemorial I’ve been using a very simple plugin called Code Auto Escape, which merely allows you to type code verbatim into your posts without having to go through all the rigmarole of HTML encoding them. I’ve never looked for anything fancier mainly because I never got round to it.

However, if you are geeky enough to post code on your blog in the first place, you need to do it properly, and that means syntax highlighting. Fortunately, it’s a simple case of finding and installing the right WordPress plugin. So, this morning, I finally got round to doing a bit of googling for one.

There are several such plugins to choose from. Most of them are based on GeSHi, a popular and very well supported PHP library which offers syntax highlighting for almost every programming language you can think of. It runs on the server, injecting extra markup into your code to achieve the desired effect.

In the end I settled for Syntax Highlighter. It takes a different approach, using JavaScript in your browser to render the highlighting and add a little toolbar at the top of each snippet with options such as copying it to the clipboard:

var highlightColour = "#ffff00";
var normalColour = "#ffffff";

$(document).ready(function() {
  $("#my-table tr").hover(
    function() {
      $(this).css("background-color", highlightColour);
    },
    function() {
      $(this).css("background-color", normalColour);
    }
  );
});

Personally I think this is a better, cleaner approach: it delegates the heavy lifting involved from the server to your browser, and reduces the size of the markup in your posts. It is also semantically cleaner: while the output from GeSHi is valid XHTML strict, it does jumble up content and presentation a bit, which is the reason why table-based layouts, the <font> tag and inline CSS tend to be frowned upon these days.

Unfortunately, none of these plugins address the biggest problem with writing code on your blog: that it is so fiddly and awkward with a rich text editor. Both Windows Live Writer and TinyMCE in WordPress take a perverse delight in messing up your indentation, your line breaks, and sometimes even with what gets HTML encoded and what doesn’t.

Comment on this »

Posted at 10:23 in WordPress plugins

Astute readers of my blog will note that I turned off my Comment Timeout plugin at the start of this year. I had begun to suspect that its effect on spam was minimal, while at the same time there were still some posts that, according to Google Analytics, attract a bit of attention — in particular, my posts about SharePoint seem to feature rather prominently in searches by people who find the subject even more confusing than I do.

Sooo… now you can even leave comments on my very first blog entry if you are that way inclined.

In the end, I found that turning it off did not result in a noticeable increase in spam comments. I am now using only three plugins to manage spam on my blog and together they put in a stellar performance. Akismet and Bad Behavior stop almost everything dead in its tracks, and beyond that, a blanket rejection of comments that contain BBCode or more than two hyperlinks keeps your spam queue short, makes it easy to check for false positives, and reduces the load that it places on Akismet and your bandwidth consumption. As far as I can tell, 80-90% of spam comments contain either BBCode, or three or more hyperlinks.

However, this raises a question: what is the future of Comment Timeout?

Unfortunately, I have had quite a lot on at work recently and I have other projects that I want to move on to that I simply haven’t had time for so far, so since I am no longer using Comment Timeout myself, maintaining it further now has a very low priority.

There are some things that could still be done on it, such as localisation, but as far as I can tell, it is stable, it works with any version of WordPress since 2.0, and pretty much all the bugs that have been brought to my attention have been ironed out. I haven’t tested it thoroughly against WordPress 2.5, but as far as I can tell it should work properly.

If anyone would like to develop it further, I have no objections. It’s dual licensed under both the GPL and the MIT/X11 licence, so you don’t even need to ask for permission, though it would obviously be nice to get a heads-up.

Comments (1) »

Posted at 13:06 in WordPress plugins

The latest version of Comment Timeout 2.0 is now available. It fixes a bug that was letting comments from spam bots through on older posts. If you are using version 2.0 alpha 1 you should upgrade.

Comments (1) »

Posted at 18:32 in WordPress plugins

There is a bug in the newly released Windows Live Writer beta 2 that causes it to choke if you are also using Bad Behavior on your blog.

I first discovered this when I installed it yesterday to check it out. When it refused to update the theme from my blog, I wondered at first if there was a problem with my custom theme, but then half an hour later I looked at my home page again to find that all the comments on my blog had closed. A quick investigation showed that Bad Behavior had been choking on the requests from Windows Live Writer and logging the failed attempts, which were then being picked up by my new plugin, Three Strikes and You’re Out.

It turns out that the problem stems from the fact that Bad Behavior expects Internet Explorer to include an “Accept” header with every HTTP request, and if it gets something that claims to be Internet Explorer yet doesn’t match up to its expectation, it throws an error.

Fortunately, it is not too difficult to fix this, though you do need to tweak the code base of Bad Behavior. Open the file msie.php in the bad-behavior subdirectory of your Bad Behavior plugin and find the lines which say:

if (!array_key_exists('Accept', $package['headers_mixed'])) {
    return "17566707";
}

Change this to read as follows:

if (strpos($package['headers_mixed']['User-Agent'], "Windows Live Writer")
    === FALSE && !array_key_exists('Accept', $package['headers_mixed'])) {
    return "17566707";
}

You should then be able to use Windows Live Writer on your blog once again, without losing the protection offered by the Bad Behavior plugin.

Comments (16) »

Posted at 08:33 in WordPress plugins

The first alpha versions of my new WordPress comment plugins are now available for download.

Comment Timeout 2.0 closes comments on posts on your blog a certain time after they are posted. It has been rebuilt from the ground up to incorporate some new features:

• You can now override the default settings to allow certain posts to have the discussion kept open for a shorter or longer time, or even indefinitely.
• You can define a “popularity level” above which the discussion can be kept open for an even longer period of time if you so desire.
• You can have comments on older posts sent to the moderation queue instead of closing the discussion altogether.
• The comment form now indicates when the discussion for a particular post will close.

Some features were added to version 1.3 but have now been spun off into two separate plugins:

Three Strikes and You’re Out examines your Bad Behavior logs and your spam queue and closes comments across the board on your blog when you are visited from any IP addresses that have been repeatedly misbehaving (the default settings are three times in a week). It also defines a couple of hooks and adds a new logging table to the database, so other plugins can register naughty events (e.g. failed captcha tests) or override the counting mechanism (e.g. to implement whitelists or blacklists).

Link Limits rejects comments which contain BBCode or more than two normal hyperlinks. I’ve found that this blocks approximately 80% of spam, yet genuine comments exceeding these limits are almost non-existent. It informs your commenters that this restriction is in place. It also logs any violations to Three Strikes And You’re Out, but it works perfectly well if you do not have Three Strikes And You’re Out installed.

I’ve marked them all as “alpha 1″ status, which means use at your own risk, though I am dogfooding them on my own blog. If you have any problems with them, I’ve written a post on how to report problems with WordPress plugins — please read it before giving me a shout, though I do welcome feedback and suggestions of course.

Starting with these plugins, I have changed the licensing terms. Whereas the old versions were GPL, these ones are available under the MIT X11 licence. It is GPL compatible but doesn’t have the “copyleft” element. This means that if you wanted to, you could adapt it for use with another, non-GPL, CMS or blog program.

Comments (5) »

Posted at 23:28 in WordPress plugins

Since I’ve released a WordPress plugin that’s been attracting a fair amount of attention, it’s inevitably had its share of users who have reported some problem or other. Most people find that everything proceeds fairly smoothly, but inevitably there will be those who, for one reason or another, simply can’t get it up and running. So I thought I’d put down some tips on what to do if you encounter a problem, and how best to go about reporting it.

This advice is intended to be fairly general, and not specific to any of my own plugins, and though different developers may have slightly different expectations, it should come in useful irrespective of which plugin you are using and who wrote it.

1. Make sure that you’ve read and understood the instructions.

This may sound obvious, but amazingly, some people don’t. Check that your version of WordPress is supported (most newer plugins these days require version 2.0 or later, and some even require version 2.1). Check that you’ve understood correctly what the plugin does, what all the configuration options mean, and whether or not you’ve overlooked something. There may also be some known issues or bugs with the plugin, so you should check to see if you’re up against one of those. It also helps to read the comments left by other users: they may be able to shed some light on the problem. A search of the WordPress support forums may also help.

You don’t have to trawl the whole Internet or even the whole site, but if you at least show that you’ve looked in the most obvious places, it helps a lot. If there’s anything you don’t understand, by all means say so, but indicate exactly what it is that you don’t understand, rather than simply saying “I don’t understand the instructions.”

2. Check to see if there’s a conflict with another plugin.

There are thousands of WordPress plugins out there, and it is simply not possible to test our creations against all of them. Consequently, there is always the possibility that your newly installed plugin could be conflicting with one of the others that you have been using.

Checking to see if this is the case is fairly straightforward, though it’s a good idea to back up your WordPress database before you do so in case anything goes wrong. Disable all your other plugins and switch to the WordPress default theme. This may or may not fix the problem. If it does, switch your theme back and then re-enable the other plugins one at a time until the problem reasserts itself. When you do this, the conflict is between your new plugin and the last one that you re-activated.

You should let us know which other plugin or theme, and which version, is causing the problem. Tell us where to get it too, and make sure that the link to its home page still works. There is little or no incentive to ensure compatibility with a plugin or theme that has vanished off the face of the web and is no longer being maintained.

3. Check to see if the problem occurs on other computers in other places.

Some plugins have features that depend on your IP address, which may be different depending on whether you are accessing the Internet at work or at home. Some have Javascript that may not have been tested thoroughly on all browsers. You may be accessing the Internet through a proxy server which could be causing unforeseen problems.

If you can, check to see whether or not you get the same problem on a different browser on another computer. You don’t have to check every permutation of plugins and so on, but if the problem occurs in one place and not another one, we’d be interested to know.

4. Make your feedback clear and specific.

Here is an example of a bad question:

I tried your plugin. I can not get it to work. What is the problem?

This haiku is worse than useless because it tells me nothing, yet I have to spend time reading it and deciding whether to respond to it or report it as spam to Akismet. If you’re lucky, you’ll get a response along the lines of: “I haven’t a clue. I am not a mind reader. Please give more details.” If you’re not, you’ll just be ignored and your comment will be flagged as spam.

By contrast, here is an example of a good bug report:

I’ve installed version 3.14159 of the Happy Pi Day plugin and I’ve found that my users are getting a Blue Screen Of Death when they visit my website on the fourteenth of March if they’re using Internet Explorer on Windows Vista. I’m running WordPress 2.1.3 on PHP 4.4.4 and MySQL 4.1. I’ve tried disabling all my other plugins and switching to the WordPress default theme, but the problem still persists. There’s an option on the plugin page that says “Einstein’s Birthday Mode” but I didn’t understand from the documentation what that is supposed to do, so I haven’t tried changing that.

You can see the problematic page at http://www.example.com/happy-pi-day/.

This is much better because it gives us a lot of useful information in clear, unambiguous terms.

At an absolute minimum, you should state:

• what you expected to happen;
• exactly what actually happened;
• the exact text of any error messages;
• the steps needed to reproduce the error;
• which versions of WordPress, PHP, MySQL and the offending plugin you are using.

You should also give as much additional information as you have been able to determine in your troubleshooting steps above:

• which browsers and operating systems are affected on the client side;
• whether you have found a conflict with any other plugins or your theme;
• anything about the documentation that you didn’t understand;
• where appropriate, the URL of a blog or post where the error can be seen in action.

Remember that you’re aiming for clarity. Write in plain English, in whole sentences. Read your report back to yourself to make sure that it’s clear and unambiguous. Don’t post guesswork as to what you think the problem might be: report the symptoms of the problem — i.e. exactly what you did, exactly what happened, and exactly how reality deviated from your expectations.

Many plugin authors — myself included — work on their offerings for free. This means that the amount of time that we can spend supporting them is strictly limited, and unless you are one of our paying clients, we have to triage bug fixes and support issues that come our way, sometimes pretty aggressively. Inevitably, it’s the queries that provide us with the most helpful information about the problem that are likely to get the most (and quickest) attention.

Comment on this »

Posted at 15:24 in WordPress plugins

A colleague of mine mentioned to me the other day that I ought to read The Mythical Man-Month by Fred Brooks. I haven’t done so yet, but I was interested to see from the various reviews that it talks about the “second-system effect” — that the second version of a system that you design will tend to be over-engineered, since it has all the features that you thought about for the first version but didn’t implement due to time constraints. It means going from a small, elegant, successful system to something large, feature-laden and bloated. Scope creep, in other words.

I’ve been thinking about this as far as the next version of my Comment Timeout plugin is concerned. The original idea was quite simple: to close comments on your blog entries after a certain length of time. The current version has extended well beyond that remit, with a whole bunch of other features that, while useful and maybe related from a technical perspective, aren’t really related from the end user’s point of view to what the plugin is ostensibly trying to do. I wonder if this is probably a bit confusing for users and making it a bit difficult to determine whether issues are due to bugs in the code itself or people misunderstanding what it’s supposed to be doing.

I think the answer is probably to separate it out into different plugins, each of which concentrates on doing a single thing and doing it well. At the moment, I’m thinking of separating it into three different plugins, perhaps something along these lines:

• Comment Timeout 2.0: a trimmed-down version, which concentrates solely on the job of closing comments on old posts after a certain length of time.
• The Black Hole: the functionality to nuke comments altogether if they contain BBCode, too many hyperlinks, or certain keywords, so they don’t even make it as far as your spam queue.
• Three Strikes and You’re Out: the bit that examines your Bad Behavior logs and spam queue and closes comments to IP addresses that are persistently causing trouble.

I’d be interested to know what people think of this idea. Would it make it easier to understand, or would it just make things a bit more confusing? Leave me a comment and let me know what you think.

Comments (6) »

Posted at 08:15 in WordPress plugins

The latest version of Comment Timeout is now available for immediate download. This fixes several bugs:

1. The plugin no longer raises a warning when installed on a server where allow_call_time_pass_reference is turned off in your php.ini file.

2. It is now possible to disallow hyperlinks in comments entirely, by setting the maximum number of hyperlinks to zero.

3. Hyperlinks that contain line breaks are now counted correctly.

One important note: If you are upgrading from an earlier version, and had set it to allow unlimited hyperlinks in your comments, it will now reject all comments containing any hyperlinks at all. To fix this, go to the options page and uncheck the box that says “Reject all comments containing more than 0 hyperlinks” — or alternatively, you can change the zero to some larger number of your choice.

Comments (19) »

Posted at 21:48 in WordPress plugins

For those of you who know a bit about PHP and WordPress internals and are interested, here is a brief technical overview of the details behind the bug in the original version of Comment Timeout.

I was originally tweaking the comment status of the posts at the start of the loop. The way I was doing it was admittedly a hack, but it worked — in PHP 5 at any rate, which has pass-by-reference semantics. However, it fell over in PHP 4, where variables are all passed by value rather than by reference.

It actually turns out that there is a non-hack way of achieving this. This evening I discovered that WordPress provides a filter, the_posts, which gives you a much better way of doing it. It passes an array containing all the posts returned by a query to your filter; your plugin modifies the array as appropriate — in this case, setting the comment status on some of the posts to “closed” — and returns it. The latest version (1.3 alpha 2) now adopts this approach.

Unfortunately, a lot of the WordPress API documentation is somewhat incomplete and sketchy, especially on the more technical side, which is probably why I missed this the first time round. Perhaps as plugin authors we ought to chip in and spend a bit of time polishing it up as we go? It is a wiki after all, so we’ve only ourselves to blame if it’s not up to scratch.

Comments (4) »

Posted at 23:05 in WordPress plugins