Chapter 1. How to install Annotate

Table of Contents

Prerequisites
Requirements on the authoring station
Requirements on the web server
Getting the software
Configuring Annotate
Converting your document
Configuring the CGI part
Check the result
If it does not work

Prerequisites

Annotate does two things:

  1. It converts your DocBook document into modified HTML. This can be done on any machine, for example on a workstation where the document itself is edited. In the following, this machine is called the authoring station (see also the upper part of Figure 1, “How Annotate Works”).

  2. It merges the HTML documents and the annotations into a new HTML document. This is done on the web server (see also the lower part of Figure 1, “How Annotate Works”).

The authoring station and the webserver can be the same machine, but they can also be separate machines. Their requirements of course differ.

Requirements on the authoring station

Requirements on the web server

  • The web server must support the CGI interface and the PATH_INFO variable. Apache will do just fine, for example. Microsoft IIS however does not seem to support PATH_INFO, so Annotate will not run with this web server.

  • Perl 5 or higher

  • Any database system which is supported by the Perl DBI, for example MySQL or Postgres (see below).

    By default, the installation script will suggest SQLite. The DBD::SQLite module includes a self-contained database engine. If using an RDBMS system is not an option for you, you should consider using SQLite. SQLite only needs file system access and therefore is easy to install and maintain.

  • A few CPAN modules. CPAN, the Comprehensive Perl Archive Network is an archive of software modules written in Perl. Annotate's installation script will check the availability of these modules. The modules needed are the following:

    Note

    Some of these modules depend on additional modules. If you use the install facility of the CPAN module (or the packaging system of your operating system), the dependencies will be handled automatically:

    Example 1.1. Installing the DBI module with CPAN

    perl -MCPAN -e 'install DBI'