relax ng to dtd and xsd using the open toolkit · relax ng to dtd and xsd using the open toolkit...
TRANSCRIPT
![Page 1: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/1.jpg)
RELAX NG to DTD and XSD using the Open Toolkit
Using RELAX NG for DITA shells and modules
28/11/14 Contrext, LLC 1
Eliot Kimber Contrext, LLC
DITA OT Day Munich 2014
![Page 2: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/2.jpg)
About the Author • Responsible for DITA 1.3 grammar files • Independent consultant focusing on DITA analysis, design, and implementaMon
• Doing SGML and XML for cough 30 years cough • Founding member of the DITA Technical CommiPee • Founding member of the XML Working Group • Co-‐editor of HyTime standard (ISO/IEC 10744) • Primary developer and founder of the DITA for Publishers project
• Author of DITA for PracMMoners, Vol 1 (XML Press)
28/11/14 Contrext, LLC 2
![Page 3: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/3.jpg)
Agenda
• A brief demonstraMon • What is RELAX NG? • RELAX NG and DITA • DITA document types and modules • Anatomy of a RELAX NG shell • See how easy: generaMng DTD and XSD shells
28/11/14 Contrext, LLC 3
![Page 4: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/4.jpg)
Executive Summary
• RELAX NG makes XML vocabulary definiMon much, much easier
• RELAX NG is a good match to DITA requirements
• Can generate conforming DITA DTD and XSD files from RELAX NG
• Makes creaMng DITA document type shells about as easy as it can be
• No more need to fight with DTD or XSD syntax
28/11/14 Contrext, LLC 4
![Page 5: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/5.jpg)
Demonstration
• Create a new document type shell • Create a new domain specializaMon • Create a new topic speicalizaMon • Generate DTD and XSD versions of all of these grammars
28/11/14 Contrext, LLC 5
![Page 6: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/6.jpg)
WHAT IS RELAX NG?
28/11/14 Contrext, LLC 6
![Page 7: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/7.jpg)
RELAX NG is
• A grammar (or schema) language for XML documents
• An OASIS and ISO/IEC standard (ISO/IEC 19757-‐2)
• Most like XML DTDs but easier to use • Designed to be as simple as possible • Used for other XML standards, most prominently DocBook
28/11/14 Contrext, LLC 7
![Page 8: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/8.jpg)
RELAX NG Basics • RELAX NG has both an XML and character-‐based syntax:
<grammar> <start> <ref name=“concept.element”/> </start> … </grammar> ______________________________________ grammar { start concept.element … }
• The two are funcMonally equivalent
28/11/14 Contrext, LLC 8
![Page 9: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/9.jpg)
RELAX NG Basics (cont.)
• A RELAX NG grammar defines a set of “paPerns” that documents must match
• PaPerns can have names (analagous to DTD parameter enMMes)
• PaPern combinaMon mechanisms are more flexible than DTD parameter enMMes or XSD groups
• Grammars can be modularized into mulMple files
28/11/14 Contrext, LLC 9
![Page 10: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/10.jpg)
RELAX NG AND DITA
28/11/14 Contrext, LLC 10
![Page 11: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/11.jpg)
Good Match to DITA Requirements
• RELAX NG’s paPern-‐based approach works well with DITA’s modular vocabulary
• PaPerns can allow extension by other paPerns • PaPerns can unilaterally extend other paPerns: the extending paPern names the paPern it extends
• Makes combining vocabularies as easy as it could be
28/11/14 Contrext, LLC 11
![Page 12: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/12.jpg)
No Added Overhead
• Unlike DTDs, RELAX NG has much simpler and easier-‐to-‐use syntax
• Avoids the conceptual and syntacMc complexity of XSD
• Close semanMc match to exisMng DTD-‐defined rules
28/11/14 Contrext, LLC 12
![Page 13: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/13.jpg)
Does require DTD Compatibility Feature
• Base RELAX NG standard does not provide for defining aPribute defaults
• Companion standard RELAX NG DTD Compa0bility provides aPribute defaults
• DITA depends on default aPribute values • George Bina (oXygenXML) has implemented DTD compaMbility in Java for use with Xerces XML parser (open source)
28/11/14 Contrext, LLC 13
![Page 14: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/14.jpg)
Result: Everything is Awesome
• RELAX NG makes DITA document type shells as easy to create as it can be
• Can generate DITA-‐conforming DTDs and XSDs from the RELAX NG grammars
• Makes it possible, if not in fact easy, for anybody to configure their own DITA document types
28/11/14 Contrext, LLC 14
![Page 15: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/15.jpg)
DITA DOCUMENT TYPES AND SHELLS
28/11/14 Contrext, LLC 15
![Page 16: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/16.jpg)
DITA Document Types
• A DITA document type is a unique set of vocabulary and constraint modules
• Modules are invariant – Every copy of a given module should be idenMcal – You never modify modules directly
• You implement DITA document types by integra0ng vocabulary and constraint modules using a document type shell
28/11/14 Contrext, LLC 16
![Page 17: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/17.jpg)
Document Type Shells
• Integrate modules to form a working document schema
• Refer to the vocabulary and constraint modules of the DITA document type
• Do any configura0on required • Two document type shells that integrate the same same set of modules implement the same DITA document type
28/11/14 Contrext, LLC 17
![Page 18: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/18.jpg)
ANATOMY OF A RELAX NG SHELL
28/11/14 Contrext, LLC 18
![Page 19: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/19.jpg)
Shell for Base Topic Document Type (basetopic.rng)
<grammar xmlns=http://relaxng.org/ns/structure/1.0 xmlns:dita="http://dita.oasis-open.org/architecture/2005/" xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"> … <div> <a:documentation>ROOT ELEMENT DECLARATION</a:documentation> <start combine="choice"> <ref name="topic.element"/> </start> </div> <div> <a:documentation>DOMAINS ATTRIBUTE</a:documentation> <define name="domains-att"> <attribute name="domains" a:defaultValue=”(topic topic) (topic hazard-d) (topic hi-d) (topic indexing-d) (topic ut-d) (topic hazard-d)”/> </define> </div> <div> <a:documentation>MODULE INCLUSIONS</a:documentation> <include href="topicMod.rng"> <define name="topic-info-types"> <ref name="topic.element"/> </define> </include> <include href="hazardstatementDomainMod.rng"/> <include href="highlightDomainMod.rng"/> <include href="indexingDomainMod.rng"/> <include href="utilitiesDomainMod.rng"/> </div> … </grammar>
28/11/14 Contrext, LLC 19
![Page 20: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/20.jpg)
Integration: Just Include the Module
• All you do is include the module you want to integrate: <include href="topicMod.rng"> <define name="topic-info-types"> <ref name="topic.element"/> </define> </include> <include href="hazardstatementDomainMod.rng"/> <include href="highlightDomainMod.rng"/> <include href="indexingDomainMod.rng"/> <include href="utilitiesDomainMod.rng"/>
28/11/14 Contrext, LLC 20
![Page 21: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/21.jpg)
Modules are Self Integrating • Unilaterally extend the base paPerns (from highlightDomainMod.rng):
<define name="hi-d-ph"> <choice> <ref name="b.element"/> <ref name="i.element"/> <ref name="sup.element"/> <ref name="sub.element"/> <ref name="tt.element"/> <ref name="u.element"/> </choice> </define> <define name="ph" combine="choice"> <ref name="hi-d-ph"/> </define>
• Only need to do something special when you need to impose constraints
28/11/14 Contrext, LLC 21
![Page 22: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/22.jpg)
Compare With DTD <!-- ============================================================= --> <!-- TOPIC NESTING OVERRIDE --> <!-- ============================================================= --> <!ENTITY % topic-info-types "topic" > <!-- ============================================================= --> <!-- DOMAINS ATTRIBUTE OVERRIDE --> <!-- ============================================================= --> <!ENTITY included-domains "&hazard-d-att; &hi-d-att; &indexing-d-att; &ut-d-att; " > <!-- ============================================================= --> <!-- CONTENT CONSTRAINT INTEGRATION --> <!-- ============================================================= --> <!-- ============================================================= --> <!-- TOPIC ELEMENT INTEGRATION --> <!-- ============================================================= --> <!ENTITY % topic-type SYSTEM "topic.mod" >%topic-type; <!-- ============================================================= --> <!-- DOMAIN ELEMENT INTEGRATION --> <!-- ============================================================= --> <!ENTITY % hazard-d-def SYSTEM "hazardstatementDomain.mod" >%hazard-d-def; <!ENTITY % hi-d-def SYSTEM "highlightDomain.mod" >%hi-d-def; <!ENTITY % indexing-d-def SYSTEM "indexingDomain.mod" >%indexing-d-def; <!ENTITY % ut-d-def SYSTEM "utilitiesDomain.mod" >%ut-d-def;
28/11/14 Contrext, LLC 22
<!-- ============================================================= --> <!-- DOMAIN ENTITY DECLARATIONS --> <!-- ============================================================= --> <!ENTITY % hazard-d-dec SYSTEM "hazardstatementDomain.ent" >%hazard-d-dec; <!ENTITY % hi-d-dec SYSTEM "highlightDomain.ent" >%hi-d-dec; <!ENTITY % indexing-d-dec SYSTEM "indexingDomain.ent" >%indexing-d-dec; <!ENTITY % ut-d-dec SYSTEM "utilitiesDomain.ent" >%ut-d-dec; <!-- ============================================================= --> <!-- DOMAIN ATTRIBUTES DECLARATIONS --> <!-- ============================================================= --> <!-- ============================================================= --> <!-- DOMAIN EXTENSIONS --> <!-- ============================================================= --> <!-- One for each extended base element, with the name of the domain(s) in which the extension was declared --> <!ENTITY % note "note | %hazard-d-note; "> <!ENTITY % ph "ph | %hi-d-ph; "> <!ENTITY % index-base "index-base | %indexing-d-index-base; "> <!ENTITY % fig "fig | %ut-d-fig; "> <!-- ============================================================= --> <!-- DOMAIN ATTRIBUTE EXTENSIONS --> <!-- ============================================================= --> <!ENTITY % props-attribute-extensions "" > <!ENTITY % base-attribute-extensions "" >
![Page 23: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/23.jpg)
SEE HOW EASY: GENERATING DTD AND XSD SHELLS
28/11/14 Contrext, LLC 23
![Page 24: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/24.jpg)
RNG-to-DITA DTD and XSD Converters
• Generate conforming DTD and XSD shells and modules from DITA RELAX NG modules
• Require DITA-‐specific metadata in the shells and modules
• Maintained by the DITA Community under direcMon of the DITA TC – Eliot writes and maintains the code, the TC determines what the code needs to do to be correct and complete.
28/11/14 Contrext, LLC 24
![Page 25: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/25.jpg)
DITA OT RNG Conversion Plugin
• TC currently provides: – OT plugin for DITA 1.3 grammars: org.oasis-‐open.dita.dita13.doctypes
– OT plugin for RNG conversion: org.oasis-‐open.dita.rng.converter
• Defines transformaMon types: – rng2dtd – Rng2all
• Requires Saxon 9.6+
28/11/14 Contrext, LLC 25
![Page 26: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/26.jpg)
File Organization Requirements • RNG files must be organized in the same way as the TC-‐provided files: – Top-‐level directory to hold all grammars types:
• doctypes/ – Directory named “rng/” for RNG grammars:
• doctypes/rng – Directory for each group of grammars (e.g., one per shell):
• doctypes/rng/indirector – Directory named “rng” under that:
• doctypes/rng/indirectory/rng
28/11/14 Contrext, LLC 26
![Page 27: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/27.jpg)
Running The DTD Generator
• Use transtype “rng2dtd” • Apply transform to file in parent directory containing all RNG modules: – E.g., catalog.xml in your doctypes/rng/ directory
• By default, only generates shells
28/11/14 Contrext, LLC 27
![Page 28: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/28.jpg)
Plugin Parameters
• generateModules=true|false – Default is “false” (only generate shells)
• usePublicIDsInShell=true|false – Default is true
• generateCatalogs=true|false – Default is true
28/11/14 Contrext, LLC 28
![Page 29: RELAX NG to DTD and XSD using the Open Toolkit · RELAX NG to DTD and XSD using the Open Toolkit Using&RELAXNG&for&DITA&shells&and& modules 28/11/14 Contrext, LLC 1 EliotKimber& Contrext,LLC&](https://reader035.vdocuments.mx/reader035/viewer/2022081222/5f7a3507c9b3b26d597bdcc0/html5/thumbnails/29.jpg)
Resources
• RELAX NG specificaMons: hPp://relaxng.org • DITA 1.3 spec: hPp://tools.oasis-‐open.org/version-‐control/svn/dita/spec/
• DITA RELAX NG conversion tools: hPp://tools.oasis-‐open.org/version-‐control/svn/dita/doctypes/tools/relaxng/
• Me: [email protected], hPp://contrext.com
28/11/14 Contrext, LLC 29