MFUG – August 2014 Meeting Notes

Under the Bonnet: Migrating Word Glossaries to Flare

Every great magic trick consists of three parts or acts.
The first part is called “The Pledge”. The magician shows you something ordinary: a deck of cards, a bird or a man. He shows you this object. Perhaps he asks you to inspect it to see if it is indeed real, unaltered, normal.

Tony started off with a simple glossary of some 200+ terms in Word. Just your basic 2 column layout – with Terms in the left column and a Description in the right column. There is no functionality (currently) in Madcap Flare to import glossaries from external sources into Flare-readable files. You could be looking at at least half a day’s work trying to manually type in all glossary terms in Flare.

The second act is called “The Turn”. The magician takes the ordinary something and makes it do something extraordinary. Now you’re looking for the secret… but you won’t find it, because of course you’re not really looking. You don’t really want to know. You want to be fooled. But you wouldn’t clap yet. Because making something disappear isn’t enough; you have to bring it back.

On the surface, Flare files look rather benign. Harmless almost. Just a layer of HTML sitting cozily with XML. But, open the Flare HTML files, including the Glossary (.flglo) in a Text editor and you will see how much of XML is really controlling the document. A newly created Glossary file viewed in a Text Editor is basically a whole lot of XML code, waiting to be manipulated, finessed, cared for. Keep this in mind and you will never have to worry about typing in glossary terms and definitions manually ever again.

Before Tony could wave his wand to work on the Word Glossary, he did some pretty basic manipulations, such as sorting the glossary table to display all blank cells at the top, removing any blank cells (assuming your Word Glossary is in a table), deleting any unnecessary text in rows/columns (think bullets etc). Don’t worry about sorting the table back – Flare will do it for you.

Next on the cards (metaphorically) was converting the table to text. Easy done in Word. Make sure you have a way of separating the terms from the definitions. Tony used a tab delimiter. (You could use anything else you fancy – comma, special characters).

A closer look at the Glossary XML in Flare revealed it’s essentially a whole lot of Term and Definition tags. Every tab delimiter in the Word document is a logical break between Term and Definition. Using Word’s search and replace feature, Tony replaced all such tabs with the relevant opening and closing tags from the XML code. Next, he searched for any carriage returns, as these would be the start of every new term, and replaced them with all the relevant tags.

Tony then did a quick check of the Word document and made sure we have an equal number of opening and closing tags (XML is pretty strict on these things). He then copied all of this text from Word into an XML validator (Oxygen in his case) to make sure the XML was well formed. XML Validators check if the XML code is “well-formed” and also “valid”, in that it adheres to a defined structure. In this case, since Flare has it’s own definitions, we can’t really validate it, but we could still make sure it was well-formed.

Tony copied all of this well-formed XML code from the XML validator into the Glossary file (opened in a Text Editor).

That’s why every magic trick has a third act, the hardest part, the part we call “The Prestige”.

Open the Glossary file in the normal way in Flare. Voila. All the 200+ terms are in.

Tutorial demonstrating how to do this – coming up soon!

Movie quotes source: imdb