DITA Xref Manager Help

The DITA Xref Manager is an easy way for technical writers to manage links in their documentation without a CMS. It works by scanning a ditamap for xrefs, and then providing an interface to manage the xref destinations.

Xrefs can be manipulated by:

  • Redirecting their href attributes
  • Replacing href attributes with keyrefs
  • Assigning new keys to keyref attributes

Note that the DITA Xref Manager does not operate on individual xrefs, but on destinations that xrefs point to. After scanning the input ditamap, the DITA Xref Manager presents a list of each xref destination it found in the documentation. If one hundred xrefs point to a particular destination URL, this destination URL only appears once in the interface.

This is useful because the DITA Xref Manager can edit a single destination and have all xrefs that point to that destination updated immediately. This is very useful for many operations, such as when moving a topic - simply find the old URL of the topic in the destinations, update it, and all links will be valid again.

This may be confusing at first, but is very powerful when you get used to it and much, much faster than editing xrefs one-by-one. Just keep in mind that when using the DITA Xref Manager you are manipulating xref destinations, not individual xref elements.

So, with this in mind, choose a procedure below to get started with the DITA Xref Manager.

Procedures

Procedure: Scan a DITAMAP

Before manaing xrefs, we first have to collect data on the xrefs that will be managed. To do this, choose a DITAMAP and scan it. The scanning process finds all the files the DITAMAP references and collects xref data from them. Files are processed recursively, so any files that are referenced by topicrefs, conrefs, or xrefs are found and scanned.

  1. Click the browse button at the top of the window to select a DITAMAP.
  2. Click "Scan" to scan this map and process all the files found.
  3. When scanning is complete, the Destination Tables are populated. These tables contain all the xref destinations found.
  4. There are two tables: Href Destinations and Keyref Destinations.
    • The Href Destinations Table contains destinations that are referenced by href attributes. Each row represents a destination.
    • The Keyref Destinations Table contains destinations that are referenced by keyref attributes. Each row represents a destination.
  5. The Destination Tables can be sorted using the "Sort By" menu. The sorting operation may take a few seconds.

More information about the Destination Tables can be found in the Destination Tables Section.

Procedure: Redirect an Href Destination

The DITA Xref Manager can redirect xrefs to point to a new destination. This is accomplished by editing an entry in the Href Destinations Table.

Prerequisites: The DITA Xref Manager must have already populated the Destination Tables as described in the procedure Procedure: Scan a DITAMAP.

  1. Ensure that the Href Destiations Table is opened by clicking on the Href Destinations tab.
  2. Choose the Xref Destination to be redirected and find its corresponding row.
  3. Double-click on the row to open the editor window.
  4. In the editor window, there are two tabs: the "Set New Href" tab and the "Set New Keyref" tab.
  5. Ensure that the "Set New Href" tab is opened.
  6. Two fields are available: the "Old Dest URL" and the "New Dest URL".
    • The "Old Dest URL" is the URL of the Destination currently being edited.
    • The "New Dest URL" is the URL of the new Destination being assigned.
  7. In the "New Dest URL" field, enter the new URL that this destination will be redirected to.
    • Optionally, click the "Browse" button to browse to a new destination.
  8. Click "Update Xrefs" button. All xrefs that point to the old destination will be updated to point at the new destination.

Procedure: Change and Href Destination to a Keyref

The DITA Xref Manager can edit xrefs so that "href" attributes are replaced with "keyref" attributes. This is accomplished by editing an entry in the Href Destinations Table.

Prerequisites: The DITA Xref Manager must have already populated the Destination Tables as described in the procedure Procedure: Scan a DITAMAP.

  1. Ensure that the Href Destiations Table is opened by clicking on the Href Destinations tab.
  2. Choose the Xref Destination to be updated and find its corresponding row.
  3. Double-click on the row to open the editor window.
  4. In the editor window, there are two tabs: the "Set New Href" tab and the "Set New Keyref" tab.
  5. Ensure that the "Set New Keyref" tab is opened.
  6. Two fields are available: the "Old Dest URL" and the "New Key".
    • The "Old Dest URL" is the URL of the Destination currently being edited.
    • The "New Key" is a list of all the keys found in the DITAMAP.
  7. Click on the "New Key" field and select a key that this Href Destination will be redirected to.
  8. Click "Update Xrefs" button. All xrefs that point to the old destination will be updated so that:
    • Their "href" attributes are removed
    • A new "keyref" attribute is created containing the selected key.

Note: It is not possible to create new keys in the editor window. The only keys available are keys that were discovered when scanning the input DITAMAP. This is to avoid unnecessary confusion in the interface window. A key-creation ability is planned for future versions.

Procedure: Change a Keyref Destination

The DITA Xref Manager can edit xrefs and assign new keys to them. This is accomplished by editing an entry in the Keyref Destinations Table.

Prerequisites: The DITA Xref Manager must have already populated the Destination Tables as described in the procedure Procedure: Scan a DITAMAP.

  1. Ensure that the Keyref Destinations Table is opened by clicking on the Keyref Destinations tab.
  2. Choose the Keyref Destination to be updated and find its corresponding row.
  3. Double-click on the row to open the editor window.
  4. Two fields are available: the "Old Keyref" and the "New Keyref".
    • The "Old Keyref" is the key currently being edited.
    • The "New Keyref" is a list of all the keys found in the DITAMAP.
  5. Click on the "New Keyref" field and select a key that this Keyref Destination will change to.
  6. Click "Update Xrefs" button. All xrefs that had the old key will be updated to use the new key.

The Destination Tables

This section describes the Destination Tables and the information they contain.

The Href Destinations Table

The Href Destinations Table contains information about all destinations that were referenced by an href attribute. Any xref that referenced a destination through an href attribute can be edited in this table.

Each row in the table represents one destination.

The table has the following columns:

  • Exists?: If the destination URL exists, than this column will contain "Yes", otherwise it will contain "No". Any xrefs that point to a destination that does not exist are broken, so using this column you can easily find and fix broken xrefs in your documentation.
  • Count: A simple count of the number of xrefs that point to this destination
  • URL: The full URL of the destination.

The Keyref Destinations Table

The Keyref Destinations Table contains information about all destinations that were referenced by an keyref attribute. Any xref that referenced a destination through an keyref attribute can be edited in this table.

Each row in the table represents one destination.

The table has the following columns:

  • Keyref: The key that references this destination.
  • Exists?: If the destination URL exists, than this column will contain "Yes", otherwise it will contain "No". Any xrefs that point to a destination that does not exist are broken, so using this column you can easily find and fix broken xrefs in your documentation.
  • Count: A simple count of the number of xrefs that point to this destination
  • URL: The full URL of the destination.