← All changes | README.text +174 -387 0.98 → 0.91 View file →

		@@ -1,427 +1,215 @@
1	1	FeedWordPress
2	2	=============
3	3
4		-* Author: [Charles Johnson](http://radgeek.com/contact)
5		-* Version: 0.98
	4	+* Author: [Charles Johnson](http://www.radgeek.com/contact)
	5	+* Version: 0.91
6	6	* Project URI: <http://projects.radgeek.com/feedwordpress>
7		-* License: GPL 2. See License below for copyright jots and tittles.
	7	+* License: GPL. See License below for copyright jots and tittles.
8	8
9	9	Introduction
10	10	------------
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][].
	11	+FeedWordPress is an Atom/RSS aggregator for WordPress. It syndicates content
	12	+from newsfeeds that you select into your WordPress blog; if you syndicate
	13	+several newsfeeds then you can WordPress's posts database and templating engine
	14	+as the back-end of an aggregation ("planet") website. I originally developed it
	15	+because I needed a more flexible replacement for [Planet][] to use at
	16	+[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 (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*.)
	22	+configuration in mind. You'll need a working installation of [WordPress 1.5][]
	23	+and FTP or SFTP access to your web host. The ability to create cron jobs on your
	24	+web host would be very helpful but it's not absolutely necessary. You *don't*
	25	+need to tweak any plain-text configuration files and you *don't* need shell
	26	+access to your web host to make it work. (Although, I should point out, web
	27	+hosts that *don't* offer shell access are *bad web hosts*.)
29	28
30		- [2.0]: http://wordpress.org/development/2005/12/wp2/
31		- [1.5]: http://wordpress.org/development/2005/02/strayhorn/
	29	+ [WordPress 1.5]: http://wordpress.org/development/2005/02/strayhorn/
32	30
33		-Installation
34		-### Requirements ###
	31	+Installation & Requirements
	32	+---------------------------
	33	+You'll need a website with WordPress 1.5 installed and configured and FTP or
	34	+SFTP access to your web space. You'll probably also want to have either (1)
	35	+the ability to create cron jobs on your web host, or (2) a computer of your
	36	+own that has always-on Internet access.
35	37
36		-To use version 0.98 of FeedWordPress, you will need:
37		-
38		-1. an installed configured copy of WordPress 2.0.x or 1.5.x. (FeedWordPress
39		- *will not work* with WP 1.2 or WP MU development builds.)
40		-
41		-2. FTP or SFTP access to your web host
42		-
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		-### Installation ###
50		-
51		-#### Upgrades ####
52		-
53		-To *upgrade* an existing installation of FeedWordPress to version 0.98:
54		-
55		-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.
60		-
61		-2. If you are upgrading from version 0.96 or earlier, **immediately** log
62		- in to the WordPress Dashboard, and go to Options --> Syndicated. Follow
63		- the directions to launch the database upgrade procedure. The new
64		- versions of FeedWordPress incorporate some long-needed improvements, but
65		- old meta-data needs to be updated to prevent duplicate posts and other
66		- possible maladies. If you're upgrading an existing installation, updates
67		- and FeedWordPress template functions *will not work* until you've done
68		- the upgrade.
69		-
70		-3. Take a coffee break while the upgrade runs. It should, hopefully, finish
71		- within a few minutes even on relatively large databases.
72		-
73		-4. `update-feeds.php` has been overhauled to improve performance and ease
74		- of use, and also to make errors easier to detect and eliminate. The
75		- overhaul doesn't require any changes to your set up *if* you used
76		- XML-RPC pings, or command-line PHP, to do scheduled updates. It *does*
77		- affect you if you used curl or some other tool to send HTTP requests to
78		- `update-feeds.php`: your old cron job will probably not work anymore.
79		- See [Setting Up Feed Updates][] below to get scheduled updates back on
80		- track.
81		-
82		-5. Enjoy your new installation of FeedWordPress.
83		-
84		-#### New Installations ####
85		-
86		-1. Install `feedwordpress.php` in your WordPress `plugins` directory
87		- and `update-feeds.php` in your WordPress `wp-content` directory.
	38	+1. Install `feedwordpress.php` in your WordPress `plugins` directory and
	39	+ `update.php` in your WordPress `wp-content` directory.
88	40
89	41	2. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by
90	42	installing the new `rss-functions.php` (archived in
91	43	`OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory.
92		- Upgrading MagpieRSS is necessary if you want to take advantage of
93		- support for Atom 1.0, multiple post categories, RSS enclosures, and
94		- multiple character encodings. (Note, however, that support for
95		- transliterating between character encodings is a very complex and
96		- iffy prospect in some PHP environments, so if you intend to use
97		- a lot of feeds with alternate encodings you should make sure that
98		- your installation of PHP is up-to-date and that you keep a copy of
99		- the old MagpieRSS around to compare results.)
100	44
101		-3. Log in to the WordPress Dashboard and activate the FeedWordPress
102		- plugin.
	45	+3. Log in to the WordPress Dashboard and activate the FeedWordPress plugin.
	46	+ Go to Options --> Syndication to set up initial settings for the
	47	+ syndication link category ("Contributors") by default and the RPC secret
	48	+ word (blank by default, but you should probably set it to something.)
103	49
104		-4. While you're at the Dashboard, once the plugin is activated, you can
105		- go to Options --> Syndication and set (1) the link category that
106		- FeedWordPress will syndicate links from (by default, "Contributors"),
107		- and (2) a "secret word" for your RPC-XML updating interface. This
108		- provides some light security by keeping passing ruffians from saying
109		- "Update all the feeds" at will to your FeedWordPress installation.
	50	+4. Set up links for syndication from the WordPress Dashboard using
	51	+ Links --> Syndicated or Links --> Import.
110	52
111		-5. Go to Links --> Syndicated to set up the list of sites that you want
112		- FeedWordPress to syndicate onto your blog. (If you have the feeds you
113		- want to aggregate in a service such as Bloglines, you may prefer to
114		- export them to an OPML file and use WordPress's Links --> Import to
115		- import them into the contributors category.)
	53	+5. FeedWordPress is now *ready* to feed syndicated content into WordPress.
	54	+ In order for it to actually receive that content, either (1) have your
	55	+ contributors add WordPress's XML-RPC URI to their blog's list of URIs
	56	+ to ping when they update posts, (2) set up a cron job to check in on all
	57	+ the feeds on a regular basis, or (3) both. If you do (2), you can either
	58	+ set up a job to run `php update-feeds.php` on your web host, or set one
	59	+ up on any computer with always-on Internet access to request
	60	+ `update-feeds.php` over the web.
	61	+
	62	+ If your copy of WordPress is installed at <http://www.zyx.com/blog>, and
	63	+ you set the secret word for XML-RPC pings to "foo", then your XML-RPC
	64	+ URI will be <http://www.zyx.com/blog/xmlrpc.php>, and the URI to request
	65	+ for `update-feeds.php` to update all feeds will be
	66	+ <http://www.zyx.com/blog/wp-content/update-feeds.php?shibboleth=foo>
116	67
117		-#### Setting Up Feed Updates ####
	68	+For detailed installation instructions, point your web browser to
	69	+<http://projects.radgeek.com/feedwordpress/install>.
118	70
119		-FeedWordPress is now ready to accept posts from its syndication sources.
120		-Unfortunately, it doesn't yet know *when* to go get them. (**This may be true
121		-even if you are upgrading an existing installation of FeedWordPress:** your old
122		-cron job will still work if you used command-line PHP or blogging software pings
123		-to do updates, but it will need to be fixed if you used curl or another tool to
124		-send HTTP requests to `update-feeds.php`.)
	71	+Feed Settings
	72	+-------------
125	73
126		-You can load in syndicated posts for the first time by pointing your web browser
127		-to `update-feeds.php`. If you have WordPress installed at, say,
128		-<http://www.zyx.com/blog> then you should point your browser to
129		-<http://www.zyx.com/blog/wp-content/update-feeds.php> and log in as any user in
130		-the user database. (You may want to create a new "dummy" user for doing
131		-scheduled updates, using **Users --> Authors & Users --> Add New User**. Tell
132		-FeedWordPress to update all feeds, and you'll get the first wave of posts
133		-imported into the database.
	74	+Once you have your links configured and regular feed updates scheduled, you can
	75	+mostly leave FeedWordPress to run on its own. If you need to add, remove, or
	76	+change information for any contributors, you can do so from the WordPress
	77	+Dashboard under Links --> Syndicated. If you want to distribute the labor of
	78	+adding, updating, and managing feeds, you can use the WordPress login and access
	79	+privileges system. Users with an access level of 5 or greater can add or modify
	80	+syndicated links, and change syndication options.
134	81
135		-Congratulations! You should now have an aggregator site full of delicious
136		-syndicated content hot off of the newswires. Now you just need a way to *keep*
137		-the content freshly updated. Unless you enjoy manually browsing to
138		-`update-feeds.php` every hour on the hour, you'll probably want to do this by
139		-setting up your site for automated updates.
	82	+All the information for a syndicated feed is managed through the WordPress Links
	83	+database. Feeds in the category to be syndicated (by default, "Contributors")
	84	+use several fields of the standard WordPress Link record:
140	85
141		-You can pull that off in one of two ways, or by a mixture of both:
142		-
143		-1. **The Blogging Software Ping Method:** You can get all of your
144		- contributors to add you to the list of URIs that they notify of updates:
145		- while FeedWordPress is activated, it will accept XML-RPC "recently
146		- updated" pings in the standard format accepted by Weblogs.com,
147		- Ping-O-Matic, Technorati, and other services. Most blogging software
148		- allows users to add a URI to the list of URIs that get pinged on each
149		- update. (See, for example, Options --> Writing --> Update Services in
150		- WordPress, or Configuration --> Preferences --> Publicity / Remote
151		- Interfaces / TrackBack in Movable Type.)
152		-
153		- If you can get a contributor to add your XML-RPC URI to her
154		- services-to-ping list (if you have WordPress installed at
155		- <http://www.zyx.com/blog>, say, the URI to add should be
156		- <http://www.zyx.com/blog/xmlrpc.php>), then whenever she updates her
157		- blog, her blogging software will ping your FeedWordPress installation,
158		- and FeedWordPress will look up her feed to grab the new posts off of
159		- it.
	86	+- The Link URI is used to store a URI to the front page (*not* the feed!)
	87	+ of the syndicated website.
160	88
161		-2. **The Scheduled Update Job Method:** You may very well not be able to
162		- get all your contributors to add your site to their blogging software's
163		- ping list, and even if you do you may want to have a back-up option to
164		- catch updates later even if the ping fails to go through on one
165		- particular occasion. You'll need to create a scheduled job to
166		- periodically check for updates on *all* the feeds. You'll need either
167		- (a) the ability to create cron jobs on your web host or (b) access to
168		- another computer with a reliable, always-on Internet connection.
	89	+- The Link Name is used to store the title of the syndicated website.
	90	+
	91	+- The Short Description is used to store the tagline of the syndicated
	92	+ website.
	93	+
	94	+- The RSS URI is used to store the URI for the feed to be syndicated.
169	95
170		- If you *can* create a crontab on your web host, then the best thing to
171		- do is to create a cron job that will run update-feeds.php through the
172		- PHP command-line interface. For example, if you have WordPress installed
173		- in `~/www/wp` (where ~ is your home directory), you might insert the
174		- following line into your crontab:
	96	+- The Link Notes are used to store a collection of manually-encoded and
	97	+ automatically-generated settings that apply to this feed. The format of
	98	+ settings in Link Notes is:
175	99
176		- 25 * * * * cd $HOME/www/wp/wp-content ; php -q update-feeds.php
177		-
178		- If you *don't* have access to (a), you can still save the day using
179		- another computer with always-on Internet access that sends a POST
180		- request to the `update-feeds.php` URI on a regular schedule. So, for
181		- example, if you have WordPress installed at <http://www.zyx.com/blog>,
182		- and you have a dummy user in your WordPress database with the login name
183		- 'login' and the password 'pass', then you could add the following line
184		- to the crontab on a home Linux box:
	100	+ key1: value1
	101	+ key2: value2
	102	+ key3: value3
	103	+ feed/key1: value1
	104	+ feed/key2: value2
185	105
186		- 25 * * * * curl --user login:pass http://www.zyx.com/blog/wp-content/update-feeds.php -d update=quiet
	106	+ And so on. Values that are prefixed by 'feed/' are automatically
	107	+ generated from feed data every time the feed syndicated by this link is
	108	+ checked for updates. Values without the prefix are set manually by the
	109	+ user.
187	110
188		- The `-d update=quiet` switch ensures that (1) `update-feeds.php` will
189		- receive an HTTP POST request rather than an HTTP GET request (which
190		- is important, since it won't take any actions with side-effects -- such
191		- as checking for new posts -- unless it receives an HTTP POST); it also
192		- tells it to suppress the HTML output that it would generate for normal
193		- web browsers, and only to output text if it encounters errors (this will
194		- keep the number of e-mails you receive from the Cron Daemon to a
195		- minimum).
	111	+Most settings in the Link Notes have no effect on FeedWordPress, but can be
	112	+accessed from templates using the ``get_feed_meta()`` template function in a
	113	+post context. For example, many aggregator sites use a "face" image for each
	114	+feed to visually distinguish posts from different feeds. To implement a face
	115	+feature, you could add a line like this to each feed's Link Notes section:
196	116
197		- If you are using Windows XP and have a version of curl (such as the
198		- version included in [Cygwin][]), you can create a Scheduled Task to
199		- similar effect.
	117	+ face: http://www.zyx.com/mugs/ugly
200	118
201		- [Cygwin]: http://www.cygwin.com/
	119	+The URI should be changed out for each feed to point to the appropriate image,
	120	+of course. Then, to use the setting from within a template:
202	121
203		-Basic Concepts
204		-FeedWordPress is written as a plugin for the WordPress weblog software. It is
205		-designed to store all the data it needs within the WordPress database and to
206		-make that data easy to manage from within the WordPress Dashboard.
	122	+ // In a post context
	123	+ <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
	124	+ <img src="<?=$img?>" alt="" />
	125	+ <?php endif; ?>
207	126
208		-### Contributors / Newsfeeds ###
209		-
210		-FeedWordPress uses the WordPress Links database to keep a list of the feeds from
211		-which it will syndicate content. WordPress allows you to place links in
212		-categories; FeedWordPress will make use of all and only the links in one
213		-category (by default, this is a category named "Contributors"; you can change
214		-the category that FeedWordPress will use using **Options --> Syndication**).
215		-
216		-From WordPress's perspective, the list of Contributors are normal links, and
217		-they can be manipulated like other links through the WordPress Dashboard.
218		-However, FeedWordPress provides a nicer interface for adding, removing, or
219		-changing information for the Contributor Links from the WordPress Dashboard,
220		-under **Links --> Syndicated**.
221		-
222		-If you want to distribute the labor of adding, updating, and managing feeds
223		-between several people, you can use the WordPress login andaccess privileges
224		-system. Any users with an access level of 5 or greater can add, delete, and
225		-modify Contributors; users with an access level of 6 or greater can change
226		-syndication options.
227		-
228		-When FeedWordPress looks for new posts, it retrieves one or all of the links
229		-from the Contributors category (depending on whether it has been told to scan
230		-for new posts on one or all of the feeds), determines which of them should be
231		-polled for updates (based on how long it has been since the last time each feed
232		-was polled for updates), and then uses an HTTP conditional GET to check for
233		-updates at the "RSS URI" for each Link that it selects. Any new posts are added
234		-to the database, and old posts that have been updated since the last poll are
235		-updated to reflect the new version.
236		-
237		-__Feed settings:__ All of the information for a syndicated feed is stored in the
238		-WordPress Links database, and can be easily edited using an interface that
239		-FeedWordPress provides under **Links --> Syndicated**. (If you're curious about
240		-the technical details of how the information is stored, you can find out more
241		-under [API: How feed information is stored][].)
242		-
243		-You can use a feed's **Edit** link under **Links --> Syndicated** to affect how
244		-FeedWordPress prcesses posts from that feed. (Most of these options can either
245		-be set for *one particular feed* using **Links --> Syndicated --> Edit**, or set
246		-as the default for *all feeds* using **Options --> Syndication**.) The **Edit**
247		-link also allows you to set **Custom Feed Settings** for use in templates,
248		-through the use of the [`get_feed_meta()`][get_feed_meta] template function in a
249		-post context (see [Template API][]). For example, many aggregator sites use a
250		-"face" image for each feed to visually distinguish posts from different feeds.
251		-To implement a face feature, you could add a custom setting for each Contributor
252		-Link, with the key of "face" and a URI such as "http://www.zyx.com/mugs/ugly"
253		-for the value. (The URI should be changed out for each feed to point to the
254		-appropriate image, of course.) Then, to use the setting from within a template,
255		-add something like:
256		-
257		- // In a post context
258		- <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
259		- <img src="<?=$img?>" alt="" />
260		- <?php endif; ?>
261		-
262	127	... which will display the image, if any, whose URI is set in the "face" setting
263	128	for the feed that post comes from. If there is no "face" setting for a
264		-particular feed, [`get_feed_meta()`][get_feed_meta] will return an empty string
265		-and no image will be displayed.
	129	+particular feed, ``get_feed_meta()`` will return an empty string and no image
	130	+will be displayed.
266	131
267		- [API: How feed information is stored]: http://projects.radgeek.com/feedwordpress/api#how-feed-information-is-stored
	132	+Not all feed settings are only for templates. Some affect how FeedWordPress
	133	+processes posts from that feed. Currently, the special settings are:
268	134
269		-### Syndicated Posts ###
	135	+- `cats:` a colon-separated list of default categories for any post coming
	136	+ from this feed. So, for example, a this line in its Notes section:
270	137
271		-Whenever FeedWordPress updates, it scans one or more of the feeds in its
272		-Contributors list and adds any new posts that it finds to the WordPress
273		-database. Syndicated posts are displayed on your WordPress pages like any other
274		-posts: they can be listed in archives by category, author, or date; they can be
275		-found with the search box; and they are included in the newsfeed of your blog.
	138	+ cats: computers:web
276	139
277		-In your WordPress templates (**Presentation --> Theme Editor**) you can access
278		-special information about syndicated posts using [functions provided by
279		-FeedWordPress][Template API], such as [`is_syndicated()`][is_syndicated],
280		-[`the_syndication_source()`][the_syndication_source],
281		-[`the_syndication_source_link()`][the_syndication_source_link], and
282		-[`get_feed_meta()`][get_feed_meta]. For example, here is the template code that
283		-I use (in a post context) to display both the author's name and the original
284		-source of the post in the templates for [Feminist Blogs][]:
	140	+ ... will make FeedWordPress place any posts syndicated from that feed in
	141	+ the "computers" and "web" categories (*in addition to*, not *instead of*
	142	+ any categories that are applied to the post in the feed)
285	143
286		- <cite class="feed">from <?php the_author_posts_link()?><?php
287		- if (is_syndicated() and (get_the_author() !== get_syndication_source())):
288		- echo ' @ <a href="'; the_syndication_source_link(); echo '">';
289		- the_syndication_source();
290		- echo '</a>';
291		- endif; ?></cite>
	144	+- `hardcode name: (yes|no)`
292	145
293		-For more information on template functions, see [Template API][].
	146	+ A yes/no setting. By default, FeedWordPress updates the value of the
	147	+ Link Name field automatically to reflect the title that is reported by a
	148	+ syndicated feed. (So, for example, if one of your contributors changes
	149	+ the title of her weblog, the change will be reflected on your
	150	+ Contributors list after the next update.) To manually set the Link Name
	151	+ and prevent your new name from being overridden by FeedWordPress (so as
	152	+ to, for example, use an abbreviated form of the site's title for reasons
	153	+ of space), change the Link Name to a title of your choosing and then add
	154	+ a line like this to the Link Notes section:
294	155
295		-### Categories ###
	156	+ hardcode name: yes
	157	+
	158	+ If `hardcode name` is absent, or set to a value other than `yes`,
	159	+ FeedWordPress will take that as a 'no' and follow the default behavior.
296	160
297		-WordPress allows for posts to be placed in *categories*. Each syndicated post
298		-that FeedWordPress adds to the WordPress database is placed into a set of
299		-categories. FeedWordPress gets the list of category names to use from two
300		-sources:
	161	+- `hardcode description: (yes|no)`
301	162
302		-1. Categories (or "tags") that the original author placed the post in on
303		- her blog
	163	+ A yes/no setting. By default, FeedWordPress updates the value of the
	164	+ Link Description field automatically to reflect the tagline or
	165	+ description that is reported by a syndicated feed. To manually set the
	166	+ Link Description and prevent your new description from being overridden
	167	+ by FeedWordPress (so as to, for example, use an abbreviated form of the
	168	+ site's tagline for reasons of space), change the Link Description to a
	169	+ title of your choosing and then add a line like this to the Link Notes
	170	+ section:
	171	+
	172	+ hardcode description: yes
	173	+
	174	+ If `hardcode description` is absent, or set to a value other than `yes`,
	175	+ FeedWordPress will take that as a 'no' and follow the default behavior.
304	176
305		-2. Categories that you set explicitly for each feed using the
306		- **Categories** checkbox under **Links --> Syndicated --> Edit**. For
307		- example, if you wanted all the posts from Alas, A Blog to be placed in
308		- the "Pacific Northwest" category and the "Cartoonists" category (*in
309		- addition to* any other categories that they were placed in on Alas, A
310		- Blog), you could do this by creating the categories, going to **Links
311		- --> Syndicated**, clicking the "Edit" link for Alas, A Blog, and
312		- checking those two categories under the checkbox captioned "Categories."
	177	+- `hardcode categories: (yes|no)`
313	178
314		-Given the list of category names, FeedWordPress looks for categories in the
315		-WordPress database with the same name as either (1) the category name, or
316		-(2) one of the "aliases" listed in the category description.
	179	+ A yes/no setting. FeedWordPress places each syndicated post in a set of
	180	+ categories within WordPress. It gets that list from two sources:
	181	+
	182	+ 1. Categories that you set explicitly for each feed (see the `cats` setting above)
	183	+
	184	+ 2. Categories that the original author placed the post in on her blog
	185	+
	186	+ If any of the categories on the list do not exist, they are created automatically.
	187	+
	188	+ If you want the posts from a particular feed to be placed *only* in the
	189	+ categories that you set manually (see the `cats` setting above), and not
	190	+ in the categories that they are in on the Contributor's blog, then add
	191	+ a line like this to the Link Notes section:
	192	+
	193	+ hardcode categories: yes
	194	+
	195	+ If `hardcode categories` is absent, or set to a value other than `yes`,
	196	+ FeedWordPress will take that as a 'no' and follow the default behavior.
317	197
318		-__Aliases:__ Different often authors use slightly different names for categories
319		-that mean the same thing (contributors to Feminist Blogs, for example, used
320		-categories including "Feminism", "feministy stuff", "Women's Issues", "Gender
321		-Issues", "Gender Equality", and so on). If you want FeedWordPress to treat one
322		-category name as a synonym for another, you can do so by creating an "alias" for
323		-the category. For example, to make FeedWordPress treat posts that are placed in
324		-the category "feministy stuff" as if they had been placed in the category
325		-"Feminism", go to **Manage --> Categories**, find the category "Feminism" and
326		-click the "Edit" link for it, and then add the following to the Description
327		-field, on a line by itself:
	198	+- `post status:` sets the default post status for posts from this feed
	199	+ This can be 'publish', 'draft', or 'private'. By default, it is set to
	200	+ 'publish' (syndicated posts go online immediately).
328	201
329		- a.k.a.: feministy stuff
	202	+- `comment status:` sets the default status for comments on posts
	203	+ syndicated from this feed. By default, all comments on syndicated posts
	204	+ are closed, but you can set it to 'open', 'closed', or 'registered_only'
	205	+ for particular feeds.
330	206
331		-You can add as many aliases as you like. You can also add any other text that
332		-you like to the Description without interfering with FeedWordPress's ability to
333		-use the aliases. Each alias must be on a line by itself.
	207	+- `ping status:` sets the default status for receiving TrackBack and
	208	+ PingBack pings on posts syndicated from this feed. By default,
	209	+ syndicated posts are closed to pings, but you can set this to 'open' or
	210	+ 'closed' for particular feeds.
334	211
335		-__Unfamiliar categories:__ If one of the category names that a newsfeed provides
336		-is *unfamiliar* -- that is, if there is not yet any category in your WordPress
337		-database that either has that name, or uses that name as an alias -- then by
338		-default FeedWordPress will *automatically create* a new category with that name
339		-and place the current post in it. The default behavior can be changed so that
340		-unfamiliar categories will *not* be added to the database, using the
341		-**Unfamiliar categories** setting, either for *all* feeds (under **Options -->
342		-Syndication**) or for *one particular feed* (under **Links --> Syndicated**).
343		-
344		-If you choose to disable the creation of new categories, either for all feeds or
345		-for one particular feed, then you can also choose whether or not FeedWordPress
346		-should syndicate posts that do not match *any* of the categories that are
347		-currently in the database. This allows you to do some simple filtering of posts
348		-by category: if you want to your blog to syndicate only the posts in one
349		-particular category from a feed that has several categories, you could do so by
350		-creating a category by that name, adding the new feed(s), and then setting
351		-**Unfamiliar categories** under **Links --> Syndicated --> Edit** to "don't
352		-create new categories and don't syndicate posts unless they match at least one
353		-familiar category".
354		-
355		-Since only posts in categories that are in your database will be included, and
356		-only the category or categories that you wanted posts from has been added to
357		-your database, this will filter out all the posts that aren't in the category or
358		-categories that you defined ahead of time. (Similarly, you could set up
359		-FeedWordPress so that *all* the feeds are filtered by author by creating the set
360		-of users named after the authors you want to syndicate, and then setting the
361		-default behavior for *all* feeds at **Options --> Syndication**).
362		-
363		-If you need a category filter with more complex logic, you can always create a
364		-`syndicated_item` filter in PHP (see [Plugin API][]) that manipulates the
365		-`['categories']` array of a syndicated item.
366		-
367		-### Authors ###
368		-
369		-Most newsfeeds include information about the author of the items on them.
370		-(If a feed doesn't, then FeedWordPress will create an author's name based on
371		-the title of the feed from which the item was taken.) This information is used
372		-to determine the WordPress user that the post will be attributed to. Given the
373		-name of the author, FeedWordPress looks for authors in the WordPress database
374		-with the same name as either (1) their login, (2) their display name, (3) their
375		-e-mail address (if given), or (4) one of the "aliases" listed in the
376		-user's profile.
377		-
378		-__Aliases:__ If there is an author who posts under more than one name (for
379		-example, one of our contributors at [Feminist Blogs][] posts on several
380		-different blogs, sometimes using her full name and sometimes using only her
381		-first name), then you can ensure that FeedWordPress will attribute those posts
382		-to the same author by creating "aliases" for the author. For example, to make
383		-FeedWordPress treat posts by "Joseph Cardinal Ratzinger" and posts by "Pope
384		-Benedict XVI" as having the same author, go to **Users --> Authors & Users**,
385		-click on the "Edit" link for Pope Benedict XVI, and add a line like this to the
386		-Profile text:
387		-
388		- a.k.a.: Joseph Cardinal Ratzinger
389		-
390		-You can add as many aliases as you like. You can also add any other text that
391		-you like to the Profile without interfering with FeedWordPress's ability to use
392		-the aliases. Each alias must be on a line by itself.
393		-
394		-__Unfamiliar authors:__ By default, if the author named by the newsfeed is
395		-unfamiliar -- that is, if there is no-one with that name registered in the
396		-WordPress author's database -- then by default FeedWordPress will automatically
397		-create a new user account with the given name and attribute the post to the new
398		-user. The default behavior can be changed, using either the global settings in
399		-**Options --> Syndication** or the [feed settings][] under **Links -->
400		-Syndicated --> Edit**, so that posts by unfamiliar authors will either be
401		-attributed to a default author (instead of creating a new user account to
402		-attribute them to), or filtered out and not syndicated at all.
403		-
404		-One of the uses of this feature is to filtering posts by author: if you want to
405		-your blog to syndicate only the posts by one particular author from a feed that
406		-has several authors, you could do so by creating a user account with that
407		-author's name, adding the new feed(s), and then setting **Unfamiliar authors**
408		-under **Links --> Syndicated --> Edit** to "don't syndicate the post". Since
409		-only posts by authors that are in your database will be included, and only the
410		-author that you wanted posts from has been added to your database, this will
411		-filter out posts by anyone else on the feeds with that setting. (Similarly, you
412		-could set up FeedWordPress so that *all* the feeds are filtered by author by
413		-creating the set of users named after the authors you want to syndicate, and
414		-then setting the default behavior for *all* feeds at **Options -->
415		-Syndication**).
416		-
417		-If you need an author filter with more complex logic than this allows, you can
418		-always create a `syndicated_item` filter in PHP (see [Plugin API][]) that
419		-manipulates the `['author_name']` or `['dc']['creator']` elements of a
420		-syndicated item.
421		-
422	212	Template API
423	213	------------
424	214	When activated, FeedWordPress makes the following functions available for use by
425	215	themes/templates:
		@@ -433,9 +221,9 @@
433	221	* ``get_syndication_permalink()``: in a post context, returns the URI of
434	222	the permalink for this post *on the website it was syndicated from*
435	223
436	224	* ``the_syndication_permalink()``: in a post context, outputs the value
437		- returned by [``get_syndication_permalink()``][get_syndication_permalink]
	225	+ returned by ``get_syndication_permalink()``
438	226
439	227	* ``get_syndication_source_link()``: in a post context, returns the URI of
440	228	the front page (*not* the feed) of the website this post was syndicated
441	229	from
		@@ -440,10 +228,9 @@
440	228	the front page (*not* the feed) of the website this post was syndicated
441	229	from
442	230
443	231	* ``the_syndication_source_link()``: in a post context, outputs the URI
444		- returned by
445		- [``get_syndication_source_link()``][get_syndication_source_link]
	232	+ returned by ``get_syndication_source_link()``
446	233
447	234	* ``get_syndication_source()``: in a post context, returns the
448	235	human-readable title of the website that a syndicated post was
449	236	syndicated from
		@@ -448,15 +235,15 @@
448	235	human-readable title of the website that a syndicated post was
449	236	syndicated from
450	237
451	238	* ``the_syndication_source()``: in a post context, outputs the value
452		- returned by [``get_syndication_source()``][get_syndication_source]
	239	+ returned by ``get_syndication_source()``
453	240
454	241	* ``get_syndication_feed():`` in a post context, returns the URI of the
455	242	feed (*not* the front page) that this post was syndicated from
456	243
457	244	* ``the_syndication_feed()``: in a post context, outputs the value
458		- returned by [``get_syndication_feed()``][get_syndication_feed]
	245	+ returned by ``get_syndication_feed()``
459	246
460	247	* ``get_feed_meta($key)``: in a post context, returns the value, if any,
461	248	of the feed setting ``$key`` for the feed that this post was syndicated
462	249	from
		@@ -462,25 +249,25 @@
462	249	from
463	250
464	251	By default, FeedWordPress also places a filter on the standard functions
465	252	``get_permalink()`` and ``the_permalink()`` that substitutes the URI returned by
466		-[``get_syndication_permalink()``][get_syndication_permalink] for the URI
467		-generated by WordPress. This means that by default the permalinks listed on your
468		-website and in your newsfeed will link to the location of the posts on the
469		-source website, *not* to their location on your website. You can switch this
470		-behavior on or off at **Options --> Syndication** in the WordPress Dashboard.
	253	+``get_syndication_permalink()`` for the URI generated by WordPress. This means
	254	+that by default the permalinks listed on your website and in your newsfeed will
	255	+link to the location of the posts on the source website, *not* to their location
	256	+on your website. You can switch this behavior on or off at Options -->
	257	+Syndication in the WordPress Dashboard.
471	258
472		-Plugin API
	259	+### Plugin API ###
	260	+
473	261	FeedWordPress creates five hooks through the WordPress plugin architecture that
474	262	you can plug in to using PHP WordPress plugins, to supplement ordinary
475	263	FeedWordPress behavior, or to filter posts according to criteria that you set.
476	264	The hooks are the action ``feedwordpress_update``, the action
477		-``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
	265	+``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
478	266	filter ``syndicated_item``, the filter ``syndicated_post``, the action
479	267	``post_syndicated_item``, and the action ``update_syndicated_item``.
480	268
481		-For more information, see <http://projects.radgeek.com/feedwordpress/api>.
	269	+For more information, see <http://projects.radgeek.com/feedwordpress/use>.
482	270
483	271	License
484	272	-------
485	273	The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code
		@@ -486,9 +273,8 @@
486	273	The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code
487	274	derived or translated from:
488	275
489	276	- [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net)
490		-- [MagpieRSS][] by [Kellan Elliot-McCrea](kellan@protest.net)
491	277	- [HTTP Navigator 2][] by [Keyvan Minoukadeh](keyvan@k1m.com)
492	278	- [Ultra-Liberal Feed Finder][] by [Mark Pilgrim](mark@diveintomark.org)
493	279
494	280	according to the terms of the [GNU General Public License][].
		@@ -493,11 +279,11 @@
493	279
494	280	according to the terms of the [GNU General Public License][].
495	281
496	282	This program is free software; you can redistribute it and/or modify it under
497		-the terms of the [GNU General Public License][] as published by the Free
498		-Software Foundation; either version 2 of the License, or (at your option) any
499		-later version.
	283	+the terms of the [GNU General Public License][] as published by the Free Software
	284	+Foundation; either version 2 of the License, or (at your option) any later
	285	+version.
500	286
501	287	This program is distributed in the hope that it will be useful, but WITHOUT ANY
502	288	WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
503	289	PARTICULAR PURPOSE. See the GNU General Public License for more details.
		@@ -502,10 +288,8 @@
502	288	WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
503	289	PARTICULAR PURPOSE. See the GNU General Public License for more details.
504	290
505	291	[wp-rss-aggregate.php]: http://laughingmeme.org/archives/002203.html
506		- [MagpieRSS]: http://magpierss.sourceforge.net/
507	292	[HTTP Navigator 2]: http://www.keyvan.net/2004/11/16/http-navigator/
508	293	[Ultra-Liberal Feed Finder]: http://diveintomark.org/projects/feed_finder/
509		-
510	294	[GNU General Public License]: http://www.gnu.org/copyleft/gpl.html
511	295