Topic Specialization Step 3. Package the Modules as a Toolkit Plugin

Now that the declarations are complete and validated, we need to package the declarations for use in documents. The best way to do this is to package it as an Open Toolkit plugin. Making it into a plugin does two things:
To set up the plugin, follow these steps:
  1. In the faq-question directory create a file named plugin.xml with this content:
    <plugin id="org.example.faq-question.doctype">
      <feature extension="dita.specialization.catalog.relative" value="catalog.xml" type="file"/>
    Note: This defines a single plugin with just this module. In practice you would normally package all the related document type shells, vocabulary modules, and constraint modules together as a single Toolkit plugin. See Packaging Document Type Shells and Vocabulary Modules as Toolkit Plugins.
  2. In the faq-question directory create a file named catalog.xml with this content:
    <?xml version="1.0" encoding="UTF-8"?>
    <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
      <nextCatalog catalog="dtd/catalog.xml"/>
  3. In the faq-question/dtd directory create a file named catalog.xml with this content:
    <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
      <public publicId=""
      <public publicId=""
      <public publicId=""
    Note: In practice you would replace "" with your own domain name or its universally-unique equivalent in the URNs.
  4. Edit the file faq-question/dtd/faq-question.dtd and update the entity declarations for the .ent and .mod files to use the URNs defined in the catalog file:
    <!ENTITY % faq-question-dec     
      PUBLIC "" 
    <!ENTITY % faq-question-typemod 
      PUBLIC "" "faq-question-v1.mod"                                                        
    Tip: Common mistake: Using the .mod file's URN for the .ent file or visa versa.

    This is an easy mistake to make and a hard one to catch because the URNs are so similar. One symptom of this is that the shell that's in the same directory as the modules works, because it's system IDs are resolvable, but a different shell that uses the same modules fails because the URNs are wrong and the system IDs are not resolvable. That is one reason to make sure that system IDs are not resolvable--it helps reveal this sort of error.

    Making this mistake can lead to baffling validation errors from XML parsers, such as duplicate element type declarations or other DTD syntax errors. Whenever you get those the first thing to check is the public IDs of the module entity declarations in the shell document types.

  5. Copy the test document to create a new test document, faq-question-test-02.xml, and modify its DOCTYPE declaration so it uses the URN of the .dtd file and uses an bogus system identifier (so the parser has to use the public ID to resolve the reference to the DTD file1):
    <?xml version="1.0"?>          
    <!DOCTYPE faq-question 
      PUBLIC "" 
    <faq-question id="question-id">
      <faq-question-statement>Can I add attributes to specific element types?</faq-question-statement>
      <faq-answer >
        <p>No, you can only define global attributes, specialized either from @ase
        or @props.</p>

    Edit this document: it should not validate as you haven't deployed the plugin to your Open Toolkit yet.

  6. Deploy the plugin to your Open Toolkit by copying the faq-question directory to the plugins directory of your Open Toolkit.
    Run the integrator.xml Ant task to integrate the plugin:
    c:\DITA-OT > ant -f integrator.xml

    This has the effect of adding a reference to the faq-question/catalog.xml file into the Toolkit's master entity resolution catalog, catalog-dita.xml.

  7. Configure your editor or a validation tool to use the catalog catalog-dita_template.xml and verify that the faq-question-test-02.xml document validates.

    If you are using OxygenXML and you deployed the plugin to Oxygen's Toolkit then you should just need perform the "Reset cache and validate" action. With other editors or validators you may need to explicitly configure the use of the catalog-dita.xml catalog.

Your new topic type is now ready to use.

1 Pedantically, the reference to the external parameter entity declaration set.