Extending subtopic-splitting to specialized topic types

[chrispitude]

In Oxygen, there is a handy Convert nested subtopics to new topics refactoring operation that splits a single large topic file (with nested subtopics in that file) to multiple smaller topic files. But we are using our own DITA-specialized topic types (defined in a RelaxNG schema), and the refactoring operation needs to know what URN values to use for such specialized topics.

Fortunately, Oxygen v22 added support for specifying this. The refactoring operation uses the following file to determine what URN to use for a given topic type:

Code: Select all

${OXYGEN_HOME}/frameworks/dita/refactoring/utils/dita-formats.xsl

Inside this file, there is a table like this:

Code: Select all

    <!-- Maps topic names to RNG URLs -->
    <xsl:variable name="DEFAULT_RNG_FORMATS" as="map(xs:string, xs:string)" select="map {
        'topic' : 'urn:oasis:names:tc:dita:rng:topic.rng',
        'task' : 'urn:oasis:names:tc:dita:rng:task.rng',
        'glossentry' : 'urn:oasis:names:tc:dita:rng:glossentry.rng',
        'concept' : 'urn:oasis:names:tc:dita:rng:concept.rng',
        'glossgroup' : 'urn:oasis:names:tc:dita:rng:glossgroup.rng',
        'reference' : 'urn:oasis:names:tc:dita:rng:reference.rng',
        'troubleshooting' : 'urn:oasis:names:tc:dita:rng:troubleshooting.rng'
        }">
    </xsl:variable>

So, how do we modify this table with our own topic types? Radu was kind enough to provide the answer to this. This solution assumes you are using a custom framework extension for DITA topics:

image.png

In the Catalogs tab of the framework configuration, add a ${framework}/refactoring/catalog.xml entry:

image.png

(The ${framework} Oxygen variable already contains the "dita/" path too - I forgot this at first and included "dita/" in the path and it didn't work.)

Now at the following path in your custom frameworks directory:

Code: Select all

<your_framework_dir>/dita/refactoring/

you must do two things:

1. Create a catalog.xml file with the following content:

Code: Select all

<?xml version="1.0"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <uriSuffix uriSuffix="dita-formats.xsl" uri="dita-formats.xsl"/>
</catalog>

2. Copy the dita-formats.xml file from the Oxygen frameworks directory to this location.

You should have a catalog.xml file and dita-formats.xml side-by-side in your framework's refactoring directory. Now you can modify the dita-formats.xml file to include the RelaxNG URN identifiers for your custom topic types in the DEFAULT_RNG_FORMATS list.

This trick works because when Oxygen's Convert nested subtopics to new topics refactoring operation references "dita-formats.xml", your new catalog file resolves this directly to the actual dita-formats.xml file located alongside it.

Thanks Radu!

[Radu]

Hi Chris,

Thanks for taking the time to post a detailed solution for this.

Regards,
Radu