Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen

Spezialisierung in DITA

Jang F.M. Graat !JANG Communication - Amsterdam

Wie machen Sie es, und warum sollen Sie es machen ?

TUT2

Wer Spricht ?

✤ Jang F.M. Graat!

✤ Technische Redaktion!

✤ FM, RH, MadCap!

✤ DITA, XSLT, JS, CSS!

✤ Minimalist!

✤ Psychologe, Philosoph!

✤ Weltbürger in Amsterdam

Tom Aldous

✤ Integrated Technologies!

✤ Adobe (TechCom)!

✤ Acrolinx!

✤ 2-teiliges Webinar “DITA Specialization”

Eliot Kimber

✤ IBM!

✤ Innodata Isogen!

✤ RSI Content Solutions!

✤ Contrext Solutions!

✤ DITA Configuration and Specialization Tutorials!

✤ www.xiruss.org

http://www.xiruss.org

Spezialisierung - Was ist es ?

Spezialisierung ist Alleinstellungsmerkmal von DITA

DITA, also nicht “ITA”

Spezialisierung ≠ EvolutionKeine völlig neue Elemente oder Strukturen

topic

title

shortdesc

prolog

body

p, note, ...

ol, ul, dl, ...

fig, image, ...

table

section

example

bodydiv

related-links

topic

concept

title

shortdesc

prolog

conbody

table

section

example

conbodydiv

related-links

concept

p, note, ...

ol, ul, dl, ...

fig, image, ...

Strukturbezogen SpezialisierungAnpassung der internen Struktur (Elemente, Reihenfolge)

Grundtyp “Zimmer”Erforderlich: Tür, Wände, Boden, Decke. Optional: viele Elemente

Spezialisierung “Schlafzimmer”Erforderlich: Bett. Nicht erlaubt: Küchenmöbel, Büro, Esstisch, ...

Spezialisierung “Esszimmer”Erforderlich: Esstisch, Stüle. Nicht erlaubt: Bett, Kleiderschrank, Toilette, ...

Eine Terrasse ist kein ZimmerErforderlich für Grundtyp “Zimmer”: Tür, Wände, Decke.

topic

title

shortdesc

prolog

body

p

note

fig

table

section

example

bodydiv

related-links

topic

hazardstatement

messagepanel

hazardsymbol

consequence

howtoavoid

typeofhazard

Domainbezogen SpezialisierungAlternatives Element hinzufügen

Grundtyp “Stuhl”Jeder weiß, wofür dieses Element gedacht ist

Spezialisierung “Bürostuhl”Hat extra Möglichkeiten, bleibt aber wesentlich ein Sitzplatz

Spezialisierung “Designstuhl”Kosmetische Anpassungen, gleiche Funktionalität

Hart an die GrenzeWürde man normalerweise nicht als Sitzplatz akzeptieren

topic

title

shortdesc

prolog

body

p, note, ...

ol, ul, dl, ...

fig, image, ...

table

section

example

bodydiv

related-links

topic

task

title

shortdesc

prolog

taskbody

prereq

context

steps

example

postreq

related-links

task

concept reference

title

shortdesc

prolog

refbody

refbodydiv

section

example

refsyn

table

properties

refbodydiv

related-links

reference

title

shortdesc

prolog

conbody

p, note, ...

ol, ul, dl, ...

fig, image, ...

table

section

example

conbodydiv

related-links

concept

result

steps-unord.

DITA Topic-TypenSpezialisierungen von (Einschränkungen auf) Grundtyp “topic”

topic

title

shortdesc

prolog

body

p

ol

ul

table

section

example

bodydiv

related-links

topic

task

title

shortdesc

prolog

taskbody

prereq

context

steps

example

postreq

related-links

task

result

steps-unord.

machineryTask

title

shortdesc

prolog

taskbody

prelreqs

context

steps

example

closereqs

related-links

task

result

steps-unord.

Mehrstufige SpezialisierungMehr Einschränkungen bei jedem Schritt (nur Strukturbezogen)

Spezialisierung - Warum ?

0"

100"

200"

300"

400"

500"

600"

1.0" 1.1" 1.2"

Base"

Spec"

Anzahl der DITA-ElementeDITA “out-of-the-box” verwenden ist Schwachsinn

145

158

170

48140

364

HTML Elemente : FormatierungBezug auf der Visualisierung in Ihrem Browser

<h1>Titel</h1>!<p>Text mit einige <i>Formatierung</i>.</p>!<h2>Titel auf zweite Ebene</h2>!<p>Und noch etwas <b>fette</b> Text</p>!<ul>!

<li>• Erster Punkt</li>!<li>• Zweiter Punkt</li>!

</ul>

XML Elemente : SemantikBezug auf Bedeutung der Elemente in deren Kontext

<topic>!<title>Performing a task</title>!<shortdesc>Just one sentence</shortdesc>!<body>!

<p>First paragraph in this task</p>!<section>!

<title>Subtask</title>!<p>Another paragraph</p>!

</section>!</body>!

</topic>

Welche Elemente brauchen Sie ?Jede bedeutungsvolle Semantik ist nur lokal gültig

Welche Elemente brauchen Sie ?Jede bedeutungsvolle Semantik ist nur lokal gültig

“Jeder Nachteil hat seinen Vorteil” (Johan Cruijff)

Benutzungsorientiert

Elemente ausblendenElemente minimieren = Eindeutigkeit maximieren

Elemente einblendenSicherstellen, daß bestimmte Elemente eingefügt werden

Terminologie erweiternElementnamen ermöglichen automatische Datenverarbeitung

Struktur festlegenLesbarkeit und Auffindbarkeit der Infos verbessern

Kreativität eingrenzenBenutzer brauchen Infos, keine Romane

Spezialisierung - Wie ?

Auswahl der ZutatenEinschränkung durch Konfiguration und “Constraints”

Konfiguration einer DTD-Shell

DITA DTDs - Modulare AufbauDTD Topic Type Shell definiert welche Module eingebunden werden

DTD Topic Type ShellDefiniert welche DTD Module eingebunden werden

highlightDomain!utilitiesDomain!indexingDomain!hazardstatementDomain

abbreviateDomain!programmingDomain!softwareDomain!uiDomain!

topic.mod

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">

Base Topic TypNur unspezifische Domäne sind eingebunden



topic.mod

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Base Topic//EN" "basetopic.dtd">

Entfernen einer DomainAlle Referenzen müssen entfernt werden

!<!ENTITY % hi-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Highlight Domain//EN" "highlightDomain.ent" >%hi-d-dec; !<!ENTITY % ph "ph | %hi-d-ph; "> !<!ENTITY included-domains "&hi-d-att; &ut-d-att; &hazard-d-att;"> !<!ENTITY % hi-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Highlight Domain//EN" "highlightDomain.mod" >%hi-d-def;

1 !!

2 !!

3 !!

4

Minimaler Topic TypKeine Spezialisierung oder Einschränkung (“.mod” Datei) erforderlich



topic.mod

<!DOCTYPE topic SYSTEM "minitopic.dtd">

Verfügbarkeit “PUBLIC”Eindeutige PUBLIC ID Schlüssel - muß nicht wirklich existieren



topic.mod

<!DOCTYPE topic PUBLIC "-//IDN ditadocs.com//DTD Mini Topic//EN" "minitopic.dtd">

Wie erzähle ich es meine OT ?XML Katalog bildet PUBLIC IDs ab auf lokale Dateien

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE topic PUBLIC "-//IDN ditadocs.com//DTD Mini Topic//EN"" "minitopic.dtd"> <topic id="topic_vck_2nc_sn"> <title>Topic title</title> <body> <p>Topic paragraph</p> </body> </topic>

 <public publicId="-//IDN ditadocs.com//DTD Mini Topic//EN"" uri="minitopic.dtd" " xml:base="plugins/com.ditadocs.minitopic/dtd/">"</public>

Einschränkungen (“Constraints”)

Extremes Constraint-ModulConstraints definieren Inhalts-Entitäten neu

!<?xml version="1.0" encoding="UTF-8"?> <!ENTITY topic-constraints "(topic TextOnlyTopic-c)" > <!ENTITY % p.content " ( #PCDATA ) ">"

TextOnlyTopicConstraints.mod

Nicht alles ausschließen ?Definition der schon bekannten Entitäten wegen Verarbeitungsreihenfolge

!<?xml version=”1.0” encoding=”UTF-8”?>""!<!ENTITY topic-constraints “(topic HighlightsOnlyTopic-c)” >"!<!ENTITY % b "b" > <!ENTITY % i "i" > <!ENTITY % u "u" > !<!ENTITY % p.content "(#PCDATA | %b; | %i; | %u;)*" >"

HighlightsOnlyTopicConstraints.mod

Constraints aktivierenReihenfolge der Definitionen in der DTD ist wichtig

!"!<!ENTITY included-domains "&topic-constraints;" > !"!<!ENTITY % TextOnlyTopic-c-def SYSTEM "TextOnlyTopicConstraint.mod"> %TextOnlyTopic-c-def; !"!..."

TextOnlyTopic.dtd

1 !!

2

Einschränkung der GültigkeitNur an Stellen, die im Constraint-Modul neu definiert wurden

!<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE topic PUBLIC "-//IDN ditadocs.com//DTD TextOnlyTopic//EN" " "TextOnlyTopic.dtd"> !<topic id="topic_vck_2nc_sn"> <title>Topic title</title> <body> <p>Topic paragraph with <term>Invalid</term> content.</p>" <note>The <term>Term</term> element is still valid here.</note> </body> </topic>

MyTestDoc.dita

DITA-taugliche SoftwareAutomatische Erkennung der Einschränkungen und Spezialisierungen

Erlaubte EinschränkungenEingeschränktes Modell muß gegen allgemeines Modell validieren

!

!

!!

xx

xx

xx

x

x11

Eigenbau ElementeWenn die 534 Standard DITA Elemente nicht ausreichen

Spezialisierung

hazardstatement

messagepanel

hazardsymbol

consequence

howtoavoid

typeofhazard

note

ul

image

li

p, ol, dl, sl, ...

fig, table, ...

apinamekeyword

GrundprinzipSpezialisierung geht immer von ein existierendes Element aus

Vererbung über “class” AttributZeigt komplette Abstammung des Elements

@class = “- topic/body task/taskbody mytask/mytaskbody “

Elemente

DTD Module

Struktur

@class = “+ topic/p mydomain-d/mypara “

Elemente

DTD ModuleDomain

Semantische ErweiterungErmöglicht einfache und bequeme Bereicherung der Inhalte

The basic principle in phenomenology is the episteme, or "putting the world within brackets". Whatever we may see in the outside world, we try to disregard. Not by closing our eyes, but by looking at the way we look at the world. The foreground (the world) becomes the background and the act of looking becomes the focus of our attention. Of course, this reflection (in an almost literal sense) can be repeated endlessly.

philosophy-term term

ElementdefinitionMehrere Elemente können in einem Modul kombiniert werden

!<!ENTITY % philo-term "philo-term" > <!ENTITY % philo-term.content " (#PCDATA)* " > <!ENTITY % philo-term.attributes ' %univ-atts; ' >"<!ELEMENT philo-term %philo-term.content; > <!ATTLIST philo-term %philo-term.attributes; > <!ATTLIST philo-term %global-atts; " class CDATA "+ topic/term jang-d/philo-term " > !

JangDomain.mod

Definition der EntitätenWerden in der spezialisierten DTD eingebunden

!<!ENTITY % jang-d-term "philo-term" > <!ENTITY jang-d-att "(topic jang-d)" >"

JangDomain.ent

!<!ENTITY % jang-d-term " "philo-concept |" philosopher |" school |" dogma" " > <!ENTITY jang-d-att "(topic jang-d)" >"

ElementdefinitionMehrere Elemente können in einem Modul kombiniert werden

!<!ENTITY % jang-d-dec SYSTEM "jangDomain.ent" >%jang-d-dec; !"!<!ENTITY % term "term | %jang-d-term; " >"!<!ENTITY included-domains "&hi-d-att; &jang-d-att;" >"!<!ENTITY % jang-d-def SYSTEM "jangDomain.mod" >%jang-d-def;

philotopic.dtd

Neues Element verfügbarBlendet keine existierende Elemente aus

Festlegen einer StrukturKeine Formatierungsänderungen erforderlich

recipebody

recipe concept

title

shortdesc

conbody

section

image

p

p

ul

li

ol

li

title

shortdesc

ingredient

recipeinfo

image

source

cuisine

ingredients

instructions

recipestep

Grundtypen auswählenIst das Mapping erlaubt ?

recipebody

recipe topic

title

shortdesc

body

section

image

p

p

ul

li

ol

li

title

shortdesc

ingredient

recipeinfo

image

source

cuisine

ingredients

instructions

recipestep

Grundtypen auswählenIst das Mapping erlaubt ?

recipebody

recipe task

title

shortdesc

taskbody

context

image

p

p

prereq

p

steps

step

title

shortdesc

ingredient

recipeinfo

image

source

cuisine

ingredients

instructions

recipestep

Grundtypen auswählenWelches Mapping ist optimal für Ihre Anwendung ?

recipebody

recipe task

title

shortdesc

taskbody

context

image

p

p

prereq

ul

li

steps

step

cmd

title

shortdesc

ingredient

recipeinfo

image

source

cuisine

ingredients

recipesteps

recipestep

cmd

recipereqs

Struktur / Mapping optimierenEin iterativer Prozeß führt zu ein optimales Ergebnis

Testdokument erstellenSo lange es ungültig ist, ist Ihre DTD noch nicht richtig definiert

!<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE recipe SYSTEM "recipe.dtd" > <recipe id="risotto-mushrooms"> <title>Risotto with mushrooms</title> <shortdesc>A simple and fast Italian dish with a modern British twist." </shortdesc> <recipebody> <recipeinfo> <image></image> <recipesrc>Jamie Oliver</recipesrc> <recipestyle>Modern Italian</recipestyle> </recipeinfo> <recipereqs> <ingredients> <ingredient>500g risotto rice</ingredient> <ingredient>250g cellery</ingredient> <ingredient>3 cloves of garlic</ingredient>

risotto-mushrooms.xml

Shell DTD erstellenKopieren und anpassen ist eine effiziente und sichere Methode

!<?xml version="1.0" encoding="UTF-8"?> "

recipe.dtd

Unbenötigte Domäne entfernenAlle Referenzen müssen entfernt werden

!<!ENTITY % hi-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Highlight Domain//EN" "highlightDomain.ent" >%hi-d-dec; !<!ENTITY % ph "ph | %hi-d-ph; "> !<!ENTITY included-domains "&hi-d-att; &ut-d-att; &hazard-d-att;"> !<!ENTITY % hi-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Highlight Domain//EN" "highlightDomain.mod" >%hi-d-def;

1 !

2 !

3 !!

4

recipe.dtd

Einbetten von Topics untersagenGenerell sind Tasks innerhalb einer Task erlaubt

!<!ENTITY % recipe-info-types "no-topic-nesting" > !

recipe.dtd

Modul-Datei erstellenKopieren der "task.mod" und referenzieren in der neuen DTD

!<!ENTITY % topic-type PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Topic//EN" "../../base/dtd/topic.mod" > %topic-type; <!ENTITY % recipe-typemod SYSTEM "recipe.mod" > %recipe-typemod;

technicalContent/dtd/task.mod recipe.mod

Entitäten definierenAlle spezialisierten Elemente werden in der "mod" Datei definiert

!<!ENTITY % recipe "recipe" ><!ENTITY % recipebody "recipebody" > <!ENTITY % recipesteps "recipesteps" ><!ENTITY % recipestep "recipestep" > <!ENTITY % recipereqs "recipereqs" > <!ENTITY % recipeinfo "recipeinfo" > <!ENTITY % recipesrc "recipesrc" ><!ENTITY % recipestyle "recipestyle" ><!ENTITY % ingredients "ingredients" ><!ENTITY % ingredient "ingredient" >

recipe.mod

Elemente definierenInhalte und Attribute aller spezialisierten Elemente

!<!ENTITY % recipebody.content "((%recipeinfo;), (%recipereqs;), (%recipesteps;) )" > <!ENTITY % recipebody.attributes "%univ-atts;" > <!ELEMENT recipebody %recipebody.content;> <!ATTLIST recipebody %recipebody.attributes;>

recipe.mod

Abstammung definierenAttribut "class" muß zeigen, welche Vorfahren jedes Element hat

<!ATTLIST recipe %global-atts; class CDATA "- topic/topic task/task recipe/recipe " > <!ATTLIST recipebody %global-atts; class CDATA "- topic/body task/taskbody recipe/recipebody " > <!ATTLIST recipesteps %global-atts; class CDATA "- topic/ol task/steps recipe/recipesteps " > <!ATTLIST recipestep %global-atts; class CDATA "- topic/li task/step recipe/recipestep " > <!ATTLIST recipereqs %global-atts; class CDATA "- topic/section task/prereq recipe/recipereqs " > <!ATTLIST recipeinfo %global-atts; class CDATA "- topic/section task/context recipe/recipeinfo " > <!ATTLIST recipesrc %global-atts; class CDATA "- topic/p recipe/recipesrc " > <!ATTLIST recipestyle %global-atts; class CDATA "- topic/p recipe/recipestyle " > <!ATTLIST ingredients %global-atts; class CDATA "- topic/ul recipe/ingredients " > <!ATTLIST ingredient %global-atts; class CDATA "- topic/li recipe/ingredient " >

recipe.mod

@class = “- module/element module/element “

Ursprung Spezialisierung

Leerzeichen am EndeStrukturell

Entitäten-Datei definierenEntität muß die Abstammung enthalten

<?xml version="1.0" encoding="UTF-8"?> <!ENTITY recipe-att "(topic task recipe)" > 

recipe.ent

Entitäten-Datei referenzierenÜber SYSTEM oder per PUBLIC ID via "catalog-dita.xml"

!<!ENTITY % recipe-dec PUBLIC "-//IDN ditadocs.com//DITA Recipe//EN" "recipe.ent" >%recipe-dec;"!<!ENTITY included-domains "&task-att;" &recipe-att; &taskbody-constraints; " >

recipe.dtd

Rezepte editieren in XMLSicherstellen, daß alle Autoren den gleichen Struktur folgen

XSLT und XPathSemantik ermöglicht einfaches Auffinden aller Inhalte

XSLT und XSL-FOSemantik ermöglicht automagische Umwandlung der Inhalte

Fragen ?

www.jang.nl!

[email protected]!

4everJang!

blogs.jang.nl

http://www.jang.nl

mailto:[email protected]

Education

Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen