5. The Dotdir

(Feeds) Prev | Index | Next

None of the information in this section of the manual is needed to use and enjoy Olive.

Olive keeps its configuration, raw data, and working data in a directory named '~/.olive'. This section describes the contents of that directory.

5.1 The Config File

The configuration file is named 'olive.yaml'. As its extension indicates, it is a YAML-formatted file. If you are unfamiliar with YAML, you should read about it before manually editing this file.

5.1.1 Miscellaneous Configuration

coe

Mnemonic: Confirm On Exit
Type: Boolean
Effect: Controls whether Olive termination is immediate (0) or confirmed (1). See Section 3.2.5.

dst

Mnemonic: Don't Show Titlebar
Type: Boolean
Effect: Controls whether the first line of the Olive window is used as a titlebar (0) or to display live list data (1). See Section 3.2.4.

fr

Mnemonic: First Run
Type: Boolean
Effect: Originally marked whether Olive had been run before (1) or not (0). Now used to store the version number of Olive when last run, paving the way for automatic upgrade procedures. Still controls display of the first-run splash screen,

gsp

Mnemonic: Global Story Paging
Type: Boolean
Effect: Controls whether keybindings are enabled so as to allow paging of the currently displayed story no matter where focus is. 1 is "bind", 0 is "don't bind". See Section 3.2.4.

knf

Mnemonic: Keep New Forever
Type: Boolean
Effect: Controls whether stories are removed from the database as they fall off their feeds, or are removed only after the user has read them. 1 is "keep", 0 is "let fall off". See Section 3.2.3.

loglevel

Mnemonic: None
Type: Enum
Effect: Sets the minimum logging level for the error log. Default is "warning". Meaningful values for Olive are "warning", "info", and "debug" (in increasing order of verbosity). For a full list of levels, see the Log::Dispatch documentation.

pw

Mnemonic: Poll Wait
Type: Positive Integer
Effect: Sets the inital value, in minutes, of the delay between automatic poll feeds. See sections 3.3 and 4.4 for more info.

sls

Mnemonic: Show List Status
Type: Boolean
Effect: Controls whether the status line will display story list stats (1) or not (0). See Section 3.2.1.

snu

Mnemonic: Skip to Next Unread
Type: Boolean
Effect: Controls the behavior of the prev/next commands: always select the story adjacent to the current selection (0) or seek to the next unread story (1). See Section 3.2.2.

to

Mnemonic: Time-Out
Type: Positive Integer
Effect: Sets the initial value for the network timeout of the internal LWP::UserAgent object which fetches feeds. See Section 3.4.

www

Mnemonic: ...
Type: String
Effect: Contains the command string which is used to launch external browser sessions. See Section 3.5.

5.1.2 Feeds

All information about subscribed feeds is stored in a HOHOH named 'feeds'. The full format is as follows:

  feeds:
    a_feed:
      disp: Display Title From User
      dormant: 0
      feed: http://feed/url
      force: 0
      last: 1119248150
      title: Actual Title From RSS Feed
      ttl: 86400

Where the 'a_feed' stanza is repeated, with appropriate changes, for each subscribed feed. The meanings of the individual values is:

1. disp: The feed's user-chosen display name; displayed in the List Pane next to stories belonging to this feed.
2. dormant: Boolean marking the feed dormant or not.
3. feed: URL of the actual feed.
4. force: Boolean marking the feed as force-fetchable or not.
5. last:Value of time() as of the feed's last fetching.
6. title: Actual title of the feed, taken from the feed data.
7. ttl: The feed's time-to-live in seconds. Taken from the feed or given a value of 3600s in the absence of a value from the feed data.

See Section 4 for more information.

5.1.3 Customizing Keybindings

There is no interface provided for changing keybindings within Olive. Not all functions can be rebound. The ones which can are altered via a HOH named 'keys' in the config file. An example which creates custom bindings for the functions normally assigned to the '[' and ']' keys is:

  keys:
    next: n
    prev: p

Here is the list of bindable functions and their standard keys:

Olive does not check for duplicate bindings or stomping on a prebound key without providing a replacement. Also, be aware that you may need to quote your choice of key if it is a YAML special character (see the YAML spec for more information).

5.2 The Error Log

Olive logs all warnings and fatal error messages (trapped or otherwise) to a file named 'errors.log'. On startup, this file is copied to 'errors.log.1' before being overwritten, so there are logs for the past 2 runs available at any time.

Error logs always start with a timestamp like this:

  -- Starting up at 2005-05-22T16:58:11 --

After that, there is no standard or predictable format for the contents of the file.

Should Olive ever suddenly quit, or if you experience any problems or weird behavior, please look at the logfile(s) and file a bug (as per Section 1.5)

5.3 The Story Database

Olive does not operate upon the raw feeds it fetches over the network. It processes them after they are retrieved and stores the relevant data in a SQLite database named 'story.db'.

The schema of the database is as follows:

  CREATE TABLE stories (id INTEGER PRIMARY KEY, 
                        nick TEXT, 
                        timestamp INT,
                        md5 TEXT, 
                        read INT, 
                        new INT, 
                        link TEXT, 
                        title TEXT, 
                        desc TEXT);

5.4 The Feeds Directory

Downloaded feeds and the data needed to perform tests for HTTP 304 status are stored in a subdirectory called 'feeds'. Every feed you're subscribed to will have two files there, a file named as a possibly modified form of the feed nickname, and file with the same name as the first one, but with ".cache" appended.

  mdxi@fornax:~$ ls .olive/feeds/
  atc             cnn_money        groklaw        mdxi         rjbs        
  atc.cache       cnn_money.cache  groklaw.cache  mdxi.cache   rjbs.cache  
  bbc_news        gloria           kate           olive        robert      
  bbc_news.cache  gloria.cache     kate.cache     olive.cache  robert.cache

The files with no extension hold the last downloaded copy of that feed. The .cache files hold HTTP header data needed to check if the feed has been updated when it is polled next.

Files associated with a feed are unlinked when the feed is removed from your feed list.

(Feeds) Prev | Index | Next

$Id: dotdir.html 434 2007-02-07 05:04:51Z mdxi $