In my last post, I discussed ways that you can build lists of related links in your MadCap Flare projects. I expressed a preference for concept links.

If you share my enthusiasm for concept links and are importing FrameMaker content into Flare, you may want to pre-configure your source FrameMaker files to include Passthrough markers with special strings. When you import the marked FrameMaker content into Flare, the Passthrough markers convert to concept markers in the equivalent Flare topics.

You can then insert a concept link help control in each topic that contains the same marker and build a dynamic list of related topics. I described this process in the following post:

MadCap Flare Tip: Helping Users Find Related Information

When preparing your FrameMaker files to include Passthrough markers, follow these steps:

1. Add a custom Passthrough marker to each FrameMaker file. If you’re not sure how to set up markers in FrameMaker files, read this post:

   Preparing FrameMaker Files for Importing into MadCap Flare

2. Insert a Passthrough marker in the heading of each topic that is related to the same concept.
3. Add the following string to the Passthrough marker definition:

   <MadCap:concept term=”term” />

4. Substitute “term” with your concept term, keeping the quotes (“”). Make sure that “MadCap” has an uppercase M and uppercase C.

To ensure that the markers convert properly, enable the following Flare import settings. If you’re using an import file in your project, you’ll find these settings on the Options tab:

• Enable ‘Passthrough’ Markers = Checked
• Passthrough Marker Format = XML

Back to top

When creating online help or user assistance, a common practice is to include a related topics link at the end of a given topic. The link usually appears as a clickable button labeled Related Topics or See Also. When a user clicks the button, a pop-up list of related topics appears, as shown below. Each topic is a clickable link.

In MadCap Flare, you can create this type of link using help controls. Flare offers three types of help control, and my favorite is the Concept Link. This control builds a dynamic list of topics that are associated by a concept. You first have to insert concept markers into the topics to create a concept association among them. This type of linking relationship is similar to A-links in other help tools.

Inserting a concept marker

Before you insert a Concept Link help control into a topic, you need to add a concept marker. To insert a concept marker, follow these steps:

1. Open the topic.
2. Open the Concept Window: View > Concept Window.
3. Do either of the following:
   • Add a new concept term by typing it in the entry field at the top; or
   • Select a previously added concept term from the list in the lower half of the window. For each existing term, you can click the plus sign (+) to the left and view a list of topics that are associated with that term. You can also drag terms into the open topic to create new markers.

I usually place both concept and index markers at the very beginning of a topic, before the topic title.

Creating a pop-up concept link

Now that you have created concept associations among topics by adding markers, add a concept link to the end of each of those topics. This procedure creates the pop-up link that users see in your help output.

To create the pop-up concept link at the end of a topic, follow these steps:

1. Open a topic that contains a concept marker.
2. Select the following menu command:
   Insert > Help Control > Concept Link (A-link).
3. Select a term on the right.
4. Click the directional button in the middle of the window to copy the term to the left side of the window.
5. Click OK.

Other types of help control

Flare offers two other types of help control. You’ll find both of them using this menu command: Insert > Help Control > [Type of Control].

Related Topics control

This control enables you to manually build a list of related topics by selecting files. The control appears as a button with the label Related Topics.

For more information, see these help topics:

• Inserting Related Topics Links into Topics
• Editing Related Topics Links

Keyword Link control

This control builds a dynamic list of topics that are associated by an index keyword. You first have to insert index markers into the topics to create a keyword association among them. The default label for the control is Search Index.

For more information, see these help topics:

• Inserting Keyword Links into Topics
• Editing Keyword Links

Another Option: Relationship Tables

When MadCap introduced DITA publishing capability in Flare 5, they cleverly integrated DITA relationship tables as yet another way to introduce related topic links. You can use this powerful feature in non-DITA projects. For more information, see About Relationship Tables.

Questions?

Help controls and relationship tables enable you to give users a simple way to find related information. They also enable users to learn by association. I encourage you to use these features when using MadCap flare to develop user assistance.

If you have questions or comments about these techniques, please add a comment or contact me.

Back to top

I haven’t written a post about MadCap Flare for a while, and the release of Flare 6 deserves special attention. With this version, Flare remains miles ahead of its competition.

When a new version of Flare is released, I usually install the new version and keep the last version installed, too. After testing the rock-solid Flare 6 beta during the past few months, I was easily convinced that I could fully upgrade on the GA release date. Flare 5 is no longer on my laptop.

I recently created Flare templates for the National Cancer Institute’s Center for Biomedical Informatics and Information Technology (NCI CBIIT). The Information Development team currently uses Adobe FrameMaker and Quadralay ePublisher. Lately I have been busy preparing Adobe FrameMaker files for import into Flare, running import routines with various settings, and testing the results.

I recommend the following process for preparing your FrameMaker files before importing their content into MadCap Flare. I will provide additional advice and tips in upcoming posts.

1. Back up your FrameMaker files.

Read this aloud: Create a backup copy of your FrameMaker files. You’ll need to alter them for an optimal import, so work with a copy—not with the original.

2. Remove formatting overrides.

Regardless of the tool you’re using to develop and publish information, you should use styles (called tags in FrameMaker). Styles automate the formatting process and ensure consistency.

Examine your FrameMaker files and make sure that they’re free of inline formatting created with the Formatting toolbar. In FrameMaker parlance, this type of formatting is called an override. In Microsoft Word, it’s called direct formatting.

I will provide advice on style mapping between Frame and Flare in an upcoming post. I have already included some advice on cleaning up your styles in a previous post. For more information, read the first of my six articles on Flare print publishing.

3. Add indentation to TOC sublevels.

A typical table of contents uses indentation to represent a hierarchy. In a Flare TOC, book icons are flush with the left margin, and topics and subtopics are indented.

Before importing a FrameMaker book, make sure that the FrameMaker TOC sublevels are indented. Flare relies on this indentation to properly create an equivalent TOC.

You can do this for FrameMaker TOC styles (levels 2 and below) by setting a property on the Basic tab of the Paragraph Designer:

1. Select the following menu command: Format > Paragraphs > Designer.
2. In the Paragraph Tag list, select the tag you want to change (for example, Heading2TOC).
3. Click the Basic tab.
4. Set the First property to a specific value. For example, a Level 2 TOC heading might be set at .25 inches, and Level 3 might be set at .5 inches.
5. Click Apply.

4. Predetermine the file names in your Flare project.

FrameMaker is a linear writing tool. Flare is a topic-based writing tool. When writers who are used to authoring in Frame first switch to Flare, they sometimes become disoriented in Flare’s authoring environment. Although Flare generally does a good job of naming topic files, the names might not always be what you expect.

To ensure that you can find your content in Flare, add a custom Filename marker to each of your FrameMaker files. You can then add this marker to FrameMaker chapter names and topic headings. During import, Flare creates a file for each chapter introduction and topic using the name that you pre-assigned.

Example:

• Let’s say that a chapter is called Browsing Terminologies. You insert a Filename marker in the chapter name and define the marker as intro_browsing_terminologies. (I typically prefix chapter introductions with intro. They also serve as section introductions in WebHelp.)
• Now let’s say that the first topic in the chapter is About the Terminology Browser. You insert a Filename marker in the topic heading and define the marker as about_terminology_browser.

During import, Flare creates one file for the chapter and a second file for the topic:

• intro_browsing_terminologies.htm
• about_terminology_browser.htm

You can set the permitted length of file names in the Flare import settings.

Adding a custom Filename marker to a FrameMaker file

To add the custom Filename marker to a file, follow these steps:

1. Select the following menu command: Special > Marker. The Marker window opens.
2. Click the Marker Type drop-down list.
3. Click Edit in the bottom of the list. The Edit Custom Marker Type window opens.
4. In the new window, follow these steps:
   1. Type Filename.
   2. Click Add.
   3. Click Done.

Adding the new marker to a FrameMaker chapter
or topic heading

To add the new marker to a chapter or topic heading, follow these steps:

1. Click anywhere on a chapter or topic heading.
2. Select the following menu command: Special > Marker.
3. In the Marker Type list, select Filename.
4. In the Marker Text box, type the file name that you want Flare to use for the current topic. Remember, you don’t need to append the .htm extension.
5. Click New Marker.

I highly recommend this method. It’s very helpful when you need to find content in your new Flare project.

5. Specify Adobe Distiller settings
for optimal image quality.

Since Flare uses Adobe Distiller to convert images, you can use Distiller to improve image quality in the imported FrameMaker content. To accomplish this, you need to specify custom Distiller settings and save them as a custom .joboptions file.

To specify your Distiller settings, follow these steps:

1. Open Adobe Distiller.
2. Click Settings > Edit Adobe PDF Settings.
3. Select the Images folder on the left.
4. For each Downsample setting, select Off.
5. For each Image Quality setting, select Maximum.
6. Click Save As.
7. Name your custom settings file. For example, mine is flareimport.joboptions.
8. Click Save.
9. Click OK to close the settings window.
10. Close Distiller.

Distiller uses the last saved file, so it will use your custom file.

Questions?

The basic steps that I have covered in this post will help you prepare your FrameMaker files for importing into MadCap Flare. I didn’t discuss the time-consuming task of mapping FrameMaker styles to Flare equivalents. I will cover that subject in an upcoming post.

As always, I welcome your questions and comments.

Back to top

Though I teach most MadCap Flare classes online these days, I am scheduled to teach a live Flare Single Sourcing class on June 3, 2009, in Arlington, VA.

About the single sourcing class

The single sourcing class is a one-day, hands-on session that uses a scenario-based model to teach you how to single source your content with Flare. The course includes an overview of single sourcing for those who are new to the concept. It also includes advanced tips and best practices for experienced information developers.

In the course scenario, One Source Hotels is expanding to open two resort hotels: one in the US and another in Canada. The company needs to develop policies and procedures for the new hotels. They need to single source one set of content to account for differences between the customs and the legal requirements of the two countries. They need to publish to HTML and PDF.

Course prerequisites

If you are a beginning Flare user and are unfamiliar with the Flare work environment, I recommend that you take the Flare Basic/Intermediate class before attempting the single sourcing class. Unfortunately, we simply cannot cover the work environment in detail. If you have no formal Flare training but are comfortable working with the product, then you will will probably do well in the single sourcing class.

Course highlights

The single sourcing course covers many powerful Flare features, including

• re-using content
• maintaining a linked workflow where contributors are writing in Word and FrameMaker and publishing in Flare
• creating ad hoc tables of content for different outputs
• using Flare page layouts for printed output
• using snippets to reuse content with embedded conditions
• using variables in topics and in a TOC
• running builds from the command line and automating builds with batch files
• creating multiple targets (one online and one print target for each hotel)

sharing content and resources using Global Project Linking.

Details for the upcoming session

• When: Wednesday, June 3, 2009, from 9 am to 5 pm
• Where: 2001 Jefferson Davis Highway, Suite 610,
  Arlington, VA 22202 (Crystal City, accessible by Metro)
• Price: $599 per student
• What to Bring: Laptop with Flare 4.2.1 installed. If you need to use a trial version, MadCap will provide a temporary key.

Questions and registration

Contact Jennifer Morse, Senior Territory Manager, MadCap Software:

• Direct: +1.858.320.0387×212
• Toll Free: 1.888.623.2271×212
• Fax: 858.320.0338
• Email: jmorse@madcapsoftware.com
• Curriculum outline: http://tiny.cc/YcylK

Even if you don’t live in the Washington, DC, area but live within a reasonable travel distance, I hope that you will join us.

I am presenting at an upcoming STC Washington, DC (STC WDC) chapter meeting. I will demonstrate and discuss many of the outstanding single-sourcing features that MadCap Flare offers.

Here are some basic details:
Date: Tuesday, April 21, 2009
Time: 6:30 – 8:30 p.m., US EST
Place: Silver Spring Library

If you are in the Washington, DC, area, I hope to see you there!

Visit the event page and register for the event.