DTD Topic Type Shell Tutorial Step 3: Add Reference to a New Domain

For this tutorial we will to integrate the XML domain defined in Element Domain Specialization Tutorial.

Note: You can get the worked result of that tutorial from the tutorial materials.

To integrate a new domain, we add the following four components:

A declaration and reference to the domain's .ent file
A reference to the domain's domain extension parameter entities, one for each different base element type the domain extends.
A reference to the domain's @domains attribute text entity in the &included-domains; text entity declaration.
A declaration and reference to the domain's .mod file.

For a given domain to be integrated you need to know the following:

The public IDs of the .ent and .mod files. This should be in the entity resolution catalog for the domain. If the domain is packaged using the pattern described here, then the catalog file should be in the same directory as the .ent and .mod files for the domain. If you are integrating a standard DITA domain, you can look in the DITA standard itself or in the catalog_dita.xml file that is in the Open Toolkit's top-level directory.
The set of domain extension parameter entities the module defines. These should be defined in the .ent file for the domain. For example, the file softwareDomain.ent has these declarations:
```
<!ENTITY % sw-d-pre     
  "msgblock
  "
>
<!ENTITY % sw-d-ph      
  "filepath | 
   msgph |
   systemoutput  | 
   userinput
  "
>
<!ENTITY % sw-d-keyword 
  "cmdname  | 
   msgnum | 
   varname
  "
>
```
Reflecting the fact that the software domain specializes from <pre>, <ph>, and <keyword>.

The name of the @domains attribute text entity, which should be named "domainShortName-d-att", e.g., "sw-d-att". This should also be declared in the .ent file for the domain. For the software domain it looks like this:

<!-- ============================================================= -->
<!--                    DOMAIN ENTITY DECLARATION                  -->
<!-- ============================================================= -->

<!ENTITY sw-d-att       
  "(topic sw-d)"
>

We want to integrate the XML domain defined in the Element Domain Specialization tutorial. The information we need for the XML domain is:

.ent file public ID: "urn:pubid:example.org:doctypes:dita:modules:xml:entities"
.mod file public ID: "urn:pubid:example.org:doctypes:dita:modules:xml:declarations"
domain extension parameter entities: %xml-d-keyword;
domains attribute text entity: &xml-d-att;

Armed with this knowledge, the process of integrating the domain is as follows:

Find the declaration and reference for the %hi-d-dec; parameter entity. Copy it and paste a new copy into myTopic.dtd immediately after the original:

...

<!-- ============================================================= -->
<!--                    DOMAIN ENTITY DECLARATIONS                 -->
<!-- ============================================================= -->


<!ENTITY % hi-d-dec     
  PUBLIC "-//OASIS//ENTITIES DITA 1.2 Highlight Domain//EN" 
         "../../base/dtd/highlightDomain.ent"
>%hi-d-dec;

<!ENTITY % hi-d-dec     
  PUBLIC "-//OASIS//ENTITIES DITA 1.2 Highlight Domain//EN" 
         "../../base/dtd/highlightDomain.ent"
>%hi-d-dec;

...

In the copy, change "hi-d-dec" to "xml-d-dec" in both places where it occurs:

<!ENTITY % xml-d-dec     
  PUBLIC "-//OASIS//ENTITIES DITA 1.2 Highlight Domain//EN" 
         "../../base/dtd/highlightDomain.ent"
>%xml-d-dec;

Replace the public identifier string with the URN for the XML domain:

<!ENTITY % xml-d-dec     
  PUBLIC "urn:pubid:example.org:doctypes:dita:modules:xml:entities" 
         "../../base/dtd/highlightDomain.ent"
>%xml-d-dec;

Replace the system identifier with "xmlDomain.ent":

<!ENTITY % xml-d-dec     
  PUBLIC "urn:pubid:example.org:doctypes:dita:modules:xml:entities" 
         "xmlDomain.ent"
>%xml-d-dec;

Find the comment "DOMAIN EXTENSIONS" and add a reference to the %xml-d-keyword; parameter entity to the declaration of the %keyword; parameter entity:
```
...






<!ENTITY % pre          "pre
                        ">
<!ENTITY % keyword      "keyword |
                         %xml-d-keyword;
                        ">

...
```
Note the leading "|" character added after "keyword " in the original declaration. This parameter entity is used to build up an OR group of element type names, so you need to add the "|" (OR) connector between "keyword" and "%xml-d-keyword;".

Tip: Common error: If you forget the "|" character or accidentally leave one out you will get validation errors that may be cryptic or misleading, because they will often point to the declarations for elements somewhere deep in the DITA declaration sets, usually the first element type encountered that happens to use the parameter entity you just modified. When you get this type of error, the first thing to check is your domain extension parameter entities—that is likely the cause of the error, especially if you are integrating pre-existing domains that you know are otherwise valid.

Find the comment "DOMAINS ATTRIBUTE OVERRIDE" and then the declaration for the &included-domains; text entity. Add a reference to the &xml-d-att; text entity:

...

<!-- ============================================================= -->
<!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
<!-- ============================================================= -->
<!--                    Must be declared ahead of the DTDs, which
                        puts @domains first in order               -->

<!ENTITY included-domains 
                          "&hi-d-att; 
                           &ut-d-att; 
                           &indexing-d-att;
                           &abbrev-d-att;
                           &xml-d-att;
  "
>

...

Find the declaration and reference for the %hi-d-def; parameter entity. Copy it and paste a new copy immediately after the original:

...

<!-- ============================================================= -->
<!--                    DOMAIN ELEMENT INTEGRATION                 -->
<!-- ============================================================= -->

<!ENTITY % hi-d-def     
  PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Highlight Domain//EN" 
         "../../base/dtd/highlightDomain.mod"
>%hi-d-def;

<!ENTITY % hi-d-def     
  PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Highlight Domain//EN" 
         "../../base/dtd/highlightDomain.mod"
>%hi-d-def;

...

Change "hi-d-def" to "xml-d-def" everywhere it occurs:

<!ENTITY % xml-d-def     
  PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Highlight Domain//EN" 
         "../../base/dtd/highlightDomain.mod"
>%xml-d-def;

Change the public identifier to the public ID for xmlDomain.mod:
```
<!ENTITY % xml-d-def     
  PUBLIC "urn:pubid:example.org:doctypes:dita:modules:xml:declarations" 
         "../../base/dtd/highlightDomain.mod"
>%xml-d-def;
```
Tip: Common error: If you are copy the public ID or URN from a catalog file, it is easy to accidently copy the public ID for the .ent file instead of for the .mod file and visa versa. If you get mysterious errors, like duplicate declaration messages or "element type note declared" messages even though you know you included the module, check the public ID value to make sure you didn't mix up the .ent and .mod public IDs.

Change the system identifier to "xmlDomain.mod":

<!ENTITY % xml-d-def     
  PUBLIC "urn:pubid:example.org:doctypes:dita:modules:xml:declarations" 
         "xmlDomain.mod"
>%xml-d-def;

Validate your test document. Assuming that the XML domain module is already deployed (you can find it in the materials package for the tutorials), then your document should validate if you haven't made any syntax errors in the shell DTD.
If the document validates, see if you can enter any of the element types from the domain, such as <xmlelem> or <xmlatt>, into a paragraph. You should be able to.

That's it, you're done. You've successfully created a new topic type shell that removes domains you don't want and adds a new domain you do want.

It should be clear from following this tutorial that creating document type shells is an entirely mechanical process and that once you've done it once or twice it becomes very easy and quick.

This tutorial did not show how to package your new shell as a Toolkit plugin. For that, see Packaging Document Type Shells and Vocabulary Modules as Toolkit Plugins.

This tutorial shows how to create a topic type shell. Creating map type shells is exactly the same.