bell notificationshomepageloginNewPostedit profile

Topic : Can we use MadCap Flare with semantic markup? My team uses MadCap Flare to produce a large body of documentation (thousands of topics). The source is "Flare HTML", HTML with some Flare additions - selfpublishingguru.com

10.02% popularity

My team uses MadCap Flare to produce a large body of documentation (thousands of topics). The source is "Flare HTML", HTML with some Flare additions (for variables, admonitions, snippets, and so on). We use CSS to style the HTML to our tastes. We use the build tool that comes with Flare to produce the output, controlled by scripts that do some preprocessing (like making sure TOC entries are updated when topic headings change).

We would prefer to use a semantic markup language, like DocBook XML or DITA XML, instead of pure HTML. Semantic markup would solve a number of writing problems for us. But we've found no way to do this in Flare, and our writers are very attached to the tool, working directly with the Flare GUI almost exclusively. Some of our users have expert-level knowledge of Flare; for this and other reasons,1 changing tools would be very difficult.

Is there a way to use Flare with a semantic markup language, preserving the benefits of using the Flare GUI so the experience for our writers will be about the same as it is now? HTML is "baked in" to Flare; can we bake in DocBook or DITA instead? (Baking in a small subset of the DocBook spec would be fine; when I've used DocBook I probably only used 20-25 of the 400 elements in the schema. I'm less familiar with DITA.)

I assume that for the build we'd have to add a transformation step, to turn the semantic markup into HTML before feeding it to the Flare build. (That seems easier than making the Flare build understand a different schema, anyway.) That's workable (we script this build anyway), though improvements on that would be welcome.

Our primary output is HTML, but we also produce PDF, where the formatting sometimes ends up being kind of messy. We can't ditch the PDF entirely yet, so a solution to this problem needs to account for PDF too. Our HTML requirement is "looks good" and our PDF requirement is "doesn't break".

1 Other reasons: (a) no budget; (b) this is the preferred corporate tool (so politics); (c) this team has already changed tools once, about 3-4 years ago I think, and every now and then we still bump into suboptimal artifacts of that change.

Load Full (1)

Login to follow topic

More posts by @Goswami879

Login to post a comment!

1 Comments

Sorted by latest first Latest Oldest Best

10% popularity

DITA is one of the output options for Flare. You can create a new DITA target right alongside any HTML or PDF targets. We don't use it at my company, but I've played with it a bit to see how it works.

I'm not sure how extensively the DITA structure is supported. In my brief experiments, I've seen that madcap's keywords are translated to indexterm element tags in the DITA output. Variables are wrapped in ph element tags with conref attributes in the DITA output and a mcvars.dita file is included in the output's Resources folder. That file lists only the variables selected in the Flare Target file for the DITA Output.

To illustrate, this is an small example of the DITA output from Flare:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="Get_Help">
<title>Get Help</title>
<body>
<p>
<indexterm>Get Help</indexterm>
<indexterm>Customer Service</indexterm>Get Help</p>
<p>
<ph conref="Resources/mcvars.dita#mcvars/variableId2" /> is committed to providing a variety of helpful resources to support your needs.</p>
<p>Online Help</p>
<p>From anywhere within <ph conref="Resources/mcvars.dita#mcvars/variableId1" />, click Help to browse our Online Help Center, where you'll find a list of Frequently Asked Questions (FAQs) for quick answers to common questions.</p>
</body>
</topic>

And, for comparison, the same topic as seen in Flare's text editor:

<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head>
</head>
<body>
<h1 class="NewPage"><MadCap:keyword term="Get Help;Customer Service" />Get Help</h1>
<p><MadCap:variable name="Text.Brand" /> is committed to providing a variety of helpful resources to support your needs.</p>
<h2>Online Help</h2>
<p>From anywhere within <MadCap:variable name="Text.AccountPage" />, click <strong>Help</strong> to browse our Online Help Center, where you'll find a list of Frequently Asked Questions (FAQs) for quick answers to common questions.</p>
</body>
</html>

The output uses .ditamap and .dita filetypes and Madcap's help site for Flare makes note that you can't edit in the DITA structure natively:

As DITA takes on a bigger role in technical communication, more and
more tools are becoming available to create this type of structured
content. In this version, you cannot use Flare to edit DITA content
natively. However, you can use a third-party tool (e.g., XMetal) to
create your structured DITA files.

However, after doing a bit of research, I found this youtube tutorial on how to create custom DITA elements by using the mc-dita-type attribute on paragraph classes in Flare. For example:

p.Note
{
background-image: url('../Images/Icons/noteicon.png');
mc-auto-number-format: '{b}{color #9EB515 }Note: {/color}{/b}';
mc-dita-type: quicktest;
}

After building the DITA output, that mc-dita-type attribute becomes a quicktest element tag in the topic file.

Conditions, however, do not work seem to in DITA output. Any text in the topic is included, regardless of condition tags used.

Load Full (0)

Back to top