This is an old revision of the document!
Table of Contents
DIG Proof of Concept in DocBook
Tina Ji, Karen Collier, Jeremy Buhler
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.
File structure
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.
Transform info
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) thehtml.stylesheet
parameter was set tositka.css
. - Source image files were sized to a maximum width of 850px. All
imagedata
tags have the attributescale="60"
which scales images to 60% their actual size, required only for PDF output. To preserve full image size for HTML output the boolean parameterignore.image.scaling
was set to1
(true).
DocBook elements
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.
CSS Markup
Links to the sitka.css
stylesheet were added to HTML output using the html.stylesheet
transformation parameter. This sample stylesheet is available here.