← All changes | README.text +142 -144 0.97 → 0.99 View file →

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