======DIG Proof of Concept in DocBook======

Tina Ji, Karen Collier, [[mailto:jbuhler@sitka.bclibraries.ca|Jeremy Buhler]]

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

  * [[http://docs.sitka.bclibraries.ca/Sitka/current/html/|HTML version]]
  * [[http://docs.sitka.bclibraries.ca/Sitka/current/pdf/Sitka_Training_Manual.pdf|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/6tzqupq2764xoyx2]]
  * [[http://markmail.org/message/pumtsszknka55zcu|http://markmail.org/message/pumtsszknka55zcu]]

Jeremy Buhler - July 6, 2010

**Note:** the links below are no longer active

=====Overview=====


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. 

  * [[http://coconut.pines.bclibrary.ca:21080/docbook/DIG/DIG_plain/en/|HTML output, plain]]
  * [[http://coconut.pines.bclibrary.ca:21080/docbook/DIG/DIG_styled/en/|HTML output, styled with CSS]]
  * [[http://coconut.pines.bclibrary.ca:21080/docbook/DIG/DIG_plain/en/DIG_docbook.pdf|PDF output]]


=====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.

{{dig_source_tree.jpg}}

A [[http://coconut.pines.bclibrary.ca:21080/docbook/DIG/DIG_zip/DIG_source.zip|.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) 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).

=====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 [[http://coconut.pines.bclibrary.ca:21080/docbook/DIG/DIG_source/DIG_elements.xls|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 [[http://coconut.pines.bclibrary.ca:21080/docbook/DIG/DIG_styled/en/sitka.css|here]].