The First Instance Conundrum

[Matt Collins]

In the world of single sourcing, how do you handle the issue of first instance rules, such as the use of ©,®, and ™ or spelling out an abbreviation or acronym?

I tip my hat to Jose Sermeno and the folks at MadCap, they cooked up a javascript that will spell out abbreviations on first mention in HTML5 output, provided that the abbreviation is within <abbr> tags and has a definition included in the opening tag. Example: <abbr title="cascading style sheet">CSS</abbr>

But I am still working on how to implement a similar solution for PDF output.

Any thoughts/suggestions?

[NorthEast]

Flare doesn't actually do anything at all with abbr tags; the popup you see in a browser is displayed by the browser itself, and no javascript is involved.

Anyway, I'd suggest using a glossary term for these; they can be displayed as a popup in the help output, and as a footnote in PDF output.

[Matt Collins]

Interesting... could a glossary term be but within <abbr> tags, or <abbr> tags within a glossary term? We're going to be using the <abbr> tags anyway for reasons related to accessibility (screen readers and the like).

[Matt Collins]

Well, I have a solution, though it may not be entirely Kosher:

How the sausage can be made:

Create a set of snippets for abbreviations you use regularly.

Create a snippet for each abbreviation, with the abbreviation inside <abbr> tags with the title value defined. Example: <abbr title"Hypertext Markup Language">HTML</abbr>.

Create a glossary of your abbreviations, using the abbreviations as the terms and their spelled out meaning as the description (you can also include a brief description for your readers, if you like). Note: I set up a separate glossary for this just for the sake of management, but this does not have to be a separate glossary.

Here's where it may get non-Kosher: Exit Flare and open your glossary file in an XML editor (I use Notepad++, but you could even do this step in plain old Notepad). Find each abbreviation within the <Term> tags and put the <abbr> tags around it. You should wind up with something like this (emphasis added):

<GlossaryEntry
TermClass="Popup">
<Terms>
<Term><abbr title="Hypertext Markup Language">HTML</abbr></Term>
</Terms>
<Definition
Link="">Hypertext Markup Language (HTML)</Definition>
</GlossaryEntry>

Last step: In your targets, under the Glossary tab in Glossary Term Conversion, select the "Convert first occurrence of term" option.

End Results:
Since Flare does not yet have a function for inserting <abbr> tags in WYSIWYG mode, creating snippets adds your predefined abbreviations to the autocomplete function, which will insert the tags with the abbreviations for you. This also helps keep your abbreviations consistent throughout your project(s).
And since you have the <abbr> tags in the glossary terms, Flare will recognize them in your topics automatically when publishing, giving you a footnote annotation in pdf and a popup/hyperlink/expanding text (depending on the option you select) in online formats (note: I've only used this in HTML5 so far).
So, now you have a automated function for spelling out abbreviations on first mention and have abbreviations in <abbr> tags to assist those that use screen reading software for online content.

What do y'all think?

[Matt Collins]

One followup: I recommend keeping your abbreviations in a separate glossary that you keep set as read-only (you can do this from the right-click Properties options in either Flare or Windows Explorer and it will take effect both places). This is because if the glossary is opened and a term that you have added the abbr tags is edited (even if the term is let alone and only the definition changed) Flare will remove the abbr tags.

So instead of editing the abbreviations glossary in Flare, keep it read only until you need to make a change, then uncheck Make Read Only in the right-click Properties options in Windows Explorer. Then open the glossary using an external editor like Notepad or Notepad++, save your work and make it read-only again when you are done.