PluginProbe
FeedWordPress / 0.98
FeedWordPress v0.98
trunk 0.8 0.9 0.91 0.95 0.96 0.97 0.98 0.981 0.99 0.991 0.992 0.993 2008.1030 2008.1101 2008.1105 2008.1214 2009.0612 2009.0613 2009.0618 2009.0707 2009.1111 2009.1112 2010.0127 2010.0528 All 65 releases
← All changes | README.text +397 -143 0.9 → 0.98 View file →
@@ -1,179 +1,427 @@
1 1 FeedWordPress
2 2 =============
3 3
4 -* Author: [Charles Johnson](http://www.radgeek.com/contact)
5 -* Version: 0.9
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; 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
25 -helpful but it's not absolutely necessary. You *don't* need to tweak any
26 -plain-text configuration files and you *don't* need shell access to your web
27 -host to make it work. (Although, I should point out, web hosts that *don't*
28 -offer shell access are *bad web hosts*.)
21 +FeedWordPress is designed with flexibility, ease of use, and ease of
22 +configuration in mind. You'll need a working installation of WordPress (version
23 +[2.0][] or [1.5][]), and also FTP or SFTP access to your web host. The ability
24 +to create cron jobs on your web host would be very helpful but it's not
25 +absolutely necessary. You *don't* need to tweak any plain-text configuration
26 +files and you *don't* need shell access to your web host to make it work.
27 +(Although, I should point out, web hosts that *don't* offer shell access are
28 +*bad web hosts*.)
29 29
30 - [WordPress 1.5]: http://wordpress.org/development/2005/02/strayhorn/
31 - [Planet]: http://www.planetplanet.org/ "Planet Planet"
30 + [2.0]: http://wordpress.org/development/2005/12/wp2/
31 + [1.5]: http://wordpress.org/development/2005/02/strayhorn/
32 32
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.
33 +Installation
34 +------------
35 +### Requirements ###
38 36
39 -1. Install `feedwordpress.php` in your WordPress `plugins` directory and
40 - `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.
41 89
42 90 2. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by
43 91 installing the new `rss-functions.php` (archived in
44 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.)
45 101
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.)
102 +3. Log in to the WordPress Dashboard and activate the FeedWordPress
103 + plugin.
50 104
51 -4. Set up links for syndication from the WordPress Dashboard using
52 - 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.
53 111
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.
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.)
117 +
118 +#### Setting Up Feed Updates ####
119 +
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`.)
126 +
127 +You can load in syndicated posts for the first time by pointing your web browser
128 +to `update-feeds.php`. If you have WordPress installed at, say,
129 +<http://www.zyx.com/blog> then you should point your browser to
130 +<http://www.zyx.com/blog/wp-content/update-feeds.php> and log in as any user in
131 +the user database. (You may want to create a new "dummy" user for doing
132 +scheduled updates, using **Users --> Authors & Users --> Add New User**. Tell
133 +FeedWordPress to update all feeds, and you'll get the first wave of posts
134 +imported into the database.
135 +
136 +Congratulations! You should now have an aggregator site full of delicious
137 +syndicated content hot off of the newswires. Now you just need a way to *keep*
138 +the content freshly updated. Unless you enjoy manually browsing to
139 +`update-feeds.php` every hour on the hour, you'll probably want to do this by
140 +setting up your site for automated updates.
141 +
142 +You can pull that off in one of two ways, or by a mixture of both:
62 143
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>
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.
68 161
69 -For detailed installation instructions, point your web browser to
70 -<http://projects.radgeek.com/feedwordpress/install>.
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
71 178
72 -Feed Settings
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
73 188
74 -Once you have your links configured and regular feed updates scheduled, you can
75 -mostly leave FeedWordPress to run on its own. If you need to add, remove, or
76 -change information for any contributors, you can do so from the WordPress
77 -Dashboard under Links --> Syndicated. If you want to distribute the labor of
78 -adding, updating, and managing feeds, you can use the WordPress login and access
79 -privileges system. Users with an access level of 5 or greater can add or modify
80 -syndicated links, and change syndication options.
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).
81 197
82 -All the information for a syndicated feed is managed through the WordPress Links
83 -database. Feeds in the category to be syndicated (by default, "Contributors")
84 -use several fields of the standard WordPress Link record:
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.
85 201
86 -- The Link URI is used to store a URI to the front page (*not* the feed!)
87 - of the syndicated website.
202 + [Cygwin]: http://www.cygwin.com/
88 203
89 -- The Link Name is used to store the title of the syndicated website.
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.
90 209
91 -- The Short Description is used to store the tagline of the syndicated
92 - website.
210 +### Contributors / Newsfeeds ###
93 211
94 -- The RSS URI is used to store the URI for the feed to be syndicated.
95 -
96 -- The Link Notes are used to store a collection of manually-encoded and
97 - automatically-generated settings that apply to this feed. The format of
98 - settings in Link Notes is:
99 -
100 - key1: value1
101 - key2: value2
102 - key3: value3
103 - feed/key1: value1
104 - feed/key2: value2
105 -
106 - And so on. Values that are prefixed by 'feed/' are automatically
107 - generated from feed data every time the feed syndicated by this link is
108 - checked for updates. Values without the prefix are set manually by the
109 - user.
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**).
110 217
111 -Most settings in the Link Notes have no effect on FeedWordPress, but can be
112 -accessed from templates using the ``get_feed_meta()`` template function in a
113 -post context. For example, many aggregator sites use a "face" image for each
114 -feed to visually distinguish posts from different feeds. To implement a face
115 -feature, you could add a line like this to each feed's Link Notes section:
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**.
116 223
117 - face: http://www.zyx.com/mugs/ugly
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.
118 229
119 -The URI should be changed out for each feed to point to the appropriate image,
120 -of course. Then, to use the setting from within a template:
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.
121 238
122 - // In a post context
123 - <?php $img = get_feed_meta('face'); if strlen($img) > 0): ?>
124 - <img src="<?=$img?>" alt="" />
125 - <?php endif; ?>
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][].)
126 244
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:
258 +
259 + // In a post context
260 + <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
261 + <img src="<?=$img?>" alt="" />
262 + <?php endif; ?>
263 +
127 264 ... which will display the image, if any, whose URI is set in the "face" setting
128 265 for the feed that post comes from. If there is no "face" setting for a
129 -particular feed, ``get_feed_meta()`` will return an empty string and no image
130 -will be displayed.
266 +particular feed, [`get_feed_meta()`][get_feed_meta] will return an empty string
267 +and no image will be displayed.
131 268
132 -Not all feed settings are only for templates. Some affect how FeedWordPress
133 -processes posts from that feed. Currently, the special settings are:
269 + [API: How feed information is stored]: http://projects.radgeek.com/feedwordpress/api#how-feed-information-is-stored
134 270
135 -- `cats:` a colon-separated list of default categories for any post coming
136 - from this feed. So, for example, a this line in its Notes section:
271 +### Syndicated Posts ###
137 272
138 - cats: computers:web
273 +Whenever FeedWordPress updates, it scans one or more of the feeds in its
274 +Contributors list and adds any new posts that it finds to the WordPress
275 +database. Syndicated posts are displayed on your WordPress pages like any other
276 +posts: they can be listed in archives by category, author, or date; they can be
277 +found with the search box; and they are included in the newsfeed of your blog.
139 278
140 - ... will make FeedWordPress place any posts syndicated from that feed in
141 - the "computers" and "web" categories (*in addition to*, not *instead of*
142 - any categories that are applied to the post in the feed)
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][]:
143 287
144 -- `hardcode name: (yes|no)`
288 + <cite class="feed">from <?php the_author_posts_link()?><?php
289 + if (is_syndicated() and (get_the_author() !== get_syndication_source())):
290 + echo ' @ <a href="'; the_syndication_source_link(); echo '">';
291 + the_syndication_source();
292 + echo '</a>';
293 + endif; ?></cite>
145 294
146 - A yes/no setting. By default, FeedWordPress updates the value of the
147 - Link Name field automatically to reflect the title that is reported by a
148 - syndicated feed. (So, for example, if one of your contributors changes
149 - the title of her weblog, the change will be reflected on your
150 - Contributors list after the next update.) To override that behavior for
151 - a particular feed (e.g. to force WordPress to use an abbreviated form of
152 - the site's title for reasons of space), add a line like this to the Link
153 - Notes section:
295 +For more information on template functions, see [Template API][].
154 296
155 - hardcode name: yes
156 -
157 - If `hardcode name` is absent, or set to a value other than `yes`,
158 - FeedWordPress will take that as a 'no' and follow the default behavior.
297 +### Categories ###
159 298
160 -- `post status:` sets the default post status for posts from this feed
161 - This can be 'publish', 'draft', or 'private'. By default, it is set to
162 - 'publish' (syndicated posts go online immediately).
299 +WordPress allows for posts to be placed in *categories*. Each syndicated post
300 +that FeedWordPress adds to the WordPress database is placed into a set of
301 +categories. FeedWordPress gets the list of category names to use from two
302 +sources:
163 303
164 -- `comment status:` sets the default status for comments on posts
165 - syndicated from this feed. By default, all comments on syndicated posts
166 - are closed, but you can set it to 'open', 'closed', or 'registered_only'
167 - for particular feeds.
304 +1. Categories (or "tags") that the original author placed the post in on
305 + her blog
168 306
169 -- `ping status:` sets the default status for receiving TrackBack and
170 - PingBack pings on posts syndicated from this feed. By default,
171 - syndicated posts are closed to pings, but you can set this to 'open' or
172 - 'closed' for particular feeds.
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."
173 315
316 +Given the list of category names, FeedWordPress looks for categories in the
317 +WordPress database with the same name as either (1) the category name, or
318 +(2) one of the "aliases" listed in the category description.
319 +
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:
330 +
331 + a.k.a.: feministy stuff
332 +
333 +You can add as many aliases as you like. You can also add any other text that
334 +you like to the Description without interfering with FeedWordPress's ability to
335 +use the aliases. Each alias must be on a line by itself.
336 +
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
348 +should syndicate posts that do not match *any* of the categories that are
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".
356 +
357 +Since only posts in categories that are in your database will be included, and
358 +only the category or categories that you wanted posts from has been added to
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
361 +FeedWordPress so that *all* the feeds are filtered by author by creating the set
362 +of users named after the authors you want to syndicate, and then setting the
363 +default behavior for *all* feeds at **Options --> Syndication**).
364 +
365 +If you need a category filter with more complex logic, you can always create a
366 +`syndicated_item` filter in PHP (see [Plugin API][]) that manipulates the
367 +`['categories']` array of a syndicated item.
368 +
369 +### Authors ###
370 +
371 +Most newsfeeds include information about the author of the items on them.
372 +(If a feed doesn't, then FeedWordPress will create an author's name based on
373 +the title of the feed from which the item was taken.) This information is used
374 +to determine the WordPress user that the post will be attributed to. Given the
375 +name of the author, FeedWordPress looks for authors in the WordPress database
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
378 +user's profile.
379 +
380 +__Aliases:__ If there is an author who posts under more than one name (for
381 +example, one of our contributors at [Feminist Blogs][] posts on several
382 +different blogs, sometimes using her full name and sometimes using only her
383 +first name), then you can ensure that FeedWordPress will attribute those posts
384 +to the same author by creating "aliases" for the author. For example, to make
385 +FeedWordPress treat posts by "Joseph Cardinal Ratzinger" and posts by "Pope
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
388 +Profile text:
389 +
390 + a.k.a.: Joseph Cardinal Ratzinger
391 +
392 +You can add as many aliases as you like. You can also add any other text that
393 +you like to the Profile without interfering with FeedWordPress's ability to use
394 +the aliases. Each alias must be on a line by itself.
395 +
396 +__Unfamiliar authors:__ By default, if the author named by the newsfeed is
397 +unfamiliar -- that is, if there is no-one with that name registered in the
398 +WordPress author's database -- then by default FeedWordPress will automatically
399 +create a new user account with the given name and attribute the post to the new
400 +user. The default behavior can be changed, using either the global settings in
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.
405 +
406 +One of the uses of this feature is to filtering posts by author: if you want to
407 +your blog to syndicate only the posts by one particular author from a feed that
408 +has several authors, you could do so by creating a user account with that
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
413 +filter out posts by anyone else on the feeds with that setting. (Similarly, you
414 +could set up FeedWordPress so that *all* the feeds are filtered by author by
415 +creating the set of users named after the authors you want to syndicate, and
416 +then setting the default behavior for *all* feeds at **Options -->
417 +Syndication**).
418 +
419 +If you need an author filter with more complex logic than this allows, you can
420 +always create a `syndicated_item` filter in PHP (see [Plugin API][]) that
421 +manipulates the `['author_name']` or `['dc']['creator']` elements of a
422 +syndicated item.
423 +
174 424 Template API
175 425 ------------
176 426 When activated, FeedWordPress makes the following functions available for use by
177 427 themes/templates:
@@ -185,9 +433,9 @@
185 433 * ``get_syndication_permalink()``: in a post context, returns the URI of
186 434 the permalink for this post *on the website it was syndicated from*
187 435
188 436 * ``the_syndication_permalink()``: in a post context, outputs the value
189 - returned by ``get_syndication_permalink()``
437 + returned by [``get_syndication_permalink()``][get_syndication_permalink]
190 438
191 439 * ``get_syndication_source_link()``: in a post context, returns the URI of
192 440 the front page (*not* the feed) of the website this post was syndicated
193 441 from
@@ -192,9 +440,10 @@
192 440 the front page (*not* the feed) of the website this post was syndicated
193 441 from
194 442
195 443 * ``the_syndication_source_link()``: in a post context, outputs the URI
196 - returned by ``get_syndication_source_link()``
444 + returned by
445 + [``get_syndication_source_link()``][get_syndication_source_link]
197 446
198 447 * ``get_syndication_source()``: in a post context, returns the
199 448 human-readable title of the website that a syndicated post was
200 449 syndicated from
@@ -199,15 +448,15 @@
199 448 human-readable title of the website that a syndicated post was
200 449 syndicated from
201 450
202 451 * ``the_syndication_source()``: in a post context, outputs the value
203 - returned by ``get_syndication_source()``
452 + returned by [``get_syndication_source()``][get_syndication_source]
204 453
205 454 * ``get_syndication_feed():`` in a post context, returns the URI of the
206 455 feed (*not* the front page) that this post was syndicated from
207 456
208 457 * ``the_syndication_feed()``: in a post context, outputs the value
209 - returned by ``get_syndication_feed()``
458 + returned by [``get_syndication_feed()``][get_syndication_feed]
210 459
211 460 * ``get_feed_meta($key)``: in a post context, returns the value, if any,
212 461 of the feed setting ``$key`` for the feed that this post was syndicated
213 462 from
@@ -213,25 +462,25 @@
213 462 from
214 463
215 464 By default, FeedWordPress also places a filter on the standard functions
216 465 ``get_permalink()`` and ``the_permalink()`` that substitutes the URI returned by
217 -``get_syndication_permalink()`` for the URI generated by WordPress. This means
218 -that by default the permalinks listed on your website and in your newsfeed will
219 -link to the location of the posts on the source website, *not* to their location
220 -on your website. You can switch this behavior on or off at Options -->
221 -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.
222 471
223 -### Plugin API ###
224 -
472 +Plugin API
473 +----------
225 474 FeedWordPress creates five hooks through the WordPress plugin architecture that
226 475 you can plug in to using PHP WordPress plugins, to supplement ordinary
227 476 FeedWordPress behavior, or to filter posts according to criteria that you set.
228 477 The hooks are the action ``feedwordpress_update``, the action
229 -``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
478 +``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
230 479 filter ``syndicated_item``, the filter ``syndicated_post``, the action
231 480 ``post_syndicated_item``, and the action ``update_syndicated_item``.
232 481
233 -For more information, see <http://projects.radgeek.com/feedwordpress/use>.
482 +For more information, see <http://projects.radgeek.com/feedwordpress/api>.
234 483
235 484 License
236 485 -------
237 486 The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code
@@ -237,8 +486,9 @@
237 486 The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code
238 487 derived or translated from:
239 488
240 489 - [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net)
490 +- [MagpieRSS][] by [Kellan Elliot-McCrea](kellan@protest.net)
241 491 - [HTTP Navigator 2][] by [Keyvan Minoukadeh](keyvan@k1m.com)
242 492 - [Ultra-Liberal Feed Finder][] by [Mark Pilgrim](mark@diveintomark.org)
243 493
244 494 according to the terms of the [GNU General Public License][].
@@ -243,11 +493,11 @@
243 493
244 494 according to the terms of the [GNU General Public License][].
245 495
246 496 This program is free software; you can redistribute it and/or modify it under
247 -the terms of the [GNU General Public License][] as published by the Free Software
248 -Foundation; either version 2 of the License, or (at your option) any later
249 -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.
250 500
251 501 This program is distributed in the hope that it will be useful, but WITHOUT ANY
252 502 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
253 503 PARTICULAR PURPOSE. See the GNU General Public License for more details.
@@ -252,8 +502,10 @@
252 502 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
253 503 PARTICULAR PURPOSE. See the GNU General Public License for more details.
254 504
255 505 [wp-rss-aggregate.php]: http://laughingmeme.org/archives/002203.html
506 + [MagpieRSS]: http://magpierss.sourceforge.net/
256 507 [HTTP Navigator 2]: http://www.keyvan.net/2004/11/16/http-navigator/
257 508 [Ultra-Liberal Feed Finder]: http://diveintomark.org/projects/feed_finder/
509 +
258 510 [GNU General Public License]: http://www.gnu.org/copyleft/gpl.html
259 511