Describes a number of open-source tools and techniques for authoring and publishing DITA glossaries and links to glossary entries.

1. Eliot Kimber — Contrext, LLC, Wayne Brissette — Arm
2019-04-17
Definition of the
DITA Glossary
DITA North America 2019
… or “how to get some cool glossary
tools for free”

2. 2 © 2019 Arm Limited
Overview
• Wait? Didn’t Eliot do this presentation last year?
• Yes. Erm, No. Erm, Kind of…
• And it’s why there’s another one this year.
• I was excited after Eliot’s talk and wanted to get a glossary working on some things I was working on.
• That was a failure.
– We didn’t have the backend working.
– The authoring experience was painful.

3. 3 © 2019 Arm Limited
So what is a DITA glossary?
• Terms and their definitions
• For presentation to readers
• May include definitions of acronyms and abbreviations
• May include lexicographic details: part of speech, etc.
• Source for use-by-reference of <term> elements in content

4. 4 © 2019 Arm Limited
So what isn’t a DITA glossary?
• Formal term list as used in terminology management tools like Congree or Acrolinx
• Terminology management is a separate concern from glossary authoring

5. 5 © 2019 Arm Limited
What about <glossref>?
• <glossref> is a topicref type designed for referring to glossary topic
• While it seems exactly what you want to do.
• The DITA spec even says: “The <glossref> element is a convenience element in maps for creating a
reference to a glossary topic.”
– But just don’t do it.
• Sets @toc to “no”
• Sets @print to “no”
– And I loved Eliot’s answer to why last year: “Nobody knows why”.
• Requires @keys attribute.
5

6. 6 © 2019 Arm Limited
Author experience
• Imagine somebody has already setup the 100-200 terms for you.
• Options are:
– Manually go into a topic and add them.
– Run a transform on them at build time that adds the requirements (I vote for this)
• Manual entry isn’t all bad, but it is time consuming.
• But it doesn’t have to be if you’re using oXygen.

7. 7 © 2019 Arm Limited
Easier methods
• If you have a glossary and you have a standard method of naming your keys, what’s
easier than highlighting the word/phrase, and clicking a button or two?
• I’ve built a framework that allows you to add a button to the toolbar, highlight a word
and have the word selected be your key.
• Demo time!
• Best of all, it’s available for you to use freely.

8. 8 © 2019 Arm Limited
Easier methods
• But what if I want to define my own key?
• I’ve built some custom oXygen code templates that allow you to do three different
things:
1. Mimic the button option and use the word as the key.
2. Enter your own key.
3. Enter an xref that can point to an online resource.
• Demo time!
• Best of all, it too is available for you to use freely.

9. 9 © 2019 Arm Limited
Let’s build a glossary
• OK, now the painful part building a glossary.
• Well, it used to be painful.
• I’ve written a script that will take an excel spreadsheet with terms and definitions in it and create a
map with all the entries (along with keys) for you.
• Demo time!
• That’s great, but I still have to hand mark things.
• I’ve got you covered there too.
• I’ve written a script that will markup all your content from your Excel spreadsheets.
• And like everything else, we’re providing these to you so you can start working on your
own DITA glossaries.

10. Eliot Kimber
Dynamic Map Processing For Publication

11. 11 © 2019 Arm Limited
Organizational Challenges With Glossaries
• Generate glossary from resource-only topicrefs
• Filter glossary entries to entries actually used in topics
• Group and sort glossary entries
• Link to master glossaries

12. 12 © 2019 Arm Limited
Authoring Challenges
• Maintaining navigation structures for glossaries is tedious
• Managing shared sets of glossary definition key definitions is challenging
• Localized glossaries compound the challenges

13. 13 © 2019 Arm Limited
Solution: Automation
• Given either or both of:
• Resource-only keydefs for glossary entries
• Authored navigation structure
• Produce published glossary that satisfies requirements:
• Grouped and sorted for glossary’s locale
• Reflects the entries desired (all or only those used from non-glossary topics)
• Replaces resource-only keys with normal-role keys

14. 14 © 2019 Arm Limited
Demo: Glossary Preprocessing Plugin
• org.dita-community.glossary.preprocess
• Provides the following options:
• Filter glossary: Only include those glossary entries actually referenced from other topics
• Sort glossary: Group and sort the glossary entries
• Generate glossary: Generate grouped, sorted, and, optionally, filtered glossary based on resource-only
topicrefs to glossary entries.
• Requires org.dita-community.i18n plugin, org.dita-community.common.xslt
• Requires Open Toolkit 3.3+
• Demo time!

15. 15 © 2019 Arm Limited
Master Glossaries as Separate Publications
• Requires cross-deliverable (cross-publication) links
• DITA 1.3 feature not yet implemented Open Toolkit
• Could be implemented as a special case for glossaries
• Looking for funding…

16. Thank You
Danke
Merci
谢谢
ありがとう
Gracias
Kiitos
감사합니다
धन्यवाद
‫ا‬ً‫شكر‬
‫תודה‬
© 2019 Arm Limited