title: Configuration of PubTal
subject: Documentation of PubTal configuration options.

All configuration is held in a single file, with all directory and file references relative to the directory containing the configuration file.  For example, if you have a configuration file <i>new-site/site.config</i> such as:

<pre><code>&lt;SiteConfig&gt;
content-dir src
&lt;/SiteConfig&gt;
</code></pre>

then the content will reside in the directory <i>new-site/src/</i>.

Three different configuration directives are supported:

<ul>
	<li>Content - Configuration options set under this directive apply to the content of the website.</li>
	<li>Template - Configuration options set under this directive apply to the templates used in the website.</li>
	<li>SiteConfig - Global configuration options are set under this directive.
	<ul><li>Upload - Several of these directives can be present under the SiteConfig directive.</li></ul></li>
</ul>

<h2>&lt;SiteConfig&gt;</h2>
If used, this directive <b>must</b> be the first directive in the configuration file.  It controls site-wide configuration.

<div class="configOptions">
<h3>content-dir <i>dir</i></h3>
Sets the location of the content directory to <i>dir</i>.  Defaults to "content".

<h3>dest-dir <i>dir</i></h3>
Sets the location of the destination directory to <i>dir</i>.  Defaults to "dest".

<h3>template-dir <i>dir</i></h3>
Sets the location of the template and macro directory to <i>dir</i>.  Defaults to "template".

<h3>ignore-filter <i>regex</i></h3>
Adds a regular expression to the filter list of files to ignore when looking for content to publish and upload.  For example, to ignore CVS and backup files (.txt~), add the lines:
<pre><code>ignore-filter .*?CVS.*
ignore-filter .*~$
</code></pre>

<h3>character-set <i>encoding</i></h3>
Sets the default character set that will be used for all templates and content across the site (can be overridden by the Content and Template directives).  Defaults to ISO-8859-15.

<h3>additional-plugins-dir <i>dir</i></h3>
Adds an additional directory to be searched for PubTal plugins.

<h3>pubtal-data-dir <i>dir</i></h3>
Sets the name of the directory that PubTal uses to store site information.  This directory is used internally by PubTal to store the state of the site, and so determines which (if any) files need to be uploaded.  Defaults to PubTalData.
</div>

<h2>&lt;Upload&gt;</h2>
Several Upload directives can be nested inside the &lt;SiteConfig&gt; directive.  They specify an upload destination which PubTal can upload content to.  An example of two different upload destinations is:
<pre><code>&lt;SiteConfig&gt;
  &lt;Upload&gt;
  host localhost
  username user
  &lt;/Upload&gt;
  &lt;Upload&gt;
  host remotehost
  username remoteuser
  &lt;/Upload&gt;
&lt;/SiteConfig&gt;</code></pre>

The following Upload options are available:

<div class="configOptions">
<h3>method <i>methodname</i></h3>
The upload method to use, defaults to FTP.

<h3>host <i>hostname</i></h3>
Specifies the hostname of the upload location.

<h3>username <i>username</i></h3>
The username to use when logging into the FTP site.

<h3>password <i>password</i></h3>
The password for the FTP site.  This is optional; the uploadSite.py command will prompt for the password if it is not specified in the configuration file.

<h3>base-dir <i>dir</i></h3>
The directory that the website should be placed into on the FTP site (e.g. public_html).  Defaults to empty.
</div>

<h2>&lt;Content <i>[directory][file][*.file-extension]</i>&gt;</h2>
The Content directive controls default name-value pairs, the template to use when expanding content, and many other options.  See the later discussion on <a href="#directive-parameters">directive parameters</a> for details of how multiple Content directives interact.

<div class="configOptions">
<h3>content-type <i>type</i></h3>
Specifies that the content should be treated as being of this type.  Here is the list of content types supported by default, although additional content types can be added using plugins:
<ul>
	<li>HTMLText</li>
	<li>OpenOffice</li>
	<li>Catalogue</li>
	<li>Raw</li>
	<li>Binary</li>
	<li>Weblog</li>
</ul>

<h3>class <i>classname</i></h3>
Specifies that this content belongs to a Class called <i>classname</i>.  All content is by default in the "normal" class, and by default the updateSite.py command will build only content that is part of the "normal" class.  By using the --class option however, a user can specify a list of classes that should be built instead.  Additionally the --all option can be used to build all content regardless of the class that it belongs to.

<h3>template <i>templateFile</i></h3>
Set the template (relative to the template directory) that should be used for this content.  Defaults to template.html.

<h3>macro <i>name</i> <i>templateFile</i></h3>
Adds <i>templateFile</i> to the list of macros that will be available.  All macros defined in the templateFile will be available to the template used when building the pages for this content.  Macros are available under the TAL path macros/<i>name</i>/macro-name.  

<h3>header <i>name</i> <i>value</i></h3>
Adds a default <i>value</i> to the header <i>name</i>.  Can be overridden by the name-value pairs set in the content.

<h3>character-set <i>charset</i></h3>
Sets the character set that this content is stored in.

<h3>preserve-html-spaces <i>true | false</i></h3>
Set to false to disable the output of &amp;nbsp; codes, which are used to preserve multiple spaces in content.  Defaults to true.

<h3>url-prefix <i>http://domain-name</i></h3>
When set this will make the "absoluteDestinationURL" property available within the template.

<h3>htmltext-ignorenewlines <i>true | false</i></h3>
Only applies to HTMLText.  Set to true to disable the output of &lt;br&gt; tags for newlines in HTMLText content.  Defaults to false.

<h3>catalogue-index-template <i>templateFile</i></h3>
Set the template (relative to the template directory) that should be used for Catalogue master index pages beneath this directory.  Defaults to template.html.

<h3>catalogue-item-template <i>templateFile</i></h3>
Set the template (relative to the template directory) that should be used for Catalogue item pages beneath this directory.  Defaults to template.html.

<h3>catalogue-max-columns <i>number</i></h3>
Set the maximum number of items to put in a row before starting a new row when populating the catalogue/rows property.  Defaults to 5.

<h3>catalogue-build-pages <i>[item],[index]</i></h3>
Control whether item, master index pages, or both should be built for Catalogue content.  Defaults to item,index.

<h3>catalogue-item-content-type <i>type</i></h3>
Specifies the content type of the items listed in the affected catalogue(s), or disables treating the entries as content if set to "None" (the default).  If a catalogue has catalogue-item-content-type set to anything other than None, it will build individual entry pages using the "page" property which comes from treating the file specified by "filename" as being a piece of content of type <i>type</i>.
</div>

<h2>&lt;Template <i>[directory][file][*.file-extension]</i>&gt;</h2>
The Template directive controls the output type (HTML or XHTML), the character set of the template, and other options.  See the later discussion on <a href="#directive-parameters">directive parameters</a> for details of how multiple Template directives interact.

<div class="configOptions">
<h3>output-type <i>type</i></h3>
Specifies that the template is expecting content to be of a particular <i>type</i>.  Recognised types are:
<ul>
	<li>HTML</li>
	<li>XHTML</li>
</ul>

Defaults to HTML.

<h3>character-set <i>charset</i></h3>
The template is encoded in the given character set.

<h3>suppress-xmldecl <i>true | false</i></h3>
Only applies to XHTML templates.  When set to true, the XML Declaration will be suppressed in the resulting file, useful for IE 6.  Defaults to false.

<h3>xml-doctype <i>doctype</i></h3>
Only applies to XHTML templates.  If pyXML is installed then PubTal will use this to determine the DOCTYPE for the XHTML page.  If pyXML is not installed then this option should be used to set the DOCTYPE.  No default.
</div>

<h2><a name="directive-parameters">Directive Parameters</a></h2>
Both the Content and Template directives take optional parameters.  These parameters are (listed lowest priority first):
<ol>
	<li>A file pattern, e.g. *.txt</li>
	<li>A directory, e.g. test/</li>
	<li>A particular file, e.g. test/example.txt</li>
</ol>

If no parameters are specified then the directive applies to the root directory (i.e. the content-dir or the template-dir depending on the directive type).

If multiple directives apply to the same content or template then they are all used.  If the same option is set multiple times then the parameter with the higher priority takes precedence.  Take for example the configuration snippet:

<pre><code>&lt;Content&gt;
header author Author One
&lt;/Content&gt;

&lt;Content test/&gt;
header author Author Two
&lt;/Content&gt;

&lt;Content test/example.txt&gt;
header author Author Three
&lt;/Content&gt;
</code></pre>

The content file <i>test/example.txt</i> will have the name-value pair "author" set to "Author Three".  Any other content in the <i>test/</i> directory will have the name-value pair set to "Author Two", and all other content in the site will have the name-value pair set to "Author One".

When parameters are set on a directory they are inherited by all the sub-directories as well.  For example content in <i>test/subdir/</i> will also have the name-value pair "author" set to "Author Two".

If an option is set on a directory, and also set on one of its sub-directories, then content in the sub-directory uses the configuration setting of the deeper option.

File patterns can be targetted at a specfic directory.  Take for example a configuration of:

<pre><code>&lt;Content test/*.txt&gt;
header subject Text File
&lt;/Content&gt;
</code></pre>

This will apply the name-value header "subject" to all files ending in .txt within the <i>test/</i> directory, and all sub-directories (e.g. <i>test/subdir/one.txt</i>).
