WP2Gopher v1.0
by Michael Proctor (michael@4d2.org)
March 27, 2008


LICENSE

WP2Gopher is released into the public domain by its author. It may be used
by anyone for any purpose.


ABOUT WP2GOPHER

WP2Gopher is a simple (well, simplish) PHP program that extracts the posts
and comments from a blog running the WordPress software and makes them
ready to be served out over Gopher (i.e., as a phlog). I've tested it
with pygopherd, which I use on my server, but it should work just as well
with Bucktooth.

I use WP2Gopher to generate the Gopher version of my WordPress blog,
which you can see here:

gopher://gopher.4d2.org/1/phlog/page1

or here:

http://blog.4d2.org

In practice, this means that it pulls data from your WordPress MySQL
database, and creates a set of directories, gophermap files and text
files containing your posts. Posts are split into pages of 50 posts
each (though this is configurable), and there is also an option for users
to view all posts, though this may be a large list in the case of a blog
with hundreds of posts.

To my knowledge, nobody has done this before. (Let us not discuss why
this might be the case.) I've found one person who offers his blog via
Gopher using a very simple Python program that does little more than pipe
the output from WordPress to the client on port 70. It still serves up
HTML, which I see as contrary to the purpose of Gopher.

By contrast, WP2Gopher makes every attempt to format your blog posts for
plain-text presentation. It translates HTML tags into appropriate
plain-text alternatives wherever possible, removing any tags it isn't
prepared to deal with; it word-wraps; it does its best to present
hyperlinked text and embedded images as URLs within the text that can be
perused if the user so chooses (and is using a capable browser).

PHP was chosen to implement this program for two reasons:

1. I like PHP.
2. Anybody running WordPress already has it.


INSTALLING WP2GOPHER

WP2Gopher consists of a single file: wp2gopher.php. As of this writing
the most current version is 1.0. All you have to do is download the file:

gopher://gopher.4d2.org/0/wp2gopher/wp2gopher.php

...and store it somewhere accessible on your server (I put mine under
/usr/local, but it's your call).

Open the file in your favorite text editor and look at the configuration
section near the top of the file. These values will need to be changed
to ones that are appropriate for your blog. If you intend to run
WP2Gopher as a cronjob, you will want to set $verbose to FALSE, but make
sure everything is working OK before you make that change. $blogname,
$httpurl and $email are only used in the default header and footer
messages, so if you change those messages to something customized you
might not need to worry about those three variables anymore.

Once you have set the variables in the configuration section, you'll need
to at least make sure that the directory you specified as $gopherpath
exists and is writable by the the gopher server, e.g.:

mkdir /var/gopher/phlog
chown gopher:gopher /var/gopher/phlog

WP2Gopher will *erase and recreate everything in $gopherpath* each time
it is run, so it's imperative that you do not specify a directory which
contains anything else.

Now you're ready to test it out, so do something like this:

/usr/bin/php /usr/local/wp2gopher.php

...obviously adjusting the paths to suit your situation. WP2Gopher should
produce helpful output notifying you of any errors that have occurred. If
it reports success, try pulling up your new phlog via Gopher, e.g.:

gopher://myserver.com/1/phlog/page1

When adding a selector for your phlog, I would recommend linking to "page1"
as shown above, but you can also link to "page4" if you want people to see
your oldest posts first, or "posts" to take visitors directly to a list of
all your posts. WP2Gopher does not generate a gophermap file in the top-
level directory ("/phlog" in this example), so you should not point
selectors there.

If everything works well for you, or if something doesn't work, I would
love to hear about it (michael@4d2.org).


TWEAKS: PLAIN-TEXT TRANSLATION

The logic that transforms HTML into plain text is contained in the function
textize(). If you'd like to change the way things are formatted, have a
look at this function. In particular, there's an array called "replaces"
that contains a large set of replacements, for example:

"<b>" and "</b>" both become "*"
"<u>" and "</u>" both become "_"
"&deg;" becomes " degrees "
"&nbsp;" becomes " "

...and so on. WordPress has a tendency to introduce a lot of special HTML
characters, like em-dashes and special quote characters, that have to be
translated, and this array is what controls that behavior.

If you have a character in one of your posts that isn't handled properly
by WP2Gopher, just add a mapping for it to this array. It should be fairly
easy even if you don't speak PHP.


RUNNING WP2GOPHER AS A CRON JOB

Since an active blog will have new posts and comments added all the time,
WP2Gopher should be re-run frequently to update the static Gopher content
it generates. On a Linux or UNIX server the easiest way to accomplish this
is by adding a cron job. I won't go into a great deal of detail, but
basically the way to do this is:

1. Make sure $verbose is set to FALSE, or you will be spammed with a large
   amount of email from cron.
2. Add a line to crontab to run WP2Gopher. Make sure you set it to run as
   the same user your gopher server runs as. I run WP2Gopher every 30
   minutes on my server, and this is the line I use:

   0,30 * * * * gopher /usr/bin/php /usr/local/wp2gopher.php

On Debian and Debian-based Linux systems, instead of crontab you'll have
a bunch of files under /etc/cron.d; just add a new one for WP2gopher.

You may be concerned about WP2Gopher deleting and recreating all of your
phlog's data every time it runs. For my medium-sized blog (about 200
posts) on my not-too-powerful server, WP2Gopher takes about half of a
second to run, which I see as an acceptable amount of "downtime" every
half hour. However, your situation may differ, and you may want to consider
pointing WP2Gopher at a directory that exists somewhere other than your
Gopher root, and then copying files over once WP2Gopher finishes. Since it
would be safe to do so without deleting the existing files, this would
result in no "downtime."

I haven't done this myself, but I could see setting wp2gopher to write
files in /tmp/wp2gopher and then using a shell script like this:

#!/bin/sh
/usr/bin/php /usr/local/wp2gopher.php
cp -R /tmp/wp2gopher/* /var/gopher/phlog

You could then use this script as your cron job. This behavior may be
included directly in the a future version of WP2Gopher if there is a
need.


CONTACTING ME

I'm michael@4d2.org, and I'd like to hear any comments you have about
WP2Gopher. If you run into any problems with it or have feature requests,
I'll do my best to help.