How to build reusable Glossary?

[reinierk]

I want to build an easy to re-use Glossary for a series of books.
I have glossentries in files, organised by letter: A-Glossary.dita, B-Glossary.dita etc. These files start with a glossgroup element, followed by a title, then the glossentries.

Then I want to build a map that references each file A-..., B-...

In the final document-bookmap I want to add a single reference to the glossary-map.

How to do that? I run into all kinds of errors!

[reinierk]

Currently I have in the document bookmap:

Code: Select all

<backmatter>

        <booklists>

            <glossarylist navtitle="Glossary" locktitle="yes">

                <topicref href="../Common-content/Glossary/OSA-Glossary.xml" print="yes"

                    format="dita"/>

            </glossarylist>

        </booklists>

       </backmatter>

And in OSA-Glossary.xml:

Code: Select all

<map format="dita">

    <title>Glossary</title>

    <glossref href="M-Glossary.dita#glossary_m" type="glossgroup" keys="glossary_m"/>

    <glossref href="M-Glossary.dita#glossentry_meta_char" type="glossentry"

        keys="glossentry_meta_char"/>

    <glossref href="M-Glossary.dita#glossentry_MIME" type="glossentry" keys="glossentry_MIME"/>

</map>

[Radu]

Hi Reinier,

What version of Oxygen are you using?
The OSA-Glossary.xml file seems to be a DITA Map so it should have the .ditamap extension.
Also the topicref to it should have the format set as format="ditamap".

Regards,
Radu

[reinierk]

After struggeling for several more hours I came up with this:

In the bookmap I have

Code: Select all

<backmatter>

 <booklists>

   <glossarylist print="yes">

     <topicref href="../Common-content/Glossary/OSA-Glossary.ditamap" navtitle="Glossary"

               format="ditamap" print="yes"/>

   </glossarylist>

 </booklists>

</backmatter>

Why may the glossarylist not href="" directly to the map?

The OSA-Glossary.ditamap has this:

Code: Select all

<map format="dita" title="Glossary">

    <glossref href="A/a-intro.dita#glossary-a" keys="glossary-a" print="yes" type="glossgroup"/>

    <glossref href="A/alsa.dita" type="glossentry" keys="glossentry_alsa" print="yes"/>

    <glossref href="A/automation.dita" type="glossentry" keys="glossentry_automation" print="yes"/>

    <glossref href="A/automatic.dita" type="glossentry" keys="glossentry_automatic" print="yes"/>

    <glossref href="B/b-intro.dita#glossary_b" type="glossgroup" keys="glossary_b" print="yes"/>

    <glossref href="B/base-64.dita" keys="glossentry_base-64" print="yes" type="glossentry"/>

    <glossref href="B/boot-loader.dita" type="glossentry" keys="glossentry_boot-loader" print="yes"/>

    <glossref href="C/c-intro.dita#glossary-c" type="glossgroup" keys="glossary-c" print="yes"/>

    <glossref href="C/call-gate.dita" type="glossentry" keys="glossentry_call-gate" print="yes"/>

<!-- etc..... -->

</map>

It does the trick, but has the following disadvantages:

• Each glossentry MUST be in a separate file. I know this is the recommendation of DITA, but my first try had all items in "Composite" files, one per letter. But if you ask the glossref to href="A/a-items.dita#automatic". The style-sheets fail with horrible errors.
• The glossref elements need to have print="yes" and you need to copy the keys=".." attribute. This is very annoying, and easy to forget!
• Nesting the glossentries in the glossgroup does not work for some reason:

  Code: Select all

  <glossref href="A/a-intro.dita#glossary-a" keys="glossary-a" print="yes" type="glossgroup"/>
  
     <glossref href="A/alsa.dita" type="glossentry" keys="glossentry_alsa" print="yes">
  
     <glossref href="A/automation.dita" type="glossentry" keys="glossentry_automation" print="yes"/>
  
     <glossref href="A/automatic.dita" type="glossentry" keys="glossentry_automatic" print="yes"/>
  
  </glossgroup>
  

• If you want the gloss items to appear in the TOC, you further need to add the toc="yes" attribute to each glossref. More room for errors! (Luckily I do not want that )

I am using Oxygen 14.1

[Radu]

Hi Reinier,

Oxygen 14.1 uses DITA OT 1.6.1.
The problem with glossarylist @href not working was reported by me a while ago and seems to be fixed in DITA OT 1.7.1:

https://github.com/dita-ot/dita-ot/issues/1197

So you should follow the suggestions I made in my other post to use DITA OT 1.7.1 with Oxygen:

http://www.oxygenxml.com/forum/post24095.html#p24095

About the other problems:

Each glossentry MUST be in a separate file. I know this is the recommendation of DITA, but my first try had all items in "Composite" files, one per letter. But if you ask the glossref to href="A/a-items.dita#automatic". The style-sheets fail with horrible errors.

Have you tried creating a <glossgroup> which has several glossentries inside? Oxygen has a new file template for <glossgroup>

The glossref elements need to have print="yes" and you need to copy the keys=".." attribute. This is very annoying, and easy to forget!

If you want the gloss items to appear in the TOC, you further need to add the toc="yes" attribute to each glossref. More room for errors!

According to the DITA 1.2 specs the @toc and @print attributes have the default value 'no' for glossref:

http://docs.oasis-open.org/dita/v1.2/cs ... ssref.html

Nesting the glossentries in the glossgroup does not work for some reason:

As far as I know there is no "type='glossgroup'" which can be set on a glossref. A glossgroup is a special type of topic:

http://docs.oasis-open.org/dita/v1.2/os ... group.html

Regards,
Radu