Integrate the FAQ specialization

Before integrating the FAQ (Frequently Asked Questions) specialization—or any other specialization—you should create a custom shell DTD and plugin. While you can integrate using IxiaDitabase.xml, it's a much better practice to use your own shell. These instructions assume you are using your own shell DTD and plugin.

These steps describe how to integrate the FAQ specialization. To integrate any other DTDs, you will follow a similar process, though each specialization is slightly different. These steps use the same file names as in the previous instructions (CompanyDitabase.dtd and catalog.xml).

If you do not already have a copy of the FAQ specialization, download it from the DITA-OT plugins repository on GitHub.

There is a long list of plugins on this page, and you must download them all as a zip file, then extract the zip file to access just the faq folder. To download the zip, click the Download ZIP button on the right side of the page.
Add the faq folder to Repository/system/plugins.
In Repository/system/catalogs, open master-catalog.xml.

Add the following lines.

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

Save, close and check in master-catalog.xml.

In the faq folder, open catalog.xml and copy these two lines.

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

Within your custom DTD plugin (com.company.dita.dtd in these examples), check out and open catalog.xml.
After the last <group>, add a new group as shown.
```

<group xml:base="../faq/">
</group>
```
Make sure the xml:base is set as shown. This setting 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 as simple as possible.

Within the new <group>, paste the two 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>

Save, close and check in catalog.xml in your custom DTD plugin.
Check out and open CompanyDitabase.dtd.
Add the following within the Topic Element Integration section:
```
<!ENTITY % faq-typemod 
  PUBLIC "-//IBM//ELEMENTS DITA FAQ//EN" 
         "../../faq/faq.mod"
>%faq-typemod;
```
The FAQ specialization is quite simple and has only a .mod file; it doesn't have any .ent files. If your specialization has .ent files, you'll need to add them to the appropriate places in CompanyDitabase.dtd.
Save, close, and check in CompanyDitabase.dtd.
Check out and open Repository/system/conf/equivalence.xml.
In the <equivalence type="topic"> section, add the following line:
```
<object type="faq" icon="/system/conf/icons/reference.png"/>
```
As shown, this 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.
Save, close and check in equivalence.xml.
Check out and open Repository/system/conf/ditaclasses.xml.
After the last existing entry that begins with <class name="- topic/topic, add the following:
```
<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"/>
```
This information is needed to ensure you can publish FAQ topics.

Important: You might want to copy and paste this text to ensure you get the correct number of spaces in the class name between "topic/topic" and "faq/faq". This class comes from the faq.mod file in the faq plugin folder. At the end of that 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.
Using an editor such as Notepad++, create a template for faq topics.
Tip: You will probably find it easiest to create the template on your desktop.
As a starter, you can copy and paste the following 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>
```
Be sure to use the correct DOCTYPE here, especially if you already have templates for your specialized topic type. This example uses the faq DOCTYPE because that is the DOCTYPE defined by the specialization.
Name the template faq.xml and add it to Repository/system/templates/topics using Insert Documents.

If you have subfolders within the topics folder, add it to the appropriate subfolder.
Restart the IXIASOFT CCMS Desktop.
(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.
(oXygen only) Select XML > Associate XSLT/CSS stylesheet.
(oXygen only) Click the arrow beside the folder icon to the right of the URL field and select Browse workspace.
(oXygen only) Navigate 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.
To add the FAQ specialization to IXIASOFT CCMS Output Generator, do the following:
1. Add the faq folder to %OutputGenDir%/data/%OT_Dir%/.
  
  Depending on your CCMS Output Generator configuration, the DITA-OT path might vary.
2. Run the integrator to integrate the plugin.

You can now create faq-type topics.