MadCap Flare: pain points and solutions

I work with the MadCap Flare tool on a regular basis. Namely, with two targets – the HTML 5 Help system and the PDF file. That presupposes that I deal with two outputs, two style sheets, and all my troubles are usually multiplied by two :). In this article, I want to share my pain points as well as possible solutions for them. So, here we go!

Trouble #1
Repeating table header across pages

I started surfing the Internet trying to find the root of the problem. The solution proposed was the following:

  1. Open your stylesheet.
  2. Click Advanced View.
  3. Select the thead style.
  4. Set the display property to table-header-group.

I used this recommendation, but that did not work out. The other option was to open the table properties and to set the Number of header rows to 1.  However, it brought no positive results as well. Then, I found out that repeating header rows was default for tables breaking across pages. So, I found myself in deadlock. Being a novice, I was not aware of HTML. That is why I never opened the MadCap Flare Text Editor to inspect any existing trouble. How wrong I was! Turned out, there was no <thead> row, and, correspondingly, no <thead> tag. Having inserted it, the trouble was resolved.

Trouble #2
Hovering navigation panel item in the HTML5 skin

Since I was setting up the project from the very beginning, one of my tasks was to create a skin for the HTML5 Help system. Everything was going on quite smoothly. However, suddenly I noticed that after generating the output, the function Navigation panel item (hover), which controls the look of text in navigation panel elements when a user hovers over it, did not work though everything was set up properly. I spent hours to find the way out and, unfortunately, there was only one possible solution – to kill the existing skin and begin again. Next time, everything was alright.

Trouble #3
Disappearance of Index in the PDF output

For a printed output, MadCap Flare allows creating an index either manually or automatically. The auto-generate method is much quicker and easier. However, the manual method is more flexible. At the same time, it requires performing a number of extra steps, such as creating topics, inserting proxies, and adding files to the outline TOC. Since I needed a customizable index, I chose the manual one. The index was added to the TOC without any problems and successfully appeared at the end of my document after each generation of the PDF file. But in some time, for no obvious reason, my index, being included in the TOC, always disappeared in the printed output. In contrast, the index of HTML5 worked properly. I was confused. I decided to delete the existing index and add it again. However, I had no success. Then I tried inserting the auto-generated index. The situation remained the same.  After hours of experimenting, the only thing that helped was adding an empty glossary topic, which I didn’t need at all, into the TOC just after the index. In the generated PDF, the pages with the index information were reflected properly while the page with the glossary was blank. It is really weird, but that was the only option which saved me from setting the project from the very beginning again.

Trouble #4
Failure to apply a style to some items of the document

Trying to fix some issues, which arise in my work with MadCap Flare, and, simultaneously, avoid losing some data, I do the working copy of the whole project and only then start experimenting. Once, in my working copy, I changed the stylesheets a bit. Then I decided to apply these stylesheets to my actual project. So, I copied the stylesheets of the working copy and then replaced the stylesheets of my project with the new ones. After that, I generated my outputs. Looking through them, it turned out that some items, having the same style applied, looked different. I tried unbinding and reapplying it, but the style did not obey. Later, I opened the Targets folder in the MadCap Flare editor and reapplied the Master stylesheets to each target. Voila! It worked out.

Trouble #5
A period after a cross-reference

To navigate the user to the right content, in my printed output, I use cross-references. In most cases, they are placed at the end of a sentence, and I need to put a period after them. Besides, I apply the “PrintOnly” condition. After generation of the PDF file, I noticed that after some cross-references (not all of them) the period disappeared. However, in the MadCap Flare editor, everything was fine.
To fix the problem, open the text editor and find the cross-reference. The cross-reference is everything between <MadCap:xref> and </MadCap:xref>. Sometimes, MadCap places the period before </MadCap:xref> and therein lies the problem. Simply put the period after the tag, and Bob is your uncle.

Work with MadCap Flare is not easy and requires a lot of patience. That is why if you had the same troubles or any other interesting cases working with this professional tool, you are very welcome to share your experience in the comments below. Each piece of advice is invaluable!

Besides, don’t forget to have a look at our article Dale Carnegie vs. MadCap Flare: 5 quotes to remember.

Thank you!

One thought on “MadCap Flare: pain points and solutions

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s