Index of /carp

Online Documentation

Display formatting
Index
Function reference
Example code

CaRP Free license agreement

CaRP User Forum - special thanks to those users who are so helpful in answering others' questions in the forum

Email Me

CaRP Tips Weblog

Weblog
RSS Feed

If you have already installed CaRP 3.5 or later (GPL, Koi or Evolution), you may simply overwrite the old files with the files from the "carp" directory in this archive. Note that carpsetupinc.php, PHPFTP.php and PHPTelnet.php are used only during installation, and need not be uploaded when upgrading.

For a fresh installation, the following process is usually the simplest.

Decide where you want to put the CaRP scripts on your webserver, and create a new folder for them if necessary.
Recommendations:
- We recommend that the folder be named "carp". This will make it more likely that the setup assistant will be able to locate it automatically. If you are going to name it "carp", you may create it by simply uploading the "carp" folder from the installation archive and its contents (see next step).
- It is good security practice to install scripts like CaRP in a location that cannot be accessed directly by a web browser. For example, if your web folder is located at "/home/joe/public_html", a good location to install CaRP would be "/home/joe/carp" rather than "/home/joe/public_html/carp". However, if you see an error message about "safe mode", you may need to install CaRP inside your web directory.
Upload all of the contents of the "carp" folder from the installation archive to the location chosen in the previous step.
Upload carpsetup.php to your webserver (in a location where you'll be able to load it in your web browser).
Recommendation: For simplicity, we recommend uploading it to your web root folder. For example, if your web folder is located at "/home/joe/public_html", upload it to there.
Load carpsetup.php in your web browser. For example, if you uploaded it to "/home/joe/public_html/carpsetup.php" and your website address is http://www.webhost.com/~joe/, load http://www.webhost.com/~joe/carpsetup.php in your web browser.
Follow the directions that are shown in that page. If you see a message about unsupported functions, that means that your web host has turned off support for functions which are necessary for CaRP to function. In that case, you will either need to contact your web host to see if they will re-enable those functions for you or install CaRP on a different server.
Once you have successfully completed setup, delete carpsetup.php and carpsetupinc.php from your server.
You may also delete PHPFTP.php and PHPTelnet.php--they are not used by CaRP. However, if you are a PHP programmer, you may find them useful. See the PHP FTP and PHP Telnet homepages for more information.

If you wish to use directory-based caching, but the installation script is unable to create cache directories, or is unable to create files in the cache directories after creating them, you will need to create them manually. To do so, create three subdirectories inside the directory where "carp.php" is located with the names "aggregatecache", "autocache", and "manualcache". Set the access permissions for these subdirectories to allow any user to read, write and "execute" them, or whatever settings are necessary on your server to enable CaRP to create files in them. For more information about how to do that, read here. (Note: if the installation script successfully creates these directories, it will be able to do so with more secure settings, so that method is preferred.)

If CaRP Free has all the features you want and you don't feel inclined or able to make a "donation" by upgrading to CaRP Koi or CaRP Evolution, then by all means, stick with CaRP Free. But just so that you can make an informed decision, here are a few examples of the difference that Koi and Evolution can make in your webpages without costing you an arm and a leg:

Images, Authors, Dates and Podcasts

CaRP Free can't display them, Koi and Evolution can. (Exception: with the right "descriptiontags" configuration, CaRP Free can display images embedded in the feed's "description" elements, but not images pointed to by the "image" or "enclosure" element.) Also notice how CaRP Evolution can optionally display relative dates (eg. "45 minutes ago"). Upgrade Now

CaRP Free	CaRP Koi	CaRP Evolution
CaRP displays feeds on websites CaRP is an RSS to HTML converter. It is used to display RSS feeds on webapges. RSS feeds are good for SEO Having automatically updating content on your webpage brings the search engines back more often and helps your search engine position by increasing your site's freshness. etc... CaRP Free can't process as many parts of the feed as Koi and Evolution can. In a real podcast feed, those Podcast buttons would be linked to the audio files.	CaRP displays feeds on websites by Antone Roundy - 23 Feb 2006 CaRP is an RSS to HTML converter. It is used to display RSS feeds on webapges. RSS feeds are good for SEO by Antone Roundy - 22 Feb 2006 Having automatically updating content on your webpage brings the search engines back more often and helps your search engine position by increasing your site's freshness. etc...	CaRP displays feeds on websites by Antone Roundy - 45 minutes ago CaRP is an RSS to HTML converter. It is used to display RSS feeds on webapges. RSS feeds are good for SEO by Antone Roundy - 1 day ago Having automatically updating content on your webpage brings the search engines back more often and helps your search engine position by increasing your site's freshness. etc...

Non-core RSS Elements

CaRP Koi and Evolution can map less common RSS elements like "content:encoded" to it's internal element names (like "desc" for the description): Upgrade Now

CaRP Free	CaRP Koi	CaRP Evolution
CaRP displays feeds on websites RSS feeds are good for SEO etc... Notice how even the "descriptions" are missing this time. This will happen in feeds that put the description in the "content:encoded" element.	CaRP displays feeds on websites by Antone Roundy - 23 Feb 2006 CaRP is an RSS to HTML converter. It is used to display RSS feeds on webapges. RSS feeds are good for SEO by Antone Roundy - 22 Feb 2006 Having automatically updating content on your webpage brings the search engines back more often and helps your search engine position by increasing your site's freshness. etc...	CaRP displays feeds on websites by Antone Roundy - 45 minutes ago CaRP is an RSS to HTML converter. It is used to display RSS feeds on webapges. RSS feeds are good for SEO by Antone Roundy - 1 day ago Having automatically updating content on your webpage brings the search engines back more often and helps your search engine position by increasing your site's freshness. etc...

Text Encodings

CaRP Free can handle UTF-8, ISO-8859-1 and US-ASCII. Koi and Evolution can handle just about anything in just about any language. (Note: your server must offer "iconv" support to PHP applications to handle other encodings). Upgrade Now

CaRP Free	CaRP Koi	CaRP Evolution
[CaRP] XML error: not well-formed (invalid token) at line 4. The free version of CaRP is unable to process this feed's encoding (WINDOWS-1252). Upgrading will likely solve this problem. Some feeds won't get displayed at all by CaRP Free because it can't process their character encodings.	CaRP displays feeds on websites by Antone Roundy - 23 Feb 2006 CaRP is an RSS to HTML converter. It is used to display RSS feeds on webapges. RSS feeds are good for SEO by Antone Roundy - 22 Feb 2006 Having automatically updating content on your webpage brings the search engines back more often and helps your search engine position by increasing your site's freshness. etc...	CaRP displays feeds on websites by Antone Roundy - 45 minutes ago CaRP is an RSS to HTML converter. It is used to display RSS feeds on webapges. RSS feeds are good for SEO by Antone Roundy - 1 day ago Having automatically updating content on your webpage brings the search engines back more often and helps your search engine position by increasing your site's freshness. etc...

Acronyms, Foul Language, etc.

CaRP Evolution can replace acronymns with expanded text (or put them in "acronym" tags), "bleep" foul language, etc. Upgrade Now

CaRP Free	CaRP Koi	CaRP Evolution
Using RSS for SEO boosts ROI If your CEO and CFO go MIA with your IRA, you'll need to boost your ROI to prevent your retirement from being DOA. What Zippy said to Zooty Zippy gave Zooty a heavy lecture today, and when he was done, he said "BTW Zooty, you're a doofus!" etc... CaRP Free and Koi display the feed content as-is.	Using RSS for SEO boosts ROI If your CEO and CFO go MIA with your IRA, you'll need to boost your ROI to prevent your retirement from being DOA. What Zippy said to Zooty Zippy gave Zooty a heavy lecture today, and when he was done, he said "BTW Zooty, you're a doofus!" etc...	Using RSS for search engine optimization boosts ROI If your CEO and CFO go missing in action with your IRA, you'll need to boost your return on investment to prevent your retirement from being DOA. What Zippy said to Zooty Zippy gave Zooty a heavy lecture today, and when he was done, he said "By the way Zooty, you're a [bleep]!" etc... CaRP Evolution's "replace text" plugin can make these kinds of changes.

What do you do if question marks and garbage characters are showing up in your feeds where things like apostrophies, quote marks, hyphens, etc. should be?

Question marks appear when the feed contains characters that can't be represented in the encoding specified in the "encodingout" configuration setting. Changing the output encoding to "UTF-8" should get rid of the question marks...but may replace them with garbage characters as described next.

Garbage characters appear when CaRP's output encoding does not match the encoding of your webpage. Here's how to solve the problem:

First, find out what the character encoding of your page is. Look for a tag like one of the following near the top of your webpage source:
- <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
- <?xml version="1.0" encoding="ISO-8859-1" ?>
In both examples, "ISO-8859-1" is the encoding. If you don't see one of those, look for the place in your web browser menus (usually something like View > Character Encoding) where you can select the encoding of the page. Whatever is checked in that menu is probably the correct encoding.
Next, try setting "encodingout" to that encoding as described in the encodingout documentation. If the garbage characters have been replaced by question marks, then the feed contains data which cannot be displayed using the encoding of your webpage. To display the feed properly, you will have to change the encoding of your webpage.
Finally, if you decide to change the encoding of your webpage, do the following:
1. First, select an encoding. I recommend choosing "UTF-8" for a few reasons:
  - If you're using CaRP Free, UTF-8 is the only available option that will solve the problem.
  - If you're using CaRP Koi or Evolution and your server doesn't offer iconv support, UTF-8 is the only available option that will solve the problem.
  - PHP's XML parser can output UTF-8, which means that the data won't have to be transcoded after it is parsed, which will improve performance.
  There are two exceptions to the UTF-8 recommendation:
  - If your web authoring tools don't support UTF-8, and you need to enter "hi-ASCII" or other non-roman characters.
  - If the language of your website uses multibyte characters and there's another encoding available that uses less bytes per character, you might consider saving bandwidth by using the other encoding.
2. Set CaRP's "encodingout" setting to that encoding.
3. Make sure your webpage contains a META tag as shown above and that it specifies the new encoding (or if your webpage is XHTML, an XML declaration as shown above).
4. Reload your webpage, and make sure that your browser has the new encoding checked in its menu. Then check the page to see if any of your content has turned into garbage characters. If so, you'll need to convert the data in your webpage to the new encoding. Generally this won't be necessary unless you have non-roman characters in your content. How to do this depends on the program you use to edit your webpage.

Because CaRP is a PHP script, it is easiest to use in PHP webpages (webpages whose names end with ".php"). However, CaRP can be used in a variety of types of webpages using the following instructions:

.php - Paste the code given to you by the installer script into the page in the place where you want the newsfeed to appear and then edit it as desired.
.shtm or .shtml (or .htm or .html, if you have SSI enabled for those filename extensions) - See the last paragraph of this information.
.htm or .html - You have three options:
- Change the filename extension to ".php" and use the instructions shown above.
- Turn on PHP processing for your HTML pages and use the instructions shown above.
- Use the example code for converting RSS to JavaScript.
.asp - Follow these instructions.
Mambo or Joomla CMS - Follow these instructions.

Occasionally when attempting to process a feed, CaRP may display an error message beginning with the words "XML Error". There are a few possible causes for this, some of which are problems in the feed, and some of which are limitations in PHP's XML parser. Here's what to do when you encounter an XML error:

If you are setting CaRP's "encodingin" configuration setting, remove that setting to allow CaRP to attempt to automatically determine the proper encoding.
If that doesn't help and you are using CaRP Free, check the error message and see if it tells you what the character encoding of the feed is. If it does, then CaRP Free will not be able to process that feed. Either choose another feed or upgrade to CaRP Koi or CaRP Evolution.
Go to Feed Validator.org and submit the URL of the feed. If the feed validator tells you that the feed is invalid, then there's probably nothing CaRP can do about it. But there is one thing you can try: add this line of code just before the line that says "CarpCacheShow":

CarpConf('fixentities',1);

With luck, that will enable CaRP to fix the broken part of the feed. With luck, it will do so without breaking parts of the feed that weren't already broken! If that doesn't work, then the only thing to do is to notify the publisher that their feed is broken (and point them to the Feed Validator so they can see for themself) and hope that they'll fix it.
If the Feed Validator says that the feed is valid, try adding this line of code just before the line that says "CarpCacheShow":

CarpConf('encodingin','ISO-8859-1');

That will tell CaRP that the feed is encoded as ISO-8859-1 (don't worry if that means nothing to you!) By default, CaRP expects feeds to be encoded as UTF-8. If the feed isn't encoded as UTF-8 and doesn't indicate it's encoding in the XML prologue (the first line of the feed source), CaRP will need you to tell it what the encoding is using the "encodingin" configuration setting.
If that doesn't solve the problem, then the feed is encoded using an encoding other than UTF-8 or ISO-8859-1, but doesn't explicitly specify its encoding. If you are using CaRP Free, you will not be able to use that feed. Either choose another feed or upgrade to CaRP Koi or CaRP Evolution. If you are already using CaRP Koi or CaRP Evolution, you will need to somehow find out what the encoding of the feed is and specify it in CaRP's encodingin setting.

Images may appear in feeds in one of two ways: the feed's <image> or <enclosure> element may point to it (in which case, the free version of CaRP will not be able to display it, but CaRP Koi and CaRP Evolution will, as long as it's a GIF or JPEG image--see the online documentation for details), of there may be an <img> tag in the HTML code in the description (or equivalent) element of the feed. In that case, any version of CaRP can display the image. But by default, none do. To make those images show up, add this line of code just before the line that says "CarpCacheShow":

CarpConfAdd('descriptiontags','|img');

CaRP keeps a list of HTML tags that it allows in the description in its "descriptiontags" setting. The default list does not contain "img" (since unexpected images would very likely disrupt the formatting of your webpage). The line of code shown above adds "img" tags to the list.

Similarly, if you want hyperlinks within the description to show up, add this line of code to add the <a> and </a> tags to the list:

CarpConfAdd('descriptiontags','|a|/a');

...or do images and links at once like this, or...:

CarpConfAdd('descriptiontags','|img|a|/a');

As much as I like having that message displayed at the end of each feed, I also understand that sometimes your site would look better without it. If you do disable that message, I only ask that you either link to the CaRP homepage from somewhere on your site or purchase one of the commercial versions.

To disable the message, add the following line of code somewhere before the line that says "CarpCacheShow":

CarpConf('poweredby','');

If you are looking for a web host, or your current host does not meet the requirements for running CaRP, Gecko Tribe recommends iPowerWeb.

We have verifed that CaRP installs easily and works properly with iPowerWeb's "Web Hosting" service. (NOTE: we have not verified it on their "Windows Hosting" option, but it may work there too). iPowerWeb is a top-notch provider offering full-featured web and email hosting with excellent prices. I personally selected iPowerWeb for another business of which I am a part owner, and I continue to recommend them without reservation. In fact, if you have any difficulty installing CaRP on iPowerWeb's "Web Hosting" service, I will personally complete the installation** at no charge, even if you are using the free version of CaRP. Request installation on iPowerWeb

** Offer includes completion of the installation script, but not additional configuration (for which technical support is available in the CaRP User Forum or by email).