Home Forums DITA and XMetaL Discussion Distributing XMetal Customization Reply To: Distributing XMetal Customization

Derek Read

Reply to: Distributing XMetal Customization

barbwire is right 😉

For DITA, doing what barbwire suggests will fail to enable the DITA authoring functionality or perhaps partially enable it (which might be worse). It really is the wrong thing to do for distributing the files needed to configure XMetaL Author Enterprise to recognize a specialized DITA DTD, even though it is very often the right thing to do for any other schema.

Many customizations are document-level only and consist solely of DTD/XSD, CSS, CTM, optional MCR file, and perhaps a few other files (like XFT). If the DOCTYPE declaration points to the schema in the same folder then all those files will be loaded, and the customization works in that case. So, in many cases for simple customizations it is a perfectly normal method for distributing customizations. See: [url=http://www.slideshare.net/XMetaL/deploying-schemas-and-xmetal-customization-files]Deploying Schemas and XMetaL Customization Files[/url]

The DITA customization is both application-level and document-level and pretty complicated (1200+ files in about 230 folders). It supports DITA specialization, it is CMS-aware, and the authoring experience can be tailored for DITA 1.1 and 1.2 capabilites. All of these things have dependencies on each other, including the document-level customizations, and if you bypass the documented method for setting up specialized DITA (the one step where you choose “Select Specialized DITA DTD”) the document-level portion of the customization for your particular specialized DITA DTD won't be created. Several files are written to during that step and they are all necessary, so distributing them all to the right location for each user in your org that needs this capability is also necessary.

So, what are you missing when DITA authoring isn't available?

  • no integration with the DITA OT for generating output
  • auto-id on elements will not work
  • CMS functionality (if a DITA-capable CMS is integrated) will likely not work
  • the Reuse menu and associated functionality for setting up conref, keyref, keyspaces, the Conditional Text dialogs, etc, will not be present
  • the ability to display “target” content inside a “source” document via conref and similar references (as above) will not be available
  • the Paragraph menu and its associated functionality won't be available
  • you will not be able to reference your specialized topic from a DITA map or another topic because the software is smart enough to check the referenced document to see if it is DITA (anything it has not been configured to recognize as DITA, via Select Specialized DITA DTD, is not)
  • support for rendering SVG in documents will be missing
  • the Insert menu and the context menu will not include any DITA-specific actions
  • the Reference Checking, Topic References and Key References features (displayed in the Results window) won't do anything
  • refreshing references (F11 or while opening a document) won't be available
  • if the specialized DITA DTD is a map then the map editor won't let you open it and so none of its special functions will be available

I'm probably missing a lot more…

Basically, if you don't want any of the DITA authoring functionality you might as well use XMetaL Author Essential and create your own very simple customization for DITA. You will need to obtain the DITA DTDs independently in that case. I wouldn't recommend this either of course, since I think the DITA authoring experience provided by XMetaL Author Enterprise is pretty valuable.