MadCap Flare: pain points and solutions (part 2)

Using MadCap Flare, a help authoring tool, can be cool and unbearable at the same time. Those InfoDevs who deal with it on a regular basis will definitely understand what I mean. The more I work with this tool, the more I learn about its capabilities and pitfalls. The work on multiple print outputs and the HTML5 target makes the challenge even more exciting. Previously, I shared some issues I encountered with possible solutions for them (See MadCap Flare: pain points and solutions). In this article, I have prepared another portion of troubles to be considered.  So, Ready Steady Go!

Trouble #1

Wrong titles in search results in the HTML5 output

Once, when I performed a search in my HTML5 output, I noticed that some search results had wrong titles to identify them.  At first, I could not find the root of the problem since my topic headings and TOC entry labels absolutely coincided.

As it turned out, when working with MadCap Flare, it is important to understand that topic titles, topic headings, and TOC entry labels are different items.

  • Topic title is used to control search results and links: related topics links, concept or “see also” links, and keyword links. Besides, a topic title is displayed in window title bars and a TOC (if you drag the topic from the Content Explorer to the TOC Editor).
    title
  • Topic heading is used to place your topic at the corresponding level in the TOC as well as for cross-reference headings.
    heading
  • TOC entry is used to navigate you to the needed topic, and its label coincides with the topic title.
    toc entry

Besides, the title set in the Properties dialog has the highest level of precedence.
1

If there is no topic title specified in the Properties dialog, MadCap Flare uses the text associated with h1 through h6 heading styles. At last, if there is no topic title or heading in a topic, the topic file name will be used.

That is why, to rename a topic correctly, you should change not only its heading, but also the existing title. Otherwise, you will have wrong titles in search results in the online output.

To rename a topic title, go to Properties > Topic Properties > Topic Title.

This time your search results will be correct.

Trouble #2

Partial word-search

Just imagine the situation when your project release is around the corner and a Tester asks why partial word-search has not been implemented in your HTML5 output.  Fortunately, the solution turned out to be quite quick and easy.

To enable partial-word search:

  1. In the Project Organizer, double-click the HTML5
  2. On the Performance tab in the Search Database section, select the Enable Partial Word Searching check
  3. In the Minimum Word Size field, type the number of characters a user must type to see the results (the minimum value is 3 characters).

Now, when you generate your HTML5 output, everything should work perfectly. However, do not forget to check titles in online search results. If there are any troubles, see Trouble #1 for the solution.

Trouble #3

Inserting index keywords

Previously, I inserted my index using the Index Window pane, which is split into two sections—the Terms area at the top and the Explorer area at the bottom. I worked with the Explorer area, where I right-clicked Index, and then clicked Add Top-Level Keyword.

2018-02-26_10-43-41

Then, I added a sub-keyword to a top-level keyword and assigned it to a topic. This method was not convenient and took longer because I had to look through a huge list of topics to find the one I wanted to assign the keyword to. When I found out that I needed to create my index from scratch due to numerous changes to my project, the whole indexing procedure seemed even more painful. However, I managed to find a way around.

To insert the index keyword, drag it from the Index pane into the topic heading.

Check this method out. Sure, you will like it too.

Trouble #4

Multiple outputs: multiple TOCs vs. conditional tags

When you work on multiple outputs and the need to create a TOC arises, you may ask yourself what is better – creating a separate TOC for each output or creating a single TOC for all outputs with conditional tags applied to corresponding topics.

From my experience, the first option is definitely the right one. When you create a TOC for each target, it makes the maintenance of your document much easier, more convenient, and less confusing. Your TOC is not very long and each item is in its place.

Hope you found this article helpful. If you have any remarks or other solutions to the issues above, you are very welcome to share them in comments.

Thank you!

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