Paperboy WDM : <pbwdm:site> DTD

<pbwdm:site> Description

Titania uses an XML file to store configuration information and metadata that is constant across a site or section thereof (like the webadmin's email address, the author, copyright information, etc). This page describes the layout of these <pbwdm:site> files in both general principals and API terms.

The DTD itself can be found at http://pbwdm.sourceforge.net/dtds/pbwdm-site.dtd and its public identifier is "-//PBWDM//DTD pbwdm:site 0.2//EN".

Terminology

The layout of <pbwdm:site> files is somewhat complex but should be easy to learn. It is organized around principals of object-oriented coding, so some of the types of elements described here may resemble classes in object-oriented programming.

Site

Each <pbwdm:site> file describes a single Site, which contains general information about the website including paperboy flags, a list of Databases, a list of Templates, and a single main Subsite.

Nodes

Most of the major elements described here are particular types of Nodes— the notable exception being that a Site is not a Node. (This should not be confused with the XML terminology of the same name.) A Node is a container which contains some basic information like a name, a URI, a file path, a list of children Nodes, and so forth. Of all the different Nodes there are some that are called site Nodes, like Databases and Templates. Site Nodes aren't particularly different than regular Nodes but this name is used to distinguish them from Nodes like Subsites because they behave a bit differently.

All Nodes have a number of child elements which contain information. Some of these are required by Titania, whereas others can be user defined (preferably under a separate namespace like "user:"). These elements are sometimes referred to as variables. One of the design specifications is that these variables should be inheritable, that is, if a given Node does not have the variable in question, then its parent Node is checked, then its grandparent, etc until the variable is found or all the Node's ancestors have been exhausted.

Databases

A Database Node describes a set of XML files which represent a cohesive group of information. At this time they only describe a singleton set of files, but there are two enhancements to this that will be designed.

First, to facilitate internationalization, alternate databases should be allowed which have "parallel" information in them. These parallel databases should be able to refer to some master translation to use if a page is unavailable or outdated in the local translation. The complexities of this should be mostly invisible to viewers.

Second, some databases (especially chronological ones like weblogs) can grow to immense size, but the most relevant information to viewers is localized (e.g. to the newest entries). They should be able to be split up serially into individual files which are smaller for editing and parsing, but which are treated as a single file from the program's and viewer's points of view.

Templates

A Template Node describes a set of XSLT templates which are applied to Databases to create output for presentation.

Templates can have multiple Template Media Nodes (singular: Template Medium) for creating different types of output from the same data. For example, you may want to have a weblog be available in XHTML, RSS, and RDF formats; each of those formats would be a different Medium. One of the Media should be marked as the default.

Subsites

A Subsite Node describes a set of output files (aka pages) obtained by applying a specific Template to a specific Database (a single Subsite can have multiple Media associated with it). A Subsite exists in a hierarchical relationship to other Subsites, unlike Databases and Templates which have a flat organization.

Site

<pbwdm:site>

Attributes: version %pbwdm.version; #REQUIRED, xmlns:pbwdm %pbwdm.uri.att; #REQUIRED

Children: (paperboy?, subsite, templates, databases)

The root element for the XML file. The version should be the version of the DTD being used. The namespace declaration should be "http://pbwdm.sourceforge.net/".

Attributes: none

Children: (verbose | xslt-module | xslt-module-extension)*

This element contains all flags you want to pass to paperboy.

Attributes: none

Children: EMPTY

-v : Turn on verbosity.

<xslt-module>

Attributes: none

Children: %pbwdm.filepath;

-x : Pass a Paperboy module.

<xslt-module-extension>

Attributes: none

Children: %pbwdm.filepath;

-y : Pass a Paperboy module extension.

Attributes: none

Children: (database+)

A container for all Databases.

Attributes: none

Children: (template+)

A container for all Templates.

Node

%pbwdm.node_elem;

This is a list of all the elements that Nodes share in common. In truth, there should only be up to one of each element in any order where absence indicates inheritance. The %user_elements; entity should be defined by the user in their <!DOCTYPE> declaration prior to calling this DTD.

%pbwdm.node_elems;

Value: "(%pbwdm.node_elem;)*"

<name>

Attributes: none

Children: %pbwdm.name;

The name of the Node. This is a short internal name and should be a valid NMTOKEN.

<path>

Attributes: relative (yes|no|name|main) "name"

Children: %pbwdm.filepath;

The path to the file on the local system which is represented by this Node. The attribute relative indicates whether the path is absolute ("no"), relative from its parent Node ("yes"), relative from its parent Node but using the value of <name> instead of the value of <path> ("name"), or relative from the main Subsite Node (using the value of <path>, "main").

<uri>

Attributes: relative (yes|no|path|main) "path"

Children: %pbwdm.filepath;

The URI for the file which is represented by this Node. The attribute relative indicates whether the URI is absolute ("no"), relative from its parent Node ("yes"), relative from its parent Node but using the value of <path> (or <name>) instead of the value of <uri> ("path"), or relative from the main Subsite Node (using the value of <uri>, "main").

<title>

Attributes: none

Children: %pbwdm.string;

A longer descriptive name of the Node.

Attributes: none

Children: (years?, holder, license?)

A container for information regarding intellectual property rights for the current Node.

<years>

Attributes: none

Children: %pbwdm.string;

The years for which the copyright applies.

Attributes: none

Children: %pbwdm.string;

The holder of the copyright.

Attributes: none

Children: %pbwdm.string;

The license of the copyright. This could be "all rights reserved" or an actual license. If you're using something like the GPL which is long, it's suggested that you use some sort of short reference to the license rather than reproduce it in its entirety.

<email>

Attributes: none

Children: %pbwdm.string;

The email address of the appropriate person to contact regarding the current Node. This is usually not important for site Nodes.

Database

Attributes: none

Children: (%pbwdm.node_elems;, db-type, %pbwdm.node_elems;)

This is a Database Node. Other than the required <db-type>, the most important child element is <path> which specifies where the XML database file is located.

<db-type>

Attributes: none

Children: %pbwdm.name;

Provides a name for the type of Database this is. For any Templates this Database is paired with, this must match the Template's element of the same name otherwise an error will be raised.

Template

Attributes: none

Children: (%pbwdm.node_elem; | db-type | entry-name | sort-by | media)*

This is a Template Node. In truth there should be only one of each element but in any order.

<db-type>

See <db-type> under Database.

<entry-name>

Attributes: none

Children: %pbwdm.xpath;

The XPath name of an "entry" in the database. The reason this is under Template rather than under Database is that you may want different Templates for the same Database which have different notions of entries. (e.g. a Database has a list of <categories> which have a list of <items>, each of these might be considered entries by different Templates.)

<sort-by>

Attributes: none

Children: %pbwdm.xpath;

An XPath expression relative from any current working entry which returns a sortable value for that entry.

<media>

Attributes: none

Children: (medium+)

A container for Template Media Nodes.

Attributes: type (index|indiv) "index", default (yes|no) "no"

Children: (%pbwdm.node_elems;, filename, %pbwdm.node_elems;)

A Template Medium Node. The type attribute indicates whether the database should be treated as a single whole document ("index"), or whether each individual entry should be considered a document ("indiv"). The default attribute specifies if this is the default Medium or not. There can be at most one default Medium per Template.

Attributes: none

Children: (#PCDATA)

This element should contain only a <![CDATA[]]>. The content of this element is a Perl subroutine that returns the file name for a given entry in a given Subsite. The arguments to the function are my ($pbwdm, $tmpl, $medium, $subsite, $db_entry) = @_; where $pbwdm is an XML::Paperboy::WDM object, $tmpl is an XML::LibXML::Element object for the current <template>, $medium is a string with the name of the current Medium, $subsite is an XML::LibXML::Element object for the current <subsite>, and $db_entry is an XML::LibXML::Element object for the current database entry. The exact nature of this element is still in a bit of flux.

Subsite

Attributes: none

A Subsite Node. In truth there should be up to one of many of the elements, but all the elements should be allowed in any order.

<db-name>

Attributes: none

Children: %pbwdm.name;

This element should match the <name> of the Database you want this Subsite to use.

<tmpl-name>

Attributes: none

Children: %pbwdm.name;

This element should match the <name> of the Template you want this Subsite to use.

<tmpl-medium>

Attributes: none

Children: %pbwdm.name;

This element should match the <name> of the Template's Medium you want this Subsite to use.

<only-match>

Attributes: none

Children: %pbwdm.xpath;

An XPath expression that for a predicate limiting which database entries are considered part of this site. (So an XPath like //$entry_name[$only_match] is used.) This is under Subsite rather than Template because you may want different Subsites to use different subsets of the same Database even if they use the same Template.

Attributes: none

Children: (subsite+)

A container for child Subsites.