DECOR-Publication

This is documentation for ART-DECOR Release 2 and tends to be out-dated. Please visit our new documentation site at docs.art-decor.org

Introduction

DECOR definitions may be exported into various formats. You may export into any format and any layout you need. DECOR comes with many predefined exports with the toolset, all conveniently accessible from one main stylesheet, and configurable through a parameter file. This page explains how to set up client-side publications and how to make it work for your purposes. Please note that ART also supports server-side publications, see ART Project Editor.

Available formats

Possible export formats (supported by the DECOR core scripts from SourceForge) are the following.

HTML

This method documents everything in the DECOR project at conversion time ("frozen" release)

Schematron

This method creates ISO Schematron with XSLT 2.0 query binding. These are useful for validating instances that are based on the specification; (optional) XSLT (stylesheets) files are generated from the schematron files that are useful for environments where native Schematron file processing is not possible. SVRL is short for Schematron Validation Reporting Language (see: http://schematron.com) and reports in an XML structure suitable for processing in other logic. See Schematron validation for information on how to use those. Other (optional) XSLT (stylesheets) files can be generated from the schematron files that reports errors and warning etc in textual ssl:message

PDF

(finalized, available upon request only, in production for several projects)

The prepared HTML output is translatable into a PDF booklet. It uses Prince as the conversion mechanism as DECOR makes use of some special CSS features that are not correctly transformed by some CSS parsers.

For further information see documentation on PDFs, Wikis and Implementations Guides.

Wiki

(finalized, available upon request only, in production for several projects)

DECOR value sets and templates can be exported into a wiki (MediaWiki) format and directly used in the respective wiki. With that writing of implementation guides that incorporates ART-DECOR rendering of value sets and templates is easily possible.

For further information see documentation on PDFs, Wikis and Implementations Guides.

DocBook

experimental work, assumed not be be finalized; DocBook is an XML based standard that allows conversion into many more formats such as PDF.

Set up

Exporting DECOR into other formats could be done in more ways than described here. The discussed way is the recommended way.

Prerequisites

  • DECOR exports are based on XSLT 2.0. To run any export you'll need an XSLT 2.0 capable processor. Development and testing is done based on Saxon-PE/HE/SE 9.x. XSLT 2.0 support is also into built into tools such as <oXygen/> (Windows/Linux/OSX) and XMLSpy (Windows).
  • Download the DECOR assets folder from Download
  • Create a directory layout resembling the layout below
  • Download your DECOR file from the DECOR server. Currently you may only do this through direct eXist-db access (TODO: add page on how to), but in future versions of ART-DECOR there should be UI options for precompiling and downloading this file.

Directory layout

pfx is your project prefix. Bold is a folder.

Error creating thumbnail: Unable to save thumbnail to destination
Folder layout
  • DECOR
    • assets -- from DECOR transformations, contains CSS, Javascript, images etc. Note that you may add your own CSS etc. into this directory if you need to match the styles common to your environment.
    • pfx-logos -- holds any image configured in DECOR copyright/@logo
    • pfx-decor.xml -- your DECOR file
    • decor-parameters.xml -- contains all parameters for exporting. Name is fixed

DECOR-Publication-Parameters

The basic setup of a publication has parameters documented in the decor-parameters.xml file and described in detail at the DECOR-Publication-Parameters page.

Partial publications (filters.xml)

Projects can become quite large. Over time they build an increasingly vast collection of interconnected artifacts. Artifacts do not always need to be republished upon every publication. Secondly when you are in the process of building new stuff you probably want to see quickly what the net result of your work would look like, e.g. a new transaction (group) with connected dataset/template/vocab.

There currently is a feature that allows consistent filtered publications which leads to a partial publication. The problem with that is, that the publication doesn't let you know in any way that it is not the full set. This may lead to misunderstandings in the audience. We need a more solid way to produce partial publications, where you can later reproduce what was in and what was out of scope for the publication. This probably includes support for filter sets so you can republish with exactly the same filter set as before. Partial publications should then also be labelled as being filtered publications.

This feature now does this: If you have a resource called filters.xml next to your decor project resource in the database, this is picked up. Anything inside is considered "in scope". Anything not inside is out of scope unless called from artifacts in scope. Syntax of filters.xml:

<filters filter="on|off">
   <dataset ref="..."/>
   <scenario ref="..."/>
   <transaction ref="..."/>
</filters>

When this resource is found and @filter='on', the set is inspected against the project. If matches are found, the value sets/templates are then calculated based on terminology associations, template//vocabulary/@valueSet and transaction/representingTemplate/@ref

So for example if you give it a transaction/@ref, the connected dataset and document level template is used. The dataset leads to inherits and terminologyAssociations. The template leads to a chain of contained/included templates each with vocabulary attached. If you feed a scenario, all transactions are checked as above. you may additionally specify to only consider transactions connected to a specific dataset. If you feed only a dataset, connected value sets but no scenarios/templates are in scope.

This is an example setup of the filters.xml file:

<filters filter="on">
   <transaction ref="2.16.840.1.113883.2.4.3.11.60.20.77.4.93"/>
</filters>

Recommended Procedure for local publications

The recommended procedure for publication is as follows:

  1. Make sure your DECOR file is consistent. This may sound obvious, but better to overstate it.
  2. Create a version or release from ART. (Project, tab Versioning.) If one or more languages are checked after 'Compile-save', a compiled version will be stored in eXist (apps/version/{project}/version-{date}. This will make your project is self contained.
  3. Retrieve the decor file (for instance with RetrieveProject) for local generation of schematron, HTML docs etc. Use:
    • decor-parameters.xml -- useLocalAssets1, useLocalLogos1, inDevelopment0
  4. When you intend to publish intermediate output to test you could opt to switch to a development build using
    • decor-parameters.xml -- inDevelopment1
  5. When your DECOR file references any Building_Block_Repository_(BBR) you need to compile your project before transforming (which is done automatically by making a version from within ART).
    • Call decor/services/modules/RetrieveProject.xquery?prefix=pfx-&mode=compiled&language=en-US on your server
  6. Transform your pfx-decor.xml file using DECOR2schematron.xsl.

Example Java call (Windows):

java -jar %saxonPath%/saxon9.jar
  -xsl:http://art-decor.org/ADAR/rv/DECOR2schematron.xsl
  -o:pfx-decor.html -s:px-decor.xml

Example Java call (OSX/Unix/Linux)

java -jar ${saxonPath}/saxon9.jar
  -xsl:http://art-decor.org/ADAR/rv/DECOR2schematron.xsl
  -o:pfx-decor.html -s:px-decor.xml

Example output:

*** Started 21:15:37.964+01:00
*** Reading DECOR parameter file
*** Creating schematrons based on scenario transaction representing templates with wrapper includes if available
*** Benchmarking indicator: 2
*** Creating schematrons
*** Creating terminology files
*** Creating documentation html + svg
*** Finished 
*** Total processing time 0h 0m 14.128s
Error creating thumbnail: Unable to save thumbnail to destination
Folder layout after export

If you created HTML, you will have a file pfx-decor.html next to your pfx-decor.xml file that essentially redirects to the pfx-html-<dateTime>/index.html. If you created Schematron, this will in the folder pfx-runtime-<dateTime> with the main Schematrons being named according to their transaction/@label.

If (and only if) there is a RESTURI for DS/HTML defined in your project: <restURI for="DS" format="HTML">...uri...</restURI> an 'overview' of dataset will be generated for each dataset and transaction, and shown on the 'Dataset' tab of HTML output.

If useLatestDecorVersion1 is set in decor-parameters.xml, a compiled project will be retrieved with RetrieveTransaction from db/apps/version and used to make the overview. If useLatestDecorVersion0 is set, the current projectr will be retrieved. useCustomRetrieve1 can be used to fine-tune the columns in dataset overview output.

Publishing XML-material

A publication page will usually also contain XML-materials not generated from ART-DECOR, such as schema's, wsdl's, XML-examples and other materials. The layout for creating such a set is described on XML material.