Creating Related Topics for Sections in a DITA Reference Topics
Purpose
We use DITA XML files as the basis for our ePublisher projects. We create reltables in our ditamaps to create family links between sequential topics within a “chapter”. However, we use reference topics that are divided into sections. Each section becomes a separate page in the online help that we output from ePublisher, but we cannot use the reltable to create related topics between each section of the reference topic.
I discovered that by adding xrefs to the end of each section in the reference topic, making use of the outputclass attribute, and modifying the default.wwconfig file, I could create related topics within a reference topic.
Authoring environment: Adobe FrameMaker 9.0
- ePublisher version: 2009.4
Output: WebWorks Help 5.0
Before you begin
Make sure that you create a Project Target Override (http://www.webworks.com/Support/ePublisher/Legacy_Docs/Tech_Notes/Common/EX_ePub_Project_Format_Overrides.shtml). In addition, make sure you back up your original default.wwconfig file.
Preparing your DITA files
Before you go “under the hood” with ePublisher, you must prepare the xrefs in you DITA files in two different ways. The xrefs that you prepare for the reference topic will become an xref paragraph style in ePublisher. However, you must prepare other types of xrefs differently in your DITA files so that they create a different paragraph style called TopicTitle in ePublisher. This allows you to manipulate those xrefs differently, and prevents them from disappearing when you generate your output.
In the reference topic:
Insert a <title> element in each section (I found that you must use the <title> element that is a child of the <section>; not the <section> element itself).
- Assign an ID for each title element.
At the end of the first section, add an <xref> element. The DITA Cross-Reference dialog box appears.
- In the Elements Tags list, select Title.
- In the Element Data list, select the appropriate ID/content.
Add all of the required <xref> elements to that section.
Add <xref> elements to each section.
If you need to filter these xref elements so they do not appear in your print output, you can, for example, set the otherprops attribute value for each <xref> element to "online", and add <prop att='otherprops' val='online' action='exclude' /> to the ditaval file that you use when you create your print output.
Preparing other types of xrefs:
In our online help ditamap, we include a file that has xrefs to other DITA files, and a file that has xrefs to external PDF files. If you use other types of xrefs in your project, you must add a value to the outputclass attribute of the <xref>element. This prevents the other types of xrefs from disappearing when you set the reference topic xrefs to related topics.
For xrefs that point to other DITA files, set the outputclass attribute to TopicTitle. In FrameMaker 9.0, you can do this by double-clicking the outputclass attribute, and then selecting TopicTitle from the Choice list in the Attributes dialog box.
For xrefs that point to external files, change the outputclass attribute value to TopicTitle manually. In FrameMaker 9.0, you can do this by double-clicking the outputclass attribute, and then manually entering TopicTitle into the Attribute Value field in the Attributes dialog box.
Modifying ePublisher
By default, ePublisher interprets the xref element as a character, rather than a paragraph. Make the <xref> element a paragraph so that you can the xrefs to a Related Topics menu at the bottom of each HTML page.
To change the xref from a character to a paragraph:
Open the \Targets\WebWorks Help 5.0\Adapters\xml\scripts\dita\default.wwconfig file and copy this line in the Types > Character section: <Type match="//*[contains(@class, ' topic/xref ')]" value="Character" />
- In the copied line, change “Character” to “Paragraph” like this:
<Type match="//*[contains(@class, ' topic/xref ')]" value="Paragraph" />
Move the new line to the Types > Paragraph section.
- Scan your documents.
Two new names should now appear in the Paragraph Styles list: TopicTitle and xref. ePub looks at the value in the <xref> element’s attribute class, and uses that value as the name of the paragraph style. When you rescan your documents, the paragraph style is xref. UNLESS you manually changed the value of the outputclass attribute for <xref>. If you did, then that value becomes the name of the paragraph style, which is this case is TopicTitle.
- Select the xref paragraph style, and on the Options tab, set Related topic to Define with no output.
Go to Project > Regenerate all.
Your xrefs from the reference topics should now appears as related topics, while your other xrefs should appear as hyperlinks.
Reference
DITA Configuration by Zoe Lawson (http://wiki.webworks.com/HelpCenter/Tips/DITA/All%20Versions/DITA%20Configuration)