Print Glossary

[nickw]

How do you include a Glossary in a DITA OT output? I can't find any specific instructions and after 4 days of grinding my teeth and going round in circles with the documentation, I am just about to call it quits and become a beachbum instead. I have created the following simple example:

The Root Map looks like this:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>Capacity Management</title>
    <topicref href="introduction.ditamap" format="ditamap"/>
    <topicref href="roles.ditamap" format="ditamap"/>
    <topicref href="glossary.ditamap" format="ditamap" print="yes"/>
   
</map>


The Glossary map looks 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>
    <keydef href="Glossary/gloss_dita.dita" keys="DITA" print="yes"/>
</map>


The Glossary term looks like this:

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<glossentry id="gloss_dita">
    <glossterm>DITA</glossterm>
    <glossdef>Darwin etc...</glossdef>
</glossentry>


[Radu]

Hi,

You need to add "processing-role='normal'" to the key definition:

Code: Select all

<keydef href="Glossary/gloss_dita.dita" keys="DITA" print="yes" processing-role="normal"/>

The main idea is that the "keydef" by default is considered just a definition of a key linked to a topic which will not appear in the published output:

https://www.oxygenxml.com/dita/1.3/specs/langRef/base/keydef.html

So by default its processing-role is "resource-only", meaning that it is not considered for inclusion in the output.
Of course, you can also define a key on a regular <topicref> like this:

Code: Select all

<topicref href="Glossary/gloss_dita.dita" keys="DITA"/>

and it will appear in the published output by default.

Regards,
Radu

[nickw]

Thanks Radu,

That worked. but it seems a bit much to have to remember to include that attribute for all the keydef entries - is there no way for it to be configured as standard?
Does that mean I don't need to add the print='yes' attribute, in which case, is the Print attribute redundant?
I do not understand your 2nd example though - what are you saying (sorry, to you it all looks quite simple, to me it's one helluva complication)?

Code: Select all

<topicref href="Glossary/gloss_dita.dita" keys="DITA"/>

[Radu]

Hi Nick,

So:

That worked. but it seems a bit much to have to remember to include that attribute for all the keydef entries - is there no way for it to be configured as standard?

Only by creating a DITA DTD specialization which would take quite some work. But out of the box, using the <keydef> as defined in the DITA specification the attribute "processing-role" is considered to have the default value "resource-only".
You can find this out for yourself if you open the DITA Map in the main editing area, switch to the text editing mode and move the caret on a <keydef> tag. The "Attributes" view will show you all default attribute values for it (the @class attribute value showing that the <keydef> is an extension of <topicref> and the @processing-role attribute value).

Does that mean I don't need to add the print='yes' attribute, in which case, is the Print attribute redundant?

Yes, by default on a <keydef> the print attribute has the value "yes". You would usually set a print="no" on topicrefs which you do not want to publish to PDF but want to publish to an HTML-type output.

I do not understand your 2nd example though - what are you saying (sorry, to you it all looks quite simple, to me it's one helluva complication)?

DITA is all about inheritance. A "keydef" is actually a "topicref" with one attribute ("processing-role") set to a default value.
So this:

Code: Select all

 <keydef href="Glossary/gloss_dita.dita" keys="DITA"/>

and this:

Code: Select all

 <topicref href="Glossary/gloss_dita.dita" keys="DITA" processing-role='resource-only'/>

are equivalent when building the output from the DITA content.
By default the <topicref> has 'processing-role='normal'' so it appears in all outputs + you can define keys on a <topicref>, you do not have to define them on a <keydef>.

At some point I wrote on the Oxygen XML Blog a post linking to various resources about learning DITA:

http://blog.oxygenxml.com/2016/03/resources-for-learning-dita-with-oxygen.html

Regards,
Radu

[nickw]

That helps a lot Radu.
I know what I'm going to be doing over Christmas - many thanks

[Radu]

Hi Nick,

No problem. As you start learning DITA if you have feedback for us, maybe ways to make the application more intuitive to use, please do not hesitate to contact us either via email (support@oxygenxml.com) or on the forum.
Happy holidays.

Regards,
Radu