← All changes | README.text +403 -142 0.8 → 0.99 View file →

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