Tag Archives: MadCap Flare

July 23, 2014 · 8:17 pm

Creating Glossaries – Step 2

Once you have your glossaries in place, you now need to include them in your output. This blog post covers how to include glossary content in your print and online output.

Enable Glossaries in you Skin file

From the Project Organizer open you skin file.
On the General tab, click the Glossary check box.
Save your work.

Set Print output

In our case, we create a Glossary topic and add it to our Print TOC. Let’s cover this process first.

Create a “Glossary” topic in Flare.
Open your new topic.
In your <h1> tag, enter the word “Glossary.” Hit enter.
On the new line, select Insert > Proxy > Insert glossary proxy. You should see a gray bar with the text “output glossary proxy.”
Add this new topic to the end of your output TOC.
Save your work.

Next, let’s set up our print target.

For Print output, open your print target.
Go to the Glossary tab.
Your options are:
1. Do not convert term: none of the glossary terms convert to hyperlinks, popups, expanding text, or footnotes in the output.
2. Convert only marked terms: only glossary terms that were inserted into topics as glossary term links convert to hyperlinks, popups, expanding text, or footnotes in the output. Glossary terms that happen to exist in topics as normal text will not be converted.
3. Convert first occurrence of term: only the first occurrence of a glossary term in a topic converts to a hyperlink, popup, expanding text, or footnote in the output. This includes terms inserted as glossary term links, as well as glossary terms that happen to exist in topics as normal text.
4. Convert all occurrence of term: every occurrence of a glossary term in a topic converts to a hyperlink, popup, expanding text, or footnote in the output. This includes terms inserted as glossary term links, as well as glossary terms that happen to exist in topics as normal text.
Because we want our terms to display in only the Glossary topic we created, we select the Do no convert term option. NOTE: If you convert terms, all linked terms will be added as footnotes to each page housing a glossary term.
In the Glossary file box, make sure the glossary you want used for this output is selected.
Save your work.

Generate output WebHelp/HTML5

We will use the Popup style for our help links. This is the default option in Flare, so you do not need to assign a style option when creating the glossary links. If you are interested in a different style, see the Step 1 blog post.

Open your help target.
Go to the Glossary tab.
Select Convert all occurrences of term. NOTE: This does not mean Flare makes all occurrences glossary entries. You still must complete the Identify/Link glossary terms procedure for each term you want linked in your output.
Save your work.

Tips

If you need to include a variable in your glossary term:
1. Add the glossary link to the term without the variable inserted.
2. Once the glossary term is in place, insert the variable where required.
3. Open the glossary term and add the variable form to the term list.
The glossary is an exact match for the term. Make sure to include all forms of the glossary term in the terms list to include the other iterations of the term.
1. For example, if the term is “database,” make sure to also include “databases,” “Databases,” and “Database” in the term list.

Creating a Glossary – Step 1

One of the great things about Flare is there are several ways to do just about everything; one of the not so great things about Flare is there are several ways to do just about everything. This was a huge hurdle for my team when we made the move to Flare four years ago. To make sure the entire team used a consistent workflow, several team members spent time testing the various workflow options available and selected the options we thought worked best. I thought I’d share with you the options we put in place for glossaries. This post addresses how we add glossary terms in our content. My next post will cover how to handle the glossary output.

Identify/link glossary terms

NOTE: By default, glossary terms will not be converted to links if they are found in any heading tags (<h>) as well as hyperlinks (i.e., content with the <a> tag). However, if the same term is found in, say, a regular paragraph, the term will be converted to a link in your online output. For your print output, you have a few options, that we’ll cover in a later post.

Open the content file (topic, snippet).
Highlight the word or phrase that you want to add as a glossary term and link.
Select Insert>Glossary Term Link. The Create Glossary Term dialog opens.
If necessary, select the glossary on the right side of the dialog (you need to do this only if more than one glossary file exists in the project.).
In the Definition field, type a definition for the term.
Click OK. The word or phrase is now shown as a linked glossary term with an icon beside it. The term and definition are added to the glossary.
To select a style class for your term, highlight the entire term – make sure to include tags around the term – and right-click. Select Class style and select your style. We use the pop-up style, which is the default.
Save your work.
If you want to make every instance of the word or phrase included in your project a glossary link, you can use the Find and Replace feature. For example, I want to link every instance of the word “database” to the glossary definition I just created.
1. Select Edit, Find and Replace.
2. In the Find what field, enter the glossary term. For this example, I’ll enter “database.”
3. In the Replace with, enter the following:
  - <MadCap:glossaryTerm class=”Popup”>database</MadCap:glossaryTerm>
  - Make sure to change “database” to the term you are defining
4. Under Options in the Find and Replace pane, in Find in, select (whole project) and select Find in source code.
5. Click Start. You will have to review each topic before selecting Replace (do not run a “Replace in All Files). Glossary links DO NOT WORK IN HEADINGS, so whenever you encounter the word in a heading, skip that term by clicking Start. Whenever you encounter a location in which you do want to add the glossary link, click Replace.

Insert glossary term links for terms that have already been created

Open the content file (topic, snippet).
Select Tools>Glossary Terms. The Glossary Terms window pane opens listing all the terms already added to the glossary.
In the Glossary Terms window pane, double-click the term that you want to insert as a glossary link.
Make sure you double-click under the Term column. If you double-click anywhere else in the row (under the Definition or File column), the Glossary Editor opens instead. The word or phrase is now shown as a linked glossary term with an icon beside it.
Save your work.

Welcome to my blog

My goal here is to share what I know/what I learn about working in the world of technical communication. A good deal of my blog posts will be focused on the authoring/help-generating tool Madcap Flare, but that will not be the entire purpose of the blog. I will share information on the broader topic of the tech com field as well.

In this post, I would like to introduce myself. My name is Denise Kadilak, and I have worked in tech com for over 16 years. My responsibilities over this time have varied, from creating and maintaining 1000s of pages of user-end documentation; to something of a technical-project lead investigating new tools, best practices, and workflows for a 22-member documentation team; to my current position of Information Architect/Team Manager. Also, about four years ago, I led my team’s move from Adobe FrameMaker to MadCap Flare – a fun and intense time for everyone.

I also present with some regularity at industry conferences, such as WritersUA, STC, and Content Management Strategy and DITA, North American Conference. In January of 2014 I did a Webinar for MadCap on making the move from FrameMaker to Flare. You can watch the recorded version of the webinar here.
Finally, in addition to my full-time job, I am a part-time college instructor at John Carroll University in Cleveland, OH. I teach the Technical Writing course included in the school’s Professional Writing program.
I hope you find my topic and my credentials interesting enough to regularly visit this blog – maybe even to consider subscribing to it!

2 Comments

Filed under MadCap Flare

Tagged as MadCap Flare, Professional writing, Technical Communicatioin