Product Preview: Samalander DITA Xref Manager

I had the opportunity last week of getting a preview of a new product that Samalander Software is planning to release today: DITA Xref Manager. Designed for small technical writing teams who are working without the benefit of a Content Management System (CMS), it automatically checks the validity of all xrefs contained within a ditamap file and gives authors the chance to fix any broken or invalid links that appear, or to change them to something else. The same process allows you to change or fix any existing keyrefs that are contained within the scope of the targeted ditamap. Those two features alone would make it useful for its intended audience. What makes this product stand out (and makes it “cool”) in my mind is that it can also be used to convert existing xrefs over to the indirect referencing method of keyrefs, allowing teams to up-convert their existing documents to using the flexible, indirect referencing method of keyrefs used in the DITA 1.2 standard. The rest of this preview steps through how this product works.

How it Works
When you launch the program the first thing to do is to point the program to the root ditamap file. It then looks for all xrefs and keyrefs that are referenced, and does a basic check of their validity. What the author gets back is a list of all xrefs and keyrefs along with a check to see if their target exists, a count of how many times this link appears within the ditamap along with the actual link URL itself. From this point the author can start fixing any problem that have been encountered, or change existing links to something else.

Sorts can be done whether there are problems with the xrefs/keyrefs, how many times they are used, the destination or the destination file name should it exist. Once you find a problematic link or one you want to change, you simply double-click it from with the list and an editor dialog pops up allowing you to set a new destination for the xref.

When you tell the program to update the xrefs, it automatically inserts the new or changed value wherever the original version appeared across all of the files referenced by the ditamap. This function is editor-independent, so if you want to you can also view the results in whatever XML editor you have. The only thing is that all of the files must be in a writable state for the program to do its job.

The process is much the same for changing or updating existing keyrefs, though you get the additional keyref definition name along with whether or not its destination exists, count and URL.

A nice feature is the ability to simply select from a list of existing keyrefs and simply choose another one that exists from a dropdown list. It couldn’t be simpler.

So what we have here is a solid tool, basically a combination of a search-and-replace function along with a link-checking mechanism. This is good and useful to have. What makes this even better is the ability to convert existing “old style” xrefs over to the indirect referencing mechanism that keyrefs afford authors – so technical writing teams can use this tool to bring the links within their documents up the mechanism adopted within the DITA 1.2 standard.

Turning xrefs into keyrefs
You might be asking yourself: why would you want to switch over xrefs to keyrefs? It simply allows for a greater level of flexibility, so instead of pointing to a specific URL (which might change at some point in the future), you simply provide a name to be associated with this URL (which is set as a key within a topic), and then in turn points to the URL. So if the URL changes, you simply have to update a single reference to the link instead of trying to track them all down individually and update them en masse. Admittedly with a tool like this it is easy to stick with plain old xrefs as this program does allow to find them all quickly and to update them all at one go, but the keyref mechanism is more straightforward, as you only have to update a single reference instead of potentially hundreds of them. A scenario where keyrefs really make a difference is if you are pulling in topics from another ditamap file that has not been update to the new URL, you need to know what the old URL was in order to be able to track down all instances of it to be able to update it. As long as you stick to a common naming convention for your keyrefs, a pointer to a key called “homepage” will always work so long as the single referencing URL to it within the ditamap is correct.

Converting xrefs over to keyrefs is no fun when done by hand, and at the very least you will want a good search-and-replace tool on hand to make the process easier. Samalander’s Xref Manager goes one better, by allowing the author to create a new keyref name, converting the chosen xref(s) over to it automatically within your ditamap file. This operation requires the ditamap file to be writable, as the program creates an additional subsidiary map file (if none already exists) to insert the new keyref into.

This is a very nice tool and I can see a lot of technical writing groups, no matter the size will find this to be of real use. I am not aware of this type of feature existing within the current popular professional XML editors that are out there, which makes this a first-to-market product, fulfilling a niche need in the DITA tools market.

For more information, go to the DITA XREF Manager page on the revamped Samalander website. A license for Samalander’s Xref Manager is $299.99 which can be found on their online store. If anyone has any questions, comments, feature requests, for this product or any of the other Samalander products, please contact Matthew Fournier at: matthew.fournier@samalander.com.