The CGI part

The third section of the configuration file configures Annotate's CGI script. This part of the configuration decides where your document and its annotations are stored and what the annotations should look like. The following is a table of all parameters:

Table 3.1. CGI part configuration parameters

ParameterDescription
DocumentRootLike the Apache directive, this specifies the directory where Annotate can find your DocBook document. This path can be given relative or absolute.
DirectoryIndexSimilar to the Apache directive, Annotate looks for this file if the requested address is a directory.
TemplateRootThis should point to the directory containing the templates.

NavigationTemplate

LinkTemplate

AnnotateTemplate

ViewTemplate

MailTemplate

LoginTemplate

These are the file names for various templates. For details, see the section called “Templates”.
DatabaseThis is the data source string for DBI. The database is used to store the annotations of your visitors. Any database which is supported by Perl DBI can be used. Please refer to the Perl documentation for more information.

Example 3.5. DBI configuration using MySQL

DBI:mysql:annotate:mysql.example.com

Example 3.6. DBI configuration using CSV files

DBI:CSV:f_dir=annotations
DatabaseUsernameContains the user name (i.e., login) for the database. Can be left empty if not needed.
DatabasePasswordContains the password for the database. Can be left empty if not needed.
DefaultOutputModeControls how annotations are displayed by default.

Valid modes are:

Hide

Do not show annotations.

Inline

Display annotations inline, directly below the element they belong to.

Link

Create links which display the annotations in a new window.

Each visitor can choose his favorite mode, which is automatically stored in a cookie by Annotate. The default value is therefore only used if the user visits the document for the first time or if there is no cookie.

eMailAddressThis can be set to one (or more, separated by comma) eMail addresses. A notification will be sent to this address if a new annotation is made to any part of the document.

If left empty, no mail is sent.

eMailSubjectThe subject of the notification eMail.
AdminUsernameThe user name for logging in to the administration mode.
AdminPasswordThe password for logging in to the administration mode.
MimeTypesThe location of Apache's mime.types database.