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.
Before you begin
Before you integrate an FAQ specialization using IxiaDitabase.xml, it's best practice to create and use your own custom shell DTD and plugin. To integrate any other DTDs, follow a similar process, using your own shell and plugin.
About this task
Suppose you need to create a set of topics dedicated to addressing frequently asked questions (FAQs). Because each specialization is slightly different, follow the identified procedure, using the same filenames for CompanyDitabase.dtd and catalog.xml.
To integrate a sample FAQ topic specialization:
Procedure
-
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.
- Add the faq folder to Repository/system/plugins.
-
In Repository/system/catalogs, open
master-catalog.xml and add the following 2 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 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"/>
- Within your custom DTD plugin, such as com.company.dita.dtd, check out and open catalog.xml.
-
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 theuri
of the system identifiers in this group is the system/plugins/faq subfolder. Starting here keeps theuri
paths simple. -
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>
- Save, close, and check in catalog.xml in your custom DTD plugin.
- Check out and open CompanyDitabase.dtd.
-
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;
- 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.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"/>
- 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 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 betweentopic/topic
andfaq/faq
. The class comes from the faq.mod file in the FAQ plugin folder. At the end of the file, there is a section namedElement 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"/>
-
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 thefaq
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>
- 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.
- Restart the IXIA 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) 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.
-
To add the FAQ specialization to IXIA CCMS Output Generator, take the
following actions:
-
Add the faq folder to
%OutputGenDir%/data/%OT_Dir%/.
Note: Depending on your CCMS Output Generator configuration, the DITA-OT path might vary.
- Run the integrator to integrate the plugin.
-
Add the faq folder to
%OutputGenDir%/data/%OT_Dir%/.