6.3.2 Publication Type Definition

6.3.2.1 Introduction

As already mentioned in the overview, a publication type describes how a book is published. If you want to customize this process (most often to change the look of the published books) then you can do this by creating new publication types (do not modify the built-in publication types). In this document we are going to discuss publication types in some more detail.

A publication type is defined by a subdirectory of the publicationtypes directory, which is located at:

For the custom publication types:
<wikidata directory>/books/publicationtypes

For the built-in publication types:
<DAISY_HOME>/daisywiki/webapp/daisy/books/publicationtypes

These two directories are transparently merged: first the publicationtypes directory in the wikidata directory is searched, then the one in the webapp.

The structure of the publication types directory is as follows:

publicationtypes/
  <name publicationtype>/
    publicationtype.xml
    sitemap.xmap
    properties.xml
    i18n/
    document-styling/
    ...
  common/
    i18n/
    properties.xml
  common-html/
    (files shared by the default HTML publications)

Each subdirectory of the publicationtypes directory which contains a publicationtype.xml file is considered to be a publication type. The name of the directory is the name of the publication type. Next to the publicationtype.xml file, the subdirectory can contain other resources such as XSLT stylesheets, a Cocoon sitemap, resources such as CSS files and images, etc.

Remember that a publication type can be customised by properties. The default properties are defined in the optional file properties.xml in the publication type directory. Properties which are common for all publication types can be defined in the common/properties.xml file. The properties used when executing the publication type are a combination of the common properties, the default properties, and the properties specified when starting the publication process.

The common-html directory contains some files that are shared between the two built-in HTML publications (html-one-page and html-chunked).

6.3.2.2 Creating a new publication type

To create a new publication type, simply start by duplicating one of the existing publication type directories (html-one-page, html-chunked or pdf).

When duplicating one of the HTML publication types, you will most likely also want to modify the files part of the common-html directory. Therefore, copy the contents of the common-html directory also into your new publication type directory. Then search for occurrences of the string "../common-html/" in the publicationtype.xml and sitemap.xmap files of the new publication type, and remove them. For example, a line like the following:

    <copyResource from="../common-html/resources" to="output/resources"/>

should be modified to:

    <copyResource from="resources" to="output/resources"/>

Next, edit the file publicationtype.xml and change the content of the <label> element to something appropriate.

When this is done, you can already try out the new publication type (which will do exactly the same as the one you copied it from).

6.3.2.3 Customizing the publication type

The publication process of a publication type is described in its publicationtype.xml file. It consists of a number of actions, which are executed one after the other. A description of these actions can be found here.

However, most often you will not need to modify that, since the layout of the books is mostly determined by the XSL stylesheets.

6.3.2.4 Publication properties and book metadata

During the book publishing, it is possible to access the publication properties and the book metadata, e.g. from the XSLTs. This way, the behaviour of a publication can be parameterised. The default publication types include examples of how to access these (or as always, just ask on the mailing list if you need more help).

6.3.2.5 Publicationtype.xml syntax

<publicationType xmlns="http://outerx.org/daisy/1.0#bookpubtype">
  <label>HTML</label>
  <startResource>output/index.html</startResource>
  <requiredParts partTypeNames="..."/>
  <publicationProcess>
    [... sequential list of tasks to be executed ...]
  </publicationProcess>
</publicationType>

The startResource is the resource that will be linked to to view the output of the publication type. This information is needed because the output of the publication process can consist of many files (e.g. for the chunked HTML publication type).

The requiredParts element is optional, and can specify for which parts the binary content should be downloaded during the dataretrieval step of the book production. By default this is only done for images. The partTypeNames attribute can contain a comma-separated list of part type names. It is also possible to implement more advanced behaviour for this, by specifying a class attribute which refers to an implementation of this interface:

org.outerj.daisy.books.publisher.impl.dataretrieval.PartDecider

In this case the partTypeNames attribute becomes irrelevant. You can add other attributes to the requiredParts element, and if your implementation of PartDecider has a constructor taking a Map as argument, the attributes will be provided via this map.

The content of the <publicationProcess> element describes the task to be performed for publishing the book, see the task reference.