Glossary sanity check requested

[James_K__Patrick]

Afternoon all,

RH 8.0.2 generating WebHelp.

After reading through dozens of forum postings on how to implement a glossary in RH8, I see there are generally 2 camps:

1. Use RH's built-in glossary feature

2. Roll-your-own in a separate topic with bookmarks to each letter of the alphabet

I'm working on a subject that has several acronyms. It also has terms that require fairly long definitions - longer than I'd like to show in an expanding hotspot.

So, here's what I've come up with - a combination of 1 and 2 above. Can someone please sanity check this and keep me from shooting myself in the foot, ankle, shin, knee, etc.?

1. Create a glossary (.GLO) and put just the acronyms in it. Run the Glossary Hotspot Wizard to create expanding text in each topic that has an acronym.

2. Create a glossary TOPIC listing ALL terms - acronyms and those needing longer definitions - add it to TOC.

3. Select the glossary on the first screen of the SSL for WebHelp.

4. Do NOT check the glossary box on the second screen of the SSL for WebHelp.

What I believe will happen is this:

1.  No glossary tab will display in the generated output.

2. Acronyms will appear as expanding hotspots.

3. The glossary topic will display in the TOC.

4. I can link non-acronym terms from topics to bookmarks for each non-acronym term in the glossary topic.

Downside: I will have to maintain acronym definitions in 2 places:

Upsides: I can use the Glossary Hotspot Wizard for acronyms. My longer definitions are no longer constrained to the limited space and styling allowed for definitions in the glossary tab.

Does that make sense? Or have I already loaded the gun?

Thanks for your brainpower,

Patrick

[RoboColum_n_]

Ready! Aim!........

Actually that all sounds fine. If you only have one glossary file you don't actually have to specify the glossary in the first dialog of the WebHelp SSL. As it is the only one you can leave it to select the default file.

---

• Read the RoboColum(n) for a tips, tricks and musings on the Technical Communication Suite products.
• Follow the RoboColum(n) on Twitter

[MergeThis]

Can an expanding hotspot contain a variable or snippet (I'm only putting it out there because I don't know, myself). Perhaps someone with experience in that area could chime in.

If it does, then you could eschew the GLO, create a variable or snippet for each entry, and manually add the variable or snippet to the expanding hotspots and to your "glossary" topic.

Good luck,

Leon

[RoboColum_n_]

Wow Leon! That got me thinking it was a starter so I tested it. The issues are that DHTML expanding hotspots created by the glosary wizard are non-editable other than by rerunning the wizard. Also variable names can not contain any spaces (only alphanumeric characters). Whilst this itself is not so much of an issue so long as the variable value is equal to the definition, it could make for a fairly difficult list of variables especially if there are loads of definitions.

---

• Read the RoboColum(n) for a tips, tricks and musings on the Technical Communication Suite products.
• Follow the RoboColum(n) on Twitter

[James_K__Patrick]

Colum,

You can use underscores and dashes in variable names (including as the first character) to help organize them. For my purpose, I can make the UDV name the acronym and the value the acronym definition. Since the acronyms are all unique it should be pretty clear. I guess I could group them all in the UDV tab by prefixing the UDV name with "ACRO-", making them easy to find.

Patrick

[James_K__Patrick]

Leon,

I setup a test project and did a little testing.

The Glossary Term expanding hotspot put in by the wizard will not accept UDVs or snippets.

A regular expanding hotspot will accept a UDV, though not a snippet.

Your idea is good. I can use the glossary and its wizard to create and automatically locate all the acronyms. I can then change the acronyms from glossary expanding hotspots to regular expanding hotspots and drag in the UDV. Then use the same UDV for acronyms in the Glossary Topic, and regular text for the other definitions.

Even if snippets worked in expanding hotspots, they wouldn't be right for me - they're block level elements that appear on their own line. So they don't appear "inline" after the acronym, which is probably why you can't insert them into a UDV.

Patrick

[James_K__Patrick]

Colum,

True enough. Though I name my TOC and index specifically, so I will the glossary as well. Makes them easy to find in Windows Explorer.

Patrick