custom xml through dita specialization in xmetal
DESCRIPTION
The "X" in XML stands for "extensible," and many organizations benefit from designing or adapting XML structural rules for their own needs. The Darwin Information Typing Architecture (DITA) is an XML language designed to be customized, using a feature called "specialization." XMetaL Author Enterprise is easily configured to work with DITA specializations. You can get up and running with a specialization in minutes, and if you have some knowledge of programming you can also customize XMetaL menus and toolbars for an optimal user experience. In this session, we'll show how to set up XMetaL to work with a realistic example of a specialized DITA document type.TRANSCRIPT
© 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