← All changes | README.text +393 -173 0.91 → 0.981 View file →

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