DIG Proof of Concept in DocBook

Tina Ji, Karen Collier, Jeremy Buhler

The proof of concept below was superseded by Sitka's published Evergreen documentation, available under a Creative Commons license in HTML and PDF:

• HTML version
• PDF version

For more information about Sitka's DocBook including a zip file with source xml see the following messages to the OPEN-ILS-DOCUMENTATION list:

• http://markmail.org/message/6tzqupq2764xoyx2
• http://markmail.org/message/pumtsszknka55zcu

Jeremy Buhler - July 6, 2010

Note: the links below are no longer active

This mock-up Evergreen manual is a sample and proof of concept for the Evergreen Documentation Interest Group (DIG). It is adapted from existing Sitka documentation and an Evergreen glossary. Author and copyright information is not accurate and serves only to illustrate DocBook elements and formatting.

The XML files were written in XMLmind and oXygen XML Editor. Transforms to HTML and PDF were done with the oXygen XML Editor using the Saxon6.5.5 transformer.

• HTML output, plain
• HTML output, styled with CSS
• PDF output

The proof of concept consists of 6 XML files linked from the root file DIG_docbook.xml using xi:include. The file tree mirrors the document structure - the cat directory corresponds to the Cataloguing Part, with one XML file for each section. Media folders contain linked images and screenshots.

To allow for multilingual versions this structure is repeated in parallel directories, one for each English (en) and French (fr). In the French version the text is not translated but xml:lang is set to fr so that headings and links are rendered correctly during the transform. A separate set of stamped images is also used to distinguish the French version.

Below is the source file structure as viewed in the oXygen XML Editor.

A .zip of the source files (XML and media, 2.7Mb) is available for download.

The oXygen XML Editor was used to generate HTML and PDF output using the Saxon6.5.5 transformer with the DocBook - HTML Chunk and DocBook PDF transformation scenarios. To customize output the following two parameters were changed from the defaults in the DocBook HTML - Chunk scenario:

• To link HTML ouptut to the sitka.css file (for the styled version) the html.stylesheet parameter was set to sitka.css.
• Source image files were sized to a maximum width of 850px. All imagedata tags have the attribute scale="60" which scales images to 60% their actual size, required only for PDF output. To preserve full image size for HTML output the boolean parameter ignore.image.scaling was set to 1 (true).

We used a wide range of DocBook elements to illustrate how they render in HTML and PDF transforms. Elements such as <editor>, <collab>, and <bibliosource> are not rendered by default even though they appear in the XML. A list of DocBook elements used in this proof of concept is available for download.

Links to the sitka.css stylesheet were added to HTML output using the html.stylesheet transformation parameter. This sample stylesheet is available here.