← All changes | README.text +125 -129 0.98 → 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.98
	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,48 +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.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*.)
	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.0]: http://wordpress.org/development/2005/12/wp2/
31		- [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
32	35
33	36	Installation
34	37	------------
35	38	### Requirements ###
36	39
37		-To use version 0.98 of FeedWordPress, you will need:
	40	+To use version 0.99 of FeedWordPress, you will need:
38	41
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.)
	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.)
41	45
42	46	2. FTP or SFTP access to your web host
43	47
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		-
50	48	### Installation ###
51	49
52	50	#### Upgrades ####
53	51
54		-To *upgrade* an existing installation of FeedWordPress to version 0.98:
	52	+To *upgrade* an existing installation of FeedWordPress to version 0.99:
55	53
56	54	1. Download the FeedWordPress archive in zip or gzipped tar format and
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.
	55	+ extract the files on your computer.
61	56
62		-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
63	72	in to the WordPress Dashboard, and go to Options --> Syndicated. Follow
64	73	the directions to launch the database upgrade procedure. The new
65	74	versions of FeedWordPress incorporate some long-needed improvements, but
66	75	old meta-data needs to be updated to prevent duplicate posts and other
		@@ -65,31 +74,34 @@
65	74	versions of FeedWordPress incorporate some long-needed improvements, but
66	75	old meta-data needs to be updated to prevent duplicate posts and other
67	76	possible maladies. If you're upgrading an existing installation, updates
68	77	and FeedWordPress template functions *will not work* until you've done
69		- 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.
70	81
71		-3. Take a coffee break while the upgrade runs. It should, hopefully, finish
72		- 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.
73	88
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		-
83	89	5. Enjoy your new installation of FeedWordPress.
84	90
85	91	#### New Installations ####
86	92
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
	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
92	104	`OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory.
93	105	Upgrading MagpieRSS is necessary if you want to take advantage of
94	106	support for Atom 1.0, multiple post categories, RSS enclosures, and
95	107	multiple character encodings. (Note, however, that support for
		@@ -98,110 +110,94 @@
98	110	a lot of feeds with alternate encodings you should make sure that
99	111	your installation of PHP is up-to-date and that you keep a copy of
100	112	the old MagpieRSS around to compare results.)
101	113
102		-3. Log in to the WordPress Dashboard and activate the FeedWordPress
	114	+4. Log in to the WordPress Dashboard and activate the FeedWordPress
103	115	plugin.
104	116
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
	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
107	119	FeedWordPress will syndicate links from (by default, "Contributors"),
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.
	120	+ and (2) whether FeedWordPress will use automatic updates or only
	121	+ manual updates.
111	122
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.)
	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.)
117	129
118	130	#### Setting Up Feed Updates ####
119	131
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`.)
	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.
126	134
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.
	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.
135	140
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.
	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.
141	147
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.
	148	+##### Manual Feed Updates #####
161	149
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
	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.
178	156
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
	157	+##### Automatic Feed Updates #####
188	158
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).
	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**.)
197	166
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.
	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.
201	171
202		- [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/":
203	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	+
204	200	Basic Concepts
205	201	--------------
206	202	FeedWordPress is written as a plugin for the WordPress weblog software. It is
207	203	designed to store all the data it needs within the WordPress database and to
		@@ -482,10 +478,10 @@
482	478	For more information, see <http://projects.radgeek.com/feedwordpress/api>.
483	479
484	480	License
485	481	-------
486		-The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code
487		-derived or translated from:
	482	+The FeedWordPress plugin is copyright (c) 2005-2007 by Charles Johnson. It uses
	483	+code derived or translated from:
488	484
489	485	- [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net)
490	486	- [MagpieRSS][] by [Kellan Elliot-McCrea](kellan@protest.net)
491	487	- [HTTP Navigator 2][] by [Keyvan Minoukadeh](keyvan@k1m.com)