Method 2: Integrate your DTDs into your custom topic and map shells for DITA 1.2

These steps assume you have created a plugin for your custom DTDs, following the procedure in Method 1: Create a custom plugin for your own shells for DITA 1.2.

These steps use some of the Learning and Training domain files to illustrate the integration process. These files are part of the org.oasis-open.dita.v1_2 plugin. Your exact process may vary depending on the nature of your custom DTDs, but the idea is the same...to reference the individual files in a separate DTD plugin within your topic and map shells.

Note: IXIASOFT recommends that you work within a local copy of your system configuration and that you use Oxygen to edit DTDs. If you mistype or add an incorrect path, Oxygen notifies you right away of the error.
  1. Open CompanyDitabase.dtd (your topic shell in com.company.dtd).
  2. Open the first custom DTD you want to integrate into CompanyDitabase.dtd.

    For this example, we'll choose learningSummary.dtd (in DITA-OT\plugins\org.oasis-open.dita.v1_2\dtd\learning\dtd).

  3. In learningSummary.dtd, scroll to the TOPIC ENTITY DECLARATIONS section.

    There are two entities there:

    <!ENTITY % learningBase-dec     
      PUBLIC "-//OASIS//ENTITIES DITA 1.2 Learning Base//EN" 
             "learningBase.ent"
    >%learningBase-dec;
    
    <!ENTITY % learningSummary-dec     
      PUBLIC "-//OASIS//ENTITIES DITA 1.2 Learning Summary//EN" 
             "learningSummary.ent"
    >%learningSummary-dec;
  4. Copy and paste these two entities into the TOPIC ENTITY DECLARATIONS section of CompanyDitabase.dtd, at the end of the list.
  5. Change the paths of both entities to correctly point to the locations of the learningBase.ent and learningSummary.ent files relative to CompanyDitabase.dtd.

    If both plugins are located in the system/plugins folder of the CCMS system configuration, the correct paths are:

    <!ENTITY % learningBase-dec
      PUBLIC "-//OASIS//ENTITIES DITA 1.2 Learning Base//EN"
             "../../org.oasis-open.dita.v1_2/dtd/learning/dtd/learningBase.ent"
    >%learningBase-dec;
    
    <!ENTITY % learningSummary-dec
      PUBLIC "-//OASIS//ENTITIES DITA 1.2 Learning Summary//EN"
             "../../org.oasis-open.dita.v1_2/dtd/learning/dtd/learningSummary.ent"
    >%learningSummary-dec;

    It is critical to get these paths correct.

  6. In learningSummary.dtd, scroll to the DOMAIN ENTITY DECLARATIONS section.
  7. Look for any entities that are unique to learningSummary.dtd.

    There are three unique entities there:

    <!ENTITY % learningInteractionBase-d-dec 
      PUBLIC "-//OASIS//ENTITIES DITA 1.2 Learning Interaction Base Domain//EN" 
             "learningInteractionBaseDomain.ent">
      %learningInteractionBase-d-dec;
    
    <!ENTITY % learning-d-dec 
      PUBLIC "-//OASIS//ENTITIES DITA 1.2 Learning Domain//EN" 
             "learningDomain.ent">
      %learning-d-dec;
    
    <!ENTITY % learningmeta-d-dec 
      PUBLIC "-//OASIS//ENTITIES DITA 1.2 Learning Metadata Domain//EN" 
             "learningMetadataDomain.ent">
      %learningmeta-d-dec;

    The other entities in this section are not unique to learningSummary.dtd and are already integrated into CompanyDitabase.dtd. You don't need to integrate them again.

  8. Copy and paste these three entities into the DOMAIN ENTITY DECLARATIONS section of CompanyDitabase.dtd, at the end of the list.
  9. Change the paths of all entities to correctly point to the locations of these files relative to CompanyDitabase.dtd.
  10. In learningSummary.dtd, scroll to the DOMAIN EXTENSIONS section.
  11. Look through each of the entities defined there to spot any extensions that are specific to the learningSummary.dtd.

    In this case, there are quite a few:

    <!ENTITY % ph           "ph |
                             %hi-d-ph;
                            ">
    <!ENTITY % fig          "fig |
                             %ut-d-fig; |
                             %learningInteractionBase-d-fig; |
                             %learning-d-fig;
                            ">
    <!ENTITY % lcInteractionBase "lcInteractionBase |
                             %learning-d-lcInteractionBase;
                            ">                        
    <!ENTITY % index-base   "index-base | 
                             %indexing-d-index-base;
                            ">
    <!ENTITY % note         "note | 
                             %learning-d-note;
                            ">
    <!ENTITY % metadata     "metadata |
                             %learningmeta-d-metadata;
                             ">

    As you can see, some are additional extensions within existing entities (fig, metadata, note) and one is an entirely new entity (lcInteractionBase). You treat these slightly differently.

  12. Copy and paste the additional extensions within the existing entities and paste them into the same entity in CompanyDitabase.dtd.

    For example, copy %learningInteractionBase-d-fig; and %learning-d-fig; and paste them into the existing fig entity in CompanyDitabase.dtd:

    <!ENTITY % fig          "fig | 
                             %pr-d-fig; | 
                             %ut-d-fig; |
    						 %learningInteractionBase-d-fig; |
                             %learning-d-fig;
                            ">

    Be sure to add the | after %ut-d-fig; and %learningInteractionBase-d-fig;.

  13. Repeat step 11 to add the remaining extensions to the existing entities (metadata, note).
  14. Copy the lcInteractionBase entity as-is from learningSummary.dtd to CompanyDitabase.dtd.
  15. In learningSummary.dtd, scroll to the DOMAIN ATTRIBUTE OVERRIDE section.
  16. Look through the list for any domains that are unique to learningSummary.dtd.

    In this case, there are six unique included domains

    <!ENTITY included-domains 
                              "&hi-d-att; 
                               &ut-d-att; 
                               &indexing-d-att;
                               &learningInteractionBase-d-att;
                               &learning-d-att;
                               &learningmeta-d-att; 
                               &learningBase-att;
                               &learningSummary-att; 
      "
    >
  17. Copy these five domains and paste them into the DOMAIN ATTRIBUTE OVERRIDE section in CompanyDitabase.dtd.
  18. In learningSummary.dtd, scroll to the TOPIC ELEMENT INTEGRATION section.

    There are three entities there:

    <!--                    Embed topic to get generic elements        -->
    <!ENTITY % topic-type   PUBLIC 
    "-//OASIS//ELEMENTS DITA 1.2 Topic//EN" 
    "../../base/dtd/topic.mod"                                           >
    %topic-type;
    
    <!--Embed learningBase to get specific elements -->
    <!ENTITY % learningBase-typemod PUBLIC 
    "-//OASIS//ELEMENTS DITA 1.2 Learning Base//EN" 
    "learningBase.mod">
      %learningBase-typemod;
    
    <!--Embed learningSummary to get specific elements -->
    <!ENTITY % learningSummary-typemod PUBLIC 
    "-//OASIS//ELEMENTS DITA 1.2 Learning Summary//EN" 
    "learningSummary.mod">
      %learningSummary-typemod;

    The other entities in this section are not unique to learningSummary.dtd and are already integrated into CompanyDitabase.dtd. You don't need to integrate them again.

  19. Copy and paste the last two entities (learningBase-typemod and learning-Summary-typemod) into the TOPIC ELEMENT INTEGRATION section of CompanyDitabase.dtd, at the end of the list.
  20. Change the paths of both entities to correctly point to the locations of the learningBase.mod and learningSummary.mod files relative to CompanyDitabase.dtd.
  21. In learningSummary.dtd, scroll to the DOMAIN ELEMENT INTEGRATION section.
  22. Look for any entities that are unique to learningSummary.dtd.

    There are three unique entities there:

    <!ENTITY % learningInteractionBase-d-def
      PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Learning Interaction Base Domain//EN" 
             "learningInteractionBaseDomain.mod">
      %learningInteractionBase-d-def;
    
    <!ENTITY % learning-d-def
      PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Learning Domain//EN" 
             "learningDomain.mod">
      %learning-d-def;
    
    <!ENTITY % learningmeta-d-def
      PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Learning Metadata Domain//EN" 
             "learningMetadataDomain.mod">
      %learningmeta-d-def;

    The other entities in this section are not unique to learningSummary.dtd and are already integrated into CompanyDitabase.dtd. You don't need to integrate them again.

  23. Copy and paste these three entities into the DOMAIN ELEMENT INTEGRATION section of CompanyDitabase.dtd, at the end of the list.
  24. Change the paths of all entities to correctly point to the locations of these files relative to CompanyDitabase.dtd.
  25. Save CompanyDitabase.dtd.

Follow this same general procedure to integrate additional individual topic DTDs into your CompanyDitabase.dtd shell and to integrate additional individual map DTDs into your CompanyMap.dtd shell.

Note: If you are actually integrating the Learning and Training domain, you do not have to add anything to the master catalog. These files are part of the org.oasis-open.dita.v1_2 plugin, which is already referenced in the master catalog.