What is Annotate?

Annotate is a system that provides an annotation facility for DocBook documents. Annotate enables visitors of an online version of a DocBook document to add comments (annotations) to any paragraph or chapter of the document.

Annotate extends the DocBook XSL style sheets, leading to a modified HTML output which contains anchors at those places where annotations can be made. Comments and notes are stored in a DBMS. A CGI program then merges the HTML document and the comments to produce the output for the visitor.

Figure 1. How Annotate Works

How Annotate Works

Comments can be made similar to, for example, the online version of the PHP manual. The Annotate interface can be customized: The user can decide which parts of the DocBook document (e.g., figures, chapters, sections or paragraphs) can be annotated.

You can find an online demonstration of Annotate at the online version of this document at http://www.brettnacher.org/users/dominik/annotate/.

Features

Annotate provides the following:

  • A modified XSL style sheet, based on the DocBook XSL style sheets by Norman Walsh.

  • The possibility to decide which DocBook parts may be annotated. Each paragraph may be annotated, or only each chapter as a whole.

  • Different possibilities to show the visitors' annotations. Annotations can be displayed in-line with the original DocBook document, they can be shown on a separate page, or they can be left out.

  • E-Mail notification about newly entered annotations can be sent to the administrator.

  • An interface for the administrator to manage existing annotations.

  • An easily modifiable look and feel through the use of templates.

  • Support for a variety of database backends (such as MySQL or SQLite) using DBI.

  • By default, it uses the SQLite zero-configuration database engine for installation with minimal effort.

  • An interactive perl script for easy installation.

  • Finally, Annotate is platform independent. It is known to work on Linux, FreeBSD, Solaris and Mac OS X. It should also work on any system running Perl 5.6 or higher.