browser-history web page

# The `browser-history` web page

This page describes the utility browser-history, a client-side X daemon maintaining a browser-independent global history of all the web sites you visited.

On this page ( http://www.inria.fr/koala/colas/browser-history) you will find:

- Introduction
- Quick usage guide
- Sample result see what the log will look like
- Installation guide
- Reference Manual
- How to download it (current version: v2.7, of 20-Jul-2000)
- Supported browsers (and how to add support for it)
- what's new on these pages, history of changes (last updated 20-Jul-2000)

# Introduction

Browser-history came from the will to overcome a Netscape bug: there was no global history, and if you close a window, its whole history is lost. For people browsing lots of sites, having a possibility to track back where one has been before means that you dont have to put everything in your bookmarks file. If you are not sure if a site may be worth remebering, don't add it in your bookmarks. If you need it later, just browse your history files.

Later, it came to our minds that this also could be a valuable add-on to people writing experimental browsers, so they dont have to add this functionality to their browser itself, and to users able thus to track their web history regardless of the browser they used.

Browser-history is a small and efficient daemon. Real user services could be built on top of the log files it maintains for more possibilities (graphical representation, advanced search options, collective histories). It can be seen as a quick-and-dirty hack wrt to the general solution of using a personal proxy to provide this history and housekeeping facilities. But in the meantime, it is easy to use and it works.

And now that Netscape has a semi-decent history, browser-history is still valuable, as it is difficult to search in the netscape history, its file format is not defined, and entries expire after some time.

## Author

Colas Nahaboo, Koala project.

## License: Open Source

The X distribution license: you can do everything with this code (selling it, modifying it), except suing me or using my name in your advertisements, or expecting any kind of support or guarantee.

# Quick usage guide

Just run the program each time you launch your X server. Just add the following line into your .xinitrc or equivalent startup file:

> browser-history &

# Installation guide

Compilation is straigthforward. See Makefile, but normally, just typing `make` is sufficient. It only uses Xlib and Xmu, not Xt. You must just install the resulting binary "browser-history" somewhere in your PATH. I tested it on linux, DEC alpha OSF/1, SGI, sun solaris 5.5, sun sunos 4.1.3.

# Sample result

You can then open with your browser the URL:
`file:$HOME/.browser-history/history-log.html`
(replace $HOME by your homedir), and you will see:

| # Tuesday 28 May 1996 Colas's home page http://www.inria.fr/koala/colas/ 1996/05/28-08:38:34 0x6004a64 Jean-Michel's home page http://www.inria.fr/koala/jml/jml.html 1996/05/28-08:42:07 0x6004a64 phk's home page http://www.inria.fr/koala/phk.html 1996/05/28-10:22:32 0x6004a64

You can click on the listed URLs to go back to them, each entry is listed with the page name in bold, followed by the clickable URL, then the date and time you loaded it, and the X ID of the browser window.

An horizontal rule indicates that at least one hour separates two entries. A file holds one week of history, past weeks are accessibles via links at the top of the page.

# Reference Manual

browser-history logs in `~/.browser-history/history-log.html` all the URLs you went through. You can then browse the log under Netscape or other browsers via the URL: `file:~/.browser-history/history-log.html` (replace the ~ by your home directory)

browser-history tracks automagically all already present browser windows, and all new ones created in the future. This program has no user interface. It just appens information to a log file in html format so you can browse it through a web browser. If more that one hour has passed since last entry, it draws an horizontal lines, and adds H1 headers to delimit new days. Each week (sunday mornings), it archives the week history, compresses it by gzip (that you must have in your path), and starts a new history with links to the older ones. To make room you can just remove the obsolete history files.

This version works with Netscape, Arena and Amaya.

URLs can be excluded from logging by putting them, one per line in the file ~/.browser-history/history-log.exclude. Then, if an URL begins with a line from this file, it is not logged. In this file, empty lines or lines beginning by # are comments This file is read once at startup, and re-read when receiving the signal 1. e.g:

        # We exclude local files
        file:
        # Exclude search engines...
        http://home.netscape.com
        http://guide.infoseek.com

browser-history maintains a hidden window on the X display, whose ID is given by the property BROWSER_HISTORY on the root window. If this window is killed, it quits gracefully. On this sub-window the following properties are maintained:

- The same BROWSER_HISTORY property to check that this is actually a browser-history window
- PROCESS, string describing where this process is running, made of null-terminated strings of the form:
  - VERSION=version_number (= 1000 * major + minor)
  - DATE, e.g: DATE=1996/05/28-10:08:26
  - MACHINE=host name
- LAST_URL, string describing the last entry added to the log, made of null-terminated strings of the form:
  - URL=last_url_logged
  - TITLE=its_document_name
  - DATE=the_date_it_was_logged_at
  - BROWSER_WINDOW_ID=the_X_ID_of_the_browser_window
- LAST_POS (since v2.7) a text property containing the index (ascii number) * of the last updated position in the current log file. This allows * external processes to read the log file and stop at the logical end * in case they read just while we are appending. Can be -1 if not defined

You can customise the header of the newly created weekly log files by putting the header you want to use as an `header.html` file in the `~/browser-history` directory. The default header is the first part of a newly generated file upto the line:

    <!-- EndOfHeader -->

When browser-history is run, it looks if another one is running, and by default it kills the previous one if it is an older version. Otherwise, it the new one is the same version number or older, it just aborts.

## Options

All options can be given by their first letter: you can specify either -verbose or -v, but you cannot group options, e.g. you must say `-v -k`, but not `-vk`

`-display display_name`
  Specifies X display, otherwise contents of $DISPLAY is used
`-verbose`
  outputs information on what it is doing. useful for debug.
`-Version`
  prints version number and exit.
`-logdir directory`
  which directory to store files into? defaults to ~/.browser-history
`-gzip gzip_filename`
  the complete path to the gzip compressor. Defaults to `gzip`.
  E.g: `-gzip /usr/gnu/bin/gzip`
`-seconds delay`
  if two entries are made are more than `delay` seconds apart, an horizontal rule will separate them, else just a simple line break. Defaults to one hour (3600).
`-replace`
  If there is an already running browser-history on the display, kills it and take its place. Default is to replace it only if the version is older than ours.
`-noreplace`
  If there is an already running browser-history on the display, aborts. Default is to replace it only if the version is older than ours.
`-kill`
  If there is an already running browser-history on the display, kills it, then terminates immediately in all cases.
`-DontGrab`
  Never Grab the X Server, which might cause deadlocks while debugging, when browser-history or gdb tries to print on the grabbed xterm or emacs.

## Specifications of the log files

A log file can have some decorative HTML to represent days, but each entry has the form: (the leading br can also be an hr)

     <b>name</b> <a href="URL">URL</a> yyyy/mm/dd-hh:mn:ss <small>windowid</small>

where the following items are:

- name the name of the document (window title)
- URL its URL
- yyyy/mm/dd-hh:mn:ss year, month number, day number, hour, minutes, seconds. Everything as 2-digit numbers, except year (since v2.5)
- windowid the X window ID of the browser window, in hexadecimal

Note: Before version 2.4, the 4 sub-parts were separated by newlines, but since 2.4, they are only blank-separated to ease searching for URL in log files via "grep".
Note:Before version 2.5, the year was stored in 2 digits. Now it is stored in 4 (or more :-) digits, to fix this Y2K bug
Note:Since version 2.6, you should skip the header by searching for the string `<!-- EndOfHeader -->` and parse entries till the end, the last one being possibly incomplete in case of concurrent update (you can check the LAST_POS property if you want to avoid this problem)
The logic is thus to parse log files made after mid-97 (v 2.4) is to open the log, and:

1. Skip beginning up to string `<!-- EndOfHeader -->`
   If not found, skip to first `<hr><p><h1>`
2. now position to next entry beginning with `r> <b>` at position A. If we cannot find one, we are done.
3. verify that the entry is valid by checking that a string `</small>` exists at position B before the end of file
4. process the entry that is being offsets A and B
5. repeat last 2 steps

# How to download it

By ftp on ftp://koala.inria.fr/pub/browser-history

# Supported browsers

Currently supported browsers are:

- Netscape, all unix versions
- Arena, since spring 1996
- Amaya, since october 1996 (v0.9)

## How to add support in the browser

You can add support for browser-history in any browser. See for instance the description of the Arena client communication system.

Just add on each browser window a string X property named `BROWSER_HISTORY_INFO` (and type `XA_STRING`) of the form (C printf string below):

    "URL=%s\0TITLE=%s\0\0"

where the first %s is the current URL, and the second the document name.

IMPORTANT! This property MUST be present and MUST contain some value BEFORE mapping (managing) the window, for browser-history to detect it. Otherwise, your browser windows will be ignored. If this proves too difficult for you, you can make the detection of your browser windows built-in in browser-history, search the string BT_AMAYA and add cases for your browser, and send me the patches.

Example from arena: each time a new URL is visited, it triggers this function on the window displaying the document at the same time as it updates the X window title by a call to `XStoreName(dpy, win, title)`.

    void SetXProperties(	    /* sets info for browser-history on each new URL */
        Display *dpy,	    /* the X display */
        Window win,		    /* the main document display window */
        char *url,		    /* the URL being visited */
        char *title)	    /* the <TITLE> of the document */
    {
        static Atom property_name = 0;
    	                                    /* 13 is strlen("URL=0TITLE=00") */
        int v_size = strlen(title) + strlen(url) + 13;
        char *v = (char *) malloc(v_size);	/* or alloca, but dont call free */
        sprintf(v, "URL=%s%cTITLE=%s%c", url, 0, title, 0);
        if (!property_name)
    	property_name = XInternAtom(dpy, "BROWSER_HISTORY_INFO", False);
        XChangeProperty(dpy, win, property_name, XA_STRING, 8, PropModeReplace,
    			v, v_size);
        free(v);
    }

# News

History of changes, both to the browser-history program and to this page:

v2.8 - 24-Jul-2000
  - bugfix: since 2.6, internal links of default generated headers were false
v2.7 - 20-Jul-2000
  - new X property LAST_POS on the browser-history window to give last valid position in log file
  - summary of use less terse
v2.6 - 08-Jun-2000
  - If a file "header.html" exists in ~/.browser-history, use it as a header to start new history-log files with. Patch contributed by Philippe Le Hégaret
  - Day names have <a> marquers on them to allow jumping directly to them from the header. Patch contributed by Philippe Le Hégaret
v2.5 - 06-Aug-1999
  - In log, links to the previous weeks are now relative (were absolute). Patch contributed by Bert Bos
  - All years in dates (in logs and in previous week filenames) are now on 4 digits. This was a Y2K bug! :-) Patch contributed by Bert Bos
  - Some users edited the netscape binary to remove the leading Netscape: in window names... I had to adapt to it.
v2.4 - 24-Aug-97
  Log entries are now on the same line, to ease grep searches in files.
v2.3 - 14-Feb-97
  bugfix: on creating a new file on sundays, one some OSes (SunOs4+NFS), the list of previous histories was empty. Problem detected and fixed by Hubert CANON
v2.2 - 03-Oct-96
  built-in support of the last Amaya version (new official editor+browser of the web consortium)
v2.1 - 13-Sep-96
  you can add support to your browser without recompiling or restarting browser-history, see Supported browsers
  new option -Version, prints version and exits.
v1.18 - 25-Jun-96
  Past weeks stored most recent first instead of oldest first at top of history file.
v1.17 - 30-May-96
  Works on SunOS and on pure BSD system, where you must add the compilation flag -DBSD or type "make bsd".
  new option -DontGrab for debug.
v1.16 - 28-May-96
  Works even if gzip is not installed, and gzip location settable by the new -gzip option
v1.14 - 28-May-96
  No need anymore for a crontab-run shell script to add day names and week cleanups to the log.
  Web page installed.
v1.6 - 03-May-96
  Directory name changed to "~/.browser-history", was "~/.netscape-history" before...
v1.4 - 15-Feb-96
  Arena implements supports too.
v1.1 - 01-Feb-96
  First version, netscape only.

Back to table of contents