| @@ -1,9 +1,9 @@ | ||
| 1 | 1 | FeedWordPress |
| 2 | 2 | ============= |
| 3 | 3 | |
| 4 | 4 | * Author: [Charles Johnson](http://radgeek.com/contact) |
| 5 | -* Version: 0.99 | |
| 5 | +* Version: 0.98 | |
| 6 | 6 | * Project URI: <http://projects.radgeek.com/feedwordpress> |
| 7 | 7 | * License: GPL 2. See License below for copyright jots and tittles. |
| 8 | 8 | |
| 9 | 9 | Introduction |
| @@ -19,57 +19,48 @@ | ||
| 19 | 19 | [Feminist Blogs]: http://www.feministblogs.org/ |
| 20 | 20 | |
| 21 | 21 | FeedWordPress is designed with flexibility, ease of use, and ease of |
| 22 | 22 | configuration in mind. You'll need a working installation of WordPress (version |
| 23 | -[2.3][], [2.2][], [2.1][], [2.0][] or [1.5][]), and also FTP or SFTP access to | |
| 24 | -your web host. The ability to create cron jobs on your web host would be very | |
| 25 | -helpful but it's not absolutely necessary. You *don't* need to tweak any | |
| 26 | -plain-text configuration files and you *don't* need shell access to your web | |
| 27 | -host to make it work. (Although, I should point out, web hosts that *don't* | |
| 28 | -offer shell access are *bad web hosts*.) | |
| 23 | +[2.0][] or [1.5][]), and also FTP or SFTP access to your web host. The ability | |
| 24 | +to create cron jobs on your web host would be very helpful but it's not | |
| 25 | +absolutely necessary. You *don't* need to tweak any plain-text configuration | |
| 26 | +files and you *don't* need shell access to your web host to make it work. | |
| 27 | +(Although, I should point out, web hosts that *don't* offer shell access are | |
| 28 | +*bad web hosts*.) | |
| 29 | 29 | |
| 30 | - [2.3]: http://codex.wordpress.org/Version_2.3 | |
| 31 | - [2.2]: http://codex.wordpress.org/Version_2.2 | |
| 32 | - [2.1]: http://codex.wordpress.org/Version_2.1 | |
| 33 | - [2.0]: http://codex.wordpress.org/Version_2.0 | |
| 34 | - [1.5]: http://codex.wordpress.org/Version_1.5 | |
| 30 | + [2.0]: http://wordpress.org/development/2005/12/wp2/ | |
| 31 | + [1.5]: http://wordpress.org/development/2005/02/strayhorn/ | |
| 35 | 32 | |
| 36 | 33 | Installation |
| 37 | 34 | ------------ |
| 38 | 35 | ### Requirements ### |
| 39 | 36 | |
| 40 | -To use version 0.99 of FeedWordPress, you will need: | |
| 37 | +To use version 0.98 of FeedWordPress, you will need: | |
| 41 | 38 | |
| 42 | -1. an installed and configured copy of WordPress 2.3.x, 2.2.x, 2.1.x, | |
| 43 | - 2.0.x, or 1.5.x. (FeedWordPress currently *will not work* with older | |
| 44 | - versions of WordPress, or with WordPress MU.) | |
| 39 | +1. an installed configured copy of WordPress 2.0.x or 1.5.x. (FeedWordPress | |
| 40 | + *will not work* with WP 1.2 or WP MU development builds.) | |
| 45 | 41 | |
| 46 | 42 | 2. FTP or SFTP access to your web host |
| 47 | 43 | |
| 44 | +And you'll probably also want to have either: | |
| 45 | + | |
| 46 | +1. the ability to create cron jobs on your web host, or at least | |
| 47 | + | |
| 48 | +2. a computer of your own and always-on Internet access | |
| 49 | + | |
| 48 | 50 | ### Installation ### |
| 49 | 51 | |
| 50 | 52 | #### Upgrades #### |
| 51 | 53 | |
| 52 | -To *upgrade* an existing installation of FeedWordPress to version 0.99: | |
| 54 | +To *upgrade* an existing installation of FeedWordPress to version 0.98: | |
| 53 | 55 | |
| 54 | 56 | 1. Download the FeedWordPress archive in zip or gzipped tar format and |
| 55 | - extract the files on your computer. | |
| 57 | + extract the files on your computer. Replace your existing FeedWordPress | |
| 58 | + files with the new files. Be sure to upgrade `rss-functions.php` if you | |
| 59 | + use the optional MagpieRSS upgrade, or don't use it yet but do want to | |
| 60 | + syndicate Atom 1.0 feeds. | |
| 56 | 61 | |
| 57 | -2. If you are upgrading from version 0.98 or earlier, then you need to | |
| 58 | - create a new directory named `feedwordpress` in the `wp-content/plugins` | |
| 59 | - directory of your WordPress installation, and you also need to *delete* | |
| 60 | - your existing `wp-content/update-feeds.php` and | |
| 61 | - `wp-content/plugins/feedwordpress.php` files. The file structure for | |
| 62 | - FeedWordPress has changed and the files from your old version will not | |
| 63 | - be overwritten, which could cause conflicts if you leave them in place. | |
| 64 | - | |
| 65 | -3. Upload the new PHP files to `wp-content/plugins/feedwordpress`, | |
| 66 | - overwriting any existing FeedWordPress files that are there. Also be | |
| 67 | - sure to upgrade `wp-includes/rss.php` and | |
| 68 | - `wp-includes/rss-functions.php` if you use the optional MagpieRSS | |
| 69 | - upgrade, or don't use it yet but do want to syndicate Atom 1.0 feeds. | |
| 70 | - | |
| 71 | -3. If you are upgrading from version 0.96 or earlier, **immediately** log | |
| 62 | +2. If you are upgrading from version 0.96 or earlier, **immediately** log | |
| 72 | 63 | in to the WordPress Dashboard, and go to Options --> Syndicated. Follow |
| 73 | 64 | the directions to launch the database upgrade procedure. The new |
| 74 | 65 | versions of FeedWordPress incorporate some long-needed improvements, but |
| 75 | 66 | old meta-data needs to be updated to prevent duplicate posts and other |
| @@ -74,34 +65,31 @@ | ||
| 74 | 65 | versions of FeedWordPress incorporate some long-needed improvements, but |
| 75 | 66 | old meta-data needs to be updated to prevent duplicate posts and other |
| 76 | 67 | possible maladies. If you're upgrading an existing installation, updates |
| 77 | 68 | and FeedWordPress template functions *will not work* until you've done |
| 78 | - the upgrade. Then take a coffee break while the upgrade runs. It should, | |
| 79 | - hopefully, finish within a few minutes even on relatively large | |
| 80 | - databases. | |
| 69 | + the upgrade. | |
| 81 | 70 | |
| 82 | -4. If you are upgrading from version 0.98 or earlier, note that the old | |
| 83 | - `update-feeds.php` has been eliminated in favor of a (hopefully) more | |
| 84 | - humane method for automatic updating. If you used a cron job for | |
| 85 | - scheduled updates, it will not work anymore, but there is another, | |
| 86 | - simpler method which will. See [Setting Up Feed Updates][] below to get | |
| 87 | - scheduled updates back on track. | |
| 71 | +3. Take a coffee break while the upgrade runs. It should, hopefully, finish | |
| 72 | + within a few minutes even on relatively large databases. | |
| 88 | 73 | |
| 74 | +4. `update-feeds.php` has been overhauled to improve performance and ease | |
| 75 | + of use, and also to make errors easier to detect and eliminate. The | |
| 76 | + overhaul doesn't require any changes to your set up *if* you used | |
| 77 | + XML-RPC pings, or command-line PHP, to do scheduled updates. It *does* | |
| 78 | + affect you if you used curl or some other tool to send HTTP requests to | |
| 79 | + `update-feeds.php`: your old cron job will probably not work anymore. | |
| 80 | + See [Setting Up Feed Updates][] below to get scheduled updates back on | |
| 81 | + track. | |
| 82 | + | |
| 89 | 83 | 5. Enjoy your new installation of FeedWordPress. |
| 90 | 84 | |
| 91 | 85 | #### New Installations #### |
| 92 | 86 | |
| 93 | -1. Download the FeedWordPress archive in zip or gzipped tar format and | |
| 94 | - extract the files on your computer. | |
| 95 | - | |
| 96 | -2. Create a new directory named `feedwordpress` in the `wp-content/plugins` | |
| 97 | - directory of your WordPress installation. Use an FTP or SFTP client to | |
| 98 | - upload the contents of the `wp-content/plugins/feedwordpress` directory | |
| 99 | - in the FeedWordPress archive to the new directory that you just created | |
| 100 | - on your web host. | |
| 101 | - | |
| 102 | -3. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by | |
| 103 | - installing the new `rss.php` and `rss-functions.php` (archived in | |
| 87 | +1. Install `feedwordpress.php` in your WordPress `plugins` directory | |
| 88 | + and `update-feeds.php` in your WordPress `wp-content` directory. | |
| 89 | + | |
| 90 | +2. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by | |
| 91 | + installing the new `rss-functions.php` (archived in | |
| 104 | 92 | `OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory. |
| 105 | 93 | Upgrading MagpieRSS is necessary if you want to take advantage of |
| 106 | 94 | support for Atom 1.0, multiple post categories, RSS enclosures, and |
| 107 | 95 | multiple character encodings. (Note, however, that support for |
| @@ -110,94 +98,110 @@ | ||
| 110 | 98 | a lot of feeds with alternate encodings you should make sure that |
| 111 | 99 | your installation of PHP is up-to-date and that you keep a copy of |
| 112 | 100 | the old MagpieRSS around to compare results.) |
| 113 | 101 | |
| 114 | -4. Log in to the WordPress Dashboard and activate the FeedWordPress | |
| 102 | +3. Log in to the WordPress Dashboard and activate the FeedWordPress | |
| 115 | 103 | plugin. |
| 116 | 104 | |
| 117 | -5. While you're at the Dashboard, once the plugin is activated, you can | |
| 118 | - go to **Syndication --> Options** and set (1) the link category that | |
| 105 | +4. While you're at the Dashboard, once the plugin is activated, you can | |
| 106 | + go to Options --> Syndication and set (1) the link category that | |
| 119 | 107 | FeedWordPress will syndicate links from (by default, "Contributors"), |
| 120 | - and (2) whether FeedWordPress will use automatic updates or only | |
| 121 | - manual updates. | |
| 108 | + and (2) a "secret word" for your RPC-XML updating interface. This | |
| 109 | + provides some light security by keeping passing ruffians from saying | |
| 110 | + "Update all the feeds" at will to your FeedWordPress installation. | |
| 122 | 111 | |
| 123 | -5. Go to the main **Syndication** page to set up the list of sites that | |
| 124 | - you want FeedWordPress to syndicate onto your blog. (If you have the | |
| 125 | - feeds you want to aggregate in a service such as Bloglines, | |
| 126 | - you may prefer to export them to an OPML file and use WordPress's | |
| 127 | - **Blogroll --> Import Links** to import them into the contributors | |
| 128 | - category.) | |
| 112 | +5. Go to Links --> Syndicated to set up the list of sites that you want | |
| 113 | + FeedWordPress to syndicate onto your blog. (If you have the feeds you | |
| 114 | + want to aggregate in a service such as Bloglines, you may prefer to | |
| 115 | + export them to an OPML file and use WordPress's Links --> Import to | |
| 116 | + import them into the contributors category.) | |
| 129 | 117 | |
| 130 | 118 | #### Setting Up Feed Updates #### |
| 131 | 119 | |
| 132 | -FeedWordPress is now ready to accept posts from its syndication sources. The | |
| 133 | -next thing to do is to make sure it knows *when* to go get them. | |
| 120 | +FeedWordPress is now ready to accept posts from its syndication sources. | |
| 121 | +Unfortunately, it doesn't yet know *when* to go get them. (**This may be true | |
| 122 | +even if you are upgrading an existing installation of FeedWordPress:** your old | |
| 123 | +cron job will still work if you used command-line PHP or blogging software pings | |
| 124 | +to do updates, but it will need to be fixed if you used curl or another tool to | |
| 125 | +send HTTP requests to `update-feeds.php`.) | |
| 134 | 126 | |
| 135 | -**N.B.:** If you are upgrading from version 0.981 or earlier of FeedWordPress, | |
| 136 | -the system for checking for new posts has been overhauled, hopefully making it | |
| 137 | -more humane, and also easier to use for people who do not have access to task | |
| 138 | -scheduling tools such as `cron`. You will need to re-read this section and | |
| 139 | -change your set-up accordingly. | |
| 127 | +You can load in syndicated posts for the first time by pointing your web browser | |
| 128 | +to `update-feeds.php`. If you have WordPress installed at, say, | |
| 129 | +<http://www.zyx.com/blog> then you should point your browser to | |
| 130 | +<http://www.zyx.com/blog/wp-content/update-feeds.php> and log in as any user in | |
| 131 | +the user database. (You may want to create a new "dummy" user for doing | |
| 132 | +scheduled updates, using **Users --> Authors & Users --> Add New User**. Tell | |
| 133 | +FeedWordPress to update all feeds, and you'll get the first wave of posts | |
| 134 | +imported into the database. | |
| 140 | 135 | |
| 141 | -FeedWordPress allows you to choose whether it will check for new posts | |
| 142 | -automatically, or only when you manually request for it to check. By default, | |
| 143 | -FeedWordPress opts for the **manual** option -- so that you can get your feeds | |
| 144 | -set up properly before FeedWordPress begins importing new posts. If you want | |
| 145 | -to use automatically scheduled updates, remember to enable them in | |
| 146 | -**Syndication --> Options** after you finish setting up FeedWordPress. | |
| 136 | +Congratulations! You should now have an aggregator site full of delicious | |
| 137 | +syndicated content hot off of the newswires. Now you just need a way to *keep* | |
| 138 | +the content freshly updated. Unless you enjoy manually browsing to | |
| 139 | +`update-feeds.php` every hour on the hour, you'll probably want to do this by | |
| 140 | +setting up your site for automated updates. | |
| 147 | 141 | |
| 148 | -##### Manual Feed Updates ##### | |
| 142 | +You can pull that off in one of two ways, or by a mixture of both: | |
| 143 | + | |
| 144 | +1. **The Blogging Software Ping Method:** You can get all of your | |
| 145 | + contributors to add you to the list of URIs that they notify of updates: | |
| 146 | + while FeedWordPress is activated, it will accept XML-RPC "recently | |
| 147 | + updated" pings in the standard format accepted by Weblogs.com, | |
| 148 | + Ping-O-Matic, Technorati, and other services. Most blogging software | |
| 149 | + allows users to add a URI to the list of URIs that get pinged on each | |
| 150 | + update. (See, for example, Options --> Writing --> Update Services in | |
| 151 | + WordPress, or Configuration --> Preferences --> Publicity / Remote | |
| 152 | + Interfaces / TrackBack in Movable Type.) | |
| 153 | + | |
| 154 | + If you can get a contributor to add your XML-RPC URI to her | |
| 155 | + services-to-ping list (if you have WordPress installed at | |
| 156 | + <http://www.zyx.com/blog>, say, the URI to add should be | |
| 157 | + <http://www.zyx.com/blog/xmlrpc.php>), then whenever she updates her | |
| 158 | + blog, her blogging software will ping your FeedWordPress installation, | |
| 159 | + and FeedWordPress will look up her feed to grab the new posts off of | |
| 160 | + it. | |
| 149 | 161 | |
| 150 | -To manually check for new posts, log in to the WordPress Dashboard and go to the | |
| 151 | -main page under **Syndication**. You can use the "Update feeds now" button to | |
| 152 | -check for new posts on feeds that are due for a scheduled update, or use the | |
| 153 | -checkboxes and "Update Checked Feeds" button to force FeedWordPress to check one | |
| 154 | -or more specific feeds for new posts. FeedWordPress will check the selected | |
| 155 | -feed or feeds for new posts, and import any new content available. | |
| 162 | +2. **The Scheduled Update Job Method:** You may very well not be able to | |
| 163 | + get all your contributors to add your site to their blogging software's | |
| 164 | + ping list, and even if you do you may want to have a back-up option to | |
| 165 | + catch updates later even if the ping fails to go through on one | |
| 166 | + particular occasion. You'll need to create a scheduled job to | |
| 167 | + periodically check for updates on *all* the feeds. You'll need either | |
| 168 | + (a) the ability to create cron jobs on your web host or (b) access to | |
| 169 | + another computer with a reliable, always-on Internet connection. | |
| 170 | + | |
| 171 | + If you *can* create a crontab on your web host, then the best thing to | |
| 172 | + do is to create a cron job that will run update-feeds.php through the | |
| 173 | + PHP command-line interface. For example, if you have WordPress installed | |
| 174 | + in `~/www/wp` (where ~ is your home directory), you might insert the | |
| 175 | + following line into your crontab: | |
| 176 | + | |
| 177 | + 25 * * * * cd $HOME/www/wp/wp-content ; php -q update-feeds.php | |
| 156 | 178 | |
| 157 | -##### Automatic Feed Updates ##### | |
| 179 | + If you *don't* have access to (a), you can still save the day using | |
| 180 | + another computer with always-on Internet access that sends a POST | |
| 181 | + request to the `update-feeds.php` URI on a regular schedule. So, for | |
| 182 | + example, if you have WordPress installed at <http://www.zyx.com/blog>, | |
| 183 | + and you have a dummy user in your WordPress database with the login name | |
| 184 | + 'login' and the password 'pass', then you could add the following line | |
| 185 | + to the crontab on a home Linux box: | |
| 186 | + | |
| 187 | + 25 * * * * curl --user login:pass http://www.zyx.com/blog/wp-content/update-feeds.php -d update=quiet | |
| 158 | 188 | |
| 159 | -If you choose an automatic update schedule, then FeedWordPress will | |
| 160 | -automatically check for new posts based on a schedule you determine. When | |
| 161 | -automatic updates are enabled, FeedWordPress will check for new posts when | |
| 162 | -(1) at least ten minutes have passed since the last update, and (2) a viewer | |
| 163 | -visits your FeedWordPress-enabled blog. (If you want the interval of time to | |
| 164 | -be shorter or longer, you can change the interval in the Dashboard under | |
| 165 | -**Syndication --> Options**.) | |
| 189 | + The `-d update=quiet` switch ensures that (1) `update-feeds.php` will | |
| 190 | + receive an HTTP POST request rather than an HTTP GET request (which | |
| 191 | + is important, since it won't take any actions with side-effects -- such | |
| 192 | + as checking for new posts -- unless it receives an HTTP POST); it also | |
| 193 | + tells it to suppress the HTML output that it would generate for normal | |
| 194 | + web browsers, and only to output text if it encounters errors (this will | |
| 195 | + keep the number of e-mails you receive from the Cron Daemon to a | |
| 196 | + minimum). | |
| 166 | 197 | |
| 167 | -Note that this is not quite the same thing as precisely scheduled updating. | |
| 168 | -If you get at least one viewer every ten minutes, then FeedWordPress will be | |
| 169 | -regularly checking for new posts on schedule; if not, not. But for a relatively | |
| 170 | -active aggregator blog this is probably close enough for government work. | |
| 198 | + If you are using Windows XP and have a version of curl (such as the | |
| 199 | + version included in [Cygwin][]), you can create a Scheduled Task to | |
| 200 | + similar effect. | |
| 171 | 201 | |
| 172 | -However, if you want to ensure regular updates, and you have access to a | |
| 173 | -task-scheduling tool such as `cron`, you can use it to schedule regular | |
| 174 | -checks for updates on a fixed schedule. For example, using `cron`, you can | |
| 175 | -easily ensure that FeedWordPress checks for new posts regularly by adding the | |
| 176 | -following line to your crontab, substituting the actual address of your | |
| 177 | -WordPress installation for "http://www.zyx.com/blog/": | |
| 202 | + [Cygwin]: http://www.cygwin.com/ | |
| 178 | 203 | |
| 179 | - */15 * * * * curl http://www.zyx.com/blog/ > /dev/null | |
| 180 | - | |
| 181 | -If you don't have direct access to `cron` or a similar scheduling tool, you | |
| 182 | -can use online tools such as [WebCron](http://www.webcron.org/?lang=en) to | |
| 183 | -schedule a regular fetch of your blog's front page to much the same effect. | |
| 184 | - | |
| 185 | -##### Feed Updates using XML-RPC ##### | |
| 186 | - | |
| 187 | -FeedWordPress also allows syndicated blogs to notify you of updates using the | |
| 188 | -XML-RPC "recently updated" pings (in the standard format accepted by | |
| 189 | -Weblogs.com, Ping-O-Matic, Technorati, and other blogging services). Most | |
| 190 | -blogging software allows users to add a URI to the list of URIs that get pinged | |
| 191 | -with each new update -- see, for example, **Options --> Writing --> Update | |
| 192 | -Services** in WordPress, or **Configuration --> Preferences --> Publicity / | |
| 193 | -Remote Interfaces / TrackBack** in Movable Type. If you can get a contributor | |
| 194 | -to add your XML-RPC URI to her list of update services to ping, then whenever | |
| 195 | -she updates her blog, her blogging software will notify your FeedWordPress | |
| 196 | -installation, and FeedWordPress will look up her feed to grab the new posts off | |
| 197 | -of it. (If you have WordPress installed at <http://www.zyx.com/blog>, say, the | |
| 198 | -URI for her to ping should be <http://www.zyx.com/blog/xmlrpc.php>). | |
| 199 | - | |
| 200 | 204 | Basic Concepts |
| 201 | 205 | -------------- |
| 202 | 206 | FeedWordPress is written as a plugin for the WordPress weblog software. It is |
| 203 | 207 | designed to store all the data it needs within the WordPress database and to |
| @@ -478,10 +482,10 @@ | ||
| 478 | 482 | For more information, see <http://projects.radgeek.com/feedwordpress/api>. |
| 479 | 483 | |
| 480 | 484 | License |
| 481 | 485 | ------- |
| 482 | -The FeedWordPress plugin is copyright (c) 2005-2007 by Charles Johnson. It uses | |
| 483 | -code derived or translated from: | |
| 486 | +The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code | |
| 487 | +derived or translated from: | |
| 484 | 488 | |
| 485 | 489 | - [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net) |
| 486 | 490 | - [MagpieRSS][] by [Kellan Elliot-McCrea](kellan@protest.net) |
| 487 | 491 | - [HTTP Navigator 2][] by [Keyvan Minoukadeh](keyvan@k1m.com) |
