For the impatient:
Download history.py 0.5
Download history-0.5.tar.gz (includes templates)
PyBlosxom home page
PyBlosxom plugin registry
svnpyblosxom (simplified), a related plugin

Updated 2009-02-24.

history.py is a PyBlosxom plugin that displays change history for entries. The change history must already exist, either in a version control system, database, or another form. This plugin just uses that backend to display change history, previous versions of entries, and textual diffs for changes.

As an example, you can see the change history for this page.

Version Control Backends

This plugin is designed to support different version control backends. Currently the only backend is Subversion, but the backend code has been abstracted to make it easy to add new backends.

The history_backend config parameter specifies the version control backend to use. For now, only subversion is supported. Add this line to your config.py:

py['history_backend'] = 'subversion'

To use the Subversion backend, the pysvn module must be installed somewhere in your PYTHONPATH.

Config Parameters

In addition to the history_backend parameter, you may also optionally specify a limit on the number of changes to fetch and display in the change history page. This is set via the history_num_changes parameter, e.g.:

py['history_num_changes'] = 20

New Urls

There are three new types of pages: past versions, change history, and diffs. They are accessed by adding these parameters to entry URLs:

?history=1

Shows the entry's change history as a series of diffs, one for each change.

?version=X

Shows version X of the entry. Depending on your backend, X may be a revision number, a date, a tag, or something else entirely. The Subversion backend supports revision numbers.

?version=X&raw=1

Shows the raw text of version X of the entry.

?diff=1&version1=X&version2=Y

For example, if an entry is located at http://snarfed.org/space/filekicker, you'd use http://snarfed.org/space/filekicker?history=1 to show its change history.

Note that all of the URL parameters require a value. The values for history, diff, and raw can be anything, but they must be present. URLs that omit the value, e.g. http://snarfed.org/space/filekicker?history, will not work.

Templates

The history plugin uses a few new templates, and provides new template variables for them. Template files for the html flavour are provided with this plugin.

history-diff: a diff between two versions of an entry. The text of the diff is provided in the $diff template variable. It's in unified format.
history-version: a previous version of an entry. This will usually be similar to your story template, with minor modifications. For example, you might not provide links to the entry's comments. All template variables available in the story template are also available here.
history-head and history-foot: These are displayed around the change history page. history-head is displayed at the beginning, history-foot is displayed at the end. The body of the page is a series of diffs, one for each change to the entry, rendered with the history-diff template.

Template Variables

These new template variables are provided in the history-diff and history-version templates:

history-diff:
  $diff      The text of the diff, in unified format.
  $version1  The base version of the diff.
  $version2  The ending version of the diff.
history-version:
  $version   The displayed version of the entry.
both:
  $author    The person who made the last change.
  $message   The changelog of the last change.
  $date      The date of the last change.

Diffs should usually be displayed in a fixed-width font, so surrounding $diff with <code> and/or <pre> is strongly suggested.

Some lines will be surrounded with <span class="...">. The class will be diff-added, diff-removed, diff-changed, or diff-line-number, depending on the type of change that the line represents.