november 2005 © 2004, 2005 ibm corporation presentation subtitle: 20pt arial regular, teal r045 |...
Post on 18-Jan-2016
217 Views
Preview:
TRANSCRIPT
November 2005 © 2004, 2005 IBM Corporation
DITA specialization demonstration
Michael PriestleyIBM®
DITA specialization © 2004, 2005 IBM Corporation2
Overview of demonstrations
Creating samples (in base markup, then in specialized markup)
Identifying new tags
Creating the structural specialization
Creating the domain specialization
Adding override processing
Summary
DITA specialization © 2004, 2005 IBM Corporation3
Creating samples
Always easiest to start with something concrete and then figure out the general rules
So start by authoring a sample document in the closest existing information type
Then go through and rename tags that should be more specific
Then reverse-engineer the document type from its instance
DITA specialization © 2004, 2005 IBM Corporation4
Sample: A task for a wizard
Assuming that wizards do sometimes require documentation
A series of screens with next, back, and finish buttons
Let's say that each wizard task needs to describe how to open and finish the wizard, with one step per page in between
Can use markup to enforce consistency
Can also use special markup for the wizard title and the wizard-specific controls (next and finish)
This sample is for demonstration purposes only, not a best practice
DITA specialization © 2004, 2005 IBM Corporation5
Sample using task.dtd (mytask.xml)<task id="atest">
<title>Creating a foo</title><taskbody>
<steps><step>
<cmd>Click <menucascade> <uicontrol>File</uicontrol> <uicontrol>New</uicontrol> <uicontrol>Foo</uicontrol> </menucascade> to open the <wintitle>New Foo</wintitle> wizard.</cmd>
<info>The <wintitle>New Foo</wintitle> wizard opens to the Name page, where you provide a name for the foo.</info>
</step><step>
<cmd>Click <uicontrol>Next</uicontrol> and turn to the <wintitle>Properties</wintitle> page.</cmd><info>The Properties page lets you define the color and shape of your foo.</info><substeps>
<substep><cmd>Set the color of the foo using the color wheel.</cmd></substep><substep><cmd>Set the shape of the foo using the shape selection bar.</cmd>
<info>You can edit the shape of the foo after you create it; this shape is just your starting point.</info></substep>
</substeps></step><step>
<cmd>Click <uicontrol>Next</uicontrol> and turn to the <wintitle>Location</wintitle> page.</cmd><info>Select the project you want to save your foo in.</info></step>
<step><cmd>Click <uicontrol>Finish</uicontrol> to close the wizard and create your foo.</cmd></step></steps><result>The foo, with the shape and color you selected, should appear in your project folder.</result>
</taskbody></task>
DITA specialization © 2004, 2005 IBM Corporation6
Sample output from mytask.xml
DITA specialization © 2004, 2005 IBM Corporation7
Sample with renamed tags<wiztask id="btest">
<title>Creating a foo</title><wiztaskbody>
<wizsteps><wizopen>
<cmd>Click <menucascade> <uicontrol>File</uicontrol> <uicontrol>New</uicontrol> <uicontrol>Foo</uicontrol> </menucascade> to open the <wiztitle>New Foo</wiztitle> wizard.</cmd>
<info>The <wiztitle>New Foo</wiztitle> wizard opens to the Name page, where you provide a name for the foo.</info>
</wizopen><wizpage>
<cmd>Click <wiznext>Next</wiznext> and turn to the <wintitle>Properties</wintitle> page.</cmd><info>The Properties page lets you define the color and shape of your foo.</info>
<substeps><substep><cmd>Set the color of the foo using the color wheel.</cmd></substep><substep><cmd>Set the shape of the foo using the shape selection bar.</cmd>
<info>You can edit the shape of the foo after you create it; this shape is just your starting point.</info></substep> </substeps>
</wizpage><wizpage>>
<cmd>Click <wiznext>Next</wiznext> and turn to the <wintitle>Location</wintitle> page.</cmd><info>Select the project you want to save your foo in.</info></wizpage>
<wizclose><cmd>Click <wizfinish>Finish</wizfinish> to close the wizard and create your foo.</cmd></wizclose>
</wizsteps> <result>The foo, with the shape and color you selected, should appear in your project folder.</result> </wiztaskbody></wiztask>
DITA specialization © 2004, 2005 IBM Corporation8
Identify structural and domain tags
Structural - tags you need in certain places, plus their containerswiztask (from task)
wizbody (from body)
wizsteps (from steps)
wizopen, wizpage, wizclose (from step)
Domain - tags you want made available wherever their ancestor elements are available
wiztitle (from wintitle)
wiznext (from uicontrol)
wizfinish (from uicontrol)
DITA specialization © 2004, 2005 IBM Corporation9
Creating the structural specialization
Copy the parent module (task.mod) to a new module (wiztask.mod)Keep anything related to task, taskbody, steps, and step
Three main sections: entities, element declarations, specialization attributes
In the entity section, delete everything except the DTD entity, included-domains entity, and entities for elements you're specializing, and the task-info-types entity
In the element section, delete everything except the elements you're specializing
In the specialization attributes section, delete everything except the elements you're specializing
DITA specialization © 2004, 2005 IBM Corporation10
Specialize entities
In the entities section, change entity names and values from task ones to wiztask ones
eg: <!ENTITY % task "task"> becomes
<!ENTITY % wiztask "wiztask">
you'll need to create three copies of step, since step has three specializations (wizopen, wizpage, wizclose)
eg: <!ENTITY % step "step"> becomes
<!ENTITY % wizopen "wizopen">
<!ENTITY % wizpage "wizpage">
<!ENTITY % wizclose "wizclose">
This prepares your specialized elements for extension by domains Rename task-info-types entity to wiztask-info-types
This prepares your module for integration with other modules in a DTD
DITA specialization © 2004, 2005 IBM Corporation11
Specialize elements
In the elements section, rename the element and attribute declarations to wiztask equivalents, and rename and adjust entities in the content model where you have changed entities from the original. For example:
<!ELEMENT steps ((%step;)+)>
<!ATTLIST steps %univ-atts;
outputclass CDATA #IMPLIED>>
becomes:<!ELEMENT wizsteps ((%wizopen;), (%wizpage;)?, (%wizclose;))>
<!ATTLIST wizsteps %univ-atts;
outputclass CDATA #IMPLIED> Again, you need three copies of the declaration for <step>, since it gets
specialized to <wizopen>, <wizpage>, and <wizclose>
DITA specialization © 2004, 2005 IBM Corporation12
Specialize specialization attributes
Add copies of the entry for step, since you need to specialize it three times
Rename the attribute declarations to point to your new element names
To the end of each attribute value string, add wiztask/elementname
For example:<!ATTLIST steps %global-atts; class CDATA "- topic/ol task/steps ">
becomes:<!ATTLIST wizsteps %global-atts; class CDATA "- topic/ol task/steps wiztask/wizsteps ">
Make sure you include a space after the value before the string closes
DITA specialization © 2004, 2005 IBM Corporation13
Result: wiztask.mod
Now the markup is declared, we just need to integrate the module into a document type, along with markup in other modules (such as ancestor structural types and appropriate domains)
DITA specialization © 2004, 2005 IBM Corporation14
Creating wiztask-simple.dtd
Copy task.dtd to wiztask-simple.dtd
Change <!ENTITY % task-info-types "task"> to <!ENTITY % wiztask-info-types "wiztask">
Lets wiztask topics nest, for no good reason
Add an entry after "Embed task to get specific elements" that does the same things for wiztask:
<!--Embed wiztask to get specific elements --><!ENTITY % wiztask-typemod PUBLIC "-//IBM//ELEMENTS DITA
Wiztask//EN" "wiztask.mod"> %wiztask-typemod;
DITA specialization © 2004, 2005 IBM Corporation15
Testing wiztask-simple.dtd
Create a copy of your sample file (eg mywiztask-test.xml) and rename the element wiztitle to wintitle, and wiznext and wizfinish to uicontrol (since we haven't added support for them yet)
Add a DTD reference at the top of your sample file:<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE wiztask SYSTEM “../wiztask-simple_shell.dtd">
Try processing it to HTML, eg:saxon mywiztask-test.xml d:\dita\xsl\dita2xhtml.xsl >mywiztask-test.html
Test with a validating editor or parser
DITA specialization © 2004, 2005 IBM Corporation16
Sample output: mywiztask-test.html
DITA specialization © 2004, 2005 IBM Corporation17
Creating the wiztask domain specialization
We have three new elements:wiztitle (from wintitle)
wiznext (from uicontrol)
wizfinish (from uicontrol) All are specialized from elements in the user interface domain, so
start by copying its files over to wiztask:uiDomain.ent to wiztaskDomain.ent
uiDomain.mod to wiztaskDomain.mod
DITA specialization © 2004, 2005 IBM Corporation18
Creating wiztaskDomain.mod
As with wiztask.mod, there are three sections: entities, element declarations, and specialization attributes.
In each section:– Delete everything except the entries for uicontrol and wintitle
– Create an extra copy of entries for uicontrol (since we have two specializations of it)
Rename the entities and values to wiztask equivalents - eg:<!ENTITY % uicontrol "uicontrol"> to <!ENTITY % wizfinish "wizfinish">
Rename the element declarations
Rename the specialization attribute declarations, and add wiztask-d values to the end of each attribute, eg:
<!ATTLIST wiztitle %global-atts; class CDATA "+ topic/keyword ui-d/wintitle wiztask-d/wiztitle ">
DITA specialization © 2004, 2005 IBM Corporation19
The domain.ent files
The domain.ent files are what make domains different from information types - they allow the elements declared in the domain to be substituted wherever an ancestor element is declared.
For each parent element, you need an entity that declares the elements you are specializing off of it.
You also need an entity that declares the ancestry of the domain as a whole, for inclusion in the domains attribute.
We need the information separated into two files - .ent and .mod - so that they can be included in the right order in the integrating DTD file.
DITA specialization © 2004, 2005 IBM Corporation20
Creating wiztaskDomain.ent
Delete the existing entries for the UI specializations, leaving only the last entity (the d-att entity)
Create the entity for specializations of wintitle:<!ENTITY % wiztask-d-wintitle "wiztitle">the name of the entity says this entity is part of the wiztask domain, and is
defining specializations of wintitle
Create the entity for specializations of uicontrol:<!ENTITY % wiztask-d-uicontrol "wiznext | wizfinish">note that there are two specializing elements, separated by a bar
Rename the d-att entity, and add the wiztask domain to its list:<!ENTITY wiztask-d-att "(topic ui-d wiztask-d)">this gets used in the domains attribute, so that processes can tell what domains
are in use by a document
DITA specialization © 2004, 2005 IBM Corporation21
Integrating domain specializations with structural specializations
Create a copy of wiztask-simple.dtd called wiztask.dtd
We are specializing ui-domain, so look for existing entries for that module (ui-domain, or ui-d)
It appears in four places:vocabulary declarations (where the .ent files are pulled in)
vocabulary substitutions (where content models that allow parent elements are extended to allow elements specialized off them)
vocabulary attributes (where the domain attribute is defined)
vocabulary definitions (where the .mod files are finally pulled in)
DITA specialization © 2004, 2005 IBM Corporation22
Integrating wiztaskDomain At the end of vocabulary definitions, add an entry for wiztask-d:<!ENTITY % wiztask-d-dec PUBLIC "-//EXAMPLE//ENTITIES DITA Wizard Task Domain//EN"
"wiztaskDomain.ent"> %wiztask-d-dec;
At the end of vocabulary substitutions, add entries for wintitle and uicontrol (which you are expanding to allow specialized elements):
<!ENTITY % wintitle " wintitle | %wiztask-d-wintitle;"><!ENTITY % uicontrol " uicontrol | %wiztask-d-uicontrol;">
And expand the definitions of ancestor elements to include the new entities (in this case, keyword for wintitle specializations, and ph for uicontrol specializations):
<!ENTITY % keyword "keyword | %pr-d-keyword; | %sw-d-keyword; | %ui-d-keyword; | %wiztask-d-wintitle;"><!ENTITY % ph "ph | %pr-d-ph; | %sw-d-ph; | %hi-d-ph; | %ui-d-ph; | %wiztask-d-uicontrol;">
Under vocabulary attributes, add the wiztask domain to the end of the included domains:<!ENTITY included-domains "&ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att; &ut-d-att; &wiztask-d-att;">
At the end of the vocabulary definition section, pull in the .mod file:<!ENTITY % wiztask-d-def PUBLIC "-//EXAMPLE//ELEMENTS DITA Wizard Task Domain//EN"
"wiztaskDomain.mod"> %wiztask-d-def;
DITA specialization © 2004, 2005 IBM Corporation23
Testing the newly integrated DTD
Go back to your original sample file, mywiztask.xml
Add a DTD reference at the top of your sample file:<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE wiztask SYSTEM "wiztask.dtd">
Try processing it to HTML, eg:saxon mywiztask.xml d:\dita\xsl\dita2xhtml.xsl >mywiztask.html
Compare results with mywiztask.html in the accompanying samples
DITA specialization © 2004, 2005 IBM Corporation24
Sample output (mywiztask.html)
DITA specialization © 2004, 2005 IBM Corporation25
Are all these outputs starting to look the same?
They should - we've added new markup, but are reusing existing processing rules that get applied based on the class attribute of each element.
As long as each specialized element obeys the rules of specialization - the same or more restrictive content models - the processing can safely handle what the specialized element throws at it.
In the next exercise, let's see what it takes to shake up the output a little.
DITA specialization © 2004, 2005 IBM Corporation26
Specializing output 1: copy an existing template
Create a new XSLT module, in the same directory as the ui-d.xsl module: wiztask-d.xsl
Add XSLT header stuff, and copy the template match for wintitle to use as a start:
<xsl:template match="*[contains(@class,' ui-d/wintitle ')]" name="topic.ui-d.wintitle"><span class="wintitle">
<xsl:call-template name="commonattributes" /> <xsl:call-template name="setidaname" /> <xsl:call-template name="flagcheck" /> <xsl:call-template name="revtext" /> </span></xsl:template>
DITA specialization © 2004, 2005 IBM Corporation27
Specializing output 2: change match statement and code
Change the match statement to point to wintitle, and change the behavior to make wiztitle bold:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="*[contains(@class,' wiztask-d/wiztitle ')]"> <b> <span class="wintitle"> <xsl:call-template name="commonattributes" /> <xsl:call-template name="setidaname" /> <xsl:call-template name="flagcheck" /> <xsl:call-template name="revtext" /> </span> </b></xsl:template></xsl:stylesheet>
DITA specialization © 2004, 2005 IBM Corporation28
Specializing output 3: integrating the specialized code
Copy dita2xhtml.xsl to dita2xhtml-wiztask.xsl
Add a reference to the wiztask-d.xsl module at the end of the import list in dita2xhtml-wiztask.xsl:
<xsl:import href="wiztask-d.xsl"/>
DITA specialization © 2004, 2005 IBM Corporation29
Test output
saxon mywiztask.xml dita2xhtml-wiztask.xsl >mywiztask-new.html
Compare with HTML output in the previous samples. The wizard title should now be bold.
Note that generic wintitles in the same document are not affected.
DITA specialization © 2004, 2005 IBM Corporation30
Sample output (mywiztask-new.html)
DITA specialization © 2004, 2005 IBM Corporation31
Mechanics
class attribute for a new structural element:starts with -
lists ancestor elements plus current element, scoped by information type (the topic-level element name)
ends with a space class attribute for a new domain element:
starts with +
lists ancestor elements plus current element, scoped by domain package name (arbitrary name, typically something-d, used consistently for element names and in domains attribute)
ends with a space domains attribute
lists the domains, and their ancestors, in use by the current document type
allows comparison of constraints (does task 1 allow the same things as task 2?)
DITA specialization © 2004, 2005 IBM Corporation32
Summary
Mechanics are simple
Design implementation is copy and extend, but copy only the parts you need to change - reuse everything else by reference
Design hierarchy has one module per structural or domain specialization, which are integrated into doctypes by a shell DTD
Processing hierarchy has an equivalent structure: processing modules integrated into a transform by a shell XSLT
But processing hierarchy can get away with a subset of the design modules: don't need processing modules for every design module, only the ones that need special processing; and within a processing module, only need rules for the special elements
DITA specialization © 2004, 2005 IBM Corporation33
What's the value?
Still work involved to define the seven new elements
But no work to define the other 100-odd already defined
No work to get those tags enabled in existing processes
No work to get the content integrated in existing books and Webs
And reuse by reference means you can pick up enhancements to both base design and base processes when you want to.
The real work is in figuring out what your tags need to be. What DITA does is simplify the mechanics of getting those tags into an authoring and processing environment you can test with your users - shorten the feedback cycle, improve more quickly.
A rapid prototyping architecture that scales to a production one.
DITA specialization © 2004, 2005 IBM Corporation34
Recommended reading
The DITA 1.0 Architectural Specification, in the DITA 1.0 Standard: http://www.oasis-open.org/committees/download.php/15316/dita10.zip
Additional reading (pre-specification, so not all examples use appropriate naming conventions):
http://xml.coverpages.org/DITA-EXTREME-SpecializationPres.pdfprovides a technical overview, with checklists/instructions
http://xml.coverpages.org/priestleySIGDOC2002-DITA.pdfprovides in-depth view of the technology, process, and policy issues of specialization
http://www.ibm.com/developerworks/xml/library/x-dita2/index.htmlspecifics of information type specialization
http://www.ibm.com/developerworks/xml/library/x-dita5/index.htmlspecifics of domain specialization
top related