README.text: 0.98 vs 0.95 · FeedWordPress

← All changes | README.text +309 -398 0.95 → 0.98 View file →

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