Six Persistent Flare Problems

Important Note: This post is now about ten years old. Flare has released eleven major updates since this post was written, troche and much (most?!) of what is written here no longer applies. MadCap has been excellent about responding to feedback and improving the product. I’ve addressed each of these concerns in a comment later in this post’s comment thread. In the near future, sale I’ll post an updated review of Flare 2017, and when I do that, I’ll create a link from this post. -Paul Pehrson (February 2017)

As I stated in my last post, I’m a Flare user, and I really, really, really like Flare as a help authoring tool (HAT). It’s a solid program that does a lot of great things. On my recommendation, my company is going to renew our maintenance contract with Flare this fall, and I expect to be using Flare for a while to come.

That said, I think that there are a few persistent problems in Flare that new users should be aware of when they start using the product. None of these are deal-breakers for me, even in the aggregate. Still, I think that these are things that if I had known were problems, I wouldn’t have spent hours banging my head against the wall trying to solve them.

Thus, for the new Flare user, I present Six Persistent Flare Problems that you should know about when using MadCap’s flagship product.

1. Cross Referencing Problems

Flare’s implementation of cross referencing on the surface is really cool. When I want to link to another topic in my project, Flare inserts a cross reference link. When the project is built, if the target is computer-based, then Flare just inserts a standard link. If the target is print-based (Word or FrameMaker), then Flare inserts the text of the link, but adds “on page X” so your readers can flip to the proper page in the printed manual.

However, the persistent problems with cross referencing include the following:

  • If the title of the target topic changes, the text of the cross reference link doesn’t. Somehow, I’d like Flare to track the topic that I’m linking to, and if I am using the topic’s title (or any heading level, really) I want Flare to know that the text changed and reflect that in the topics that link to it. (Edit: 7.11.07) It turns out that this does work like I want it to. When you build the project, the cross references are updated in the output. The source files aren’t updated in the Flare editor, but the resulting output has the correct cross reference titles. You can update the cross references in a particular topic by using the Tools, Update Cross References option.
  • Cross referencing doesn’t know if a topic has been excluded from the output. If I create a cross-reference link to a topic, that cross reference link will display even if the target topic has been marked for exclusion from the output. So say I’m using the “lite” version of the software, I’ll see links to all the topics that are only in the professional version. Cross referencing should be smart enough to not link to topics that are marked for exclusion for the output that is being compiled.(Edit: 7.11.07)This works, if you know what you are doing. If you just mark the topic for exclusion in the TOC, then the cross reference is still included. Which makes sense, since the topic is still available in the output, it’s just not listed in the TOC. In order to exclude a topic and disable cross references to the topic, you have to mark the conditional setting in the topic properties in the Content Explorer pane, not in the TOC. When you exclude a topic in the Content Explorer, then cross references to the topic lose their hyperlink, and just the text of the link remains. (However, the text won’t show the most current topic title; it will only show the topic title that the XML editor found last time you updated the cross reference, as mentioned in the previous bullet point.
  • In my Word output, occasionally I have a cross references in print that say …”See page 1″ when the target topic is not on page 1. I submitted this to Flare tech support, and they can’t figure out why it is happening. I ended up having to search through my Word doc after it was compiled to find any references to “page 1” and insert the correct page number. This happened for about 1 in 4 of my cross reference links. (Edit: 12.05.07) I have confirmed that this is still a problem in my Word output using Flare V3.1. MadCap Support reports this is a high priority open issue.

2. Word Output Trouble

Being able to compile directly to a Word file works pretty good for the most part. I love being able to set CSS styles for printed output that are reflected in the Word document. Yet, I still encounter the following problems when using Word output:

  • Word ignores CSS spacing (margins and padding) that are applied to tables, lists, and the <body> tag. I don’t know if this is a Word limitation or if Flare isn’t sending the proper info to Word for this, but I have an open help request about this issue.
  • Word ignores CSS background images. It simply won’t display them. I haven’t yet figured out how to place text in front of a graphic, because theoretically, in CSS it is easy. However, it just doesn’t work in Word.
  • When a topic starts a new chapter in two-sided printed documentation, generally you want this first page to be on the recto, or right page. That’s just where chapters start. In CSS there is a property you can apply to the chapter heading that should make the heading appear at the top of a right page. Word calls this an “odd” page, because odd-numbered pages are on the recto side of the paper. However, when Flare compiles the Word output, new chapters can’t be forced to start on the recto page. They always just start on the next blank page, regardless of whether it is a recto or a verso page. I have an open bug about this one too, as I currently have to do post-processing to make this work properly.(Edit: 12.05.07) In Flare version 3.0.3 and later this has been fixed, as per an article in MadCap’s knowledge base. I’ve tested this, and it works beautifully! The squeaky wheel does get the grease!
  • Auto numbering for chapters is funky. I’m not sure how this happens, but in my project, I have to apply my auto numbering characteristics to the chapter before I want the characteristics to appear. So in order to get my Appendix A to have the letter A as its auto number, I have to set the properties of chapter 10 to be “restart numbering, type A”. If I try to do this on the chapter that is Appendix A, the settings aren’t applied until Appendix B. Again, I’ve an open help request on this one.(Edit: 7.17.07) This problem was resolved in Flare V3 which was recently released by MadCap. I even got an e-mail from customer support letting me know that an issue I had logged has been resolved. I’ve tested my Flare project, and it works as you would expect it should with regards to chapter numbering.

3. Variables

Variables are a great way to work with content. Instead of constantly referencing your product name, you insert a variable. Then, if the product name changes, you just change the variable, and build the project, and the variable is replaced throughout the help system. Or maybe you supply the help system to various clients and they are integrating your system with a proprietary product name as part of their project. In that case, you would create different target outputs, and specify the variable name for that target. When you build the project, the variable is replaced throughout the help system.

Sort of.

This works unless you are using the variable in the title of a topic. Topic titles are a special case because they are used for linking (see <Topic Tile>), in the TOC, etc. The topic title is generally a <h1> tag, but can be any heading level you define. When you use a variable in a heading, and the heading is pulled for the name in many cases Flare either omits the variable entirely, or it puts the plain text of the current variable definition in the target text. This means you have to edit your output carefully to ensure that your variables are replaced correctly. (I do a find/replace in Word to see if there are any problems.)

4 . Glossary Problems

Flare includes support for creating a glossary. It also gives you a number of options on how to display your glossary entries, depending on your output options. In computer-based output, you can have every instance of the word tagged so that it becomes a link. When users click on the link, the glossary definition is shown in a pop-up, or as expanding text after the glossary item. You can have this happen every time the word is found, or only the first time it is found in each topic—or not at all. The computer-based outputs give you the option of having a separate glossary pane with the glossary items listed. You click on them to see the definition. And the glossary proxy in printed documentation lets you include an appendix that includes all the glossary terms in your output.

This is a powerful tool, and is a great improvement over Robohelp (at least RH X3 that I used). In Robohelp, when you entered a glossary item, RH searched through the current topics, and actually modified the topic with the glossary entry. If you did this process twice, then you actually inserted the glossary definition TWICE in the output. Flare doesn’t input these until it compiles the project, so you can create the glossary at any time and update it at any time without worrying about how this will affect the content in your topics. However, this also isn’t without its flaws.

First, if you have the computer-based output insert glossary references in your text, it will modify the formatting and text in EVERY glossary item it encounters, or optionally in only the first glossary item in each topic. In either case, if the first time the glossary entry is found is in a heading, the heading gets totally messed up. Flare needs to figure out a way to ignore content in heading tags when it does the glossary compiler.

Second, there is an “undesirable feature” in the way Flare handles synonyms. In the glossary editor, you enter the search term and its synonyms, separated by commas. Then in the next field you enter the definition. This is a great idea. Instead of creating separate entries for “help authoring tool” and “HAT” you can list them together and only enter the definition once. Every instance of either the word or its synonyms is tagged with the definition. This isn’t great, however, when you go to print your printed glossary in your printed output. Flare inserts each synonym as a separate entry in the glossary, with the entire definition. In one of my topics, I had a word with about 4 synonyms, including acronym variations. In the printed glossary, all four words were inserted, in order, in the glossary. I wish Flare could allow me to choose the master glossary term with child terms. The master term would be shown in the glossary, with the definition. Child terms would say “See <master term>”.

5. Win-centric Design

For some reason, MadCap decided to program Flare using Microsoft’s .NET Framework. Thus, MadCap products are tied to machines running the Windows operating system. Now I’m not a programmer, so I’ll admit ignorance on this topic. However, off the top of my head I can’t think of other major products that require you to install the .NET Framework in order to use the product. I also worry that this is a short-sighted decision, as it alienates the ever-growing Mac user base and Linux user base.

I’d love to be able to make the switch to Linux as my primary OS. However, I’m stuck using Windows because it’s the only OS that my tools will allow me to use.

One of the problems with this mindset is it makes the command-line build option pretty useless for me. First, in order to use the command-line builder, you have to have a separate full license of Flare (unless you use your work system as the build machine. But if you are going to do that, why use command line?). Plus, since Flare only works on Windows, your build machine can’t be a Linux machine. Our software does a nightly build, and I want the nightly build to include the latest version of the help system. But I can’t integrate them because our builder is a Linux box and Flare won’t work with it.

Flare needs to provide a command line compiler that works on Linux. Additionally, it would be better if that were a separate utility that I could purchase from MadCap, without having to purchase an entire Flare license just for command line compiler.

6. Misc Items

My final gripes can’t be grouped into one cohesive category, but I don’t think any of them were big enough to merit a separate topic number, so here they are, grouped as “Misc Items”:

  • Flare is very powerful. However, its design isn’t very intuitive in a lot of ways. For example, the blocks feature is powerful, but has different unmarked hotspots, where if you click on the block in different areas, you get separate options. This isn’t documented and you just figure it out by trial and error. The menu items are often placed in odd locations, particularly some of the dock items in the Windows menu. Once you know where to look, it kind of makes sense, but searching for them the first time can be tedious.
  • When you link to a heading in a topic, if the heading is an expanding text hotspot, the expanding text isn’t expanded by default in the computer-based output. The only way to get this to work is to place the anchor inside the drop-down hotspot, but then you lose the hot spot header.
  • When you paste information into Flare, you lose all formatting, including spacing and line breaks. This was really unfortunate when I was manually converting topics from Frame, and I pasted entire topics into Flare. Flare stripped the formatting and the line breaks and inserted the text as one long paragraph. This drove me nuts.
  • If I use Flare’s conditional settings to exclude a topic (at the topic level, in the Content Explorer), that topic still gets included in the project’s web-help folders for WebHelp targets. This is a bug, and a major one at that. Since the topic files are stored in the compiled help project as .html files, anybody can go into the source and find the extra topics. If I’ve marked them for exclusion, there is a reason. Flare should respect its own conditional settings and not publish topics that aren’t marked for publication.Edit (6/18/07): MadCap Support contacted me, and together we were unable to duplicate this behavior. I think it was pilot error. When I cleaned my target files, the excluded files were not published. Thanks to Richard at MadCap for helping me resolve this issue.

There you have it. These are the problems that I’ve found with my favorite help authoring tool. In most cases, I’ve figured out how to solve the problems I’ve encountered, and like I said in the beginning, none of these are deal breakers. I still think Flare is the best authoring tool for my needs.

Stay tuned next week for my post on my favorite features in Flare, to give some positive balance to this list of Flare’s problems.

If you’ve made it all the way to the end, thanks for reading. I hope you found my experience helpful as you evaluate Flare as a potential help authoring tool.

20 responses to “Six Persistent Flare Problems”

  1. Paul,

    Thanks for the detailed write-up on Flare’s shortcomings. The problems you described are ones only power users (like you) of the product can discover after working with it extensively. I was totally unaware of some of these shortcomings.

    I also like your balanced tone — still preferring Flare despite all of the problems associated with it. I hope we can raise awareness of the problems to encourage Madcap to fix them.


  2. Hi, Paul 🙂

    Nice write-up! (Now I’m thinking that we should get other users to create blog entries that mimic your structure for other HATs…hmmm…)

    To address a couple of issues:

    – HelpStudio and HelpServer are the only HATs that I know of who track the “hotspot” text for a hyperlink to the topic title and change it automatically.

    – Several HATs now rely on .NET. And they’ve all been Win-centric forever.

    – The rule of thumb used to be to never add hyperlinks to a topic title. I don’t know if this is now being done because we forgot to share the information 😉 or if it’s no longer considered a usability issue.


  3. hey paul, this helps with our evaluation of tools. Flare is a complex tool and it was a struggle to get a grip on basic features.

  4. One restriction I’ve found is that there’s no “Advanced Search” feature. You can’t search for a phrase. If you type a sequence of words, it treats each word individually and returns topics with large numbers of those individual words. Is anyone else frustrated by this?

  5. Thanks for this. My shop invested in Flare recently. The learning curve is steep, but we are slowly “getting it”. I have found I am much more confortable working in the code than the WYSIWYG as I convert our library of docs from Word to Flare. One feature that drives me crazy is that there is no word-wrap for the internal text editor! I can’t imagine anyone not including that basic feature. I look forward to reading more.

  6. Paul:
    This is great, and I’ve experienced several of these quirks myself. I’ve hung on to v1.12 for a while due to the fact that I’m a broke independent contractor. (I will probably upgrade to v3 in a month or so.)
    As for .NET, I’m afraid it’s here to stay. Several of the software products I document are based on a .Net framework. I believe it even comes installed on Windows Vista w/o the user needing know a thing about its existence. Upgrades are automatic through the dangerous windows Auto-Update. Since my clients require .Net, and Flare requires it, I haven’t been able to upgrade to the wonderful MacBook I’ve had my eye on. I know they run Windows now, but I’m afraid .Net might be asking too much.


  7. Hey Paul,
    I’ve Googled & Forum’d this one to death, and can’t find it anywhere in the interface…. is there a way to up the font size in the XML editor? I find working in is giving me eye strain, and it’s currently my number one Flare gripe, to the point where I keep publishing to do every single proofread, which is slowing me down.

  8. Hi, Jay

    Thanks for the comment.

    You aren’t the first to complain about this. There isn’t a setting anywhere that allows you to change the size of the text in the XML editor (unfortunately). However, what I have heard other people suggest is that you add an additional media type to your CSS style sheet, and when you are editing in the XML editor select that medium from the drop-down (top right of the XML editor). In fact, you could just go through the elements in your new media type, and change the font size. The other features would be inherited from the basic style sheet.

    Then, when you publish your targets, just make sure you have selected the default style medium, and nothing in your output should change.

    Its a bit more work, but you should be able to get the XML editor to show the text in a larger font.

    It might be worth it to submit a feature request to MadCap software. Their bug/feature page is:

  9. Great workaround Paul.
    I’ve also added a subtle a light green background colour to my new “BigOnScreen” medium’s styles, so that I have a visual cue to remind me to change the medium before I publish.

  10. You don’t even have the change the medium in your display before you publish; the medium is set in the target file (whether a Word target, a WebHelp target, or whatever). No matter what is shown on your screen, when you publish the target, the medium set in the target file will be used. (On the Advanced tab of your target, you can specifically set the Stylesheet Medium.)

    I do think the background color is a good idea, just so you remember what you are looking at. Did you just apply the background color the the body tag?

  11. Somewhere deep in the Flare forums I once came across a thread that indicated that MadCap sells “build licenses”. I assume they are less expensive than the full license and I further assume that other than using the command line compile that license doesn’t allow for doing much else.
    Way back when before Flare 1.0 came out I write to Mr. Hamilton and command line compile and source control integration were two of the core things that I though had to be in Flare 1.0. Well, the command line compile was there, but not the source control integration. Now it is there, but apparently fairly shaky and also fully Microsoft-centric. For a build server that may not come into play as one can pull the source out of source control via batch file and CLI. Speaking of which, I recommended multiple times to implement source control integration in Flare via CLI . A front end fires console commands via CLI and all is well. At one of my previous jobs we had a bunch of build scripts that pulled the source code from VSS, ran the compile, and packaged it all up using InnoSetup. That always worked, never gave a problem, and would have worked with any source control system that supports CLI. But no, MadCap had to use a proprietary, Microsoft-only API. I guess developer convenience won again over usability and flexibility.
    I really like MadCap’s products and their approach in general, but they really block their way quite a bit by doing everything Microsoft-only. Number 5 is really dead-on.

  12. Paul, you mentioned in your Blog about the problems with Flare the issue of not being able to include your latest Help files with the nightly builds because the build machine is Linux… do you mean that the compiling of your help cannot be done on the linux box? Surely the output can be included in the builds, right? Know what i mean?
    Thanks, I am seeking a new HAT… so far it is between Eclipse and Flare. And I need to do some research on Flare’s DotHelp, as my product is that platform, so if you have any insight on DotHelp, I would appreciate it.

  13. Tana,

    Yes, the Linux box can obviously incorporate the builds, but there is no way for my Linux build box to kick off a new build. It can only grab whatever build I most recently made. If I made changes to the project and didn’t build it, then those changes won’t be included in the product build. (But if your application is a .NET application, then you won’t be worried too much about this for your own project.)

    I’ve never heard of somebody using Eclipse as a HAT, so I’m not sure I can give you and advice there. Flare does, however, have a .NET help output for .NET applications. It is a pretty popular help output option. There are tons of ways you can integrate it directly into your application as well, so that is cool.

    I recommend that you go to MadCap’s website and download an evaluation copy of Flare and see what it can do for you.
    Also, you can visit the MadCap Forums for more information on the .NET output options and how you can integrate them into your application.

    Thanks for reading!!

    • Paul,

      WRT a nightly build and using a Linux box to get the truly latest version: have a look at AutoIt ( That can automate mouse clicks etc. in a simple scripting language. You can use Windows scheduler to kick off a build, then Linux can pick it up.

      If you need to kick off the build script from Linux at an arbitrary time, install netcat ( or if you want more security, cryptcat ( on both machines. See for a friendly introduction to their use.

      One question: do you have any idea why some fonts just won’t embed when going to PDF output? I need to use a specific set of OpenType fonts for a client, and could only use them after converting to TTF. They still wouldn’t embed, but at least I can use the PDF as input to a PDF printer driver to embed the fonts to generate another PDF which I then use. MadCap forums say it’s because of them using .NET, but our programmers are not convinced. They think it’s a limitation of a library they are using, and don’t want to change from.

  14. Hi,
    Iam using Flare demo version. After generating any output file the words are all misspelled. implies the content in WYSWIG is not matching with the content of output file. Is this because m using demo…..plz help me out in this reagard.

  15. Hi Chris,

    Yes, the munged output is a result of the Flare Demo. Basically MadCap doesn’t want you downloading the demo version and using it to create all your content files without purchasing Flare.

    In fact, Flare warns you of this when you load it. Since you haven’t registered your version, when Flare starts, it asks you if you want to run in trial mode, or if you want to purchase a copy. When you select trial mode, a pop-up warns you that all output will be munged. What you are calling “misspellings” is what Flare calls “munging.”

    When you purchase a full copy of Flare, the files build as you would expect, without messing up the content.

    This allows you to create an unlimited number of topics so you can see how your particular project scales. The nice thing about munging the output is that when you purchase a copy of Flare, you can continue to use the topics you’ve already written, because the trial munging only happens to the output. The source files are not altered. Simpily enter your registration key, and you can continue working where you left off in Flare.

    Hope this helps. Have a great day.

    Thanks for reading.

  16. Hi, Paul,

    I’m looking at Flare as a replacement for FrameMaker, and I wondered whether these issues had been resolved in the new 2017 version or in Flare 12? Any information you could give me would be great. Thank you for the great article!


    Danielle Simmons

    • Hi Danielle, I’ve updated the heading to this post so future readers will recognize, as you did, that this post is almost 10 years old. Most of what is written here no longer applies. Let me respond to each of my “complaints” above with the information that is relevant, now in Flare 17:

      1. Cross references. In this post I complained about how cross references were formed, and how they were updated. For many years now, all the issues I bring up here have been resolved. Cross references work wonderfully, and text is updated when the target text updates. My concern about cross reference page numbers in Word has been resolved for many years as well.

      2. Word output. When I originally wrote this post, direct-to-PDF output wasn’t possible in Flare. You had to build a Word target, and then convert that to PDF. Back in version 4, MadCap added the ability to create PDF targets directly, and many of us stopped using Word all together. To be fair, those who still create Word targets do report some functionality that doesn’t work exactly like it does in PDF output, but that is due, in large part, to limitations in Word. Word can’t do what it can’t do, if you know what I mean.

      3. Variables. These have been greatly improved over the years. In the latest versions you can even use variables in headings and anywhere else (including in screen callout text if you use MadCap Capture). You can ignore all my previous rants about variables, as these are much, much improved.

      4. Glossary Problems. My first complaint ten years ago was that when Flare found a glossary term in a heading it converted that term, making headings look weird. First, I have found that most of my clients don’t need/want the variables to be converted in the text, so we don’t run into this very often, but even when they do, Flare has been updated so that if you convert the first glossary term in a topic, Flare ignores those glossary terms that are in headings, and converts the first glossary term that is in a paragraph. This is much improved. My second complaint had to do with synonyms. This still works basically the same way, but you can work around it by creating child terms directly in the glossary file. Glossaries have also been greatly improved because you can mark individual glossary entries with conditions, or you can include only specific glossaries in a target. Ten years ago (if memory serves me correctly) Flare would insert glossary terms in alphabetical order for the individual glossary file, but if you included two separate glossary files, it would not merge the lists before alphabetizing, making it impractical to use multiple glossary files in a target. Flare now merges all glossary files, then alphabetizes the terms when creating the glossary, so you have A LOT more control over how glossary content is included in individual targets.

      5. Win-centric Design. This is still true. Flare requires the .NET framework, so you have to run Flare on Windows. In the mean time, I’ve successfully run Flare on a Mac using VMWare, and it was functional (though my computer lacked enough resources to run two operating systems at the same time effectively, but that was a hardware problem, not a Flare problem). So, be aware, you do need Windows to run Flare.

      6. Misc-Items. Flare is still an advanced tool, and not all the features are readily apparent or necessarily intuitive the first time you use it. But that is true for most advanced software programs like PhotoShop, InDesign, Framemaker, and Illustrator, to name a few. Flare is sophisticated software and it does require some training, or some time spent learning to figure out how it is done. What is nice these days that wasn’t true when I wrote this original post is that there are several books on Flare that you can purchase online to help you learn the tool, which I recommend for new users (even if you get Training, the books are still good resources). Another gripe I expressed ten years ago related to linking to headings. Linking to drop-down text does work as I had hoped now. Flare is good about expanding the text whether you get there via a link or via the search functionality in the output. Pasting information into Flare is much better now as well. When you paste into Flare, if you hover your mouse over the pasted content, you will see a pop-up control at the end of your pasted block. Click on that control, and you have a lot of options about how Flare will paste the content including pasting as a list, pasting as paragraphs, and pasting with the formatting from the source.

      So, that is a comprehensive review of my concerns from ten years ago and how they have been resolved in the intervening years of releases. I’m still an avid Flare user, a Flare trainer, and a big advocate of using Flare in documentation projects.

      I hope this helps you understand how the tool has changed since I first wrote this list of concerns.

Leave a Reply