Story Web Browsing History Browser — Manual

Story is a working prototype of a simple Web browsing history browser. Main features are:

Homepage:, Contact:


  1. Installation
    1. Required Further Software
    2. Setting up the System
    3. Providing Places Databases
  2. Usage
    1. Invocation
    2. Password Protection
    3. Page Types

1. Installation

The system has been tested on Debian Linux and Mac OS-X platforms, details on requirements are shown in the table in Section 1.1. It should be possible to install the system analogously also on other Linux platforms and on Windows with Cygwin.

1.1 Required Further Software

Software Tested versions For Debian 4.0 “etch” For Mac OS-X 10.4 with Fink 0.8.1
SWI-Prolog 5.6.40
  1. Download the stable release of SWI-Prolog/XPCE for Linux (RPM package) from
  2. Convert the RPM package to a DEB package by calling alien as root, e.g.:
    # alien -v pl-5.6.40-290.i586.rpm
  3. Install the DEB package, e.g.:
    # dpkg -i pl_5.6.40-291_i386.deb
Download and install the stable release of SWI-Prolog/XPCE for MacOS X 10.4 from

Unfortunately version 5.6.43 seems to require a newer version of libXft.2.dylib than that provided by Apple. With Darwinports it can be installed by

$ sudo port install xft2

Version 5.6.40 works out of the box.

GNU sed 4.0.5, 4.1.5 Package sed Fink package sed

GNU sed is required. /usr/bin/sed, which comes with OS-X, is not sufficient.

sqlite3 3.2.8, 3.3.8 Package sqlite3 Fink package sqlite3

/usr/bin/sqlite3 version 3.1.3, which comes with OS-X, is too old for the databases of Firefox 3 Alpha 7

htpasswd unspecified Package apache2-utils Comes with OS-X as /usr/bin/htpasswd

1.2 Setting up the System

  1. Unpack the distribution archive. A directory story is created.
    $ tar xzvf story.tgz
  2. Move the story directory to some place. Write access to the story directory is not required. By default, the application assumes story is placed directly in your home directory. If another location is used, set the environment variable STORYDIR, for example by a line like the following in ~/.bash_profile:
    export STORYDIR=/usr/local/software/story
  3. Create the user specific directory ~/.story with configuration files and stores for temporary data with the command
    $ story/bin/
    This command creates a password file ~/.story/passwd with an entry for a single user of the Web server interface of the system. The user name is by default the value of $USER, but can also be supplied as optional argument to The password is prompted by

    If ~/.story already exists, then aborts without any effect.

    Configuration settings are in ~/.story/ This file can of course be manually adapted to specific needs.

1.3 Providing Places Databases

The system reads in places.sqlite history database files in the SQLite format generated by the Firefox 3 (Gran Paradiso) browser. The tested version is Firefox 3 (Gran Paradiso) Alpha 7.

The places.sqlite file can be found in your Firefox profile folder, for example on Linux

and on Mac OS-X
    ~/Library/Application Support/Firefox/Profiles/xxxxxxxx.default/places.sqlite.

A small example of a places database is provided with the distribution as


History Time Span. Obviously, history databases are much more useful if the history spans longer time than the default 9 days (changed to 180 days in recent versions of Firefox 3). You can set this in the Firefox preferences: Edit -> Preferences -> Privacy: History, Remember visited pages for the last ... days.

Conversion from a Firefox 2 profile. Since you might not want to use Firefox 3 regularly while in alpha status, you can convert history data from a Firefox 2 profile folder, by just invoking Firefox 3 once. The places.sqlite file is then automatically generated, and you can copy it from the Firefox profile folder to some other place. To ensure that your Firefox profile folder is not permanently affected by the one-time invocation of Firefox 3, you can reconstruct it from a backup after quitting Firefox 3, or you can run Firefox 3 as a different user with a copy of your original profile folder.

2. Usage

2.1 Invocation

  1. Start the Web server with
    $ story/bin/
    Optionally a port number can be given as argument to The default port is 2210.

  2. Open the root page of the server in a Web browser. For the default port, its URL is:

2.2 Password Protection

Access to the server is password protected as configured in a password file, which by default is ~/.story/passwd. This is implemented with the basic method of the HTTP authentication of the SWI-Prolog HTTP support library.

2.3 Page Types

The server provides pages of four types:

Control Page

A Control page allows to perform actions like loading places SQLite database files and changing configuration. It also shows information about the status of the system.

The server root points to a Control page.

[Image: Control Page]

Searches Page

The Searches page provides a kind of index or abstract of the entire history by just showing a choice of search terms of performed Google searches and associated date information. Visits are grouped into sessions, as specified with a Control page.

If there already is a browser window displaying the Searches page, this window is re-used, effecting just a re-positioning in that window. Hence we speak of the (instead of a) Searches page. This is implemented with the HTML target attribute.

[Image: Searches Page]

Sessions Page

A Sessions page shows an excerpt of the history in reverse chronological order. Visits are grouped into sessions, as specified with a Control page.

[Image: Sessions Page]

Full History Page

A Full History page is an alternative to Searches and Sessions pages, which combines features of both page types into a single page for the entire history. It is only suitable for small histories, such that Full History pages are not too large for reasonable handling.

Its upper part is like a Searches page, and its lower part like a Sessions page, but for all sessions in the entire history. The image shows the main differences to these page types.

[Image: Full History Page]

Christoph Wernhard (