I usually work on DITA modules with Oxygen XML Editor, but some of my colleagues prefer to use XMetaL for their editing needs. They are mostly happy with the tool, but found some of the out-of-the-box features a bit annoying.

Updating the topic type templates

Whenever you create a new topic with XMetaL, the editor adds the following comment on each new topic:

This is not a big deal and it doesn’t really affect the published content, but having to look at the comment might bug some authors. So, let’s make it go away.

The comments come from the standard topic templates in XMetaL and they can be removed by editing the template files. With our slightly outdated XMetaL 7.0, the templates are located in the following folder:

C:\Program Files (x86)\XMetaL 7.0\Author\Template\DITA Topic

To remove the comment, simply open up each topic type template, and remove the line

<!-- Created with XMetaL (http://www.xmetal.com) -->

from the files. And while you’re at it, you may want to remove the automatically added element in case you do not use them in your documentation. You can do this by removing the line

<shortdesc><?xm-replace_text Short Description?></shortdesc>

from the files.

Fiddling with customization files

XMetal has some preconfigured magic that sometimes happens when you add elements. For example, when you add a element in a task module, XMetaL will automatically add a element after it. We rarely use these elements in our documentation, so getting rid of them manually can be a bit of a pain in the backside. Luckily, this behaviour is easily cured through XMetaL Application Customization (XAC) files. These files are located in folders:

C:\Program Files (x86)\XMetaL 7.0\Author\DITA\XACs\1.2

and

C:\Program Files (x86)\XMetaL 7.0\Author\DITA\XACs\1.1

Be sure to pick the correct folder based on which DITA version you use!

Each topic type has its own preconfigured events that fire when you add certain elements onto your module. XMetal defines these events through templates that you can find in each topic type’s own customization file (.ctm). In this case, we needed to edit the task topic’s customization file located at:

C:\Program Files (x86)\XMetaL 7.0\Author\DITA\XACs\1.2\task\task_ditabase.ctm

This file contains a lot of information, but we’re mainly interested in the template that is used when the user adds a new step:

<Template>
    <Name ns="">step</Name>
    <MiniTemplate><![CDATA[<step><cmd><?xm-replace_text Step?></cmd><stepresult><?xm-replace_text Step Result?></stepresult></step>]]></MiniTemplate>
</Template>

This template defines that whenever a users adds a element, the editor also adds a element after this. To change this behaviour, we need to remove the part that adds the element:

<stepresult><?xm-replace_text Step Result?></stepresult>

After this bit is removed, the template should look like this:

<Template>
    <Name ns="">step</Name>
    <MiniTemplate><![CDATA[<step><cmd><?xm-replace_text Step?></cmd></step>]]></MiniTemplate>
</Template>

After you’ve edited and saved the file, restart XMetaL and the unwanted behaviour should be history.