rapple configuration guide

rapple looks for control information in a configuration file and searchs for it in the following order:

• the file specified by the -f option on the command line;
• the file specified by the value of the RAPPLE_CONF environment variables;
• a file called rapple.conf in the current working directory.

once located rapple reads the information in the configuration file and uses it to locate necessary directories and processing information. in some cases entries in the configuration file can be overridden by command line options.

as a general rule it is a good idea to maintain a separate rapple configuration for each website that you are building. it is not advisable to set the RAPPLE_CONF environment variable in your shell inialisation script unless you are only ever working on a single website. please note too that all pathnames in your configuration must be absolute. a sample template (rapple.conf) is located in the tarball of the rapple distribution and in the CVS sources.

locating source and web directories

rapple processing sources are drawn from the source directory and are used to produce the final website located in the web directory. both these directories are specified in the configuration file or can be located using the -d and -o command line options respectively (when present the options take priority over the configuration file entries)

<srcdir>/path/to/src/dir</srcdir>
<webdir>/path/to/web/dir</webdir>

rapple places (sensible) restrictions on your choice of source and web directories (e.g., the web directory cannot be located inside the source etc.) and will complain if you have nested or overlapping directories.

configuring logging

rapple stores messages in a logfile which you can look at to learn more about anything that might have gone wrong during processing (if you are investigating problems with your sources you should also look at the output in the datastore too.) you can choose a suitable location for your logfile and adjust the log level by editing the appropriate entries in your rapple.conf file. the following is a description of the log levels used by rapple:

setting a log level to a certain value means that messages at that level or higher are recorded in the logs (e.g., setting the level to 4 means that only errors and fatals are recorded in the logs.) note that if you set the log level to a low value (e.g., 2) then your log files might grow rather fast. unless you have a particular need to audit logs you may wish to delete your logfiles periodically.

tip: if you do not want any logs recorded at all then you can disable logging entirely by setting the logfile to /dev/null

configuring the datastore

the datastore is where rapple stores by-products of your website build and is located in the basedir element entry of the configuration file:

<datastore>
<basedir>/path/to/datastore/dir</basedir>
</datastore>

the contents of the datastore consists of the following subdirectories:

note that the datastore should not overlap with the original website sources (which may be maintained elsewhere) or the final website. the contents of the datastore can be deleted using the -x command line option.

tip: the conversion of source into XHTML is performed by Tidy, a very useful HTML parser. you can learn a lot about (X)HTML by reading the warnings and errors generated by Tidy, these are also useful as feedback to authors.

configuring tidy (optional)

if you are already familiar with the HTML Tidy tool then you may want rapple to use your settings instead. to do so simply the tidy config entry in the rapple.conf to locate your Tidy configuration file. a sample file (tidy.conf) with the settings used by rapple is provided in the distribution. note: you should only override the (sensible) rapple tidy settings if you are very familiar with tidy and have good reasons to prefer your own configuration!

configuring the XSLT location and website domain parameter

the template section of the configuration file deals with matters related to XSLT processing. for example the location of the XSLT used to style your website must be specified in the tmplXSLT child of template and the domain of your website can be stated in the domain child of template.

<template>
<domain>http://localhost/mysite/</domain>
<tplXSLT>/path/to/xslt/file</tmplXSLT>
</template>

during XSLT processing rapple passes the stylesheet an optional host parameter (which bears the value of the domain element) that can be used to resolve links in the output (e.g., to state full URLs for images, CSS and other resources in the output.) the following extract from an XSLT shows how the host parameter is declared:

<?xml version="1.0" encoding="iso-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:param name="host"/>

...XSLT Contents...

<xsl:stylesheet>


the XSLT parameter, host, can be accessed elsewhere in the document as shown in the following example where it is used to fix the location of the CSS file:

<link rel="stylesheet" type="text/css" href="{$host}rapple.css"/>

the XSLT used to generate this website (rapple.xsl) along with the XSLT implementation of context highlighting (found in librapple.xsl) contain examples of how to use an XSLT with rapple. other examples can be found in the resources module of the CVS.

configuring XSLT cataloging (optional, for libxslt only)

libxslt provides an entity resolution mechanism known as a catalog. if you are using libxslt and wish to make use of the catalog then you must state the location of the catalog directory in the configuration file:

<catalog>/path/to/catalog/dir</catalog>

as a convenience the libxslt catalog files are provided in the rapple distribution or are available from CVS sources.

configuring indexing (optional)

rapple can index the contents of directories to automatically generate index.html files (warning: the generated index.html replaces any existing index.html file!). this is useful if you have a directory that is acting as an archive and you simply wish to be able to link to individual files. you can configure which directories you wish to have indexed by adding an "digest" entries under the "generators" element of the configuration file. the "digest" element acts as a container for the "dir" elements that determine which directories are to be cataloged. the value of the "dir" element is the absolute path to the directory to be cataloged and the value of the title attribute is the display title (and document title) of the index.html file.

<generators>
<digest>
<dir title="Index Title" >/path/to/catalog/dir</dir>
</digest>
</generators>


configuring mysql (optional)

rapple has built-in support for the MySQL database that enables the storage of metadata gathered whilst processing your website to be stored in a database table (the table itself is emptied at the start of each site build). in order to ensure support is present rapple must have been built with the --enable-mysql option.

you must also have a local instance of MySQL running and already have created the necessary tables using the SQL scripts contained in the distribution and the CVS sources, these scripts can be invoked from within your MySQL instance using the source command (see MySQL documentation for further information).

the database must be configured in the configuration file so that rapple knows which database instance, host and port to use and which credentials are used to access it. if security is a concern then appropriate file permissions need to be applied to the configuration file which must be owned by the user running the rapple process. the following configuration concerns to rapple defaults.

<database>
<dbname>rappledb</dbname>
<host>localhost</host>
<port>3306</port>
<username>rpl_user</username>
<password>rpl_pwd</password>
</database>


testing your configuring

you can test your configuration by issuing the following rapple command:

%rapple -cf /path/to/rapple.conf

examining your configuration.
configuration file is well-formed!

source dir......../home/joesoap/html/src
web dir.........../usr/local/www/html/mysite
config file......./usr/local/rapple/conf/rapple.conf
logfile.........../usr/local/rapple/log/rapple.log
loglevel..........3 (WARNING)
datastore........./home/joesoap/html/ds
tidy conf.........None defined! Using system defaults.
domain............http://localhost/
xslt............../usr/local/rapple/xslt/rapple.xsl
the following directories will be indexed:
..................reports/annual
..................news
MySQL support.....disabled

done! please check that the above values are what you expect.

%

if you have an error in your configuration which results in a file that is not well-formed then you will receive an error similar to the following:

Error: configuration file is not well formed!
mismatched tag at line 9