Users' Manual

Caterpillar is designed to be ridiculously easy to use, but there are some things you can do with it that may not be immediately obvious. This document attempts to address those things, and the obvious ones too.


Caterpillar requires Java 1.4.2 or higher. If you don't have it you will need to download it from Sun. Don't download the version with NetBeans in it unless you actually want NetBeans. Either the SDK or the JRE version will work.


Unzip the archive you downloaded and move the Caterpillar folder to wherever you'd like it to live.

*Nix users: edit the script and chage the INSTALL_DIR variable near the top to to reflect where you copied the Caterpillar directory to. Example: INSTALL_DIR=/home/me/bin/Caterpillar/.


  • Mac OS X: Double-click the Caterpillar icon.
  • Windows: Double-click the run_caterpillar.bat
  • *nix: Execute the after first changing the INSTALL_DIR in it to reflect where you copied the Caterpillar directory to.

Adding a Feed

Adding a feed is pretty simple. Open the "File" menu and choose "Add Feed" (or just hit control+n) and paste in the URL of the feed you wish to add a subscription to. Then just hit enter or the "Add" button. Caterpillar supports RSS, RDF, and ATOM feeds.

Reading entries is probably the simplest thing in Caterpillar. Just select it by either clicking on a title in the list or using your arrow keys to move between titles. The content associated with the given title will be displayed in the bottom of the window.

Reading a Specific Feed

Your search field is also a pull-down that contains a list of all the feeds you're subscribed to. Just choose the one you're interested in from the list.
When a new entry comes in, it will be green. This indicates that you haven't read it yet. Once you've selected an entry for one second, it will turn white when your selection moves to another entry. A white entry is one that you have read that will eventually be deleted. Purple entries are ones that will be permanently saved.
Saving entries, like everything else, is pretty simple. If you've got its title selected, you can just hit the enter key. Alternately, you can double-click the title. The title should turn Purple. Caterpillar will never delete an entry once you've indicated you want to save it. If, later on, you decide you don't want to keep an entry any more you can either hit enter or double click it to un-save it.


Caterpiller has a pretty sophisticated search engine called Lucene hiding under the covers. For the most part, you can just pretend it's Google and search as you would there. After searching for something, it will be added to the pull down options for the search field. That way, if you search for something and later want to find that same thing again but forgot what you searched for, you can just pull down the list.

If you want to know all the complex operators you can use for really precise searching you can check out Lucene's Query Parser Syntax page.

In addition to the use of complex operators, Caterpillar allows you to search within specific fields by prefacing your search term with the name of the field. For example if you wanted to find all the entries with "happy" in their title, you'd type "title:happy" without the quotes. All the searcable fields are listed below:

  • title - Searches the titles of each entry.
  • content - Searches the content of each entry.
  • feed - Searches by for a feed whose name contains the specified text.

Getting the Latest Entries

Caterpillar will update all the feeds you're subscribed to when you launch it and every hour thereafter. If you just can't wait till the next hour select "Reload Feeds" from the "File" menu.

E-mailing an Entry

From the file menu choose "e-mail entry" and enter your email address and the address you want to send it to. If you want to send it to more than one person, just separate the addresses with commas. Then click send. That's it. If there's any problem sending, Caterpillar will let you know. Sometimes it takes a minute to look up the servers and send the e-mail to them, so give it a little bit before checking your inbox.

email an entry
Click Thumbnail for Larger Image


Caterpillar will let you export all your feeds and their entries to XML. I'll leave it up to you to decide what to do with the XML. To export your feeds, just choose "Export Feeds" from the "File" menu and a file called exportedFeeds.xml will be created in Caterpillar's home directory.

Copyright © 2004 Katherine C. Rhodes. All Rights Reserved. Design by AtomicPink.