DECOR-Publication
Contents
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. Other (optional) XSLT (stylesheets) files can be generated from the schematron files that reports errors and warning etc in textual ssl:message
(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.
- 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
- resources -- contains more CSS, Javascript, images etc. which are used in dataset overview (especially for the expandable tree view and hideable columns).
decor-parameters.xml
This is the basic setup of the decor-parameters.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<decor-parameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://art-decor.org/ADAR/rv/decor-parameters.xsd">
<!-- create Schematron with switchCreateSchematron1 or
don't create (switchCreateSchematron0) -->
<switchCreateSchematron1/>
<!-- create Schematron with HL7v3 messaging wrappers includes
(switchCreateSchematronWithWrapperIncludes1) or don't create
(switchCreateSchematronWithWrapperIncludes0) -->
<switchCreateSchematronWithWrapperIncludes0/>
<!-- create closed qualification quality schematrons (switchCreateSchematronClosed1) or
respect whatever is actually configured (switchCreateSchematronClosed0) -->
<switchCreateSchematronClosed0/>
<!-- create Schematrons with includes only for those that are actually part of the template
(representingTemplate/@ref and/or @flexibility) -->
<switchCreateSchematronWithExplicitIncludes1/>
<!-- create HTML documentation (switchCreateDocHTML1) or
don't create (switchCreateDocHTML0) -->
<switchCreateDocHTML1/>
<!-- create SVG images where applicable (switchCreateDocSVG1) or
don't create (switchCreateDocSVG0) -->
<switchCreateDocSVG1/>
<!-- if the conversion process should create the PDF based documentation the element
<switchCreateDocPDF1>...</switchCreateDocPDF1>; should be present; creating PDF is
skipped with <switchCreateDocPDF0/>. The element content of
this element should contain letters d, s, t, r, and/or i for
datasets, scenarios, terminologies, rules and issues to be
included in the PDF or if omitted, dstri is assumed. -->
<switchCreateDocPDF1>dsntri</switchCreateDocPDF1>
<!-- create DocBook documentation (switchCreateDocDocbook1) or
don't create (switchCreateDocDocbook0) -->
<switchCreateDocDocbook0/>
<!-- use local assets dir ../assets (useLocalAssets1) instead of online
version (useLocalAssets0) on http://art-decor.org/ADAR/rv/assetsvxx/
(xx depends on DECOR2Schematron.xsl) -->
<useLocalAssets1/>
<!-- use local logos dir ../pfx-logos (useLocalLogos1) instead of online
version (useLocalLogos0) on /decor/project/reference + /pfx-logos/ -->
<useLocalLogos1/>
<!-- add a logo to the top right on HTML pages, optionally with a URL
(useCustomLogo1) or don't add (useCustomLogo0) -->
<useCustomLogo0 src="../pfx-logos/nictiz.jpg" href="http://pfx.art-decor.org"/>
<!-- If set, decor2html will get overview results using RetrieveTransaction for the
most recent version in project-decor.xml. If absent, current RetrieveTransaction
results will be used. -->
<useLatestDecorVersion1/>
<!-- create artifacts in timestamped directories (inDevelopment0) or
create artifacts in pfx-runtime-develop / pfx-html-develop (inDevelopment1)
while we are just publishing/testing intermediate results-->
<inDevelopment1/>
<!-- override /decor/project/@defaultLanguage with a specific language.
Value ALL activates all languages -->
<defaultLanguage>nl-NL<defaultLanguage>
<!-- If switchCreateDatatypeChecks1 all XML elements with a datatype are
created with an extends in Schematron. Normally left active. -->
<switchCreateDatatypeChecks1/>
<!-- Creates pseudo XML instances in HTML folder -->
<createDefaultInstancesForRepresentingTemplates0/>
<!-- Customizations to be used in RetrieveTransaction. May contain attribute
@hidecolums, which contains columns to be hidden when calling RetrieveTransaction. -->
<useCustomRetrieve1/>
<!-- URI for ART-DECOR, e.g. http://art-decor.org/art-decor/.
MUST end with a /. The value is used to build the URI to the
live project for example to get to full issue details.
If you do not set it here, we will try decor/@deeplinkprefix
which gets set through project compilation, if that
has no value, and you do not supply it directly to
DECOR2schematron (e.g. through the ADRAM service),
the value is empty and links will not work -->
<artdecordeeplinkprefix>http://x.y.z</artdecordeeplinkprefix>
<!-- bindingBehavior determines the binding behavior for the
schematron engine and influences schematron generation:
freeze
The schematron engine generates code for dynamically bound value sets
by treating the most recent version at the time of generation as
static (freeze the most recent version and treat it as if it was declared static)
preserve
The schematron engine generates code for dynamically bound value sets
by using the actual most recent version at the time of validation and
therfore create true value set look-up code to retrieve the recent version
from the ART-DECOR terminology service (preserve the real most recent
version and treat it as such) -->
<bindingBehavior valueSets="freeze"/>
</decor-parameters>
Recommended Procedure
The recommended procedure for publication is as follows:
- Make sure your DECOR file is consistent. This may sound obvious, but better to overstate it.
- 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.
- Retrieve the decor file (for instance with RetrieveProject) for local generation of schematron, HTML docs etc. Use:
- decor-parameters.xml -- useLocalAssets1, useLocalLogos1, inDevelopment0
- When you intend to publish intermediate output to test you could opt to switch to a development build using
- decor-parameters.xml -- inDevelopment1
- 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
- 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
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.