Example topic specialization: FAQ

Topic specializations typically define new element types as well as their hierarchy, or structure. One readily-available example of a topic specialization is the Frequently Asked Questions (FAQ) specialization.

1. If you do not already have a copy of the FAQ specialization, download it from the DITA-OT plugins repository on GitHub.
   Note: You must download all plugins identified in this task as a ZIP file by clicking the Download ZIP button on the right side of the page, and then extract the ZIP file to access just the faq folder.
2. Add the faq folder to Repository/system/plugins.
3. In Repository/system/catalogs, open master-catalog.xml and add the following 2 lines.

   <!--FAQ specialization -->
   	<nextCatalog catalog="../plugins/faq/catalog.xml"/>

4. Save, close, and check in master-catalog.xml.
5. In the faq folder, open catalog.xml and copy the following 2 lines.

   <public publicId="-//IBM//DTD DITA FAQ//EN" uri="faq_shell.dtd"/>
   <public publicId="-//IBM//ELEMENTS DITA FAQ//EN" uri="faq.mod"/>

6. Within your custom DTD plugin, such as com.company.dita.dtd, check out and open catalog.xml.
7. After the last <group>, add a new group.

   <!-- FAQ -->
   <group xml:base="../faq/">
   </group>

   Make sure the xml:base is set, which specifies that the starting point of the relative path in the uri of the system identifiers in this group is the system/plugins/faq subfolder. Starting here keeps the uri paths simple.

8. Within the new <group>, paste the 2 lines you copied from the faq catalog.xml.

   <!-- FAQ -->
   <group xml:base="../faq/">
      <public publicId="-//IBM//DTD DITA FAQ//EN" uri="faq_shell.dtd"/>
      <public publicId="-//IBM//ELEMENTS DITA FAQ//EN" uri="faq.mod"/>
   </group>

9. Save, close, and check in catalog.xml in your custom DTD plugin.
10. Check out and open CompanyDitabase.dtd.
11. Add the following lines within the Topic Element Integration section.
    Note: The FAQ specialization is not complex with only a .mod file and no .ent files. If your specialization has .ent files, you'll need to add them to the appropriate places in CompanyDitabase.dtd.

    <!ENTITY % faq-typemod 
      PUBLIC "-//IBM//ELEMENTS DITA FAQ//EN" 
             "../../faq/faq.mod"
    >%faq-typemod;

12. Save, close, and check in CompanyDitabase.dtd.
13. Check out and open Repository/system/conf/equivalence.xml.
14. In the <equivalence type="topic"> section, add the following line.
    Note: The line specifies that the CMS should use the same icon for FAQ topics that it does for reference topics. If you want to specify a unique icon for FAQ topics, you can add it in the location shown and edit the line accordingly.

    <object type="faq" icon="/system/conf/icons/reference.png"/>

15. Save, close, and check in equivalence.xml.
16. Check out and open Repository/system/conf/ditaclasses.xml.
17. After the last existing entry that begins with <class name="- topic/topic, add the following lines to ensure you can publish FAQ topics.
    Important: You should copy and paste this codeblock to ensure you get the correct number of spaces in the class name between topic/topic and faq/faq. The class comes from the faq.mod file in the FAQ plugin folder. At the end of the file, there is a section named Element specialization declarations. The first entry in that section is <!ATTLIST faq class CDATA "- topic/topic faq/faq ">. The number of spaces you use in ditaclasses.xml must exactly match the number of spaces in the class declaration in faq.mod.

    <class name="- topic/topic       faq/faq " path="//*[contains(@class, 'topic ' )]/prolog/metadata" 
        position="//*[contains(@class, 'topic ' )]/prolog/metadata/unknown|//*[contains(@class, 'topic ' )]/prolog/metadata/foreign|//*[contains(@class, 'topic ' )]/prolog/metadata/data-about|//*[contains(@class, 'topic ' )]/prolog/metadata/data" 
        type="faq" variables="false"/>

18. Use an editor, such as Notepad++, to create a template for faq topics.
    Tip: The simplest approach is to create the template on your desktop.

    Important: Use the correct DOCTYPE, especially if you already have templates for your specialized topic type. This FAQ example uses the faq DOCTYPE because that is the DOCTYPE defined by the specialization.
    To start with, copy and paste the following codeblock into the file.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE faq PUBLIC "-//COMPANY//DTD DITA Composite//EN" "CompanyDitabase.dtd">
    <faq id="faq">
       <title></title>
       <faqbody>
          <faqgroup>
             <title></title>
             <faqlist>
                <faqitem>
                   <faqquest></faqquest>
                   <faqans></faqans>
                </faqitem>
             </faqlist>
          </faqgroup>
       </faqbody>
    </faq>

19. Name the template faq.xml and add it to Repository/system/templates/topics using Insert Documents.
    Note: If you have subfolders within the topics folder, add it to the appropriate subfolder.
20. Restart the IXIA CCMS Desktop.
21. (Oxygen only) Create a FAQ topic and attempt to view it in Author view.

    Oxygen displays an error message indicating it cannot find the CSS for FAQ topics.

22. (Oxygen only) Select XML > Associate XSLT/CSS stylesheet.
23. (Oxygen only) Click the arrow beside the folder icon to the right of the URL field and select Browse workspace.
24. (Oxygen only) Browse to the system/plugins/faq folder in your workspace and select the faq.css file.

    The CSS is now associated with the FAQ topic type so that Oxygen can display FAQs correctly. You only need to make this association once.

25. To add the FAQ specialization to IXIA CCMS Output Generator, take the following actions:
    1. Add the faq folder to %OutputGenDir%/data/%OT_Dir%/.
       Note: Depending on your CCMS Output Generator configuration, the DITA-OT path might vary.
    2. Run the integrator to integrate the plugin.