Wednesday, January 03, 2018

Sorting glossary lists in a DITA Bookmap

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

The idea behind this DITA refactoring action started from this forum post: https://www.oxygenxml.com/forum/viewtopic.php?f=2&t=15284&p=45137#p45137.

Let's say you have a DITA Bookmap which at some point refers to all its glossary entries:
            <glossarylist>
                <topicref href="glossary/glossItem1.dita"/>
                <topicref href="glossary/glossItem2.dita"/>
                <topicref href="glossary/glossItem3.dita"/>
                <topicref href="glossary/glossItem4.dita"/>
            </glossarylist>
and you want to have all these glossary topics sorted alphabetically by title as they appear in the PDF output.

One option for this is to create a PDF customization which automatically sorts the glossary entries no matter in what order they were originally specified in the DITA Map.

The other option is to create a custom Oxygen XML Refactor operation which when applied on the DITA Bookmap containing the "glossarylist" will sort out the glossentries in aphabetical order looking at the title of each glossentry. Below you can find some steps for this:
  1. Create somewhere on disk a folder called for example customRefactor and add a reference to it in the Oxygen Preferences->"XML / XML Refactoring" page.
  2. Create in that custom folder an XML file called for example sortGlossentries.xml having as content:
    <refactoringOperationDescriptor 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.oxygenxml.com/ns/xmlRefactoring" id="op_tck_rp1_hcb" name="Sort glossentries">
        <description>Sort glossentries.</description>    
        <script type="XSLT" href="sortGlossentries.xsl"/>
    </refactoringOperationDescriptor>
    This particular descriptor file contains the name of the operation, its description and points to an XSLT stylesheet which will be applied to sort the entries in the DITA Bookmap.
  3. Create in the same folder a file called sortGlossentries.xsl having as content:
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        exclude-result-prefixes="xs"
        version="2.0">
        <xsl:template match="node() | @*">
            <xsl:copy>
                <xsl:apply-templates select="node() | @*"/>
            </xsl:copy>
        </xsl:template>
        <xsl:template match="glossarylist">
            <xsl:copy>
                <xsl:apply-templates select="@*"/>
                <xsl:for-each select="*" >
                    <xsl:sort select="document(@href, .)/*/glossterm/text()"/>
                    <xsl:apply-templates select="."/>
                </xsl:for-each>
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>
    This particular XSLT processing copies almost all the Bookmap content unchanged. But the topicrefs in the glossarylist are sorted according to the glossterm titles specified inside in each of them.
  4. Restart Oxygen.
  5. Open the bookmap containing the glossarylist in the Oxygen main editing area, right click, choose Refactoring and in the Other operations submenu you will find the new Sort glossentries refactoring action. Invoke the action and use the Preview button to check if the sorting is properly done.