← All changes | README.text +124 -130 0.981 → 0.99 View file →

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