feedwordpress / README.text

README.text in FeedWordPress 0.96, at README.text

696 lines 33.3 KB

Raw Download Zip

1	FeedWordPress
2	=============
3
4	* Author: [Charles Johnson](http://www.radgeek.com/contact)
5	* Version: 0.96
6	* Project URI: <http://projects.radgeek.com/feedwordpress>
7	* License: GPL. See License below for copyright jots and tittles.
8
9	Introduction
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
14	engine as the back-end of an aggregation ("planet") website. I originally
15	developed it because I needed a more flexible replacement for [Planet][] to
16	use at [Feminist Blogs][].
17
18	[Planet]: http://www.planetplanet.org/ "Planet Planet"
19	[Feminist Blogs]: http://www.feministblogs.org/
20
21	FeedWordPress is designed with flexibility, ease of use, and ease of
22	configuration in mind. You'll need a working installation of [WordPress
23	1.5][] and FTP or SFTP access to your web host. The ability to create cron
24	jobs on your web host would be very helpful but it's not absolutely
25	necessary. You don't need to tweak any plain-text configuration files and
26	you don't need shell access to your web host to make it work. (Although, I
27	should point out, web hosts that don't offer shell access are *bad web
28	hosts*.)
29
30	[WordPress 1.5]: http://wordpress.org/development/2005/02/strayhorn/
31
32	Installation & Requirements
33	---------------------------
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.
38
39	1. Install `feedwordpress.php` in your WordPress `plugins` directory
40	and `update.php` in your WordPress `wp-content` directory.
41
42	2. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by
43	installing the new `rss-functions.php` (archived in
44	`OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory.
45	Upgrading MagpieRSS is necessary if you want to take advantage of
46	support for multiple post categories, RSS enclosures, and multiple
47	character encodings. (Note, however, that support for
48	transliterating between character encodings is a very complex and
49	iffy prospect in some PHP environments, so if you intend to use
50	a lot of feeds with alternate encodings you should make sure that
51	your installation of PHP is up-to-date and that you keep a copy of
52	the old MagpieRSS around to compare results.)
53
54	3. Log in to the WordPress Dashboard and activate the FeedWordPress
55	plugin. Go to Options --> Syndication to set up initial settings for
56	the syndication link category ("Contributors") by default and the
57	RPC secret word (blank by default, but you should probably set it to
58	something.)
59
60	4. Set up links for syndication from the WordPress Dashboard using
61	Links --> Syndicated or Links --> Import.
62
63	5. FeedWordPress is now ready to feed syndicated content into
64	WordPress. In order for it to actually receive that content, either
65	(1) have your contributors add WordPress's XML-RPC URI to their
66	blog's list of URIs to ping when they update posts, (2) set up a
67	cron job to check in on all the feeds on a regular basis, or (3)
68	both. If you do (2), you can either set up a job to run `php
69	update-feeds.php` on your web host, or set one up on any computer
70	with always-on Internet access to request `update-feeds.php` over
71	the web.
72
73	If your copy of WordPress is installed at <http://www.zyx.com/blog>,
74	and you set the secret word for XML-RPC pings to "foo", then your
75	XML-RPC URI will be <http://www.zyx.com/blog/xmlrpc.php>, and the
76	URI to request for `update-feeds.php` to update all feeds will be
77	<http://www.zyx.com/blog/wp-content/update-feeds.php?shibboleth=foo>
78
79	For detailed installation instructions, point your web browser to
80	<http://projects.radgeek.com/feedwordpress/install>.
81
82	Basic Concepts
83	--------------
84	FeedWordPress is written as a plugin for [WordPress 1.5][]. It is designed
85	to store all the data it needs within the WordPress database and to make
86	that data easy to manage from within the WordPress Dashboard.
87
88	### Contributors / Newsfeeds ###
89
90	FeedWordPress uses the WordPress Links database to keep a list of the feeds
91	from which it will syndicate content. WordPress allows you to place links in
92	categories; FeedWordPress will treat all and only the links in one category
93	(by default, this is a category named "Contributors"; you can change the
94	category that FeedWordPress will use using Options --> Syndication).
95
96	From WordPress's perspective, the list of Contributors are normal links, and
97	they can be manipulated like other links through the WordPress Dashboard. If
98	you need to add, remove, or change information for any contributors, you can
99	do so easily under Links --> Syndicated. If you want to distribute the labor
100	of adding, updating, and managing feeds, you can use the WordPress login and
101	access privileges system. Users with an access level of 5 or greater can
102	add, delete, and modify Contributors; users with an access level of 6 or
103	greater can change syndication options.
104
105	When FeedWordPress looks for new posts, it does so by retrieving one or all
106	of the links from the Contributors category (depending on whether it has
107	been told to scan for new posts on one or all of the feeds).
108
109	__Feed settings:__ All of the information for a syndicated feed is stored in
110	the WordPress Links database. Feeds in the category to be syndicated (by
111	default, "Contributors") use several fields of the standard WordPress Link
112	record:
113
114	- The RSS URI is used to store the URI for the feed to be syndicated.
115	(Note that this is not the same as the Link URI. The Link URI
116	points to the human-readable front page of the website that the
117	feed syndicates.)
118
119	- The Link URI is used to store a URI to the human-readable front page
120	(not the feed!) of the syndicated website. FeedWordPress
121	automatically updates this URI using the URI that is reported by the
122	newsfeed whenever it checks the feed for new posts, so if the page
123	moves this will be reflected automatically on your Contributors
124	links list.
125
126	- The Link Name is used to store the title of the syndicated website.
127	By default, FeedWordPress automatically updates the name of the link
128	whenever it checks for new posts, using the title that the
129	newsfeed reports (so that if a Contributor changes the title of her
130	website, this is reflected automatically on your Contributors links
131	list). This behavior can be turned off for all feeds through the
132	settings in Options --> Syndication. The default behavior can be
133	overridden for specific feeds using the feed setting
134	`hardcode name`.
135
136	- The Short Description is used to store the tagline of the syndicated
137	website. By default, FeedWordPress automatically updates the
138	description whenever it checks for new posts, using the tagline or
139	description that the newsfeed reports (so that if a Contributor
140	changes the tagline of her website, this is reflected automatically
141	on your Contributors links list). his behavior can be turned off for
142	all feeds through the settings in Options --> Syndication. The
143	default behavior can be overridden for specific feeds using the feed
144	setting `hardcode description`.
145
146	- The Link Notes are used to store a collection of manually-encoded
147	and automatically-generated settings that apply to this feed. The
148	format of settings in Link Notes is:
149
150	key1: value1
151	key2: value2
152	feed/key1: value1
153	feed/key2: value2
154
155	And so on. Values that are prefixed by 'feed/' are automatically
156	generated from feed data every time the feed syndicated by this link
157	is checked for updates. Values without the prefix are set manually
158	by the user.
159
160	The Link Notes section can be used to add, remove, and change custom feed
161	settings. For example, if you want to add the feed setting for `unfamiliar
162	author` with the value `filter`, you can do so by going to Links -->
163	Syndicated, clicking the "Edit" link for the feed that you wish to add this
164	setting for, and then adding the following, on a line by itself, to the Link
165	Notes section:
166
167	unfamiliar author: filter
168
169	To remove the setting, follow the same procedure, but find the line for the
170	feed setting that you want to remove and remove it. To change the value,
171	simply change the text that follows after the colon.
172
173	Most settings in the Link Notes have no effect on FeedWordPress, but you can
174	use them to store information for templates to retrieve using the
175	`get_feed_meta()` template function in a post context (see Template API
176	below). For example, many aggregator sites use a "face" image for each feed
177	to visually distinguish posts from different feeds. To implement a face
178	feature, you could add something like this to each feed's Link Notes, on a
179	line by itself:
180
181	face: http://www.zyx.com/mugs/ugly
182
183	The URI should be changed out for each feed to point to the appropriate
184	image, of course. Then, to use the setting from within a template:
185
186	// In a post context
187	<?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
188	<img src="<?=$img?>" alt="" />
189	<?php endif; ?>
190
191	... which will display the image, if any, whose URI is set in the "face"
192	setting for the feed that post comes from. If there is no "face" setting for
193	a particular feed, ``get_feed_meta()`` will return an empty string and no
194	image will be displayed.
195
196	Not all feed settings are only for templates. Some affect how FeedWordPress
197	processes posts from that feed. Currently, the settings with special effects
198	on FeedWordPress are `cats`, `hardcode name`, `hardcode description`,
199	`hardcode categories`, `post status`, `comment status`, `ping status`,
200	`unfamiliar author`, and `unfamiliar categories`. For descriptions of their
201	effects, see Special Feed Settings below.
202
203	### Syndicated Posts ###
204
205	Whenever FeedWordPress updates, it scans one or more of the feeds in its
206	Contributors list and adds any new posts that it finds to the WordPress
207	database. Syndicated posts are displayed on your WordPress pages like any
208	other posts: they can be listed in archives by category, author, or date;
209	they can be found with the search box; and they are included in the newsfeed
210	of your blog.
211
212	In your WordPress templates (Presentation --> Theme Editor) you can access
213	special information about syndicated posts using functions provided by
214	FeedWordPress, such as `is_syndicated()`, `the_syndication_source()`,
215	`the_syndication_source_link()`, and `get_feed_meta()`. For example, here is
216	the template code that I use (in a post context) to display both the
217	author's name and the original source of the post in the templates for
218	[Feminist Blogs][]:
219
220	<cite class="feed">from <?php the_author_posts_link()?><?php
221	if (is_syndicated() and (get_the_author() !== get_syndication_source())):
222	echo ' @ <a href="'; the_syndication_source_link(); echo '">';
223	the_syndication_source();
224	echo '</a>';
225	endif; ?></cite>
226
227	For more information on template functions, see Template API below.
228
229	### Categories ###
230
231	WordPress allows for posts to be placed in categories. Each syndicated
232	post that FeedWordPress adds to the WordPress database is placed into a set
233	of categories. FeedWordPress gets the list of category names to use from two
234	sources:
235
236	1. Categories (or "tags") that the original author placed the post in
237	on her blog
238
239	2. Categories that you set explicitly for each feed using the `cats`
240	feed setting. For example, if you wanted all the posts from Alas, A
241	Blog to be placed in the "Pacific Northwest" category and the
242	"Cartoonists" category (in addition to any categories that they were
243	placed in on Alas, A Blog), you could do this by going to Links -->
244	Syndicated, clicking the "Edit" link for Alas, A Blog, and adding
245	the following line to the Link Notes section:
246
247	cats: Pacific Northwest:Cartoonists
248
249	(The colon separates one category name from the next.)
250
251	Given the list of category names, FeedWordPress looks for categories in the
252	WordPress database with the same name as either (1) the category name, or
253	(2) one of the "aliases" listed in the category description.
254
255	__Aliases:__ Different often authors use slightly different names for
256	categories that mean the same thing (contributors to Feminist Blogs, for
257	example, used categories including "Feminism", "feministy stuff", "Women's
258	Issues", "Gender Issues", "Gender Equality", and so on). If you want
259	FeedWordPress to treat one category name as a synonym for another, you can
260	do so by creating an "alias" for the category. For example, to make
261	FeedWordPress treat posts that are placed in the category "feministy stuff"
262	as if they had been placed in the category "Feminism", go to Manage -->
263	Categories, find the category "Feminism" and click the "Edit" link for it,
264	and then add the following to the Description field, on a line by itself:
265
266	a.k.a.: feministy stuff
267
268	You can add as many aliases as you like. You can also add any other text
269	that you like to the Description without interfering with FeedWordPress's
270	ability to use the aliases. Each alias must be on a line by itself.
271
272	__Unfamiliar categories:__ By default, if one of the category names that a
273	newsfeed provides is unfamiliar -- that is, if there is not yet any category
274	with that name (or with that name as an alias) in your WordPress database --
275	then by default FeedWordPress will automatically create a new category
276	with that name and place the current post in it. The default behavior can be
277	changed, using either the global settings in Options --> Syndication or the
278	`unfamiliar categories` feed setting (see Feed Settings above), so that
279	unfamiliar categories will not be added to the database. If you choose to
280	disable the creation of new categories, you can also choose whether or not
281	FeedWordPress should syndicate posts that do not match any of the
282	categories that are currently in the database.
283
284	One of the uses of this feature is filtering posts by category: if you want
285	to your blog to syndicate only the posts in one particular category from a
286	feed that has several categories, you could do so by creating a category by
287	that name, adding the new feed(s), and then adding the following line to the
288	Link Notes section of the feed(s) that you want to filter:
289
290	unfamiliar categories: filter
291
292	Since only posts in categories that are in your database will be included,
293	and only the category or categories that you wanted posts from has been
294	added to your database, this will filter out all the posts that aren't in
295	the category or categories that you defined ahead of time. (Similarly, you
296	could set up FeedWordPress so that all the feeds are filtered by author by
297	creating the set of users named after the authors you want to syndicate, and
298	then setting the default behavior for all feeds at Options -->
299	Syndication).
300
301	If you need a category filter with more complex logic, you can always create
302	a `syndicated_item` filter in PHP (see Plugin API below) that manipulates
303	the `['categories']` array of a syndicated item.
304
305	### Authors ###
306
307	Most newsfeeds include information about the author of the items on them.
308	(If a feed doesn't, then FeedWordPress will create an author's name based on
309	the title of the feed from which the item was taken.) This information is
310	used to determine the WordPress user that the post will be attributed to.
311	Given the name of the author, FeedWordPress looks for authors in the
312	WordPress database with the same name as either (1) their login, (2) their
313	first name, (3) their nickname, (4) their full name, or (5) one of the
314	"aliases" listed in the user's profile.
315
316	__Aliases:__ If there is an author who posts under more than one name (for
317	example, one of our contributors at [Feminist Blogs][] posts on several
318	different blogs, sometimes using her full name and sometimes using only her
319	first name), then you can ensure that FeedWordPress will attribute those
320	posts to the same author by creating "aliases" for the author. For example,
321	to make FeedWordPress treat posts by "Joseph Cardinal Ratzinger" and posts
322	by "Pope Benedict XVI" as having the same author, go to Users --> Authors &
323	Users, click on the "Edit" link for Pope Benedict XVI, and add a line like
324	this to the Profile text:
325
326	a.k.a.: Joseph Cardinal Ratzinger
327
328	You can add as many aliases as you like. You can also add any other text
329	that you like to the Profile without interfering with FeedWordPress's
330	ability to use the aliases. Each alias must be on a line by itself.
331
332	__Unfamiliar authors:__ By default, if the author named by the newsfeed is
333	unfamiliar -- that is, if there is no-one with that name registered in the
334	WordPress author's database -- then by default FeedWordPress will
335	automatically create a new user account with the given name and attribute
336	the post to the new user. The default behavior can be changed, using either
337	the global settings in Options --> Syndication or the `unfamiliar author`
338	feed setting (see Feed Settings above), so that posts by unfamiliar authors
339	will either be attributed to a default author (instead of creating a new
340	user account to attribute them to), or filtered out and not syndicated at
341	all.
342
343	One of the uses of this feature is filtering posts by author: if you want to
344	your blog to syndicate only the posts by one particular author from a feed
345	that has several authors, you could do so by creating a user account with
346	that author's name, adding the new feed(s), and then adding the following
347	line to the Link Notes section of the feed(s) that you want to filter:
348
349	unfamiliar author: filter
350
351	Since only posts by authors that are in your database will be included, and
352	only the author that you wanted posts from has been added to your database,
353	this will filter out posts by anyone else on the feeds with that setting.
354	(Similarly, you could set up FeedWordPress so that all the feeds are
355	filtered by author by creating the set of users named after the authors you
356	want to syndicate, and then setting the default behavior for all feeds at
357	Options --> Syndication).
358
359	If you need an author filter with more complex logic than this allows, you
360	can always create a `syndicated_item` filter in PHP (see Plugin API below)
361	that manipulates the `['author_name']` or `['dc']['creator']` elements of a
362	syndicated item.
363
364	Special Feed Settings
365	---------------------
366	Most feed settings (see Feed Settings above) have no effect on FeedWordPress
367	itself, but can be useful because they can be accessed from templates using
368	the `get_feed_meta()` template function in a post context (see Feed Settings
369	above for an example). However, you can use some feed settings to affect how
370	FeedWordPress will process posts from that particular feed. Currently, these
371	special settings are:
372
373	- `cats:` a colon-separated list of default categories for any post
374	coming from this feed. So, for example, a this line in its Notes
375	section:
376
377	cats: computers:web
378
379	... will make FeedWordPress place any posts syndicated from that
380	feed in the "computers" and "web" categories. Note that by default,
381	FeedWordPress will place them in those categories in addition to
382	any categories that the author of the post put them in on her own
383	website. If you want to place posts from a feed only in the
384	categories you explicitly set, then you should use the `cats`
385	setting together with the `unfamiliar categories` setting. (See
386	Categories above and `unfamiliar categories` below for the
387	nitty-gritty.)
388
389	- `hardcode name: (yes\|no)`
390
391	By default, FeedWordPress updates the value of the Link Name field
392	automatically to reflect the title that is reported by a syndicated
393	feed--so that if one of your contributors changes the title of her
394	website, the change will be reflected on your Contributors list
395	after the next update. If you want to stop this behavior (so that
396	you can set the title of a Contributor link manually -- e.g. so that
397	you can use an abbreviated form for reasons of space), you can
398	change the default behavior for all feeds using the settings in
399	Options --> Syndication. If you want to override the default
400	behavior for only one feed, you can use the `hardcode name` feed
401	setting. If FeedWordPress updates the title of all feeds by default,
402	but you wish to use a manually-set title for one particular feed,
403	you can add a line like this to the Link Notes section of the feed
404	that you want to manually set the title for:
405
406	hardcode name: yes
407
408	Similarly, if FeedWordPress uses your manually-entered titles for
409	all feeds by default, but you wish to use an automatically updated
410	title for one particular feed, you can add a line like this to the
411	Link Notes section of the feed that you want to manually set the
412	title for:
413
414	hardcode name: no
415
416	If `hardcode name` is absent, or set to a value other than `yes` or
417	`no`, FeedWordPress will follow the default behavior set under
418	Options --> Syndication.
419
420	- `hardcode description: (yes\|no)`
421
422	By default, FeedWordPress updates the value of the Link Description
423	field automatically to reflect the tagline or description that is
424	reported by a syndicated feed--so that if one of your contributors
425	changes the tagline for her website, the change will be reflected on
426	your Contributors list after the next update. If you want to stop
427	this behavior (so that you can set the tagline of a Contributor link
428	manually -- e.g. so that you can use it to provide information of
429	another sort or use an abbreviated form for reasons of space), you
430	can change the default behavior for all feeds using the settings
431	in Options --> Syndication. If you want to override the default
432	behavior for only one feed, you can use the `hardcode description`
433	feed setting. If FeedWordPress updates the description of all feeds
434	by default, but you wish to use a manually-set description for one
435	particular feed, you can add a line like this to the Link Notes
436	section of that particular feed:
437
438	hardcode description: yes
439
440	Similarly, if FeedWordPress uses your manually-entered descriptions
441	for all feeds by default, but you wish to use an automatically
442	updated description for one particular feed, you can add a line like
443	this to the Link Notes section of that particular feed:
444
445	hardcode description: no
446
447	If `hardcode description` is absent, or set to a value other than
448	`yes` or `no`, FeedWordPress will follow the default behavior set
449	under Options --> Syndication.
450
451	- `hardcode url: (yes\|no)`
452
453	By default, FeedWordPress updates the value of the Link URI field
454	automatically to reflect the link to the front page of the website
455	you are syndicating, as reported by the syndicated feed--so that if
456	one of your contributors changes the front page of her website (from
457	<http://www.zyx.com/blog/> to <http://www.zyx.com/>, say), the
458	change will be reflected on your Contributors list after the next
459	update. If you want to stop this behavior (so that you can set the
460	human-readable URI that a Contributor link points to manually), you
461	can change the default behavior for all feeds using the settings
462	in Options --> Syndication. If you want to override the default
463	behavior for only one feed, you can use the `hardcode url` feed
464	setting. If FeedWordPress updates the human-readable URI of all
465	feeds by default, but you wish to use a manually-set URI for one
466	particular feed, you can add a line like this to the Link Notes
467	section of that particular feed:
468
469	hardcode url: yes
470
471	Similarly, if FeedWordPress uses your manually-entered URIs for all
472	feeds by default, but you wish to use an automatically updated URI
473	for one particular feed, you can add a line like this to the Link
474	Notes section of that particular feed:
475
476	hardcode url: no
477
478	If `hardcode url` is absent, or set to a value other than `yes` or
479	`no`, FeedWordPress will follow the default behavior set under
480	Options --> Syndication.
481
482	- `hardcode categories: (yes\|no)`
483
484	This setting has been deprecated. If set to `yes` it is now
485	treated as equivalent to `unfamiliar categories: default`. (See
486	below.)
487
488	- `post status: (publish\|draft\|private)`
489
490	By default, FeedWordPress sets all new syndicated posts to be
491	published immediately. If you want syndicated posts to have some
492	other status (for example, to hold them as drafts for moderation, or
493	to hold them as private posts), you can change the default behavior
494	using Options --> Syndication. If you want to override the default
495	post status for syndicated posts from one particular feed, you
496	can do so using the `post status` feed setting. So, for example, if
497	you have FeedWordPress set to publish new syndicated posts
498	immediately, but you want posts from one particular feed to be put
499	into the drafts pile for moderation, you can do so by placing the
500	following line in the Link Notes section of that feed's Contributor
501	link:
502
503	post status: draft
504
505	- `comment status: (open\|closed)`
506
507	By default, FeedWordPress sets all new syndicated posts to be
508	closed for comments--if users want to comment on posts then it's
509	often best for them to comment on the original website rather than
510	your syndication site. But if you want syndicated posts to be open
511	for comments, you can change the default behavior for all syndicated
512	posts using the settings in Options --> Syndication. If you want to
513	override the default comment status for one particular feed, you
514	can do so using the `comment status` feed setting. So, for example,
515	if you have FeedWordPress set not to open up new syndicated posts
516	for comments, but you want posts from one particular feed to be
517	opened for comments, then you can do so by placing the following
518	line in the Link Notes section of that feed's Contributor link:
519
520	comment status: open
521
522	- `ping status: (open\|closed)`
523
524	By default, FeedWordPress sets all new syndicated posts not to
525	accept PingBack or TrackBack link notifications ("pings"). If you
526	want syndicated posts on your syndication site to accept pings, you
527	can change the default behavior for all syndicated posts using the
528	settings in Options --> Syndication. If you want to override the
529	default ping status for one particular feed, you can do so using
530	the `ping status` feed setting. So, for example, if you have
531	FeedWordPress set not to accept pings for new syndicated posts, but
532	you want posts from one particular feed to accept pings, then you
533	can do so by placing the following line in the Link Notes section of
534	that feed's Contributor link:
535
536	ping status: open
537
538	- `unfamiliar authors: (create\|default\|filter)`
539
540	By default, FeedWordPress creates new author accounts whenever it
541	finds a new post that is by an author whose name is not already in
542	the WordPress database, and uses that account for this post and any
543	future posts by an author of that name. FeedWordPress also allows
544	you to attribute posts by unfamiliar authors to a default user
545	account (currently, this means the System Administrator account),
546	instead of creating a new author, or simply not to syndicate posts
547	by unfamiliar authors (thus only syndicating posts by authors who
548	are already in the database).
549
550	Which of these FeedWordPress does by default can be set using the
551	settings in Options --> Syndication. You can also override the
552	default behavior for specific feeds by adding the `unfamiliar
553	author` feed setting to the Link Notes section of a feed. For
554	example, to ensure that FeedWordPress filters out posts by
555	unfamiliar authors for one particular feed, add the setting:
556
557	unfamiliar author: filter
558
559	To ensure that FeedWordPress assigns posts by unfamiliar authors to
560	the default user account instead of creating a new user account, add
561	the setting:
562
563	unfamiliar author: default
564
565	If you changed the default behavior under Options --> Syndication
566	but want to ensure that FeedWordPress creates new author accounts
567	for unfamiliar authors on one specific feed, add the setting:
568
569	unfamiliar author: create
570
571	If the setting is anything other than `create`, `default`, or
572	`filter`, FeedWordPress will ignore the setting and follow the
573	default behavior that you specified under Options --> Syndication.
574
575	- `unfamiliar categories: (create\|default\|filter)`
576
577	By default, FeedWordPress creates categories whenever it finds a new
578	post that is placed in categories whose names are not already in the
579	WordPress database. FeedWordPress allows you to change this
580	behavior, so that it will not create new category names. It also
581	allows you to choose whether or not posts must match at least one
582	familiar category to be syndicated at all.
583
584	Which of these FeedWordPress does by default can be set using the
585	settings in Options --> Syndication. You can also override the
586	default behavior for specific feeds by adding the `unfamiliar
587	categories` feed setting to the Link Notes section of a feed. For
588	example, to ensure that, when adding new posts from *one particular
589	feed, FeedWordPress does not* create new categories, and filters
590	out any posts that don't match at least one of the categories that
591	you have already defined, add the setting:
592
593	unfamiliar categories: filter
594
595	To ensure that FeedWordPress does not create new categories, but
596	will still syndicate categories even if they don't match any of
597	the pre-defined categories, add the following to the feed settings:
598
599	unfamiliar categories: default
600
601	If you changed the default behavior under Options --> Syndication
602	but want to ensure that FeedWordPress creates new categories for
603	posts from one particular feed, add the setting:
604
605	unfamiliar categories: create
606
607	If the setting is anything other than `create`, `default`, or
608	`filter`, FeedWordPress will ignore the setting and follow the
609	default behavior that you specified under Options --> Syndication.
610
611	Template API
612	------------
613	When activated, FeedWordPress makes the following functions available for
614	use by themes/templates:
615
616	* ``is_syndicated()``: in a post context, returns ``TRUE`` if the post
617	was syndicated from another website, or ``FALSE`` if it was
618	originally posted here
619
620	* ``get_syndication_permalink()``: in a post context, returns the URI
621	of the permalink for this post on the website it was syndicated from
622
623	* ``the_syndication_permalink()``: in a post context, outputs the
624	value returned by ``get_syndication_permalink()``
625
626	* ``get_syndication_source_link()``: in a post context, returns the
627	URI of the front page (not the feed) of the website this post was
628	syndicated from
629
630	* ``the_syndication_source_link()``: in a post context, outputs the
631	URI returned by ``get_syndication_source_link()``
632
633	* ``get_syndication_source()``: in a post context, returns the
634	human-readable title of the website that a syndicated post was
635	syndicated from
636
637	* ``the_syndication_source()``: in a post context, outputs the value
638	returned by ``get_syndication_source()``
639
640	* ``get_syndication_feed():`` in a post context, returns the URI of
641	the feed (not the front page) that this post was syndicated from
642
643	* ``the_syndication_feed()``: in a post context, outputs the value
644	returned by ``get_syndication_feed()``
645
646	* ``get_feed_meta($key)``: in a post context, returns the value, if
647	any, of the feed setting ``$key`` for the feed that this post was
648	syndicated from
649
650	By default, FeedWordPress also places a filter on the standard functions
651	``get_permalink()`` and ``the_permalink()`` that substitutes the URI
652	returned by ``get_syndication_permalink()`` for the URI generated by
653	WordPress. This means that by default the permalinks listed on your website
654	and in your newsfeed will link to the location of the posts on the source
655	website, not to their location on your website. You can switch this
656	behavior on or off at Options --> Syndication in the WordPress Dashboard.
657
658	### Plugin API ###
659
660	FeedWordPress creates five hooks through the WordPress plugin architecture
661	that you can plug in to using PHP WordPress plugins, to supplement ordinary
662	FeedWordPress behavior, or to filter posts according to criteria that you
663	set. The hooks are the action ``feedwordpress_update``, the action
664	``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``,
665	the filter ``syndicated_item``, the filter ``syndicated_post``, the action
666	``post_syndicated_item``, and the action ``update_syndicated_item``.
667
668	For more information, see <http://projects.radgeek.com/feedwordpress/api>.
669
670	License
671	-------
672	The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses
673	code derived or translated from:
674
675	- [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](mailto:kellan@protest.net)
676	- [HTTP Navigator 2][] by [Keyvan Minoukadeh](mailto:keyvan@k1m.com)
677	- [Ultra-Liberal Feed Finder][] by [Mark Pilgrim](mailto:mark@diveintomark.org)
678
679	according to the terms of the [GNU General Public License][].
680
681	This program is free software; you can redistribute it and/or modify it
682	under the terms of the [GNU General Public License][] as published by the
683	Free Software Foundation; either version 2 of the License, or (at your
684	option) any later version.
685
686	This program is distributed in the hope that it will be useful, but WITHOUT
687	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
688	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
689	more details.
690
691	[wp-rss-aggregate.php]: http://laughingmeme.org/archives/002203.html
692	[HTTP Navigator 2]: http://www.keyvan.net/2004/11/16/http-navigator/
693	[Ultra-Liberal Feed Finder]: http://diveintomark.org/projects/feed_finder/
694	[GNU General Public License]: http://www.gnu.org/copyleft/gpl.html
695
696