Flare 5 DITA feature review (Part 1: Overview and map files)

Sarah O'Keefe / Reviews6 Comments

[Disclosure: Scriptorium is a Certified Flare Instructor.][Full disclosure: We’re also an Adobe Authorized Training Center, a JustSystems Services Partner, a founding member of TechComm Alliance, a North Carolina corporation, and a woman-owned business. Dog people outnumber cat people in our office. Can I start my post now?]

These days, most of our work uses XML and/or DITA as foundational technologies. As a result, our interest in help authoring tools such as Flare and RoboHelp has been muted. However, with the release of Flare 5, MadCap has added support for DITA. This review looks at the DITA features in the new product. (If you’re looking for a discussion of all the new features, I suggest you wander over to Paul Pehrson’s review. You might also read the official MadCap press release.)

The initial coverage reminds me a bit of this:

(My web site stats prove that you people are suckers for video. Also, I highly recommend TubeChop for extracting a portion of a YouTube video.)

Let’s take a look at the most important Flare/DITA integration pieces.

New output possibilities
After importing DITA content into Flare, you can publish to any of the output formats that Flare supports. Most important, in my opinion, is the option to publish cross-browser, cross-platform HTML-based help (“web help”) because the DITA Open Toolkit does not provide this output. We have created web help systems by customizing the Open Toolkit output, and that approach does make sense in certain situations, but the option to publish through Flare is appealing for several reasons:

  • Flare provides a default template for web help output (actually, three of them: WebHelp, WebHelp Plus, and WebHelp AIR)
  • Customizing Flare output is easier than configuring the Open Toolkit

I took some DITA files, opened them in Flare, made some minimal formatting changes, and published to WebHelp. The result is shown here:

Sample WebHelp from DITA through FlareNot bad at all for 10 minutes’ work. I added the owl logo and scriptorium.com in the header, changed the default font to sans-serif, and made the heading purple. Tweaking CSS in Flare’s visual editor is straightforward, and changes automatically cascade (sorry) across all the project files.

Ease of configuration
Flare wins. Next topic. (Don’t believe me? Read the DITA Open Toolkit User Guide — actually, just skim the table of contents.)

Language support
The Open Toolkit wins on volume and for right-to-left languages; Flare wins on easy configuration (I’m detecting a theme here.)

Out of the box, both Flare and the Open Toolkit provide strings (that is, localized output for interface elements such as the “Table of Contents” label) for simplified and traditional Chinese, Danish, Dutch, English, Finnish, French, German, Italian, Japanese, Korean, Norwegian, Portugese, Spanish, Swedish, and Thai (I have omitted variations such as Canadian French).

Beyond that, we have the following:

  • Right-to-left language support: Only in the Open Toolkit
  • Language strings provided by the Open Toolkit but not by Flare: Arabic, Belarusian, Bulgarian, Catalan, Czech, Greek, Estonian, Hebrew, Croatian, Hungarian, Icelandic, Latvian, Lithuanian, Macedonian, Polish, Romanian, Russian, Slovak, Slovenian, Serbian, Turkish, and Ukrainian
  • Ease of adding support for a new language: Flare wins. In the Open Toolkit, you modify an XML file; in Flare, you use the Language Skin Editor (although it looks as though you could choose to modify the resource file directory directly if you really wanted to)

Thus, if you need Hebrew or Arabic publishing, you can’t use Flare. The Open Toolkit also provides default support for more languages.

Map files
I imported a map file into Flare and published. Then, I changed the map file to include a simple nested ditamap. Here is what I found:

  • Flare recognized the map file and the nested map file and built TOC files in Flare with the correct relationships.
  • Inexplicably, the nested map file was designated the primary TOC. I speculate that this might be because the nested map file was first in alphabetical order. I changed the parent map file to be the primary TOC to fix this. I don’t know what would happen for a more complex set of maps, but I am concerned.
  • Flare inserted an extra layer into the output TOC where the nested map is found.
  • The titles generated in the TOC are different in Flare than they are through the DITA Open Toolkit (see below).

I generated the output for my map file (the nested map is the “The decision to implement” section in this screen shot) through the DITA Open Toolkit and got the following XHTML output:
Then, I imported the same map file into Flare, generated WebHelp, and got the following TOC output:

Notice that:

  • The TOC text is different (!!). The DITA Open Toolkit uses the text of the topic titles from inside the topic files. Flare uses the text of the @navtitle attribute in the map file. My topic titles and @navtitles don’t match because I created the map file, then changed a bunch of topic titles. The map file didn’t keep up with the new titles (because it doesn’t matter in the Open Toolkit), but it appears to matter for Flare. The entry in the map file for the first item is:
  • <topicref href="introduction.xml" navtitle="Introduction" type="topic">
    Flare picks up the “Introduction” from the navtitle attribute.

    Inside the file, you find:

    <title>Executive summary</title>
    The Open Toolkit uses the content of the title element from inside the file.

  • The Implementation section has added an extra layer in the Flare output. It appears that nesting a map file results in an extra level of hierarchy.

The inconsistency between the two implementations is annoying.

In part 2 of this review (coming soon), I’ll look at cross-references, reltables, conrefs, specialization, and conditional processing.

About the Author

Sarah O'Keefe

Twitter

Content strategy consultant and founder of Scriptorium Publishing. Bilingual English-German, voracious reader, water sports, knitting, and college basketball (go Blue Devils!). Aversions to raw tomatoes, eggplant, and checked baggage.

6 Comments on “Flare 5 DITA feature review (Part 1: Overview and map files)”

  1. (Disclosure: I work for JustSystems but I’m speaking as an individual not on behalf of the company, and I like cats, although I’m allergic to them…)
    Good review. I’m looking forward to part 2.
    Regarding the TOC text being different between Flare output and Open Toolkit output: In this case, the Open Toolkit’s behaviour is compliant with the DITA specification, and Flare’s behaviour is not compliant. If a title exists in a referenced topic, it should be used in output unless the pointing to it has the “locktitle” attribute set to “yes”. See: http://docs.oasis-open.org/dita/v1.1/CD02/langspec/common/topicref-atts.html.
    Regarding the extra indentation Flare gives to nested maps: Say you have a chapter with 20 first-level headings in it. With the Open Toolkit’s behaviour, you can have the first 5 of these topics be in one submap the next 5 in a second submap, and the last 10 be in a third submap. With the behaviour that you described for Flare, you cannot set up your submaps this way, which will significantly affect how you set up your content files. The difference is more than annoying: It means that if you use submaps, you can’t use the same map in a non-Flare processor for PDF output and in Flare for help output.

  2. I meant to say, “If a title exists in a referenced topic, it should be used in output unless the pointing to it has the “locktitle” attribute set to “yes”.

  3. [Disclosure: I’m also a certified Flare instructor, and Flare aficionado]
    Great review. Like I said in my review, I don’t use DITA (yet), so I didn’t have a chance to review any of the DITA implementation in Flare 5. However, I suggest that you submit these as bugs to MadCap Support, as I assume it is their desire to fully support the specification.
    I’m also looking forward to part 2. Great work.

  4. Third try: I meant to say, “If a title exists in a referenced topic, it should be used in output unless the TOPICREF pointing to it has the “locktitle” attribute set to “yes”.
    (I get it now – the blogging software hides anything that has angle brackets around it, so the word “topicref” didn’t appear in my previous comments.)

  5. Your note about not being able to use Flare for publishing in Hebrew and Arabic caught my eye. After doing some research, it looks like that comment is slightly misleading. According to the Microsoft Health Services Group, they are able to use Flare to publish in these languages. They use the command-line compiler to build the files they get back from the localization vendor.
    Thus, although the process is not “out of the box”, it sounds like it IS possible to use Flare for right-to-left languages.

  6. @Joan Thank you for the notes about Hebrew and Arabic. According to MadCap, right-to-left languages are not (yet) supported. So perhaps “not supported” does not equal “can’t be done.” 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *