Flare 5 DITA feature review, part 2
[Alan Pringle wrote most of this review.]
This post is Part 2 of our Flare 5 DITA feature review. Part 1 provides an overview and discusses localization and map files.
Cross-references and other links
I imported DITA content that contained three xref elements (I shortened the IDs below for readability):
- Reference to another step in the same topic:
<stepresult>
Result of step. And here’s a reference to the <xref href=”task1.xml#task_8F2F9″ type=”li” format=”dita” scope=”local”>third step</xref>.
</stepresult>
- Reference to another topic:
<stepresult>
Result text. And here’s a link to the other task topic:
<xref href=”task2.xml#task_8F2F94 type=”task” format=”dita” scope=”local”></xref>.
</stepresult>
- Link to web site:
<cmd>
Here’s another step. Here’s a link with external scope:
<xref href=”https://scriptorium.com” scope=”external” format=”html”>www.scriptorium.com</xref>
</cmd>
All three came across in the WebHelp I generated from Flare:
On the link to the topic, Flare applied a default cross-reference format that included the word “See” and the quotation marks around the topic’s name. You can modify the stylesheet for the Flare project to change that text and styling.
Relationship tables
DITA relationship tables let you avoid the drudgery of manually inserting (and managing!) related topic links. Based on the relationships you specify in the table, related topic links are generated in your output.
I imported a simple map file with a relationship table into Flare and created WebHelp. The output included the links to the related topics. I then tinkered with the project’s stylesheet and its language skin for English to change the default appearance and text of the heading for related concepts. The sentence-style capitalization and red text for “Related concepts” in the following screen shot reflect my modifications:
conrefs
DITA conrefs let you reuse chunks of content. I created a simple conref for a note and then imported the map file with one DITA file that contains the actual note and a second file that references the note via a conref.
Flare happily imported the information and turned the conref into a Flare snippet. It’s worth noting that the referencing, while equivalent, is not the same. In my source DITA files, I had this:
aardvark.xml contains:
<note id=””>Do not feed the animals
baboon.xml contains:
<note conref=”aardvark.xml#aardvark/nofeeding”>
Thus, we have two instances of the content in the DITA files — the original content and the content reference. In Flare, we end up with three instances — the snippet and two references to the snippet. In other words, Flare separates out the content being reused into a snippet and then references the snippet. This isn’t necessarily a bad thing, but it’s worth noting.
Specialization
Specialized content is not officially supported at this point. According to MadCap, it worked for some people in testing, but not for others. If you need to publish specialized DITA content through Flare, you might consider generalizing back to standard DITA first.
Conditional processing
When you import DITA content that contains attribute values, Flare creates condition tags based on those values. I imported a map file with a topic that used the audience attribute: one paragraph had that attribute set to user, and another had the attribute set to admin. When I looked in the Project Organizer at the conditions for the WebHelp target, conditions based on my audience values were listed:
I set Audience.admin to Exclude and Audience.user to Include, and then I created WebHelp. As expected, the output included the user-level paragraph and excluded the admin-level one.
DITA support level
Flare supports DITA v1.1.
Our verdict
If you’re looking for a path to browser-based help for your DITA content, you should consider the new version of Flare. Without a lot of effort, we were able to create WebHelp from imported DITA content. Flare handled DITA constructs (such as conrefs and relationship tables) without any problems in our testing. Our only quibble was with the TOC entries in the WebHelp (as mentioned in Part 1), and we’ve heard that MadCap will likely be addressing that issue in the future.
We didn’t evaluate how Flare handles DITA-to-PDF conversion. However, if the PDF process in Flare works as smoothly as the one for WebHelp, Flare could provide a compelling alternative to modifying the XSL-FO templates that come with the Open Toolkit or adopting one of the commercial FO solutions for rendering PDF output.
About the author
Yves Barbion
Hi Alan. This is a great review. Thank you very much. I cannot wait to give Flare a whirl.
Alan Pringle
Thanks, Yves. I was happy (relieved?) to see the DITA constructs work in the simple WebHelp projects I created for the review. The thought of creating browser-based help through Flare appeals to me a lot more than doing so through XSL templates, I have to admit.
Yves Barbion
Hello again, Alan. I have already downloaded and installed a trial version of Flare, which went very well. My first experiences with importing DITA-structured content into Flare, however, are not that good. I import a DITA map (actually a bookmap), but I got the following error message: “Data at the root level is invalid. Line 4, position 1”. I got this for topics which I created with DITA-FMx, because they contain these comments (I have replace the angle brackets with round brackets):
(?xml version=”1.0″ encoding=”UTF-8″?)
(!DOCTYPE topic PUBLIC “-//OASIS//DTD DITA Composite//EN” “ditabase.dtd” [
(!– Begin Document Specific Declarations –)
(!– End Document Specific Declarations –)
])
However, these topics validate okay in FrameMaker, oXygen and XMetaL, so there’s nothing wrong with them.
When I remove these comments, Flare gives me another error: it does not seem to like non-breaking spaces (nbsp). Okay, I remove the non-breaking spaces, but then I get the following error: “object reference not set to an instance of an object”. Here, I’m lost, because I haven’t got a clue what it means and I also can’t find anything related in the Flare Help. The topics have quite a lot of conrefs, so I guess that’s the problem.
Alan Pringle
Yves, I did not encounter the problem with the comments. I did my testing with simple files I developed in XMetaL. The files had comments: the XML version, DOCTYPE, and a comment indicating the file was created in XMetaL. When I imported that sample content into Flare, I didn’t get any error messages.
I put a nonbreaking space in one of my sample files to see what would happen. I got an error on import just like you did: Reference to undeclared entity ‘nbsp’.
Alan Pringle
More on nonbreaking spaces…
Sarah suggested trying the numerical entity. Sure enough, didn’t generate import errors.
Alan Pringle
Sigh. Make that (ampersand)#160;
Steve Goodman
Thanks for the excellent, time-saving review.
Questions:
What happens to the DITA code when you import into Flare? How does Flare know what transforms to make from DITA XML to XHMTL?
And can you describe the working methodology? Once you create a DITA project, and make the changes in Flare that you described in your review, do you have to make those changes every time you publish the content? Or is it a one-time thing?
Also, do you know the time table for Flare implementing specializations? Right now, it sounds like it implements ITA, not DITA.
Ravi
Hi,
Can somebody help me as to why I am getting this error (Error: Could not find a part of the path) when I try to import a VALID DITA Book Map (complete with Frontmatter, Chapters (valid ditamaps) and backmatter). Please note that I am able to create multiple outputs (CHM, HTML, PDF so far) through the DITA-OT with the same book map. I want to know if Flare V5 supports book map or is there something I must do?
Regards,
Ravi
Bookmap code
AB
Version 4.0
ab.ditamap code