| # BottomFeeder Technology Guide Version 4.4 July 1, 2007

© 2007, Richard A. Demers | Contents

| ## Contents

|- Introduction | |- Notice | |- Related Documents | |- System Requirements | |- BottomFeeder and Smalltalk | |- Concepts | |- Feeds | | |- Feed Standards | | |- A Sample Feed | | |- Aggregating Feeds | | |- Updating Feeds | |- Installing BottomFeeder | |- Windows | |- Apple | | |- Mac OS 8/9 | | |- Mac X | | |- Mac X 10.2.x | |- BottomFeeder Initialization File | |- Blog Poster Initialization File | |- Running BottomFeeder | |- Windows | | |- Command Line Arguments | | |- Windows Registry Keys | |- UNIX | | |- Environment Variables | |- Plugins | |- What Are Plugins? | |- Downloading Plugins | |- BottomFeeder's Plugin API | |- Creating Plugins | |- Customizing Menus | |- Getting Notified Of Events | |- Object Messages

| ## Introduction

Most users of the BottomFeeder RSS aggregator do not care to know the technical details of how it works, how to install it, how to customize it, or how to extend it with plugins. This document is for people who do.

Contents

### Notice

BottomFeeder has been released as an Open Source program, under the Artistic License. When you download it, you agree to abide by this license.

Contents

### Related Documents

The following documents are available to help you get the most benefit from BottomFeeder:

- Quick Start Guide -- a brief introduction to BottomFeeder for new users.
- Tutorial -- explains why you need a tool like BottomFeeder, and helps you learn how to do specific tasks using BottomFeeder.
- User's Guide -- provides detailed information about setting up BottomFeeder and using each feature of its windows, controls, commands and settings.

Contents

### System Requirements

BottomFeeder can be installed and run on any system that meets the following minimum requirements:

Component | Minimum Requirement
--- | ---
Operating System | Windows, Linux86, Macintosh (OS8, OS9, OSX), HPUX (10, 11), SGI, AIX, Solaris, or Alpha Unix
RAM | 128MB (~32Mb for BottomFeeder)
Free Hard Drive (prior to installation) | 32MB
Monitor | 640x480 display, 256 colors (or higher)
Printer | Optional.
Internet Connection | Minimum of 28.8 Kbps connection speed, but broadband connection preferred.

Contents

### BottomFeeder and Smalltalk

BottomFeeder was produced using the VisualWorks 7.5 Smalltalk software development system, which is why it is available on so many operating systems. At its core is a Virtual Machine (VM) that has been efficiently implemented on a wide variety of operating systems. The VM executes programs written in the Smalltalk programming language, providing them with many services, such as memory management.

But operating system independence is only one of the reasons why BottomFeeder was implemented using VisualWorks Smalltalk. The primary reason is that programming in Smalltalk is super-productive. Smalltalk makes it possible for small teams to quickly explore new ideas and build high quality products. While a number of programmers have contributed to BottomFeeder's development and many enhancements, it is essentially the work of one person. But even a hard-working and talented person can only do so much each day; using powerful tools makes a big difference.

Smalltalk is a powerful, dynamic, and elegant programming language that has a simple, easy-to-learn syntax and fully supports object-oriented programming. VisualWorks includes large libraries of predefined object classes that reduce the amount of new code that needs to be written; everything from mathematics to database access and Internet communications. It also includes a wide range of programming tools for organizing, browsing, creating and modifying programs, and for inspecting, debugging and optimizing programs. All together, programming with VisualWorks Smalltalk is not only efficient, it is fun.

BottomFeeder does not make the Smalltalk language or the VisualWorks development tools available to its users, but a free, non-commercial version of VisualWorks is available for download. However, the Smalltalk Workspace tool is available as a menu option. Users can key in and execute Smalltalk expressions, and create Smalltalk scripts that can be saved and executed at any time. Some downloadable examples of such scripts are available at the BottomFeeder Scripting wiki page. These scripts show how to extract information from webpages and format it as a feed that BottomFeeder can process.

Contents

| ## Technical Concepts

You do not have to understand how BottomFeeder works in any great detail -- no more than the driver of a car needs to know how its engine works -- but you may find it helpful to understand a few basic concepts.

The most basic concept is object orientation -- also called action on an object. BottomFeeder is all about objects and commands to those objects. Folders, Feeds and Items are the kinds of objects you see in BottomFeeder. (More about them in the following sections.) Icons and text in BottomFeeder's windows represent each kind of object, so you always know what you are seeing.

But objects are more than just pretty pictures. Each object responds to your commands. All you have to do is select an object and choose a command from a menu or a toolbar. The main trick is knowing what kind of object to select to do what you want, but that will become clear when you know a bit more about each kind of object.

The really cool thing (if you're into technical stuff) is that BottomFeeder is itself made up of objects that send commands to each other. So there is a direct relation between your commands and the way that BottomFeeder performs those commands. But that's the beauty of programming in Smalltalk!

Contents

### Feeds

A feed is an object that represents a special kind of file in a website; one that specifies what has changed in the other files of the website. It is called a feed because it supplies, or feeds, information to whomever will consume it. The website does not have to send messages to individual subscribers to tell them about changes. It just updates its feed file. Anyone on the web can then ask for a copy of the feed file.

BottomFeeder does not care how a website creates a feed file and adds new items to it. In some cases, the website accumulates items in a change log, and on a periodic basis builds a new feed file, and replaces its old feed file. Other websites update their feed file every time there is a new item. And still other websites dynamically build feed files in response to query-style requests from their users. As a consumer of feed files, you really do not care.

If the website covers multiple topics, it may produce multiple feeds so that users can select which ones they want to monitor.

Contents

#### Feed Standards

A website creates its feed files according to the RSS standard. RSS stands for Really Simple Syndication. There have been several versions of this standard, with many differences among them as people have tried to make RSS feeds handle different things. As a user of BottomFeeder, you do not have to be concerned with this; BottomFeeder handles all of the common standards just fine, including:

- RSS 0.9. This was the original, very simple standard for feeds.
- RSS 0.91. RSS 0.91 is upward compatible with RSS 0.9.
- RSS 0.92. RSS 0.92 is upward compatible with RSS 0.91.
- RSS 0.93. RSS 0.93 is upward compatible with RSS 0.92.
- RSS 1.0. RSS 1.0 is upward compatible with RSS 0.9, but with an RDF syntax and extension through modules.
- RSS 1.0 Content Module. A module for the actual content of websites, in multiple formats.
- RSS 1.0 Syndication Module. Provides syndication hints to aggregators, such as feed update frequency.
- RSS 1.0 Administrative Module. This module provides administrative properties that can be used to help improve providers, aggregators, clients, and other users.
- RSS 2.0. RSS 2.0 is upward compatible with RSS 0.93, with extensions through modules.
- Dublin Core Module. A metadata standard for cross-domain information resource description.
- Trackback Module. Trackback informs the receiving site that the sending site has made a reference to a post on the receiving site.
- Pingback Module. This is a way to request notification when somebody links to a document.
- RDF Geographical Module. This is a vocabulary for describing Points with latitude, longitude, and altitude.
- ICBM Geographical Module. This is an alternate vocabulary for describing Points with latitude, longitude, and altitude.
- Well Formed Web Comment API Module. This is a vocabulary for sending comments about a feed or item.
- includedComments Module. This is a vocabulary for describing comments about a feed or item.
- Atom 1.0 This is an attempt to resolve the differences in all of the above with an entirely new standard.

Contents

#### A Sample Feed

Here's an example of a minimal RSS 0.91 feed (taken from a RSS Tutorial):

    <?xml version="1.0"?>
    <rss version="0.91">
      <channel>
        <title>Example Channel</title>
        <link>http://example.com/</link>
        <description>My example channel</description>
      </channel>
      <item>
         <title>News for September the Second</title>
         <link>http://example.com/2002/09/01</link>
         <description>other things happened today</description>
         <trackback:ping>
              http://foo.com/trackback/tb.cgi?tb_id=20020923
         </trackback:ping>
      </item>
      <item>
         <title>News for September the First</title>
         <link>http://example.com/2002/09/02</link>
         <trackback:ping>
              http://foo.com/trackback/tb.cgi?tb_id=20020924
         </trackback:ping>
      </item>
    </rss>

Without going into all of its details, this is an XML encoded file consisting of tagged elements. The root element, `<rss>` to `</rss>`, encloses all other elements. Its first element is `<channel>`, which specifies the title, link and description of the feed's source website. This is followed by a series of `<item>` elements, each of which specifies the title, link and description of some aspect of the source website that is new or changed.

Each item can also include a `trackback` element. A trackback is an Internet message that specifies the URL of its sender and identifies a specific resource (such as a feed item). When your item links to other items (that have requested a trackback), your feed server sends a trackback message to each to tell them that your item is linked to them. Similarly, if your item requests trackbacks and an item in some other feed server links to your item, their feed server sends a trackback message to your server.

Contents

#### Aggregating Feeds

BottomFeeder is a program that aggregates -- a fancy word for "brings together" -- feeds from multiple websites. You tell BottomFeeder what feeds you are interested in by subscribing to them. BottomFeeder then checks for changes by getting the feed file, and telling you about each change. Just leave BottomFeeder running in the background; it checks for feed updates every N minutes, and let's you know when something is new.

But there's a catch; for BottomFeeder to do its thing, a website must publish a feed. An ever increasing number of websites publish feeds, and it's an idea that is quickly catching on. People tend to revisit sites that provide feeds - and that's a good thing, so more and more sites are coming on board. If you find an interesting website that doesn't publish a feed yet, send the web master a message to "get with the program."

Contents

#### Updating Feeds

The process by which BottomFeeder updates feeds from their source websites is straightforward, and worth a few minutes of time to understand.

1. BottomFeeder keeps an internal object model that consists of a Feed object for every subscribed feed. And for every feed, there is a collection of Item objects that is sorted by timestamp. Each item also has an identifier that is unique within its feed.
2. BottomFeeder saves a maximum of N items for any feed (default = 50). These are the N items with the most recent timestamps.
3. Subscribed feeds are updated automatically by BottomFeeder every M minutes (default = 30 minutes). Feeds can also be updated on your command.
4. When a feed is updated, BottomFeeder begins by asking the feed's website if the feed file has changed since the timestamp of the last received feed file. If the feed file has changed, BottomFeeder requests a copy of the entire feed file from the website.
5. BottomFeeder examines the identifier of each incoming item and eliminates duplicates of items it already has.
6. BottomFeeder determines if the item passes through any filters you created for incoming items. It adds the accepted items to the feed's collection -- in timestamp order.
7. If the number of items saved for a feed's collection is greater than the maximum number allowed, items with the oldest timestamps are discarded.
8. An exception to the last point is that you can tell BottomFeeder that an item is to persist. The number of items saved for a feed can then be greater than the maximum number allowed.
9. You can also tell BottomFeeder to delete an item, but this just means you don't want BottomFeeder to show it to you again. A deleted item continues to hang around until the update process replaces it with a new item; meanwhile, you can ask to see deleted items, and even restore them to the normal item views.

Contents

| ## Installing BottomFeeder

### Installing BottomFeeder on Windows

Do the following to download and install BottomFeeder on Windows:

1. Choose a convenient directory of your local hard disk to be the BottomFeeder Home Directory. For example, in Windows, the BottomFeeder Home Directory could be `c:\Program Files\BottomFeeder\`.
2. Using an Internet browser, go to the BottomFeeder Downloads Page.
3. Decide whether you want the currently released version of BottomFeeder or the latest version from the development team. The development version has the latest updates to the program, but it may not be as reliable as the released version.
4. Select the `Windows Installer` version of BottomFeeder that is appropriate for your system. The installer will guide you through the rest of the installation process.
5. You may also want to create a shortcut to BottomFeeder on your desktop. On Windows, right-drag the icon of `bottomFeeder.exe` to your desktop and select `Create Shortcuts Here` from the popup menu.

Contents

### Installing BottomFeeder on Apple

#### Installing BottomFeeder on Mac OS 8/9

Do the following to download and install BottomFeeder on a Mac OS 8/9 system:

1. Download BottomFeeder from the BottomFeeder Home Page, choosing the Mac OS OS 8/9 version.
2. Uncompress the folder onto your desktop. The zipped package does not include a straightforward installer; it has, instead, the following files:
   - `bottomFeeder` - the executable file
   - `bottomFeeder.im` - an image file.
   - two Lib files: `NetManage WinSock Lib` and `StdCLib`
   - plus some folders that will be used once the application installs.
3. Drop the icons for `NetManage`, `StdLibC` and `bottomfeeder` on `Stuffit! Expander`. You will end up with the `NetManage` and `StdLibC` icons looking like puzzle pieces and `bottomfeeder` will expand to an icon called "visual". Visual will have its creator already set to HPS7. To get the `bottomfeeder.im` icon to highlight the "visual" icon upon drag, run `ResEdit 2.1.3` and change the creator for `bottomfeeder.im` to `HPS7`.
4. A so-called `hosts` must be defined. To define a `hosts` file, open the `TCP/IP` control panel. Press the `Select Hosts File` button (if it is not visible, press `Command-U` to switch the User Mode from `Basic` to `Advanced`). Now locate the default `Hosts` file, which can be usually found in your System Folder's `Preferences` folder. If there's none, simply create an empty file using the `SimpleText` application, then select this as your new `Hosts` file. Finally, add this line to the file:

       localhost.      A                       127.0.0.1

5. After that, BottomFeeder should run. Just drop `bottomfeeder.im` on `bottomfeeder`.

The above was provided by a Mac user on the Internet.

Contents

#### Installing BottomFeeder on Mac X

Do the following to download and install BottomFeeder on a Mac OS X system:

1. Download BottomFeeder from the BottomFeeder Home Page, choosing the Mac OS X version.
2. Uncompress the folder onto your desktop.
3. The first time you run BottomFeeder, it will do everything else needed to install itself.

Contents

#### Installing BottomFeeder on Mac X 10.2.x

Apparently there is a special challenge to installing BottomFeeder on an Apple Mac X 1.2.x system. The following was adapted from a blog by James Savidge:

First you'll need to download and install Apple's X11 server. Ignore the fact that Apple's website says that you need 10.3. It works fine under 10.2.8.

Next make sure that you have the X11 version of the VisualWorks runtime engine installed. The `readme.txt` file in the `macxx11` directory says the following:

> 1. Set the DISPLAY environment variable to a sensible value.
>    To use the graphical environment,
>    - create the directory `~/.MacOSX`
>    - copy the file environment`.plist` to `~/.MacOSX`
>      The `.plist` file is included with 10.3 but not with 10.2. You can download it from here.
>    - logout and login again

Once you have put the `.plist` file in the directory and logged in again, start up X11 by double clicking on X11 application in the `Applications` directory. Then, start VisualWorks by double clicking on the `visual` application in the `macxx11` directory.

After downloading and installing BottomFeeder, move the following directories into one of the subdirectories in the Package contents of bottomFeeder.app:

- app
- btfSave
- images
- stylesheets

And if you have already been using the BottomFeeder CST Blog Tool plugin, move the following, as well:

- cache
- deferred-post
- postingUrls.csb

To get to the proper directory, select the `BottomFeeder` icon, pop-up the context menu, and select the `Show Package Contents` menu item. In the resulting window, open the `Contents` folder and then the `Resources` folder. Move the files selected or copied above, into the `bottomFeeder.app/Contents/Resources/` directory.

To start BottomFeeder in X11 by double clicking the icon,

- Download file StartX11BottomFeeder.command and place it in your main BottomFeeder directory.
- Open the file in a text editor and check to see if your copy of X11 and BottomFeeder are in the same directories as specified in the file.
  - If not, modify the parameters of the `open` commands to match your location.
  - In the parameters of the second `open` command, replace `...[put your path here]...` with the the correct part of the path in which you have installed the VisualWorks X11 engine.
  - If double clicking on the `.command` file produces the error:

    > The `.command` file `/Applications/bottomFeeder/StartX11BottomFeeder.command` could not open. Most likely it is not executable.

    You many need to open a terminal window, change to the bottomFeeder directory, and execute the following:

        chmod +x StartX11BottomFeeder.command

While running BottomFeeder under X11, there are a couple of reported bugs that can be worked-around if you set the `User Interface` setting to `OSF Motif`.

- If you set the `User Interface` setting to one of the Mac emulation settings, BottomFeeder locks-up the next time you start it.
- Some of the buttons in the dialog boxes are positioned incorrectly the first time they are displayed.

Contents

| ## BottomFeeder Initialization File

When you start BottomFeeder, its operation is controlled by settings loaded from a file in your home directory. This type of file is called an initialization file, and its name has a suffix of `.ini`. The default initialization file installed with BottomFeeder is named `btfSettings.ini`.

You can temporarily override some of the settings in the initialization file, when BottomFeeder is started, by command line arguments, or by environment variables. These overrides persist only for the current run of BottomFeeder.

You can also change the current settings so they persist in subsequent uses of BottomFeeder. Select `System > BottomFeeder settings...` in the main menu, and make your changes in the BottomFeeder `Settings` window. When you exit from BottomFeeder, the current values of these settings are saved so they can be reloaded when you next start the program. The `Settings` window also allows you to return to the values in the `.ini` file.

The first line of the initialization file identifies the type of `.ini` file -- `[Settings]` -- which should not be changed under any circumstances. Each setting is then specified on a separate line as a `key``=value` pair. String values are specified in single quotes. Boolean values must be specified as `true` or `false`. If you specify relative file paths for the file settings, they are relative to BottomFeeder's home directory.

Strong recommendation: Make a backup copy of file `btfSettings.ini` before making any changes to it.

Initialization File Line | Description
--- | ---
`[Settings]` | Do not change this line.
`absoluteMemoryCeiling` =96000000 | Specifies the maximum memory BottomFeeder should consume.
`alwaysBrowseInline` =false | Specifies whether all requested Internet pages are to be displayed by a browser opened in the `Item` pane (true), or in an external browser (false).
`alwaysSaveBackupXMLFile` =true | Specifies on exit whether BottomFeeder should save an XML file without items, but with all the rest of the tree structure. This file is used for automatic recovery if the file BottomFeeder normally saves is damaged.
`autoBrowseNullDescriptions` =false | Specifies whether BottomFeeder should automatically open a browser when an item selected in the `Item List` pane contains only an Internet address (true), or display the URL of the address (false).
`backgroundLoadPriority` =40 | Specifies the processing priority (in a range of 0 to 100) to be used by BottomFeeder when loading upgrades as a background task.
`bfTechGuideUrl` ='http://www.cincomsmalltalk.com/ BottomFeeder/doc/ TechnologyGuide/TechnologyGuide.htm' | Specify the URL of the BottomFeeder Technology Guide.
`browsingHistoryDepth` =10 | Specifies the number of items to be kept in the history of items displayed in a tag page.
`browserPixelSizeSetting` =nil | Specifies the scale of the text size (small, medium, etc) in the Item pane.
`checkItemReferences` =true | Specifies that cached feed items should be checked for references to each other.
`commentingName` ='' | Specifies the `Posting name` used in the `Comment` window for the last comment sent on any item. This setting is initially empty; BottomFeeder updates it.
`daysWithoutUpdates ToMarkAFeedBad` =30 | Specifies that a feed should be marked as bad if it has not been updated the specified number of days.
`defaultHttpTimeout` =20000 | Specifies how long BottomFeeder should wait for a response to an update request. The default is 20 seconds. For some feeds, especially on slow (dialup) links, 20 seconds may not be enough.
`delay` =30 | Specifies the number of minutes between BottomFeeder updates (the update percent you see reflected in the `Main` window status bar).
`deliciousBaseUrl` ='http://del.icio.us/api/posts/' | Specifies the URL of the del.icio.us social bookmarking website.
`deliciousUsername` =nil | Specifies the user name of an account in the del.icio.us social bookmarking website.
`deliciousPassword` =nil | Specifies the password of an account in the del.icio.us social bookmarking website.
`docUrl` ='http://www.cincomsmalltalk.com/ BottomFeeder/doc/ UsersGuide/UsersGuide.htm' | Specify the URL of the BottomFeeder User's Guide.
`dontLimitMemoryGrowth` =true | Specify whether BottomFeeder can increase the amount of memory it uses to the limits of the hosting system.
`emailAddress` ='' | The user's email address (from `User Settings`).
`emailPassword` ='' | The user's email server password (from `User Settings`).
`emailServer` ='' | The user's email server (from `User Settings`).
`externalBrowser` ='' | Specifies the Internet browser to open outside of the BottomFeeder `Main` window.
`favoritesDirectory` ='' | Obsolete.
`feedFilename` ='btfSave\rssFeeds.btf' | Specify the local file in which BottomFeeder should save feeds.
`feedsterQueryString` ='/search.php?hl=en&ie=UTF-8&q=' ISO-8859-1&q=' | Specify the template of the Feedster query string.
`feedsterURL` ='http://www.feedster.com/' | Specify the URL of the Feedster website.
`ftpHost` ='' | The URL of the FTP host (from `User Settings`).
`ftpPassword` ='' | The user's password on the FTP host (from `User Settings`).
`ftpUsername` ='' | The user's Username on the FTP host (from `User Settings`).
`googleKey` =nil | Specify the authorization key to use when performing a search on Google, an Internet search engine. When BottomFeeder is installed, it has a default authorization key that allows it to perform up to 10,000 searches a day, but this one key is used for all BottomFeeder users. Users who perform many Google searches a day through BottomFeeder should get their own authorization key. This can be done by clicking the `Get a Google Key` button on the `Search` window.
`ignoreTimeoutErrors` =false | Specifies that timeout errors detected during communication operations are to be ignored.
`includeCommentsInNewspaper` =true | Specifies that comments should be included with their items in a newspaper view.
`infoUrl` ='http://www.cincomsmalltalk.com/ BottomFeeder/' | Specify the URL of the BottomFeeder information web page.
`isOnline` =true | Specifies whether BottomFeeder is to be online (true), or offline (false). When offline, all network functions are turned off, and network menu items are disabled. You can still add feeds to folders; but they are not updated until BottomFeeder is again online.
`lastPlatform` =#win32 | Specifies the last platform on which BottomFeeder was run. You can specify one of the following: #win32 - Windows. #unix - OS 8/9. #mac - OS X.
`launchNewBrowserOnWindows` =true | Specifies whether BottomFeeder should open a new browser for any action that requires one (true), or reuse an existing browser (false). Opening a new browser is the default action on non-Windows platforms.
`lookPolicy` =#AutoSelect | Specifies the appearance of BottomFeeder windows and controls. You can specify #AutoSelect - the underlying system platform. #DefaultLook - default Smalltalk look. #Macintosh - Macintosh OS/8. #MacOSXAqua - Macintosh X Aqua. #MacOSXPollock - Macintosh X using VisualWorks Pollock widgets. #OSFMotif - Motif. #Win95NT - Windows 95/NT. #Win982k - Windows 98/2000. #WinXP - Windows XP.
`numberOfItemsToCache` =50 | Specifies the total number of items BottomFeeder should cache.
`password` ='' | Specifies the password BottomFeeder is to use in your proxy server. If you are concerned about password security, change this setting to `password=` and enter your proxy password into `Network Settings` so that BottomFeeder can encrypt it.
`patchDirName` ='btfPatch' | Specify the local directory in which BottomFeeder should save software patch files.
`patchSiteFilename` ='patches.xml' | Specifies the name of the patch definitions file in the patches website.
`patchSiteUrl` ='http://www.cincomsmalltalk.com/ BottomFeeder/patches/' | Specifies the URL of the website from which BottomFeeder can obtain software patches.
`pluginSiteFilename` ='plugins.xml' | Specify the local directory in which BottomFeeder should save plugin files.
`pluginSiteURL` ='http://www.cincomsmalltalk.com/ BottomFeeder/plugins/' | Specify the URL of the website from which BottomFeeder can obtain plugin files.
`proxyDomain` ='BOTTOMFEEDER' | Specifies the domain of the proxy server
`proxyExceptions` ='' | Specifies a comma separated list of Smalltalk exceptions from the proxy server to be ignored.
`proxyPort` =80 | Specifies the port to use on the proxy server
`proxyServer` ='' | Specifies the IP address of the proxy server. Do not specify unless you cannot browse the Internet without proxy settings.
`quickStartGuide` ='http://www.cincomsmalltalk.com/ BottomFeeder/doc/ QuickStart/QuickStart.htm' | Specifies the IP address of the proxy server. Do not specify unless you cannot browse the Internet without proxy settings.
`runThreadedUpdates` =false | Specifies that BottomFeeder should updates in a separate processing thread, thereby allowing continued user interactions.
`saveAfterUpdate` =true | Specifies that BottomFeeder should do a save of its application state after each update cycle.
`saveFileDirectory` ='btfSave' | Specify the local directory in which BottomFeeder should save feeds and window settings when `File/Save All` is requested. `File/Save All` saves BottomFeeder settings in the directory containing the BottomFeeder program (`bottomFeeder.exe`).
`searchFeedFile` ='btfSave\searchFeeds.btf' | Specifies the save file for the search folders.
`shouldCommentsFlagNew` =true | Specifies that the arrival of comments on an item should cause the item to be marked as new.
`shouldDoItemCaching` =true | Specifies whether BottomFeeder should keep up to N total items after updates that contain new items (true), or always grab just what is in a feed after an update (false). N is set by the numberOfItemsToCache setting. The intent here is to preserve some content from rapidly changing feeds - otherwise, you may not ever see an item from some of them.
`shouldFollowComments` =false | Specifies that BottomFeeder should request item comments that are separately linked to their websites, and add them to the item.
`shouldKeepCacheInMemory` =false | If true, Http protocol messages received from the Internet are cached in memory (besides being cached on disk). Caching them in memory can consume a lot of memory.
`shouldKeepHTMLInMemory` =false | If true, HTML tagged feed texts are cached in memory; otherwise, they are cached on disk. Caching them in memory can consume a lot of memory.
`shouldRunCompatibleServers` =true | Some website pages displayed by a browser contain button-icons of feed-reading tools other than BottomFeeder (not the BottomFeeder fish). You can click any of these buttons to add a BottomFeeder subscription to the website's feed. This setting specifies whether a running instance of BottomFeeder should add the subscription (true), or reject the subscription (false). If true, BottomFeeder adds the subscription to the root Subscriptions folder of the Feeds tree.
`shouldRunLocalServer` =true | Some website pages displayed by a browser contain a button-icon (the BottomFeeder fish). You can click this button to add a BottomFeeder subscription to the website's feed. This setting specifies whether a running instance of BottomFeeder should add the subscription (true), or reject the subscription (false). If true, BottomFeeder adds the subscription to the root Subscriptions folder of the Feeds tree.
`shouldSaveFileOnExit` =true | Specifies whether changes to BottomFeeder's initialization file should be automatically saved on exit from the program (true), or discarded (false).
`shouldSetLocaltimeZone` =false | Specifies that BottomFeeder should set its internal clock to the local time zone on startup and adjust the timestamps of displayed items to the local timezone.
`shouldSpreadUpdates` =false | If true, BottomFeeder should wait a short period of time between sending requests for feed updates. This spreads out the processing required for an update cycle, significantly reducing the amount of memory and processor resources consumed by BottomFeeder during the cycle.
`shouldThrottleThreads` =false | When `runThreadedUpdates=true` and `shouldThrottleThreads=true`, BottomFeeder uses a separate processing thread per feed update; otherwise, it uses a thread from a pool of threads for each feed update.
`shouldTrackNonUpdatingFeeds` =true | Specifies that BottomFeeder should continue to check feeds that have not updated.
`shouldTruncateAllFeeds OnEachUpdate` =true | Specifies whether BottomFeeder should truncate each feed to N items on each update of the feed's item from its source website. N is set by the `numberOfItemsToCache` setting. The intent here is to limit the number of items saved from rapidly changing feeds - otherwise, you may see a rapidly growing number of them.
`shouldTruncateAllFeeds ToLimitOnSave` =false | Specifies whether BottomFeeder should truncate each feed to N items on saves (true), or save all items (false). N is set by the `numberOfItemsToCache` setting. The intent here is to limit the number of items saved from rapidly changing feeds - otherwise, you may see a rapidly growing number of them.
`showExtraInfoInDescription` =false | Specifies whether the name of the feed containing an item should be included with the item. This is particularly useful in a newspaper display.
`showFeedsterResultsInline` =false | Specifies whether to show Feedster results in the `Item` pane of the `Main` window (true), or in a new browser (false).
`showGridScrollbar` =true | Specifies whether a scrollbar should be shown in an Item List.
`showNewViewInTree` =false | Specifies that BottomFeeder should present a Tree View of new items when the `New Items` view button is clicked. This tree view consists only of feeds with new items, plus their containing folders.
`showTabularView` =true | Specifies whether BottomFeeder should display the `Item List` pane as a table with a date column and a title column for each item (true), or as a simple list of item titles (false).
`softMemoryCeiling` =48000000 | Specifies the soft limit on memory BottomFeeder should consume.
`suppressImagesInBf` =false | Specifies that a feed's image should not be displayed when the feed is selected.
`textSize` =#default | Specifies how text is to be rendered in BottomFeeder. The following can be specified: #small - slightly smaller than "default", useful for small displays on the order of 640x480 pixels. #default - the usual size, suitable for 1024x768 displays. #large - slightly larger size, for 1600x1280 hi-res displays. #fixed - similar to "default", but all characters are the same size. This is useful for presenting table-oriented data or in a terminal emulator.
`tickerColorStyle` =light | Specify the background color style of the ticker.
`tickerSpeed` =#medium | Specify the speed at which the ticker shows item titles.
`tickerItemWidth` =#medium | Specify the width of the displayed ticker.
`tutorial` ='http://www.cincomsmalltalk.com/ BottomFeeder/doc/ Tutorial/Tutorial.htm' | Specify the URL of the BottomFeeder Tutorial document.
`unixShellToUse` =sh | Specify the shell to use when BottomFeeder is installed in a Unix or Linux system.
`updateLoopPriority` =#medium | Specify the priority (Low, Medium or High) at which BottomFeeder should perform updates relative to other system tasks.
`upgradeFilename` ='upgradeBtf.xml' | Specify the local directory in which BottomFeeder should save upgrade files.
`upgradeURL` ='http://www.cincomsmalltalk.com/ BottomFeeder/upgrades/' | Specify the URL of the website from which BottomFeeder can obtain upgrade files.
`useLibTidy` =true | If true, BottomFeeder converts the items received from each feed into a form (XHTML) that can be more easily displayed. BottomFeeder only includes TidyHTLM libraries for x86 Linux and Windows. Technically oriented users could build a shared library for their platform if they want to download the C sources. If the TidyHTML dll/shared library is not available, this setting is ignored.
`useProxySettings` =false | Specifies whether BottomFeeder should use the proxy settings when establishing Internet communications.
`username` ='' | Specifies the user name BottomFeeder is to use in your proxy server.
`userStyleSheet` =#Simple | Specifies the name of the user-defined stylesheet BottomFeeder is to use.
`useTickerForSlimMode` =true | Specifies the user name BottomFeeder is to use in your proxy server.
`useXHTMLEditorWhenCommenting` =true | If true, BottomFeeder uses its WYSIWYG editor in the Commenting window.
`validationService` ='http://www.feedvalidator.org/check?url=' | Specifies the user name BottomFeeder is to use in your proxy server.
`windowSettingsFilename` ='btfSave\btfWinSettings.btf' | Specify the local file in which BottomFeeder should save window settings.

Contents

| ## Blog Poster Initialization File

For the Blog Poster to be able to work with your blog, you need to provide it with some basic information. This is done in a special initialization file in your BottomFeeder home directory, called `postingUrls.csb`.

The first line of the initialization file identifies the type of file -- `[SiteInformation]` -- which should not be changed under any circumstances. Each setting is then specified on a separate line as a `key``=value` pair. String values are specified in single quotes. Boolean values must be specified as `true` or `false`. If you specify relative file paths for the file settings, they are relative to BottomFeeder's home directory.

Strong recommendation: Make a backup copy of file `postingUrls.csb` before making any changes to it.

File Line | Description
--- | ---
`[SiteInformation]` | Do not change this line.
`apiToUse` =#cstAPI | The API to use to communicate with your blog server. You can specify one of the following: #cstAPI -- the Cincom Smalltalk blog server API #metaAPI -- the MetaWebLog API #mtAPI -- the Moveable Type API #bloggerAPI -- the Blogger API
`appkey` ='' | An application key used by the Blogger API. Set it to the same value as `logicalName`.
`bloggerUrl` ='' | This is the URL for a blog that supports the Blogger API.
`blogId` ='' | The identifier of the blog within the blog server.
`blogRollURL` ='' | URL for the CST Blogroll servlet interface.
`categoryURL` ='' | URL for the CST Category servlet interface for this blog.
`defaultImageDestination` ='' | The blog server directory in which images are to be stored. This is a relative path; do not specify a leading /.
`deleteURL` ='' | URL for the CST Delete servlet interface for this blog.
`doClientTransforms` =false | If true, BottomFeeder transforms certain wiki-style markups into HTML.
`encryptionKey` =N | Key used to encrypt blog access.
`fileUploadUrl` ='.' | This is the URL for uploading files to a CST blog server.
`getURL` ='' | URL for the CST Get posts interface for this blog.
`kickServlet` ='' | Not used at this time.
`logicalName` ='' | This is the name of the blog that is displayed in the header of the Blog Poster window.
`metaUrl` ='' | This is the URL for a blog that supports the MetaWebLog API.
`mtUrl` ='' | This is the URL for a blog that supports the Movable Type API.
`numberPostsToRetrieve` =25 | This is the maximum number of items to retrieve when retrieving items from the blog server.
`password` ='' | This is the password to use when communicating with the blog server.
`postURL` ='' | URL for the CST POST interface for this blog.
`updateURL` ='' | URL for the CST Update interface for this blog.
`username` ='' | The username to use when communicating with the blog server.
`useSpellchecker` =true | If true, BottomFeeder checks the spelling of items as they are entered or updated.
`useServerMarkup` =false | If true, certain wiki-style markups are transformed into HTML by the blog server.
`viewMode` =#XML | Specifies how items are to be edited by the Blog Poster. The values that can be specified are: #XML -- use the WYSIWYG editor. #plain -- use the plain text editor.

Contents

| ## Running BottomFeeder

### Running BottomFeeder On Windows

What you need to do to start BottomFeeder depends on the operating system you are using. For example, to run BottomFeeder under Windows, double-click the BottomFeeder shortcut on your desktop. Alternatively, select `Run` in the desktop `Start` menu, type

       [path\]bottomFeeder.exe [argument]...

in the input field of the Run dialog, and click the `OK` button.

`[path\]` is the path to your BottomFeeder Home Directory.

`[argument]...` consists of optional arguments (see Command Line Arguments).

For example,

       c:\Program Files\BottomFeeder\bottomFeeder.exe -offline

BottomFeeder is a very flexible program. Use the `Settings` window to make it work in the way that suits you best, but when you are first getting started, it is best to use the program's default settings.

Contents

#### Command Line Arguments

To run BottomFeeder under Windows, double-click the BottomFeeder shortcut on your desktop.

Alternatively, select `Run` in the desktop `Start` menu, type

       [path\]bottomFeeder.exe [argument]...

in the input field of the Run dialog, and click the `OK` button. For example,

       c:\Program Files\BottomFeeder\bottomFeeder.exe -online -ini myIni.ini

`[path/]` is the directory path to the `bottomFeeder.exe` program.

`[argument]...` consists of optional arguments, as specified in the following table:

Argument | Description
--- | ---
`-offline` | Start Bottom Feeder in offline mode. All network functions are turned off, and network menu items are disabled.
`-online` | Start Bottom Feeder in online mode. All network functions are turned on, and network menu items are enabled.
`-ini iniFilename` | Override the BottomFeeder initialization file. The default filename is btfSettings.ini. This file holds the initialization settings loaded at startup. It is an editable text file - see Initialization File for details.
`-f feedsFilename` | Override the feed file specified in the initialization file (rssFeeds.btf) with the named file. This file holds everything saved under the 'Subscriptions' folder. It is a binary file and cannot be edited.
`-w winSettingsFilename` | Override the windows settings file specified in the initialization file (btfWinSettings.btf) with the named file. This file holds the saved window position and size and the learning menu scores (if used). It is a binary file and cannot be edited.
`-d directoryName` | Override the save directory specified in the initialization file (btfSave) with the named directory. This is the directory in which all other BottomFeeder files are saved.
`-convert` | Convert the old (pre 2.6) settings to the new format and quit.

1. It is not possible to edit the binary files listed above, but it is possible to load a binary file saved by a previous run of BottomFeeder.
2. You could push the feed files between two systems (say Linux and Windows) and keep the window settings for each locally.

Contents

#### Windows Registry Keys

When operating under Windows, BottomFeeder sets the following registry keys:

Registry Key | Description
--- | ---
`BtfSaveFile` | Specifies the local directory in which BottomFeeder should save its initialization file after changes by the user.

The Registry path used is `KEY_CURRENT_USER/Software/BottomFeeder`.

Contents

### Running BottomFeeder On UNIX

To run BottomFeeder on a UNIX system, do the following:

1. Open a shell.
2. `cd` to the directory in which you installed BottomFeeder.
3. `% cd bottomFeeder`
4. `% ./bottomFeeder bottomFeeder.im`

- You could also write a shell script to set environment variables. See Environment Variables for details on what can be set.
- On Linux (or Unix), there's no way for BottomFeeder to identify the "default" browser to be spawned on a browse request. Therefore, the default browser BottomFeeder uses is the same one it uses in its own `Item` pane -- a good tool for basic browsing, but not a full browser replacement. To use a different default browser, open the System Settings window, select the Browsing tab, and specify a browser (or a script that launches one). After that, browse requests will go to that external browser.

Contents

#### Environment Variables

In a Unix or Linux system, you can control the operation of BottomFeeder by setting environment variables. For example, you can do something like this:

       BtfSave=/home/auser/btf/btfSettings.ini
       export BtfSave

and then that environment variable is set for that run. If you want variables always set, you can add them to the startup script for the shell you use.

The environment variables for BottomFeeder are specified in the following table:

Environment Variable | Description
--- | ---
`$BtfSaveDir` | Override the save directory specified in the initialization file (btfSave) with the named directory. This is the directory in which all other BottomFeeder files are saved.
`$BtfSave` | Override the BottomFeeder initialization file. The default filename is btfSettings.ini. This file holds the initialization settings loaded at startup. It is an editable text file - see Initialization File for details.
`$BtfFeedsFile` | Override the feed file specified in the initialization file (rssFeeds.btf) with the named file. This file holds everything saved under the 'Subscriptions' folder. It is a binary file and cannot be edited.
`$BtfWinSettingsFile` | Override the windows settings file specified in the initialization file (btfWinSettings.btf) with the named file. This file holds the saved window position and size and the learning menu scores (if used). It is a binary file and cannot be edited.
`$BtfPatchDir` | Override the patch file directory specified in the initialization file (btfSave\patches) with the named directory.

Contents

| ## Plugins

### What Are Plugins?

Plugins are programs that plug into a host program to enhance it or change it in some way. The host program works well without any plugins, but if you install plugins, the host program becomes more useful to you in some way.

BottomFeeder is a host program to an open-ended set of plugins. BottomFeeder adds the names of the plugins you install to the `Plugins` menu of its `Main` window. When you click on a plugin name in that menu, BottomFeeder starts the selected plugin program. Depending on its function, the plugin may open additional windows or it may enhance BottomFeeder in some other way.

Contents

### Downloading Plugins

One source for plugins is BottomFeeder, itself. Useful plugins have been created by the BottomFeeder development team. In other cases, other people have sent plugins to the development team. All of these plugins can be downloaded by using the `System / Check for Upgrades...` command.

Any file transfer program can be used to download plugins from other sources. Just put them into the `plugins` directory under the BottomFeeder Home Directory.

Contents

### Creating Plugins

Creating plugins is best left to experienced VisualWorks Smalltalk programmers.

The plugins that BottomFeeder can install and start are VisualWorks Smalltalk programs that have been deployed as VisualWorks parcels. To create a plugin, use Cincom VisualWorks to create and test appropriate Smalltalk classes and methods, and export them as a `.pcl` file. Put this file into the BottomFeeder `plugins` directory so it can be loaded when BottomFeeder is started.

When BottomFeeder loads a plugin, the parcel loader evaluates the block specified by the parcel's `Post-load Action` property. Specify the following block so that it can initialize itself.

    	[:parcel | ...plugin initialization code... ]

This block must send one of the following call-back messages to BottomFeeder to register itself as a plugin:

    	#{RSS.RSSFeedViewer} ifDefinedDo: [:cls |
    	   cls
    	      registerPluginClass: PluginClassName
    	      startupMessage: #startupMethodName
    	      label: labelString].

    	or

    	#{RSS.RSSFeedViewer} ifDefinedDo: [:cls |
    	   cls
    	      registerPluginClass: PluginClassName
    	      startupMessage: #startupMethodName
    	      label: labelString
    	      isForUI: false]

The #ifDefinedDo: message just ensures that RSS.RSSFeedViewer has been imported by the class of the plugin.

If a plugin has a user interface, BottomFeeder adds an entry to its `Plugins` menu. When clicked, this menu entry sends the startup message specified in plugin's registration to the registered plugin class. If the plugin does not have a user interface, the startup message is sent immediately after registration.

When BottomFeeder unloads a plugin, the parcel unloader evaluates the block specified by the parcel's `Pre-unload Action` property. Specify the following block:

    	[:parcel | parcel unregisterPluginClass: PluginClassName]

Contents

### BottomFeeder's Plugin API

Some plugins, such as the `IRC Client`, provide new capabilities that have little or nothing to do with the basic BottomFeeder application of aggregating feeds. For them, the basic plugin interface described above is all they need.

Other plugins, however, augment BottomFeeder's handling of feeds in some way. For example, the `CST Blog Tool` opens a tool for creating a blog entry about a selected item of a feed. They need a way to work with selected feeds or items, and users need a way to request their services. For them, BottomFeeder provides an Application Programming Interface (API) for customizing menus, and to be notified of BottomFeeder events.

Contents

#### Customizing BottomFeeder Menus

BottomFeeder's primary user interface is through menu actions that can be requested on a selected feed or item. A plugin can add an action to the `Item List` popup menu. When a feed is selected in the `Tree` pane, BottomFeeder sends the following message to the plugin's class (the one registered with BottomFeeder):

    	PluginClassName
    		customizeMenu: aMenu
    		forItem: anItem
    		andFeed: aFeed

Here is an example of such a plugin method:

    	customizeMenu: aMenu forItem: anItem andFeed: aFeed
    		"add a menu pick if appropriate"
    		self isMyActionAvailableForItem: anItem andFeed: aFeed
    			ifTrue: [aMenu addItem: self myAction]

Contents

#### BottomFeeder Events

A variety of events occur when BottomFeeder processes user requests. In some cases, a plugin needs to take actions beyond what BottomFeeder has already done. To be notified of these events a plugin must register itself as a receiver of each event. Depending on whether or not the event includes an argument, register by sending one of the following messages:

    RSS.RSSFeedViewer
       when: #placeEventNameHere
       send: #placeYourEventHandlerMethodNameHere
       with: argument

    or

    RSS.RSSFeedViewer
       when: #placeEventNameHere
       send: #placeYourEventHandlerMethodNameHere

Event | Argument | Description
--- | --- | ---
`#addedFeed:` | `aFeed` | Sent when a feed is successfully added.
`#tgOffline` | `aFeed` | Sent when BottomFeeder goes offline.
`#tgOnline` | `aFeed` | Sent when BottomFeeder goes online.
`#bottomFeederStarting:` | `RSSFeedViewer instance` - the main BottomFeeder window | Sent after BottomFeeder has started, but before it has updated any feeds. Plugins can perform additional startup operations for themselves.
`#bottomFeederQuitting:` | `RSSFeedViewer instance` - the main BottomFeeder window | Sent after the BottomFeeder feed viewer application model has terminated, but before the containing Smalltalk image has been terminated. Plugins can perform additional termination operations for themselves.
`#newItemsFor:` | `aFeed` | Sent when there are new items for a feed (after a manual update, or via the update loop).
`#newItemsForAlert:` | `aFeed` | Sent when there are new items for a feed which is set for alerts (after a manual update, or via the update loop).
`#removedFeed:` | `aUrl` | Sent when a feed is removed. The argument is the feed's URL; the removed feed is not available.
`#quitting` | `` | Sent when the BottomFeeder image is going to quit. The image does not quit before the plugin method returns. (Sent by deployment image, only.)

A plugin only needs to register for the events it wants to handle; the others are ignored.

Contents

#### BottomFeeder Object Messages

BottomFeeder passes feed objects on some of the API's listed in the previous section. This makes it possible for the plugin to send messages to those objects to request various services. The obvious questions to ask are, "What services?" and "What messages?"

At this point in the development of BottomFeeder, these questions can only be answered by repeating that you have to be a VisualWorks Smalltalk programmer. If you are, download a VisualWorks development image from Cincom Smalltalk Downloads, and a copy of the current BottomFeeder bundle from the Public store. Look for class `RSSFeed` in the `RSSViewer-Domain` package.

Contents

| ## The End