Creating a glossary and referencing a term

[rww]

Can anyone point me to a step by step guide to creating a Glossary using DITA, adding entries to it, and then adding a link in a topic to a glossary entry.

From reading the manuals, I believe the process is:

1. Create glossentry topics for each glossary term.
2. Create a new DITA map that will become the glossary.
3. In the glossary map add create keyrefs to the topics created in step 1
4. Add the glossary map to the master map.
5. In a topic that needs a glossary link, insert one of the keyrefs defined in step 3.

But it's not working. I get errors like, "processing role must be defined for element type glossref" for step 3 or, if I add the glossary topics to the glossary map and then create the keys and try to use the key in a task topic I end up with the term and definition.

Hopefully someone can see where I'm going wrong.

[Radu]

Hi,

The <glossref> element is just a specialization of <topicref> which sets certain default values to attributes in order to avoid having a link to the glossentry in the TOC when the output is published:

http://docs.oasis-open.org/dita/v1.2/os ... l#glossref

In my opinion you should have in the DITA Map (in the main DITA Map or in a submap) a glossref (or topicref) to each glossentry topic something like:

Code: Select all

 <glossref href="concepts/glossaryABS.dita" keys="ABS"/>

 <glossref href="concepts/glossaryAirbag.dita" keys="AIRBAG"/>

and then in the DITA topics you could use either cross references:

Code: Select all

<xref keyref="ABS"/>

or abbreviated-form:

Code: Select all

<abbreviated-form keyref="ABS"/>

The error you encountered:

"processing role must be defined for element type glossref"

looks like a bug in the DITA Open Toolkit engine which publishes the content. So if you have the time to put together a small DITA project in which the situation could be reproduced, please send it to support@oxygenxml.com

Regards,
Radu

[rww]

Happy to report it's all working fine now. I started the glossary from scratch and worked through my own steps and it's all working perfectly. One thing I missed in my steps though was the need to add the glossary topic to the glossary map, otherwise the link doesn't work and the glossary topic isn't included in the PDF output.

So the full process is now:

1. Create glossentry topics for each glossary term.
2. Create a new DITA map that will become the glossary.
3. Add the topic created in step 1 to the glossary map.
4. In the glossary map create keyrefs to the relevant topic created in step 1. Specify as resource-only.
5. Add the glossary map to the master map.
6. In a DITA topic, to insert a link to a glossary topic insert the relevant keyrefs defined in step 4.

Hopefully this will help anyone else struggling with glossaries.

[BogdanM777]

Hi,

I am also interested in creating a Glossary in my DITA project, and the steps outlined are very useful.
I would have however some extra questions regarding those, as I am not so experimented with DITA and oXygen:

Step 4: What do you mean by "create keyrefs to the relevant topic created in step 1. Specify as resource-only."
Step 5: how do I add the glossary ditamap to the master ditamap?
In the Glossary ditamap, do I have also to create the TOC (<booklists><toc/></booklists>), or just the entries as chapters? Or just as topicref?

Thank you

[BogdanM777]

I managed to add the new ditamap (glossary.ditamap), comprised of glossentries, in the main ditamap (bookmap) as:
<chapter format="ditamap" href="glossary.ditamap"/>
however everything that is in this ditamap (glossary.ditamap), i.e. all the glossentries that I added to the ditamap, do not appear in the main documentation as I generate the pdf.
Also, I managed to add the glossentries to the ditamap (glossary.ditamap), however I did not know how to specify them as resource-only. I do not know though if this has any influence to my pdf generation or not.
Would anybody tell me what I should do to have the Glossary in the TOC as well as in the generated pdf documentation?

Thank you.

[Radu]

Hi Bogdan,

Your entire setup is not very clear to me. But if you use the DITA glossref element to refer to glossentry topics, the contents of the topics will appear in the PDF content but they will not appear in the TOC. This happens because the glossref element has the attribute toc set to "no" by default.

http://docs.oasis-open.org/dita/v1.2/os ... l#glossref

You can forcefully set toc="yes" on the glossref or refer to the glossentries using plain topicrefs.

Regards,
Radu

[BogdanM777]

Hi Radu,

Thank you for your response.
I tried with and without toc="yes", and still I do not have that glossary, neither in the TOC, nor in the documentation.
To have it in the TOC would be "nice", however I need it to be at least in the documentation, right?
Do I need to do any special configuration in the DITA-OT?
My bookmap has inside all the chapters, and then I have a ditamap where I have all the gossrefs which I added to the bookmap as a chapter:

Code: Select all

    <chapter href="topics/gettingMoreInformation/ch_getting_more_information.dita">

        <topicref href="topics/gettingMoreInformation/help_page.dita"/>

        <topicref href="topics/gettingMoreInformation/support.dita"/>

    </chapter>

    <chapter format="ditamap" href="glossary.ditamap" toc="yes"/>

</bookmap>

, and the ditamap where I have the glossrefs is something like:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">

<map>

 <title>Glossary</title>

 <glossref href="glossary/galigeo_ext-viz.dita" keys="Gext-viz" keyref="Gext-viz" toc="yes"/>

 <glossref href="glossary/galigeo_maps.dita" keys="GMaps" keyref="GMaps" toc="yes"/>

 <glossref href="glossary/standard_layer.dita" keys="stdlayer" keyref="stdlayer" toc="yes"/>

 <glossref href="glossary/custom_layer.dita" keys="cstlayer" keyref="cstlayer" toc="yes"/>

 <glossref href="glossary/standard_catalog.dita" keys="stdcatalog" keyref="stdcatalog" toc="yes"/>

 <glossref href="glossary/custom_catalog.dita" keys="cstcatalog" keyref="cstcatalog" toc="yes"/>

 <glossref href="glossary/geodimension.dita" keys="geodim" keyref="geodim" toc="yes"/>

 <glossref href="glossary/layer_field.dita" keys="lyrfield" keyref="lyrfield" toc="yes"/>

 <glossref href="glossary/arcgis_feature_service.dita" keys="arcgisfeatserv" keyref="arcgisfeatserv" toc="yes"/>

</map>

[Radu]

Hi Bogdan,

You should also add the print="yes" attribute on the glossref, by default its content is not printed to PDF.
You also seem to have on all glossrefs both the keys and the keyref attributes set to the same value keys="Gext-viz" keyref="Gext-viz". So you should remove the @keyref attribute, it is an attribute used to refer to defined keys but it makes no sense to refer to a key defined on the same topicref.

Regards,
Radu

[BogdanM777]

Thank you very much Radu,

I will try those suggestions and let you know how it worked, OK?

[BogdanM777]

Hi Radu,

I tried what you suggested, and now I have every entry from the glossary as a separate Chapter, and this is a little bit too much.
I would like to have it like a chapter Glossary with some entries for each term and description, nothing more. Would that be possible?

Thank you

[Radu]

Hi Bogdan,

Yes, sure. References to DITA maps do not become separate categories in the TOC.
So for what you want you can do something like:

Code: Select all

<chapter href="glossaryOverview.dita">

<topicref format="ditamap" href="glossary.ditamap"/>

</chapter>

and the glossaryOverview.dita topic would have a meaningful title (the title of the chapter) and probably empty content.

Regards,
Radu

[BogdanM777]

Thank you so much for the speed Radu!
I will give it a try and let you know.

Bogdan

[BogdanM777]

Radu, you're the best!
Thank you so much, it works like a charm!

Have a great weekend,

Bogdan

[Victor]

Hello,

The way described above results in a map, in which all available glossary terms are published. I would like a glossary list, automatically composed only out of the terms used in the document. So - for example - if only three terms are used in a document, it results in a glossary list with these three terms, regardless how many terms the glossary map contains as a whole. I presume this is described in the OASIS white paper 'DITA 1.2 Glossary and Terminology Specialization Feature Description', but it seems hard to make it work.
Any suggestions?

Kind regards,
Victor

[Radu]

Hi Victor,

I'm not sure how we could help you, indeed the publishing results in all glossentry topics referenced in the DITA Map being published even if the glossentries are not referenced anywhere. But I don't think that the specification states that only used glossentries should be published.

Regards,
Radu

[Victor]

Hi Radu,

In paragraph 5.2.3 ('Creating a glossary deliverable') of this paper, it is stated that:
'(...) shows how to use a <map> element with <topicref> elements pointing to
individual glossary entry DITA files, to assemble a glossary deliverable. Manually arranging a
glossary with a <map> element is standard for assembling deliverables but required only when
a processor is not available that can automatically sort and group the glossary entries referenced
in topics.'
Did I perhaps misinterpret this text? It could also be, that I'm using a processor without this capability.

Kind regards,
Victor

[Radu]

Hi Victor,

From what I see the paragraphs discusses about manually arranging the references to the glossary entries in the DITA Map and the fact that the processor may help in automatically sorting these references when creating the Glossaries list. I do not see the paragraph discussing about automatically adding links to the glossentry topics in the DITA Map depending on the glossary terms used using abbreviated-form inside the topics.

Maybe you could also write about this on the Yahoo Groups DITA Users List, most members of the DITA specification committee are registered there and they might be able to clarify certain aspects.

Regards,
Radu

[urbanrobots]

Hi, is there any way to reference a glossary entry in the text but to not have a glossary at the end of the book? We'd like to use glossary references, but for very short documents a glossary is not desired. Right now, if we do not include the glossary entry at the end of the book, no output appears for the inline references.

Thanks,
- Nicholas

[Radu]

Hi Nicholas,

You can probably set the toc="no" attribute in the DITA Map on the reference to the glossary entry files. This might result in some broken links though...

Regards,
Radu