© 2011 JustSystems Episode 17 Episode 17 Custom XML through DITA Custom XML through DITA Specialization Specialization Su-Laine Yeo, Solutions Consultant January 2011 in 37 minutes
Jan 16, 2015
© 2011 JustSystems
Episode 17Episode 17Custom XML through DITA Custom XML through DITA
SpecializationSpecialization
Su-Laine Yeo, Solutions Consultant
January 2011
in 37 minutes
© 2011 JustSystems
Agenda
• Today’s slides are on http://www.slideshare.net/XMetaL
• Custom XML with DITA specialization:– Using a realistic example– You can download the free example package – Use example as a model for creating your own specialization
© 2011 JustSystems
DITA specializations
• Why DITA specialization?
• Step 1: Put specialized DTD files in place
• Step 2: Make XMetaL provide a “DITA authoring experience” for the document type
• Step 3: Add a template for creating new documents
• Step 4: Optimize the user experience in XMetaL
• Step 5: Customize the publishing system
• Power user tips
© 2011 JustSystems
Features of base DITA
• Basic element types: paragraphs, lists, tables, cross-references
• Reuse features: conditional text, content references
• Good tool support
• Wide adoption
© 2011 JustSystems
Custom XML facilitatesautomated formatting
Example of specialized DITA source:
HTML output of the above:
© 2011 JustSystems
Custom XML facilitatesintegration with data sources
• E.g. produce API documentation by parsing source code and pulling out comments– e.g. JavaDocs
© 2011 JustSystems
Specialized DTDs enable custom XML
Features of base DITA plus:– Custom elements– Custom attributes– Additional rules– Removal of elements that you don’t need
© 2011 JustSystems
Examples of specialized DTDs
• In DITA Open Toolkit “plugins” built by others:– http://sourceforge.net/projects/dita-ot/files/
• Grow your own:– http://www.xiruss.org/tutorials/dita-specialization/
© 2011 JustSystems
Specialized DTDs and plugins
• Recommended practice: Create a folder containing:– your specialized DTDs– files for extending the DITA Open Toolkit to produce
custom output
• This folder is called a “plugin”
• But note: Not all plugins contain specialized DTDs
© 2011 JustSystems
Step 1: Put specialized DTD files in place
© 2011 JustSystems
Where to put DTD files
• Anywhere, but usually in a folder within: – C:\Program Files\Common Files\XMetaL Shared\
DITA_OT\plugins
or– C:\Program Files\Common Files\XMetaL Shared\
DITA_OT\demo
• You don’t have to put specialized DTD files in more than one place
© 2011 JustSystems
Step 2: Make XMetaL recognize a document type as being DITA
© 2011 JustSystems
Document “treated as DITA”
DITA-specific menus and styling
Invisible features such as copy/paste from Word, automatic ID generation
© 2011 JustSystems
Document “not treated as DITA”
No “Reuse” or “Paragraph” menus
Not styled like other DITA documents
© 2011 JustSystems
Quick configuration
• Copy the PUBLIC identifier from either the DTD or a sample document. You should see something like this:
PUBLIC "-//IBM//DTD DITA API Classifier Reference Type//EN"
• Click Tools > Select Specialized DTD
© 2011 JustSystems
Now, paste
Paste the PUBLIC identifier without quotes
© 2011 JustSystems
Oops!
How to fix mistakes made with the “Select Specialized DTD” command:
• Delete the subfolder from C:\Program Files\XMetaL 6.0\Author\DITA\XACs
• Remove the item from C:\Program Files\XMetaL 6.0\Author\Rules\dita_specialized.soc
• Remove the item from C:\Program Files\XMetaL 6.0\Author\DITA\XACs\dita_xac_catalog_specialized.xml
© 2011 JustSystems
Step 3: Add a template for creating new documents
© 2011 JustSystems
New documents
• With the setup so far, you can edit existing documents that use the specialized DTD
• Next, configure XMetaL so that you can easily create new documents that use the specialized DTD
© 2011 JustSystems
Templates folder
• Files in the “Templates” folder automatically appear in the File > New dialog.
© 2011 JustSystems
Tip: Put stuff in the template
Instructions at: http://forums.xmetal.com/index.php/topic,284
© 2011 JustSystems
Step 4: Customize how specialized elements display in XMetaL
© 2011 JustSystems
Default styling in XMetaL
© 2011 JustSystems
Optimized styling in XMetaL
© 2011 JustSystems
What controls styling in XMetaL?
Default styling comes from base DITA stylesheets that are installed with XMetaL
Custom styling comes from this file, which you can edit
© 2011 JustSystems
Edit this file!
© 2011 JustSystems
Important: Style using the“class” attribute
Don’t do this: Do this instead:
© 2011 JustSystems
Tip: Turn on display of the “class” attribute
• By default, the “class” attribute does not display in the Attribute Inspector
• Click Tools > DITA Options.
© 2011 JustSystems
Step 5: Customize the publishing system
• The DITA Open Toolkit includes:– stylesheets to produce general-purpose output in
multiple formats – extension points for adding custom stylesheets for
each format
• You must add a line to the catalog-dita_template.xml file
© 2011 JustSystems
Power user tips
© 2011 JustSystems
Configure the Reusable Components feature
• To use the Reusable Components feature with specialized elements, edit the following file: dcspecialized-typemods.ent
• Put this file in the following places:– C:\Program Files\XMetaL 6.0\Author\DITA\
DITA_OT_DTD– C:\Program Files\Common Files\XMetaL Shared\
DITA_OT\dtd
© 2011 JustSystems
Advanced customization
• Custom forms, dialog boxes, menu items, keyboard shortcuts
• Custom behavior when inserting elements
• The XMetaL Developer product is recommended
• See “Extending the XMetaL interface for your specialization” in the XMetaL Programmer’s Guide
© 2011 JustSystems
Summary
• Custom XML markup facilitates consistent layout, integration with data sources, and powerful search
• Create or download plugins for specialized DTD files
• “Select Specialized DITA DTD” command to get started
• Customize templates, stylesheets, and editor behavior
© 2011 JustSystems
• Global Presence– 1,000 employees, ‘07 revenues of $110M
– HQ in Japan; Corporate Offices in Vancouver and London; Sales Offices Worldwide
• Our Experience– Established in 1979
– Market leader with over 2,500 customers
• Our Expertise– Global provider of office productivity, information
management, consumer & enterprise software
– Framework for XML-based content creation, integration, visualization and delivery
• Our Credibility
– eContent 100 member in 2009
– KMWorld Trend-Setting Product Award 2009
– KM World “100 Companies that Matter” 2010
2,500 Customers,Marquee Brands
About JustSystemsAbout JustSystems
© 2011 JustSystems
AutomotiveAutomotive AerospaceAerospace
PublishingPublishing OtherOther
High-TechHigh-Tech
FinancialFinancial
Global CustomersGlobal Customers