© 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